使用说明

MCP学习入门-完整指南

A. 动手、生产就绪的MCP（模型上下文协议）学习库 它教你如何：

从头开始构建MCP服务器（基于stdio的NDJSON+异步TCP选项）
创建一个HTTP适配器，将LLM（如Claude通过Copilot）桥接到MCP工具
为函数调用集成添加模式导出器
开发VS代码扩展以与MCP交互
专业地编写测试和结构项目

🚀 快速开始

1. 设置您的环境

cd /Users/ashc/Code/MCP\ Learn
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. 运行Canonical MCP服务器

cd project
python -u src/server.py

在另一个终端中，启动客户端：

cd project
python src/client.py

3. 启动HTTP适配器

export MCP_ADAPTER_TOKEN="your-secret-token"  # optional
python project/src/adapter.py

从任何HTTP客户端调用适配器：

curl -X POST http://127.0.0.1:5000/call-tool \
  -H "Authorization: Bearer your-secret-token" \
  -H "Content-Type: application/json" \
  -d '{"tool": "get_time", "args": {}}'

4. 运行测试

make test

或手动：

python -m unittest discover -s project/tests -p "test_*.py" -v

5. 跑林婷

make lint

📁 存储库结构

MCP Learn/
├── project/                    # ⭐ Canonical learning code
│   ├── src/
│   │   ├── server.py          # NDJSON-over-stdio MCP server
│   │   ├── adapter.py         # HTTP adapter (spawns stdio server)
│   │   ├── async_server.py    # Asyncio TCP alternative
│   │   ├── client.py          # Demo client
│   │   └── schema_exporter.py # Export tools schema for LLMs
│   ├── tests/
│   │   ├── test_mcp.py        # Integration tests
│   │   └── test_adapter_auth.py # Auth validation tests
│   └── docs/
│       ├── ARCHITECTURE.md
│       ├── PROTOCOL.md
│       └── ...
│
├── tools/
│   └── vscode-extension/       # VS Code extension for MCP
│       ├── extension.js
│       ├── package.json
│       ├── src/
│       ├── webview/
│       └── ...
│
├── legacy/
│   ├── .old-root/             # Old root-level files (archived)
│   └── old-tests/             # Old test files (archived)
│
├── integrations/              # Integration examples
├── scripts/                   # Utility scripts
│
├── Makefile                   # Build & test tasks
├── requirements.txt           # Python dependencies
├── .gitignore
├── .github/
│   └── workflows/
│       └── python-ci.yml      # CI/CD pipeline
│
├── CODE_EXPLAINED.md          # Deep-dive documentation
├── LEARNING.md                # Step-by-step lessons
├── SECURITY_CHECKLIST.md      # Security best practices
└── CONNECT_MCP_TO_COPILOT.md  # LLM integration guide

📚 学习路径

第一阶段：基础（从这里开始）

运行规范服务器和客户端
学习项目/src/server.py --协议实施
了解工具注册表和消息处理

第二阶段：高级

阅读 CODE_EXPLAINED.md --详细的代码演练
探索 project/src/adapter.py --HTTP适配器和身份验证
学习项目/src/async_server.py --异步替代方案
审查项目/测试/ --测试模式

第三阶段：整合

阅读 CONNECT_MCP_TO_COPILOT.md
使用导出工具模式 schema_exporter.py
通过HTTP适配器与LLM集成
设置承载令牌身份验证

第4阶段：扩展和部署

探索工具/vcode扩展/ --VS代码集成
审查安全性_CHECKLIST.md --生产硬化
使用您自己的工具扩展服务器
在您的环境中部署适配器

🛠️ 可用命令

# Build / Run
make test          # Run all tests
make lint          # Check code style (flake8)
make package-extension  # Package the VS Code extension

# Manual runs
python -u project/src/server.py          # Start stdio server
python project/src/client.py             # Run demo client
python project/src/adapter.py            # Start HTTP adapter
python project/src/schema_exporter.py    # Export tool schemas
python -m pytest project/tests/ -v       # Run tests with pytest

🔐 主要特点

✅ 标准设计

Stdlib优先Python（核心服务器无外部依赖）
基于stdio传输的NDJSON（符合MCP规范）
异步TCP在高性能场景中的替代方案

✅ 超文本传输协议适配器

桥梁LLMs→ MCP通过简单的REST API
承载令牌身份验证
子流程管理，并进行适当的清理

✅ 教育的

注释良好的源代码
每个模块的课程文档 project/docs/
集成测试示例
CI/CD工作流（.github/works/）

✅ 生产准备就绪

类型提示和参数验证
错误处理和日志
包括安全检查表
Git工作流（分支+PR就绪）

🎯 用例

1.学习MCP内部

# Start the server, send raw NDJSON messages
python -u project/src/server.py < /dev/stdin
# Manually craft JSON messages to understand the protocol

2.与Claude集成（通过HTTP适配器）

# Start the adapter with auth
export MCP_ADAPTER_TOKEN="my-secret"
python project/src/adapter.py

# Use with OpenAI client or similar (POST to /call-tool)

3.使用自定义工具进行扩展

编辑 project/src/server.py 并使用添加工具 @tool 装饰师：

@tool
def my_custom_tool(arg1: str, arg2: int = 42):
    """A tool that does something useful."""
    return {"result": f"Processed {arg1} with {arg2}"}

4.开发VS代码扩展

看工具/vcode扩展/README.md 用于扩展开发。

🧪 测试

所有测试都在CI管道和本地运行：

# Run all tests
python -m unittest discover -s project/tests -p "test_*.py" -v

# Run specific test file
python -m unittest project.tests.test_adapter_auth -v

# Run with coverage
python -m pytest project/tests/ --cov=project/src

测试文件：

project/tests/test_mcp.py --集成测试（服务器+客户端握手）
project/tests/test_adapter_auth.py --承载令牌身份验证

📖 文档

文件	目的
学习.md	概述和学习进展
CODE_EXPLAINED.md	深入代码演练
CONNECT_MCP_TO_COPILOT.md	LLM+适配器集成
安全性_CHECKLIST.md	生产硬化
项目/文档/	每模块课程

🔄 工作流程

代码更改 → 测试在本地通过
推送到功能分支 → CI运行（测试+lint）
创建PR → 审查与合并
部署适配器 → 与LLM集成

📋 需求

Python 3.7+
sqlite3（包含在Python中）
VS代码（可选，用于扩展）
Node.js 14+（仅用于扩展打包）

通过安装 requirements.txt:

flake8 （林）

🎓 后续步骤

→ 首先运行测试： make test
→ 然后运行服务器： python -u project/src/server.py
→ 然后运行客户端： python project/src/client.py
→ 探索代码： 看项目/src/ 和项目/文档/
→ 与LLM集成： 使用HTTP适配器（请参阅CONNECT_MCP_TO_COPILOT.md）

快乐学习！ 🚀