Configuration

The CLI accepts explicit arguments and a strict tracked project config:

sumi-docs-mcp serve [docs-source] [--config <path>] [--openapi <path>] [--base-url <url>] [--transport <stdio|streamable-http>] [HTTP options] [--verbose]
sumi-docs-mcp doctor [docs-source] [--config <path>] [--json] [--show-paths]

Resolution order is explicit CLI source, explicit --config, the nearest sumi-docs.config.json within the current Git boundary, then the trusted project root docs/. In a directory without Git, discovery does not walk upward.

When an explicit CLI source selects a local v2 locator or remote manifest, a configured directory openapi path belongs to the replaced source and is ignored. An explicit CLI --openapi is invalid for either manifest-backed source; declare OpenAPI in the manifest.

Address model

docs-source selects what the machine reads. It may be a local Markdown/MDX directory, the exact local _mcp/v2/current.json locator generated by the Web publisher, or a remote HTTPS manifest/base URL. Arbitrary local JSON files and direct v2 manifest paths are rejected.

--base-url selects what a person opens when an MCP result contains a URL. It does not host content and does not change the MCP transport. Markdown extensions are removed, and a final index.md or index.mdx maps to its directory page.

--transport selects how the agent client reaches MCP. stdio launches a local child process. streamable-http exposes /mcp on 127.0.0.1:3000 by default. The source URL, page URL, and MCP endpoint are independent addresses.

HTTP options are --http-host, --http-port, --http-path, repeatable --allowed-host, repeatable --allowed-origin, and --allow-public-network. A non-loopback bind requires the acknowledgement and at least one allowed Host. Public service TLS and request-rate policy belong at the reverse proxy.

GET /healthz is a lightweight liveness check. GET /readyz reports the loaded document count and, for a local or remote immutable v2 source, its corpus revision after HTTP startup has completed. Local directories and v1 sources report a null revision. A v2 deployment may set SUMI_DOCS_EXPECTED_CORPUS_REVISION to a full sha256: revision; a missing or mismatched revision fails before the listener becomes ready.

Runtime diagnostics

serve reserves stdout for JSON-RPC. Runtime failures and optional lifecycle diagnostics use stderr. With --verbose, the server emits one-line JSON events for sumi_docs_mcp.starting, sumi_docs_mcp.ready, and, after a successful snapshot load, sumi_docs_mcp.corpus_loaded.

Lifecycle events contain only the transport, package version, source classification, and bounded corpus metadata such as document count and corpus revision. They do not include the source path, source URL, credentials, or a stack trace. Error diagnostics remain on stderr whether or not verbose mode is enabled.

After building the Web workspace, the same sealed projection can be consumed directly from disk without an HTTP source server:

node packages/mcp/dist/index.js serve ./apps/web/dist/_mcp/v2/current.json --base-url http://127.0.0.1:4321/

The local loader verifies the locator, canonical manifest, byte counts, SHA-256 digests, and real-path containment before committing the in-memory snapshot. The manifest supplies OpenAPI, so do not add --openapi.

Development and distribution

Mode	Entry point	Purpose
MCP source development	pnpm --filter @sumi-os/docs-mcp dev	Work on TypeScript against the checked-in example
Web source development	pnpm --filter @sumi-os/docs-web dev	Serve the local Starlight site with reload
Node distribution	node packages/mcp/dist/index.js	Run the compiled package from this workspace
Standalone executable	packages/mcp/artifacts/bin/sumi-docs-mcp.exe	Run without an external Node installation

The Node distribution and maintained container support both transports. The standalone executable is a stdio artifact until HTTP packaging receives an independent acceptance profile.

Local operation and Pages-only publication require no runtime secrets. SITE_URL belongs to the Web release build. The optional production remote stage keeps SSH credentials and known-hosts material in the protected production-mcp environment. The container maps documented SUMI_DOCS_* variables to validated CLI options; build and expected corpus revisions are freshness guards, not credentials. Source changes require a process restart because each server keeps one read-only corpus snapshot.

The Web release build accepts PUBLIC_MCP_URL and PUBLIC_MCP_READINESS_URL as an optional pair. Both must be absolute HTTPS URLs without credentials, query, or fragment. The publisher never derives the readiness endpoint from the Streamable HTTP endpoint. When configured, it emits <BASE_PATH>_mcp/server.json from the installed MCP package identity. For the project Pages deployment, the public path is /sumi-docs/_mcp/server.json. Without the pair, no remote server metadata is emitted and the readiness probe is skipped.

Before a configured Pages artifact is uploaded, the release probe requires the remote /readyz response to report the expected service, package version, protocol version, and the exact revision in the built _mcp/v2/current.json. GITHUB_SHA, when present, also requires the remote buildRevision to identify the same commit. The probe has a 10-second timeout, a 64 KiB response limit, and does not log upstream response bodies or errors. This revision guarantee applies to a remote MCP service loaded from the Web v2 projection. A local directory source has no immutable corpus revision and is verified through its byte and tool contracts instead.

doctor reports the selected source format (directory, manifest-v1, or manifest-v2) and the corpus revision when one exists. Paths remain project-relative or explicit external placeholders by default. --show-paths reveals resolved local paths for interactive diagnosis only; credentials and stack traces remain redacted. The flag is rejected by serve.

State placement

Do not create a product .sumi/ directory. The parent folder may already be an operator workspace container. Tracked defaults belong in sumi-docs.config.json; future mutable cursor, cache, lease, checkpoint, or database state belongs in the platform user-data directory outside the repo.