MCP Semantic Gateway

MCP Semantic Gateway

One gateway. Every API. Any agent.

Plug your legacy stack, your SaaS APIs, and your MCP servers into a single semantic catalog — and let agents discover the exact tools, skills, and workflows they need, on demand.

______________________________________________________________________

为什么存在

现代特工正被工具淹没。一个单一的工作空间可以扩展到GitHub， Slack，Jira，Stripe，内部计费API，您的三个OpenAPI规范 平台团队和少数MCP服务器——他们每个人都转储自己的 每次转弯时，将完整的工具列表放入模型的上下文中。结果：产生幻觉 工具调用、令人垂涎的象征性账单，以及一个看不见木头的模型 树木。

MCP语义网关是您指向所有内容的地方。 本地MCP 服务器、OpenAPI/Swagger规范，来自您的传统后端，手工编写 技能， *和* 它从您的工具目录中自动生成的技能——全部统一 在单个MCP端点后面。代理从语义上查询它： *“退款a 客户最后的订单”* 返回三个工具和工作流 实际上是这样做的，而不是400个无关的定义。

正是 通用适配器 在您现有的基础设施和现代AI堆栈之间。

______________________________________________________________________

它做的三件事

1.MCP语义工具搜索

将任何讲MCP的客户端指向网关。它从每一个地方收获工具 在您配置的上游，创建对工具的语义理解，以及 仅提供当前任务的顶级匹配项。 tools/call 请求是 将所有身份验证都透明地路由回正确的上游 机智。

2.自动生成技能和用例发现

工具描述告诉代理 *什么 createOrder 做*他们不说 *如何为客户退款*网关挖掘现实世界 用例 在...之外 您的工具编目和综合代理技能规范 SKILL.md 工作流-- 基于意图，而不是API名称。您不熟悉的传统API立即看起来 就像一个有据可查的例子。

3.传统API适应

有OpenAPI/Swagger规范吗？你完了。网关伪造实时MCP 直接来自规范的工具，处理auth和（with generate_skills = true)在它们之上生成一个技能库。连接一个15岁的孩子 在五分钟内将内部REST服务发送到LLM驱动的代理。

______________________________________________________________________

快速开始

安装

# From PyPI
pip install mcp-semantic-gateway

# Or from source with uv
gh repo clone codeninja/mcp-semantic-gateway && cd mcp-semantic-gateway
uv sync

1.初始化

mcp-semantic-gateway init

创造 ~/.mcp_semantic_gateway/ 用起动机 config.toml.

2.连接你的消息来源

编辑 ~/.mcp_semantic_gateway/config.toml:

# A native MCP server
[servers.github]
type = "mcp"
command = "npx"
args = ["@modelcontextprotocol/server-github"]

# A legacy REST API via its OpenAPI spec
[servers.billing]
type = "openapi"
url = "https://internal.example.com/openapi.json"
generate_skills = true            # opt in to skill synthesis

# A SaaS API
[servers.weather]
type = "openapi"
url = "https://api.weather.gov/openapi.json"

# (Optional) LLM provider for skill synthesis
[llm]
provider = "anthropic"            # or "openai-compatible"
model = "claude-sonnet-4-6"
api_key_env = "ANTHROPIC_API_KEY"

3.构建索引

mcp-semantic-gateway index

为每个工具在本地创建的嵌入 all-MiniLM-L6-v2。没有数据离开设备。

4.（可选）综合技能

mcp-semantic-gateway synth                  # mine + cluster + generate
mcp-semantic-gateway synth init-skill-source # register the generated skills
mcp-semantic-gateway index                   # re-index so they're searchable

对未更改的输入重新运行是免费的——缓存会吃掉它们。

5.连接您的代理

克劳德桌面/代码/任何MCP客户端：

"mcpServers": {
  "mcp-semantic-gateway": {
    "command": "mcp-semantic-gateway",
    "args": ["proxy"]
  }
}

