# 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

```bash
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:

```bash
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:

```bash
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.

```json
{
  "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.

## 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.