MCP 服务器

MCP Learning Project

A custom MCP server providing tools for date/time, calculations, mock weather, and note management, enabling AI agents to perform these tasks via natural language.

README

MCP Learning Project

A hands-on project to learn Model Context Protocol (MCP) by building a custom MCP server, an AI agent, and a full-stack web application with semantic document search.

What is MCP?

Model Context Protocol (MCP) is an open standard that lets AI models (like Claude) call external tools and services in a structured, language-agnostic way. Think of it like USB — any tool built to the MCP standard works with any MCP-compatible AI.

Project Structure

MCP Project/
├── api.py                  — FastAPI web server (primary entry point)
├── agent.py                — CLI agent (original learning version)
├── mcp_server.py           — MCP server with 8 tools
├── database.py             — SQLite layer (notes + sessions)
├── rag.py                  — ChromaDB semantic search
├── convert_pdfs.py         — Tesseract OCR for scanned PDFs
├── inspect_db.py           — Utility to view SQLite contents
├── templates/
│   └── chat.html           — Browser chat UI
├── docs/                   — Drop your documents here
├── LEARNING_JOURNEY.md     — Full phase-by-phase learning record
└── requirements.txt

Architecture

Browser (http://localhost:8000)
  │
  │ HTTP / Server-Sent Events
  ▼
api.py (FastAPI)
  │
  ├──► Claude Sonnet 4.6 (Anthropic API)
  │         │ tool calls
  │         ▼
  └──► mcp_server.py (8 MCP Tools)
            ├──► database.py  → SQLite (notes + sessions persist across restarts)
            ├──► rag.py       → ChromaDB (semantic document search)
            └──► docs/        → your documents (txt, md, PDF)

All 8 Tools

Tool	Description
`get_current_datetime`	Current date and time
`calculate`	Safe math expression evaluator
`get_weather`	Mock weather data by city
`manage_notes`	Persistent CRUD notes (SQLite)
`list_docs`	Lists files in docs/ folder
`read_doc`	Reads full content of a document
`index_docs`	Indexes docs into ChromaDB for semantic search
`search_docs`	Semantic search — finds relevant chunks for any query

Setup

Prerequisites

Python 3.10+
An Anthropic API key (console.anthropic.com)
Tesseract OCR (for scanned PDFs): github.com/UB-Mannheim/tesseract/wiki

Install dependencies

pip install anthropic[mcp] mcp pymupdf pytesseract pypdf fastapi "uvicorn[standard]" chromadb sentence-transformers

Set your API key (one-time, permanent)

[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-...", "User")

Run the web app

$env:ANTHROPIC_API_KEY = [System.Environment]::GetEnvironmentVariable("ANTHROPIC_API_KEY", "User")
python -m uvicorn api:app --reload --port 8000

Open http://localhost:8000 in your browser.

Or run the CLI agent

python agent.py

How to Add a New Tool

Step 1 — Declare the tool in list_tools() inside mcp_server.py:

types.Tool(
    name="my_tool",
    description="What it does and WHEN Claude should use it.",
    inputSchema={"type": "object", "properties": {"param": {"type": "string"}}, "required": ["param"]},
),

Step 2 — Handle it in call_tool() inside mcp_server.py:

if name == "my_tool":
    result = do_something(arguments["param"])
    return [types.TextContent(type="text", text=result)]

Restart the server — Claude discovers the new tool automatically.

How to Add Documents

Drop .txt, .md, or .pdf files into the docs/ folder
For scanned PDFs: run python convert_pdfs.py first
Restart the server (auto-indexes on startup) or say "Re-index my documents" in chat

RAG — How Semantic Search Works

Indexing (once):
  docs/*.txt → split into ~500 char chunks → embed with all-MiniLM-L6-v2 → store in ChromaDB

Querying (every question):
  question → embed → ChromaDB similarity search → top 4 relevant chunks → Claude

This handles documents of any size — only the relevant parts are sent to Claude.

Key Concepts

Concept	File	Purpose
`@app.list_tools()`	`mcp_server.py`	Declares tools to any MCP client
`@app.call_tool()`	`mcp_server.py`	Executes tools and returns results
`lifespan`	`api.py`	Keeps MCP server alive across all HTTP requests
`StreamingResponse`	`api.py`	SSE streaming to the browser
`init_db()`	`database.py`	Creates SQLite tables on startup
`index_all()`	`rag.py`	Chunks + embeds all docs into ChromaDB
`search()`	`rag.py`	Semantic similarity search
`async_mcp_tool()`	`agent.py` / `api.py`	Bridges MCP tools to Anthropic SDK

Dependencies

Package	Purpose
`anthropic[mcp]`	Anthropic SDK + MCP integration
`mcp`	MCP protocol implementation
`fastapi`	Web framework
`uvicorn[standard]`	ASGI web server
`pypdf`	Text-based PDF extraction
`pymupdf`	PDF → image rendering for OCR
`pytesseract`	Tesseract OCR wrapper
`chromadb`	Vector database
`sentence-transformers`	Local embedding model