就是这样。你的经纪人现在有四个工具-- mcp_semantic_gateway_context, find_prompts, find_skills, get_skill --上游有几百个 工具在翅膀里等着，随时准备被召唤。

______________________________________________________________________

让你的编码代理（一个命令）上车

除了原始的MCP布线，网关还提供了一个代理技能规范库 SKILL.md 教导编码代理的包 *如何使用这个东西* — 配置源、语义查询、生成技能、回馈。 单个CLI将它们放置在代理已经发现的目录中 启动时：

mcp-semantic-gateway onboard claude     # → ~/.claude/skills/
mcp-semantic-gateway onboard codex      # → ~/.agents/skills/
mcp-semantic-gateway onboard opencode   # → ~/.config/opencode/skills/
mcp-semantic-gateway onboard pi         # → ~/.pi/agent/skills/

两个系列在车轮上：

• consumer --对于代理人来说 *使用* 网关。开始，

配置源、猜测前搜索发现模式以及 技能综合管道。

• development --对于代理人（或人类） *贡献* 到

网关回购。本地设置、测试布局、发布流程和 添加新源类型的配方。

默认情况下，两个集合都已安装。过滤器 --include:

mcp-semantic-gateway onboard claude --include consumer       # end users
mcp-semantic-gateway onboard claude --include development    # contributors

项目级别（与您的回购一起提交，而不是在$HOME）：

mcp-semantic-gateway onboard codex --project   # writes to ./.agents/skills/

其他旗帜：

跑步 onboard claude 两次没有 --force 是一个安全的无行动——存在 技能目录被保留并报告为 skipped.

______________________________________________________________________

看看它在行动：Petstore演示

回购附带了完整的端到端展示 examples/petstore_chat/:

• A. 传统风格的FastAPI petstore后端 具有19个操作的OpenAPI表面。
• A. 聊天CLI 启动后端，启动网关，生成技能，

并将您放入一个可以管理商店的交互式代理中。

• 在终端中呈现实时MCP事件流，以便您可以观看每个

tools/list, find_skills，以及 tools/call 经过。

export OPENAI_API_KEY=sk-...
uv sync --dev
python examples/petstore_chat/chat.py --generate-skills

you ▸ onboard a new pet named Rex and put him up for sale
[12:04:01] → MCP tools/call  mcp_semantic_gateway_find_skills({"query": "onboard a pet"})
[12:04:01] ← 1 skill: manage-petstore-inventory
[12:04:02] → MCP tools/call  mcp_semantic_gateway_get_skill({"name": "manage-petstore-inventory"})
[12:04:03] → MCP tools/call  createPet({"name": "Rex", "status": "available"})
...

代理人有 *零* 对petstore API的先验知识。它发现 正确的技能，阅读程序，调用遗留后端的工具，并获取 工作完成了——纯粹是通过网关。

看 examples/petstore_chat/README.md 为了 完整的故障，包括如何针对Ollama、OpenRouter、vLLM运行它， 或任何其他OpenAI兼容端点。

______________________________________________________________________

技能和用例发现是如何工作的

*工具名称是错误的搜索关键字。工作流是很好的搜索关键字。*

当你设置 generate_skills = true 在源代码上运行 mcp-semantic-gateway synth，网关运行一个离线管道 将您的原始工具目录放入可发现的工作流库中。

  harvest ──► chunk ──► mine use cases ──► cluster ──► synthesize SKILL.md
     │                       │                                    │
     │                       │  one LLM call per chunk            │
     │                       │  structured output, validated      │
     │                                                            │
     └─ tools from MCP /                              one SKILL.md per cluster,
        OpenAPI / Swagger                             grounded in real tool names

1.我的。 每个工具块都交给一个发出候选的LLM *用例* --简短的陈述，如 *“退还客户最近的 订单”* --每个链接到实现它的特定工具 工具名称在进入磁盘之前会被确定地拒绝。

2.集群。 用例描述按余弦嵌入和聚类 相似性。相关意图合并成一个概念；medoid 成为集群的代表。

