使用说明
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
目录
先决条件
- Python 3.11+
- 版本控制系统, 卷曲, jq
- 码头工人 & Docker Compose （可选但推荐）
- （可选） VS Code + 开发容器 一键式设置
快速入门
A） Makefile+uv（推荐）
Makefile使用 紫外线 创建/同步虚拟环境并运行工具，而不会污染您的全局Python。
# 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
启动网关（选择一个）：
# 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并将其放在手边：
make token
# prints a token — export it for later use
export TOKEN="$(make token | tail -n 1)"
B） Docker Compose（一次完成所有任务）
提出 郎福, 适配器，（可选） 代理, 网关，以及 凤凰:
docker compose up -d
docker compose ps
你仍然需要一个 JWT公司 调用受保护的端点。使用
make token或scripts/create_jwt.py.
C） 手册（无Docker）
# 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
注册适配器：
export BASE_URL=http://localhost:4444
export TOKEN=<bearer-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)uv run -- uvicorn src.mcpws.servers.calculator_server:app --port 9100 -
实验3 –客户端和CLI
-
实验4 –包装/传递： httpbin (
httpbin.get)uv run -- uvicorn src.mcpws.servers.httpbin_wrapper:app --port 9200 -
实验5 –护栏：启用 速率限制器 并挑衅 429
所有CLI、curl示例、策略和屏幕截图都在文档网站上。 有关每个文件夹、每个实验室的代码指针和确切命令，请参阅
src/README.md.
第2天拱顶石
- 建立一个 郎福 汇总流程（文本在→ 总结出来）
- 跑吧 适配器：暴露
lf.summarize作为MCP工具 - 注册 网关
- 跑吧 船员AI 调用网关工具的代理
- 打开 基于角色的访问控制, 秘密检测，以及 追踪收集证据
最小端到端（无Docker）：
# 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） 安装和环境
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):
export WATSONX_API_KEY="<your-ibm-cloud-api-key>"
export WATSONX_PROJECT_ID="<your-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.
uv run -- uvicorn src.mcpws.servers.docling_mcp_server:app --host 0.0.0.0 --port 9200
烟雾测试：
# 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） 向网关注册
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）
# 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)
您应该看到一个可靠的答案和源元数据。 对于一个 能动性 变体，运行：
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.envLANGFLOW_URL=http://langflow:7860/api/v1/run/<flow_id>TIMEOUT=60LOG_LEVEL=INFO
代币 （HS256）：
# 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烟雾测试:
# 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）
提出 凤凰:
docker compose up -d phoenix
为网关设置OTEL：
export OTEL_ENABLE_OBSERVABILITY=true
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
发送带有相关ID的跟踪请求：
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.
