go-docs-mcp: Instructions file for Claude Code

go-docs-mcp

Go MCP server serving documents (PDF, TXT, MD, CSV, Office files, EPUB, HTML, RTF, IPYNB, images) to LLMs via stdio.

Build & Run

make build          # ./go-docs-mcp binary
make install        # /usr/local/bin/go-docs-mcp
make test           # go test -v -race ./...
DOCS_MCP_DIR=~/docs ./go-docs-mcp   # custom dir

Architecture

• main.go — MCP server init, 13 tool registrations, instructions, stdio transport
• resources.go — docs://{filename} resources, list rebuilt on every resources/list
• internal/pdf/reader.go — Document extraction (pdftotext/pdfinfo/pdfimages/tesseract), mtime cache, search, metadata, images, OCR, outlines, tables

Key Decisions

• Uses pdftotext -layout for text extraction (preserves formatting)
• mtime-based cache: re-extracts only when file changes; bounded by DOCS_MCP_CACHE_MB (default 256, 0 disables) with LRU eviction, a text larger than the cap is not cached; summary, outline and tables share it
• Confinement: filepath.Base() + extension allowlist, then filepath.EvalSymlinks of the file must stay under the resolved DOCS_MCP_DIR (symlinks out are rejected and not listed)
• Every external process runs with exec.CommandContext and a per-operation deadline; page ranges are capped at 200 and checked against the real page count
• Tools are registered with read-only / non-destructive / idempotent annotations; only read_url is open-world, and DOCS_MCP_DISABLE_URL=1 removes it
• Page tracking uses form feed (\f) characters from pdftotext output
• Homebrew path detection for macOS (/opt/homebrew/bin/)
• Env vars: DOCS_MCP_DIR (primary), PDF_MCP_DIR (backward compat), DROLO_DOCS_DIR (legacy), DOCS_MCP_OCR_LANG (tesseract language, default eng), DOCS_MCP_DISABLE_URL, DOCS_MCP_URL_PROXY (opt-in proxy for read_url), DOCS_MCP_CACHE_MB (text cache cap)
• Default directory: ~/.docs-mcp/documents/
• Text tools page their output: offset + max_chars (default 50000, cap 200000) with a trailer naming the next offset; search_document has max_results; extract_images returns PNG image content, skips masks, scales to 1600 px, 8 MB budget
• Structured output (outputSchema + structuredContent) on list_documents, list_formats, get_document_metadata, get_document_outline, extract_tables (text JSON kept for old clients), and on the paged read_document, convert_to_markdown and ocr_document (text, next_offset, total_chars)
• URL downloads: 60 s timeout, 50MB cap, application/pdf or text/*, private/loopback/link-local hosts refused on every hop
• Image extraction: pdfimages -list first, only rows of type image (soft masks skipped), extracted as PNM (not -png: poppler's PNG writer is the slow part) and decoded in Go, box-filtered to 1600 px, 4 MB per image, max_images (default 10) and 8 MB per answer
• Tool results over 9 MB are replaced with an error (server.WithToolResultSizeLimit)
• Dual-era: one binary serves the legacy initialize handshake and the stateless MCP 2026-07-28 (_meta envelope, server/discover), all from mcp-go v1.5.0, no era branch in our code; raw_wire_test.go is the arbiter, any mcp-go bump must pass it unchanged (doc/MCP-2026-07-28.md)
• Supports: PDF, TXT, MD, CSV, and through pandoc DOCX, XLSX, PPTX, ODT, EPUB, HTML, RTF, IPYNB; images (PNG, JPG, WebP, TIFF, BMP) with tesseract