Sumi Docs

English | 简体中文

Sumi Docs publishes one reviewed documentation corpus for two consumers:

• people browse an Astro and Starlight website;

• local agents query the same corpus through a read-only MCP server over stdio.

The reviewed root docs/ tree and content catalog are the semantic source of truth. The Web site and MCP server are independently addressable projections; an agent host is the MCP client.

The source repository and documentation site are public and under active development. Package publication, tagged releases, and supported binary artifacts are separate release surfaces; verify the relevant external artifact and provenance before consuming one.

Prerequisites

• Node.js 25.5.0 or newer

• pnpm 10.26.0 through Corepack or the version declared in packageManager

• a trusted checkout when loading repository-provided agent host configuration

Related MCP server: mcp-docs

First Run

pnpm install --frozen-lockfile
pnpm run build
node packages/mcp/dist/index.js doctor --json

Doctor reports project-relative paths or external-source placeholders by default. Add --show-paths only for local diagnosis; do not attach that output to public issues or build artifacts.

The checked-in sumi-docs.config.json selects root docs/ and the example OpenAPI document. Start the human site with:

pnpm --filter @sumi-labs/docs-web dev

Open http://127.0.0.1:4321. Codex, Claude Code, and VS Code project adapters are described in Agent host integration. They expose the four MCP tools without requiring the optional maintainer Skill.

Local agent integrations are stdio-first. The host launches the compiled MCP process and exchanges JSON-RPC messages on the child process's stdin/stdout; diagnostics stay on stderr and no local HTTP port is required. Streamable HTTP is a separate deployment surface for an explicitly configured remote or HTTP client; it is not the local agent default or a fallback transport.

Host-owned shared corpora are opt-in profiles, not a hidden product default: set SUMI_DOCS_PROFILE_<NAME>_SOURCE in the MCP child environment and pass --profile <name>. Without that explicit profile, Sumi Docs still resolves the current project's docs/ source.

To expose the same corpus on a loopback Streamable HTTP endpoint:

node packages/mcp/dist/index.js serve --transport streamable-http

Connect a compatible MCP client to http://127.0.0.1:3000/mcp. The static Web site and _mcp corpus projection do not themselves run that endpoint.

For a hardened local container using the same reviewed root corpus:

docker compose up --build

The service exposes MCP at http://localhost:3000/mcp, liveness at /healthz, and corpus readiness at /readyz. Docker is optional for source development; public deployment still requires HTTPS termination and explicit Host policy.

The repository also provides three optional project workflows under .agents/skills/: $sumi-docs-use for setup and operation, $sumi-docs-pr for proposal and pull-request preparation, and $sumi-docs-audit for read-only, evidence-bound repository and release audits. They route work but do not replace MCP or publish remote changes.

Workspace

apps/web/                   Astro/Starlight site and corpus publisher
packages/mcp/               stdio and Streamable HTTP MCP server and CLI
packages/corpus-contract/   manifest schemas and conformance fixtures
docs/                       product handbook and default corpus
.agents/skills/             optional project usage and contribution workflows

Local operation and the default Pages-only publication require no runtime secrets. SITE_URL is required only for a release-site candidate. Enabling the optional production Streamable HTTP service requires reviewed endpoint variables and SSH material in the protected production-mcp environment. The container accepts documented SUMI_DOCS_* deployment variables; generated output, local state, logs, caches, and .env files remain ignored.

Package-specific instructions remain in each workspace. Active architecture decisions live in the owning workspace's docs/decisions/ directory; the root handbook presents their user-facing consequences without duplicating the decision records.

Source and site visibility do not publish a tag, package, or binary. Those artifacts remain subject to the documented release gates.