docs2mcp

Turn a directory of Markdown, HTML, or TXT files into a remote, read-only MCP server that any compatible MCP client or agent can connect to for documentation retrieval. This includes AskMesh, Claude integrations, Codex, and custom MCP clients.

Quick start

uvx docs2mcp serve ./docs \
  --base-url https://docs.example.com/docs \
  --host 0.0.0.0 \
  --port 8765

uvx creates an isolated environment from PyPI and runs the published docs2mcp CLI without a manual installation step. For local development from a checkout, use python -m docs2mcp.runtime instead.

Enable incremental synchronization with file watching and periodic reconciliation:

uvx docs2mcp serve ./docs \
  --host 0.0.0.0 \
  --port 8765 \
  --watch \
  --sync-interval 30

The first startup scans the entire directory. Later changes are applied per document: new files are inserted, modified files are re-indexed, deleted files are removed, and unchanged files are skipped. The watcher uses a short debounce window and the periodic scan provides a fallback for filesystems that do not reliably emit events.

When binding to a specific public address with DNS-rebinding protection enabled, allow the incoming Host header explicitly:

uvx docs2mcp serve ./docs \
  --host 0.0.0.0 \
  --port 8765 \
  --allowed-host 'docs.example.com:*'

Use the same Python interpreter for installation and startup. docs2mcp requires the official MCP Python SDK mcp>=1.27.0,<2; an older or unrelated package named mcp does not provide mcp.server.fastmcp.

The legacy doc2mcp command remains available as a compatibility alias.

The process prints the MCP connection configuration on startup. Authentication is optional: pass --token to enable Bearer authentication, or omit it to run without authentication.

{
  "endpoint": "http://127.0.0.1:8765/mcp",
  "auth_type": "none",
  "token": null,
  "search_tool": "search_docs",
  "read_tool": "get_document",
  "contract_version": "agent-qa.docs/v1"
}

Enter the endpoint, authentication mode, search_docs, and get_document values in your MCP client configuration. When auth_type is none, select no authentication and leave the token empty. Clients that support Streamable HTTP can connect to the same endpoint without an AskMesh-specific adapter.

GET /readyz reports the document count and the latest synchronization counters, including added, updated, deleted, skipped, failed, duration, and the last error.

Related MCP server: Synapse

Supported formats

The MVP supports .md, .markdown, .txt, .html, and .htm. Indexing uses SQLite FTS5, so no separate vector database is required.

MCP contract

The server implements the interoperable agent-qa.docs/v1 document contract and exposes two read-only tools:

• search_docs(query, limit): returns route, title, url, snippet, and score.

• get_document(route, max_characters): returns document content, sections, and a citation URL.

search_docs.query uses SQLite FTS5 syntax. Whitespace is an AND query, OR matches either term, quoted text searches an exact phrase, NOT excludes a term, and * enables prefix matching. It is not semantic natural-language search; clients should show this syntax to users.

Connect from any MCP client

Use the Streamable HTTP endpoint and the two tool names in any client that supports remote MCP connections. AskMesh is one supported integration; Claude-based clients, Codex, and custom agents can use the same endpoint and read-only contract.

Current limitations

This release is a single-host MVP: documents are imported from a local directory and the index is stored in SQLite. Git synchronization, PDF parsing, object storage, vector search, and a multi-tenant control plane are planned for later releases.