Sumi Docs

English | 简体中文

Sumi Docs publishes one reviewed documentation corpus for two consumers:

• people browse an Astro and Starlight website;

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

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. The MCP and corpus-contract packages are published under the @sumi-labs scope. No tagged GitHub Release or supported binary has been published.

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: okf-mcp-server

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.

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

There are no required runtime secrets. SITE_URL is required only for a release-site candidate. 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.