Learning MCP the Hard Way: Building a Local Documentation Server

2026-07-13 · Source: AI Advances - Medium · Field: Technology & Digital — Software Development & Engineering, Artificial Intelligence & Machine Learning · Depth: Intermediate, extended

Summary

The article details the creation of "doc-index-mcp," a local documentation server built as a weekend project to deeply understand the Model Context Protocol (MCP). This Python-based server, utilizing `uv` for project management and `rank-bm25` for indexing, recursively scans a specified folder, chunks text files into overlapping windows, and constructs an in-memory BM25 lexical index. It exposes five tools—`search_docs`, `list_indexed_files`, `read_indexed_file`, `reindex`, and `index_info`—via `FastMCP` over stdio. This allows various LLM hosts, such as VS Code Copilot Chat and Claude Desktop, to interact with the server. The primary motivation was to learn MCP's "USB for LLM tools" pattern, enabling the application of this architecture to custom internal tools, while also offering benefits like fully offline operation and deterministic retrieval for non-workspace folders.

Key takeaway

For AI Engineers developing custom LLM tools, understanding the Model Context Protocol (MCP) is crucial for broad host compatibility. By building a simple server like `doc-index-mcp`, you can quickly grasp the protocol's "write once, use everywhere" pattern. Focus on separating core logic from the MCP interface and rigorously validating inputs to ensure secure, reusable tool development for internal systems.

Key insights

Building a small MCP server clarifies the protocol's mechanics for integrating LLM tools across diverse hosts.

Principles

• MCP enables tool reuse across LLM hosts.
• Separate domain logic from protocol implementation.
• Validate all filesystem paths against a defined root.

Method

Implement an MCP server by indexing content, chunking files, building a BM25 index, and exposing tools via `FastMCP` over stdio, ensuring logs are routed to stderr.

In practice

• Use `uv` for Python project setup and dependency management.
• Chunk files with overlapping windows for LLM context.
• Return pre-formatted strings with citations for LLM consumption.

Topics

• Model Context Protocol
• LLM Tooling
• BM25 Indexing
• Python Development
• Local AI
• VS Code Copilot

Code references

• astral-sh/uv
• KishanChoudhury/MCP-Projects
• modelcontextprotocol/python-sdk
• dorianbrown/rank_bm25

Best for: AI Engineer, Software Engineer, AI Student

Related on AIssential

• The Architecture of Next-Gen AI: Deep Diving into Model Context Protocol (MCP) — MCP standardizes AI tool integration by decoupling execution from LLM decision-making, enabling modular and secure agent architectures.
• FastMCP: The Pythonic Way to Build MCP Servers and Clients — FastMCP simplifies Model Context Protocol (MCP) server and client development using Python decorators and async support.
• Connecting LLMs to the Real World: Tool Use, Function Calling, and MCP — LLMs use an application layer and standardized protocols to interact with external tools, extending their capabilities beyond text generation.
• A Large-Scale Dataset of MCP Implementations on GitHub — A new dataset provides verifiable, code-grounded insights into real-world Model Context Protocol implementations on GitHub.
• Whitepaper Companion Podcast - Agent Tools & Interoperability with MCP — MCP standardizes LLM tool integration, enabling real-world actions and fostering a modular, scalable AI agent ecosystem.
• Making AI Personal: Building Context-Rich AI Tools with MCP • Kris Jenkins • GOTO 2025 — Agentic AI combines LLMs with programmer-defined tools, enabling context-rich answers to ambiguous personal queries.

See Counsel's argued verdicts on the open AI decisions leaders are weighing →

Open in AIssential →

Editorial summary, takeaway, and curation by AIssential. Original article published by AI Advances - Medium.