AI导哈

MCP服务器构建实验室

一个实践性的指导实验室，专注于构建和调试连接AI代理与企业搜索API的MCP服务器。

  • by sojohnnysaid
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 sojohnnysaid/mcp-lab

使用说明

MCP集成实验室

一个动手操作的、由讲师指导的实验室，用于构建和调试模型上下文协议（MCP）服务器，该服务器将人工智能代理连接到模拟企业搜索API。

你将学到什么

  • MCP基础 --客户端-服务器架构、工具发现、JSON-RPC和stdio传输
  • 构建MCP服务器 --实施a kb_search(query, top_k) 使用Python SDK（FastMCP）的工具
  • 验证有根据的答案 --确认结果包括引用、相关性得分和权限边界
  • 排除集成故障 --使用MCP检查器隔离客户端、服务器和端点层的故障

建筑

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌──────────────────┐
│   AGENT     │───>│ MCP Client  │───>│ MCP Server  │───>│ Mock Search API  │
│  User prompt│    │ Tool        │    │ kb_search() │    │ HTTP endpoint    │
│  LLM reason │    │ discovery   │    │ Schema +    │    │ Ranked results   │
│             │    │ JSON-RPC    │    │ trust       │    │                  │
└─────────────┘    └─────────────┘    └─────────────┘    └──────────────────┘

MCP服务器公开了一个 kb_search 查询本地模拟企业搜索API的工具（涉及3个主题的8个文档：续订、入职和安全）。结果包括相关性得分、引用和ACL权限组。

先决条件

组件 所需版本 检查命令
Python 3.12+ python3.12 --version
Node.js 18+ node --version
npm/npx 9+ npx --version

快速开始

1.设置

cd mcp-lab
bash setup.sh

这将安装依赖关系，预缓存MCP检查器，并运行3个端到端验证测试。所有3个都应该显示 通过.

2.启动模拟搜索API

python3.12 mock_search_api.py

3.卷曲测试（在第二个端子中）

curl -s "http://localhost:8080/search?q=renewal+process&top_k=3" | python3 -m json.tool

4.通过MCP检查器发现工具

npx @modelcontextprotocol/inspector --cli \
  --config inspector-config.json \
  --server enterprise-search \
  --method tools/list

5.通过MCP调用工具

npx @modelcontextprotocol/inspector --cli \
  --config inspector-config.json \
  --server enterprise-search \
  --method tools/call \
  --tool-name kb_search \
  --tool-arg 'query=What is our Q4 renewal process' \
  --tool-arg 'top_k=3'

文件结构

mcp-lab/
├── server.py               # MCP server with kb_search tool (stdio transport)
├── mock_search_api.py       # Mock enterprise search API (local HTTP on port 8080)
├── lambda_function.py       # Same search logic packaged for AWS Lambda (reference)
├── inspector-config.json    # MCP Inspector config for CLI mode
├── setup.sh                 # One-command setup + validation
├── teardown.sh              # Kill all running processes + clean temp files
├── reset-lab.sh             # Teardown + setup (between lab sessions)
├── 00-PRE-SETUP-GUIDE.md    # Facilitator pre-setup instructions
├── 01-LAB-GUIDE.md          # Learner-facing lab guide (7 sections)
└── TALK-TRACK.md            # Full presenter talk track with timing

实验室部分

# 节 持续时间
1 客户故事和架构 ~8分钟
2 环境验证 ~5分钟
3 探索模拟搜索API ~15分钟
4 构建MCP服务器 ~15分钟
5 端到端查询验证 ~15分钟
6 故障排除和调试 ~12分钟
7 客户定位总结 ~10分钟

总计：60-90分钟

故障排除

问题 症状 修复
端点URL错误 工具调用失败，出现连接错误 请更正 ENDPOINT 在 server.py
stdout损坏 服务器随机中断 确保所有 print() 通话使用 file=sys.stderr
Mock API未运行 连接被拒绝 启动它： python3.12 mock_search_api.py
端口8080正在使用 地址已在使用中 pkill -f mock_search_api; sleep 2; python3.12 mock_search_api.py
一切都坏了 多次失败 bash reset-lab.sh

生产注意事项

为了简单起见，该实验室使用stdio传输和本地HTTP服务器。对于生产部署，请添加：

  • OAuth 2.1授权 对于MCP传输
  • 可流式HTTP传输 而不是stdio（支持多个客户端）
  • 源标头验证 用于HTTP传输
  • 最小权限工具范围 --代理只看到他们需要的工具
  • HTTPS端点 -Lambda函数URL或API网关，而不是本地主机
  • 快速注射控制 --工具边界处的输入验证

许可证

麻省理工学院

相关 MCP