MCP Gateway Workshop

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（推荐） - - - 运行工作坊 - 第一天实验室 - 第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。

# 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

• 郎福： http://localhost:7860
• 网关： http://localhost:4444/health
• 凤凰： http://localhost:6006

你仍然需要一个 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=  # 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=""
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.

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.env

- LANGFLOW_URL=http://langflow:7860/api/v1/run/ - TIMEOUT=60 - LOG_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

______________________________________________________________________

生成文件目标

______________________________________________________________________

故障排除

• 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.