Metadata-Version: 2.4
Name: docs2mcp
Version: 0.1.0
Summary: Turn documentation into an AskMesh-compatible read-only MCP server.
License-Expression: Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115
Requires-Dist: mcp<2,>=1.27.0
Requires-Dist: uvicorn>=0.30
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: watchfiles>=0.21
Dynamic: license-file

# docs2mcp

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

## Quick start

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

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

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

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