Sumi-Docs-MCP

Sumi-Docs-MCP is a read-only MCP server for Markdown, MDX, and OpenAPI documentation stored in a local directory or on a remote HTTPS host. It exposes four tools over stdio: list documents, search by keyword, fetch one document, and retrieve an OpenAPI specification.

Source is hosted at GitHub. No npm package or GitHub Release has been published for pre-release 0.1.0; run the checkout locally or build the documented executable artifact.

Quick start

Prerequisite: Node.js 25.5.0 or newer.

npm ci
npm run example:smoke

The smoke test builds the server, starts a real stdio child process, and verifies all four tools against the checked-in corpus in examples/basic/.

Start the same corpus for an MCP client:

npm run build
node dist/index.js serve examples/basic/docs --openapi examples/basic/openapi.json --base-url https://docs.example.com/product/

The process uses stdout for JSON-RPC. Diagnostics go to stderr. It is normal for the process to wait silently until a client sends a request.

For client configuration, start from examples/clients/launcher-template.json, replace the placeholders with absolute paths, and follow the configuration contract of your MCP client. Remote-source clients can start from examples/clients/remote-launcher-template.json.

For Codex, the equivalent user- or project-level config.toml entry is:

[mcp_servers.sumiDocs]
command = 'C:\absolute\path\to\sumi-docs-mcp.exe'
args = [
  'serve',
  'C:\absolute\path\to\docs',
  '--openapi',
  'C:\absolute\path\to\openapi.json',
  '--base-url',
  'https://docs.example.com/product/'
]

With --base-url, list_docs, search_docs, and fetch_doc include a public url for each document. MCP clients can show the result to the model and render the URL as a link for the operator.

If the public site is not deployed yet, start the loopback-only preview in a separate terminal:

npm run preview:docs

Then use http://127.0.0.1:4173/ as --base-url. The preview serves the checked-in example by default. To preview another corpus:

npm run preview:docs -- --docs C:\absolute\path\to\docs --port 4173

Related MCP server: docusaurus-plugin-mcp

Commands

To serve another corpus, invoke the CLI directly:

node dist/index.js serve C:\absolute\path\to\docs --openapi C:\absolute\path\to\openapi.json --base-url https://docs.example.com/

To serve a remote corpus, point the same command at its manifest or containing directory:

node dist/index.js serve https://content.example.com/product/

The remote host must expose sumi-docs-manifest.json. The same four MCP tools operate on the downloaded read-only snapshot. Remote OpenAPI is declared in the manifest, so --openapi is local-only. See Remote documentation sources for the manifest format and network limits. The only implemented MCP transport is stdio.

Tool surface

See docs/tool-reference.md for exact schemas, result fields, error behavior, protocol metadata, and snapshot lifecycle.

The server has no client or session state. It builds one process-local, read-only corpus snapshot on the first tool call. Source changes require a process restart.

Configuration model

Runtime configuration comes from CLI arguments, not .env files:

sumi-docs-mcp serve <docs-source> [--openapi <path>] [--base-url <url>] [--transport stdio] [--verbose]

<docs-source> is either a local directory or a remote HTTPS manifest/base URL. --base-url controls clickable human-facing page URLs; it is not the remote content source.

The benchmark has its own command options; see docs/development.md. There are no required application environment variables.

Documentation

• Getting started

• Configuration and environments

• Remote documentation sources

• Development and validation

• Git workflow and commit policy

• Release candidates and human acceptance

• Architecture and constraints

• Architecture decisions

• Troubleshooting

• Contributing

• Historical project reports

Current limitations

• stdio is the only transport.

• Search is lexical keyword matching, not embedding or semantic search.

• The corpus is loaded into memory on first use and is not refreshed in place.

• Remote sources require an explicit manifest; the server does not crawl sites.

• The standalone executable is a local build artifact, not a published release.

• The documented cold-start hard limit of 100 ms is not currently met; prior Node 25.5 measurements were approximately 150-218 ms.

License

MIT. See LICENSE.