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 sync1.初始化
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 | 完全覆盖目标根目录。 |
--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-skillsyou ▸ 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 names1.我的。 每个工具块都交给一个发出候选的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参考
| 命令 | 它的作用 |
|---|---|
mcp-semantic-gateway init | 脚手架 ~/.mcp_semantic_gateway/ 使用starter配置。 |
mcp-semantic-gateway index | （重新）将每个工具、提示和技能嵌入到本地向量库中。 |
mcp-semantic-gateway doctor | 验证配置、索引、身份验证环境变量、OpenAPI可达性和技能路径。退出非零，并对任何故障进行可操作的补救。 |
mcp-semantic-gateway search "" | 卫生检查检索。打印顶部匹配项，包括名称、来源、项目类型和相似性得分。 --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 | 捆绑安装 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.