Demo Document Search Server

Companion repo for the YouTube video "MCP Explained for Engineers — Not Just Another API Wrapper"

A production-style MCP server that lets Claude Desktop search your local documents. No LangChain. No heavy frameworks. Plain Python + the official MCP SDK.

Clone → install → add to Claude Desktop → done in under 10 minutes.

---

What is MCP?

MCP (Model Context Protocol) is an open standard for connecting AI models to external tools and data sources. Think of it as a USB-C port for AI — one protocol, many connectors.

The problem it solves: every AI integration used to be custom code. You'd write OpenAI function calling differently than Anthropic tool use, differently again for Gemini. MCP standardizes the interface so a single server works with any compatible client.

┌─────────────────┐    JSON-RPC over stdio    ┌──────────────────────┐
│  Claude Desktop │ ◄──────────────────────► │  Your MCP Server     │
│  (MCP Client)   │                           │  (this repo)         │
│                 │   list_tools()            │                      │
│                 │   call_tool("search_documents", {query: "..."})  │
│                 │ ◄─── results ─────────── │  TF-IDF search over  │
│                 │                           │  local .md/.txt docs │
└─────────────────┘                           └──────────────────────┘

The server speaks JSON-RPC 2.0 over stdin/stdout. Claude Desktop manages the connection. You write Python functions; the protocol handles the rest.

---

What This Demo Does

The server exposes three tools to Claude:

Tool	What it does
search_documents	TF-IDF keyword/phrase search, returns ranked results with snippets
get_document	Returns the full text of any indexed document
list_documents	Lists all documents with word counts

Five sample engineering documents are included (async Python, API design, Docker, Git, system design). Drop any .md or .txt files into documents/ and restart the server to index them.

---

Quick Start

Prerequisites

• Python 3.10 or higher
• Claude Desktop installed (for the full demo)
• pip or uv

Step 1 — Clone and install

git clone https://github.com/YOUR_USERNAME/mcp-demo.git
cd mcp-demo
pip install -r requirements.txt

Step 2 — Run the smoke test

This verifies the search engine works correctly without needing Claude Desktop:

python test_server.py

Expected output:

=== MCP Demo — Search Engine Smoke Test ===

Indexed 5 document(s) from .../documents

  [PASS] at least 5 documents indexed (got 5)
  [PASS] all documents have >50 words
Search relevance checks:
  [PASS] 'async await event loop' → python_async.md (got python_async.md)
  [PASS] 'REST API versioning idempotent' → api_design.md (got api_design.md)
  ...

All checks passed.

Step 3 — Connect to Claude Desktop

Find your Claude Desktop config file:

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

Add this block to the config (replace the path):

{
  "mcpServers": {
    "doc-search": {
      "command": "python",
      "args": ["-m", "server.main"],
      "cwd": "/absolute/path/to/mcp-demo"
    }
  }
}

Windows example:

{
  "mcpServers": {
    "doc-search": {
      "command": "python",
      "args": ["-m", "server.main"],
      "cwd": "C:\\Users\\you\\mcp-demo"
    }
  }
}

Restart Claude Desktop. You should see a hammer icon (🔨) in the chat input bar — that confirms MCP tools loaded successfully.

Step 4 — Try it in Claude

Ask Claude any of these to see MCP working:

What documents do I have indexed?

Search my docs for information about async Python and the event loop

Find everything about Docker multi-stage builds and summarize the key points

Compare what my docs say about caching strategies

Watch Claude automatically invoke list_documents, search_documents, and get_document as needed — reasoning over your local files without any copy-paste.

---

How It Works

The MCP Handshake

When Claude Desktop starts, it launches your server as a subprocess and sends an initialize request. The server responds with its capabilities. Claude then calls tools/list to discover available tools and their schemas.

All subsequent calls use the same stdio pipe:

Claude Desktop                    server/main.py
     │                                  │
     │── initialize ──────────────────► │
     │◄─ initialized ─────────────────  │
     │── tools/list ────────────────── ►│
     │◄─ [search_documents, ...] ─────  │
     │                                  │
     │   (user asks a question)         │
     │── tools/call ────────────────── ►│  search_documents(query="async")
     │◄─ result ──────────────────────  │  TF-IDF scores → ranked results

The Search Engine

server/search.py implements TF-IDF scoring from scratch — no scikit-learn, no embeddings:

• TF (term frequency): how often a term appears in a document, normalized by document length
• IDF (inverse document frequency): log(N / df) — penalizes terms that appear in every document
• Score: sum of TF×IDF for each query term present in the document

This is the same algorithm that powered early web search. It works well for keyword queries over small document collections and has zero runtime dependencies.

FastMCP

server/main.py uses FastMCP — the high-level API from the official MCP SDK:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("doc-search")

@mcp.tool()
def search_documents(query: str, max_results: int = 5) -> str:
    """Ranked keyword search across indexed documents."""
    ...

mcp.run()  # starts stdio transport

FastMCP introspects your function signatures to generate the JSON Schema that Claude uses to understand what arguments each tool accepts. The docstring becomes the tool description shown to the model.

---

Repository Structure

mcp-demo/
├── server/
│   ├── main.py          # FastMCP server — 3 tools, ~60 lines
│   └── search.py        # TF-IDF engine — no ML dependencies
├── documents/
│   ├── python_async.md
│   ├── api_design.md
│   ├── docker_guide.md
│   ├── git_workflow.md
│   └── system_design.md
├── test_server.py                    # smoke test (no Claude needed)
├── claude_desktop_config_example.json
├── requirements.txt                  # mcp[cli]>=1.0.0
└── pyproject.toml

---

Adding Your Own Documents

Drop any .md or .txt files into documents/ and restart Claude Desktop (which restarts the server subprocess). The index rebuilds at startup.

Ideas:

• Your team's runbooks and internal docs
• Architecture decision records (ADRs)
• Personal notes exported from Notion or Obsidian
• API documentation in markdown format

---

Troubleshooting

No hammer icon in Claude Desktop

• Check the config path is correct for your OS
• Verify the cwd path is absolute and the directory exists
• Check Claude Desktop logs: ~/Library/Logs/Claude/ (macOS) or Event Viewer (Windows)

ModuleNotFoundError: No module named 'mcp'

• Make sure you installed dependencies: pip install -r requirements.txt
• If using a virtual environment, Claude Desktop needs to use the same Python: replace "command": "python" with the full path to your venv's Python

Server starts but returns no results

• Run python test_server.py to verify the search engine directly
• Check that documents/ contains .md or .txt files

Testing the server manually (without Claude Desktop)

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}' | python -m server.main

---

Going Further

• Add semantic search: replace TF-IDF with embeddings using sentence-transformers and cosine similarity for better recall on paraphrased queries
• Add resources: expose documents as MCP Resources (read-only, URI-addressed) in addition to tools — clients can subscribe to resource changes
• Add prompts: package common workflows as MCP Prompts that pre-fill Claude's context
• Connect other clients: the same server works with Cursor, Zed, or any MCP-compatible editor

Official MCP docs: https://modelcontextprotocol.io
MCP Python SDK: https://github.com/modelcontextprotocol/python-sdk