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

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

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

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

Windows example:
```json
{
  "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:

```python
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)**
```bash
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