3.综合。 每个集群都会收到一个LLM调用，该调用会生成一个完整的 SKILL.md 包——一个名称、一个描述、一个程序体和确切的 工具依赖关系列表。三次验证通过（规范一致性、工具 接地、长度限制）门出版物。

4.指标。 生成的技能降落在 ~/.mcp_semantic_gateway/skills////v1/SKILL.md 并加入 下一次索引传递时，矢量存储中的手工编写技能。

5.缓存。 缓存密钥为 (server, source_hash, chunk_hash, model, prompt_version)针对不变的输入重新运行synth是零成本的 无操作。缓冲提示版本，只有受影响的块才能重新运行。

从代理的角度来看，结果是一个关键的工作流库 意图。 *“对陈旧问题进行分类”*, *“带上一只新宠物”*, *“结束昨天的 命令”* --人类实际上要求代理人做的事情。代理人 电话 find_skills 为了发现候选人， get_skill 阅读 程序，然后配备 *什么* 和那个 *怎么* 在此之前 触摸单个上游工具。

完整的设计说明已发布 docs/design/use-casesynthesis.md 和 文档/设计/技能生成.md.

______________________________________________________________________

CLI参考

有关端到端设置、故障排除和每个源的配方，请参阅 安装指南.

______________________________________________________________________

建筑概览

   ┌─────────────────────────────────────────────────────────────┐
   │                      Your agent                             │
   │     (Claude Desktop / Claude Code / Cursor / custom)        │
   └───────────────────────────┬─────────────────────────────────┘
                               │  stdio MCP
                               ▼
   ┌─────────────────────────────────────────────────────────────┐
   │              MCP Semantic Gateway proxy                     │
   │  ┌──────────┐   ┌───────────────────┐   ┌────────────────┐  │
   │  │ Registry │   │  Semantic search  │   │   Router       │  │
   │  │  (SQLite)│   │  (hnswlib + MiniLM│   │  tools/call →  │  │
   │  │          │   │   embeddings)     │   │  upstream      │  │
   │  └──────────┘   └───────────────────┘   └────────────────┘  │
   └─────────┬────────────────────────────────────┬──────────────┘
             │                                    │
   ┌─────────▼─────────┐  ┌─────────────────┐  ┌──▼──────────────┐
   │  Native MCP       │  │  OpenAPI /      │  │  Skill packages │
   │  servers          │  │  Swagger specs  │  │  (auto-generated│
   │  (github, slack…) │  │  (legacy APIs)  │  │ + hand-authored)│
   └───────────────────┘  └─────────────────┘  └─────────────────┘

• 本地优先。 嵌入在盒子上运行。没有遥测。无云依赖

除非 *你* 将其指向一点以进行技能综合。

• 可插拔LLM。 人类原生或任何与OpenAI兼容的端点--

OpenAI、OpenRouter、Gemini、Ollama、vLLM。

• 可观察。 每个合成阶段都会发出结构化的JSONL事件；

失败和拒绝写入您可以grep的每次运行诊断。

对于合成流水线、提示版本控制和验证门， 看 设计文档 --尤其是 使用酶合成.md 和 技能生成.md.

______________________________________________________________________

贡献

我们正在构建地球上每一个API和每一个 地球上的代理人。需要帮助：

• 搭建一个利基API。 将示例放入 /examples 展示你如何

把你的堆栈连接起来。

• 改进锻造。 帮助改进OpenAPI→ MCP转换逻辑。
• 新后端。 Chroma、pgvector、远程嵌入提供商——都是开放的。
• 告诉我们它在哪里产生幻觉。 使用查询和

目录，我们将修复检索。

# Fork, branch, hack
git checkout -b feat/your-thing

# Run the E2E suite
uv run pytest tests/test_e2e.py

# PR it

______________________________________________________________________

Built by codeninja and a custom agentic development engine.

Apache 2.0 — go build something.