MCP上下文锻造大师班
概述
这 MCP上下文锻造大师班 是一个完整的、从零到英雄的建筑工作室 受控、生产级代理AI 随着 模型上下文协议(MCP)网关.
什么是MCP上下文锻造?\
这是一个政策和连接层 代理商/客户 和 工具/数据。您无需将每个代理直接连接到数十个API,而是可以集中:
- 工具注册和发现 (MCP服务器、REST适配器、包装器)
- 护栏 (RBAC、速率限制、机密/PII过滤器、模式保护)
- 可观测性 (结构化日志、关联ID、OTEL跟踪)
- 治理 (代表租赁,审计准备就绪)
到最后,您将:
- 跑吧 MCP上下文锻造 本地(也可选择通过Docker Compose)
- 注册和 联邦成员工具 来自MCP服务器和REST适配器
- 执行 护栏 在边缘
- 捕捉 可观测性 随着 凤凰
- 船a 顶点石一 船员AI 代理人消费a 郎福 工具 通过网关
- (奖金)建立一个 Docling+IBM沃森人工智能 网关背后的RAG聊天机器人
完整文档(MkDocs):
make docs-serve → open http://127.0.0.1:8000\
代码之旅 src/: 看见 src/README.md
目录
- MCP上下文锻造大师班
- 概述
- 目录
- 先决条件
- 快速入门
- A) Makefile+uv(推荐)
- B) Docker Compose(一次完成所有任务)
- C) 手册(无Docker)
- 运行工作坊
- 第一天实验室
- 第2天拱顶石
- 额外奖励:通过MCP Context Forge进行Docling+IBM watsonx.ai RAG
- 1) 安装和环境
- 2) 启动Docling MCP服务器
- 3) 向网关注册
- 4) 通过网关聊天(无法直接访问Docling)
- 配置和环境
- 可观测性(凤凰城+OTEL)
- 项目布局
- 生成文件目标
- 故障排除
- 贡献
- 许可证
- 致谢
先决条件
- Python 3.11+
- 版本控制系统, 卷曲, jq
- 码头工人 & Docker Compose (可选但推荐)
- (可选) VS Code + 开发容器 一键式设置
快速入门
A) Makefile+uv(推荐)
> Makefile使用 紫外线 创建/同步虚拟环境并运行工具,而不会污染您的全局Python。```bash
1) Create the environment and install deps (installs uv if missing)
make install
2) Serve docs locally (optional)
make docs-serve
3) Build docs in strict mode (optional)
make docs-build
启动网关(选择一个):```bash
# Option 1: Use your own gateway binary
mcpgateway --host 0.0.0.0 --port 4444
# Option 2: Use Docker Compose service (see below)
docker compose up -d gateway
生成一个演示JWT并将其放在手边:```bash
make token
prints a token — export it for later use
export TOKEN="$(make token | tail -n 1)"
### B) Docker Compose(一次完成所有任务)
提出 **郎福**, **适配器**,(可选) **代理**, **网关**,以及 **凤凰**:```bash
docker compose up -d
docker compose ps
- 郎福: http://localhost:7860
- 网关: http://localhost:4444/health
- 凤凰: http://localhost:6006
> 你仍然需要一个 JWT公司 调用受保护的端点。使用 make token 或 scripts/create_jwt.py.
C) 手册(无Docker)```bash
venv + gateway (if you want to run the gateway locally)
python3 -m venv .venv && source .venv/bin/activate
pip install -U mcp-contextforge-gateway
mcpgateway --host 0.0.0.0 --port 4444
Adapter (for the capstone)
pip install -U fastapi uvicorn requests
uvicorn src.mcpws.adapters.langflow_adapter:app --port 9100
注册适配器:```bash
export BASE_URL=http://localhost:4444
export TOKEN= # from `make token` or your gateway’s jwt tool
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name":"langflow","url":"http://localhost:9100","enabled":true,"request_type":"STREAMABLEHTTP"}' \
$BASE_URL/gateways | jq '.'
运行工作坊
第一天实验室
-
实验室0 –环境检查
-
实验1 –网关+健康检查
-
实验2 –第一台MCP服务器: 计算器 (
calc.add)```bash
uv run -- uvicorn src.mcpws.servers.calculator_server:app --port 9100
- **实验3** –客户端和CLI
- **实验4** –包装/传递: **httpbin** (`httpbin.get`)```bash
uv run -- uvicorn src.mcpws.servers.httpbin_wrapper:app --port 9200
- 实验5 –护栏:启用 速率限制器 并挑衅 429
> 所有CLI、curl示例、策略和屏幕截图都在文档网站上。
> 有关每个文件夹、每个实验室的代码指针和确切命令,请参阅 src/README.md.
第2天拱顶石
- 建立一个 郎福 汇总流程(文本在→ 总结出来)
- 跑吧 适配器:暴露
lf.summarize作为MCP工具 - 注册 网关
- 跑吧 船员AI 调用网关工具的代理
- 打开 基于角色的访问控制, 秘密检测,以及 追踪收集证据
最小端到端(无Docker):```bash
Langflow (build your flow at :7860)
pip install -U langflow
langflow run --host 0.0.0.0 --port 7860
Adapter
uv run -- uvicorn src.mcpws.adapters.langflow_adapter:app --port 9100
Register & verify
make seed
curl -s -H "Authorization: Bearer $TOKEN" http://localhost:4444/tools | jq '.[] | {name, gateway: .gatewaySlug}'
Agent
uv run -- python -m src.mcpws.agents.crew_agent
______________________________________________________________________
## 额外奖励:通过MCP Context Forge进行Docling+IBM watsonx.ai RAG
本附录将真实世界的PDF/图像转换为 **多模式RAG聊天机器人**--完全由Gateway管理。
**为什么叫Docling?**
它将杂乱的文档(PDF、Office文件、扫描图像)转换为干净、结构化的文本(和可选图像),保留标题/表格并启用多模式上下文。
### 1) 安装和环境```bash
uv run --with "docling" \
--with "ibm-generative-ai" \
--with "chromadb" \
--with "sentence-transformers" \
--with "python-multipart" \
--with "pydantic" \
--with "fastapi" \
--with "uvicorn" -- python -c "print('deps ready')"
设置watsonx.ai变量(或使用本地嵌入 USE_LOCAL_EMBEDDINGS=1):```bash
export WATSONX_API_KEY=""
export WATSONX_PROJECT_ID=""
export WATSONX_URL="https://us-south.ml.cloud.ibm.com"
export WATSONX_EMBED_MODEL="sentence-transformers/all-minilm-l6-v2"
export WATSONX_LLM_MODEL="meta-llama/llama-4-scout-17b-16e-instruct"
Local dev fallback (no IBM key needed)
export USE_LOCAL_EMBEDDINGS=1
### 2) 启动Docling MCP服务器
服务器公开了三个工具: `docling.parse`, `docling.ingest`, `docling.query`.```bash
uv run -- uvicorn src.mcpws.servers.docling_mcp_server:app --host 0.0.0.0 --port 9200
烟雾测试:```bash
Parse single file
curl -s -F return_images=false -F file=@/path/to/file.pdf \
http://localhost:9200/call/docling.parse | jq '.text | length'
Ingest multiple
curl -s -F files=@one.pdf -F files=@two.pdf \
-F metas='{"tenant":"acme"}' \
http://localhost:9200/call/docling.ingest | jq .
Query
curl -s -H 'Content-Type: application/json' \
-d '{"query":"What is the warranty period?","k":4}' \
http://localhost:9200/call/docling.query | jq .
### 3) 向网关注册```bash
export BASE_URL=http://localhost:4444
export TOKEN=$TOKEN # from `make token`
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"name": "docling",
"url": "http://localhost:9200",
"description": "Docling RAG Server",
"enabled": true,
"request_type": "STREAMABLEHTTP"
}' \
$BASE_URL/gateways | jq '.'
curl -s -H "Authorization: Bearer $TOKEN" $BASE_URL/tools | jq '.[] | {name, gateway: .gatewaySlug}'
4) 通过网关聊天(无法直接访问Docling)```bash
Simple gateway client
uv run -- python -m src.mcpws.tools.chat_rag_client
Env it uses:
GATEWAY_URL (default http://localhost:4444)
GATEWAY_TOKEN (your JWT)
您应该看到一个可靠的答案和源元数据。
对于一个 **能动性** 变体,运行:```bash
uv run -- python -m src.mcpws.agents.crew_agent_docling
> 策略延续:速率限制、秘密检测和RBAC可以限制 docling.* 具体角色。
> Phoenix traces:设置OTEL变量(见下文)并在聊天时浏览跨度。
配置和环境
网关策略 (你可以改编的例子):
configs/gateway/plugins.yaml– 速率限制器 & 秘密检测configs/gateway/rbac.yaml–角色→ 允许的工具configs/gateway/well-known.env–robots.txt、security.txt等。
适配器设置 (郎福):
-
configs/adapters/langflow_adapter.env -
LANGFLOW_URL=http://langflow:7860/api/v1/run/ TIMEOUT=60LOG_LEVEL=INFO
代币 (HS256):```bash
Print a JWT
make token
or:
uv run --with pyjwt -- python scripts/create_jwt.py --sub analyst@example.com --role analyst --secret dev-secret --exp 120
**RBAC烟雾测试**:```bash
# Analyst (allowed)
export TOKEN=$(uv run --with pyjwt -- python scripts/create_jwt.py --sub analyst@example.com --role analyst --secret dev-secret --exp 60)
# Viewer (blocked)
export TOKEN_VIEWER=$(uv run --with pyjwt -- python scripts/create_jwt.py --sub viewer@example.com --role viewer --secret dev-secret --exp 60)
可观测性(凤凰城+OTEL)
提出 凤凰:```bash
docker compose up -d phoenix
为网关设置OTEL:```bash
export OTEL_ENABLE_OBSERVABILITY=true
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
发送带有相关ID的跟踪请求:```bash
uv run -- python -m src.mcpws.tools.trace_probe
Open Phoenix at http://localhost:6006
______________________________________________________________________
## 项目布局```
.
├── docker/ # Dockerfiles (adapter, agent, base python)
├── docker-compose.yml # Langflow, adapter, agent, gateway, Phoenix
├── configs/ # Gateway + adapter environment/policies
│ ├── adapters/
│ └── gateway/
├── examples/ # JSON schema, sample policies, sample logs
├── scripts/ # Bootstrap, JWT, seeding
├── src/
│ └── mcpws/ # All workshop code (servers, adapters, agents, tools)
│ ├── servers/ # calculator, httpbin wrapper, docling RAG server
│ ├── adapters/ # langflow_adapter.py
│ ├── agents/ # crew_agent.py, crew_agent_docling.py
│ ├── tools/ # gateway tool, probes, chat_rag_client
│ └── utils/ # gateway_client, logging helper
└── docs/ # MkDocs site (workshop book + solutions)
➡️ 详细的、逐个实验室的操作手册,适用于以下所有内容 src/: src/README.md
生成文件目标
| 目标 | 它做什么 |
|---|---|
make install |
确保Python≥3.11(如果缺少自动安装),创建/同步 .venv 随着 紫外线 |
make update |
重新解析和同步依赖关系 |
make docs-serve |
在本地提供MkDocs |
make docs-build |
使用构建文档 --strict |
make token |
打印演示JWT(HS256) |
make up / make down |
docker compose up -d / docker compose down -v |
make seed |
向网关注册适配器(scripts/seed_gateway.sh) |
make lint / make format / make test |
QA工作流程 紫外线运行 |
故障排除
-
429请求太多
你碰到了限速器。调整configs/gateway/plugins.yaml或后退。 -
403禁止
你的代币role不允许。看configs/gateway/rbac.yaml和那个role在JWT中提出索赔。 -
适配器显示502
检查上游(Langflow URL/流ID)。使用src/mcpws/tools/probe_langflow.py以验证。 -
文档查询返回空
验证摄入是否有效(寻找chunks > 0).如果使用watsonx.ai,请确保 型号ID 匹配您的帐户。 -
凤凰城没有痕迹
确保OTEL环境变量已设置,Phoenix正在监听:4317。在启用OTEL的情况下重新启动网关。 -
端口已在使用中
冲突:4444(网关)、7860(Langflow)、9100/9200(适配器)、6006/4317(Phoenix)。 -
视窗
使用 Git Bash 或 WSL 为了make依赖Bash脚本的目标。
贡献
欢迎发布问题和PR。请包括:
- 重现步骤
- 预期行为与实际行为
- 建议的更改或修复
我们使用 MkDocs 对于文档和 紫外线 适用于Python环境;为学生保留可粘贴的示例。
许可证
发布于 阿帕奇-2.0。参见 许可证.
致谢
由...创建 鲁斯兰 马格纳.
如果这有助于你运送更安全、更可控的代理AI,请与你的团队分享💙
感谢 国际商业机器公司 社区和团队使这项工作成为可能。特别感谢 米哈伊·克里维蒂 在MCP Context Forge和 彼得·斯塔尔 对于周围的领导 Docling.
