docs2mcp

Turn a directory of Markdown, HTML, or TXT files into a read-only MCP server that AskMesh can connect to directly.

Quick start

python3 -m venv .venv
. .venv/bin/activate
pip install -e .
python -m docs2mcp.runtime ./docs --base-url https://docs.example.com/docs --host 0.0.0.0 --port 8765

Enable incremental synchronization with file watching and periodic reconciliation:

python -m docs2mcp.runtime ./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:

python -m docs2mcp.runtime ./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 the AskMesh knowledge source configuration. When auth_type is none, select no authentication and leave the token empty.

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

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 agent-qa.docs/v1 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.

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.