Name: 语义网关中间件
Author: codeninja

使用说明

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/

其他旗帜：

Flag	它的作用
`--dry-run`	打印计划；什么都不写。
`--force` / `-f`	覆盖同名的现有技能目录。
`--target <dir>`	完全覆盖目标根目录。
`--list-providers`	显示每个受支持的代理+它写入的路径
`--list-skills`	显示每个捆绑 `SKILL.md` （收藏+描述）。

跑步 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/<server>/<hash>/<id>/v1/SKILL.md 并加入下一次索引传递时，矢量存储中的手工编写技能。

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

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

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

CLI参考

命令	它的作用
`mcp-semantic-gateway init`	脚手架 `~/.mcp_semantic_gateway/` 使用starter配置。
`mcp-semantic-gateway index`	（重新）将每个工具、提示和技能嵌入到本地向量库中。
`mcp-semantic-gateway doctor`	验证配置、索引、身份验证环境变量、OpenAPI可达性和技能路径。退出非零，并对任何故障进行可操作的补救。
`mcp-semantic-gateway search "<query>"`	卫生检查检索。打印顶部匹配项，包括名称、来源、项目类型和相似性得分。 `--top-k`, `--type`, `--json` 可用。
`mcp-semantic-gateway proxy`	运行stdio MCP服务器。这就是你的代理人所连接的
`mcp-semantic-gateway server`	作为HTTP服务器运行（用于远程客户端）。
`mcp-semantic-gateway synth`	矿山用例+集群+综合 `SKILL.md` 选择OpenAPI源代码的包。
`mcp-semantic-gateway synth status`	显示上次运行摘要、缓存命中率、令牌支出、拒绝。
`mcp-semantic-gateway synth init-skill-source`	将生成的技能注册为 `type = "skill"` 源代码在您的配置中。
`mcp-semantic-gateway onboard <agent>`	捆绑安装 `SKILL.md` 打包到编码代理的技能目录中(`claude`, `codex`, `opencode`, `pi`).

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

建筑概览

   ┌─────────────────────────────────────────────────────────────┐
   │                      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.