MCP Semantic Gateway

MCP搜索检索

提供方 codeninja

搜索检索 stdio · 本地进程 无需鉴权 社区 / 第三方 Claude DesktopClaudeCursor
查看接入方式

MCP语义网关是一个中间件,用于将传统堆栈、SaaS API和MCP服务器集成到一个统一的语义目录中,使代理能够按需发现所需的工具、技能和工作流。

一句话选型结论

按资料字段整理

MCP Semantic Gateway 属于搜索检索类 MCP 服务器,stdio · 本地进程,无需鉴权,可直接接入 Claude Desktop、Claude、Cursor,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类搜索检索 传输方式stdio · 本地进程 鉴权无需鉴权 部署方式本地部署
GitHub 星标 4 仓库热度,无公开仓库时显示未标注
工具数 4 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

搜索检索
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量4暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

语义搜索Python本地部署API集成工具发现工作流生成中间件

安装与配置

stdio · 本地进程 无需鉴权
客户端在本机拉起子进程,数据不出本机
pip install mcp-semantic-gateway

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Node.js 等运行时,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 4 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
联网搜索取证

让模型查最新资料并给出出处。

资料聚合

把一个主题的网页、文档集中抓回来整理。

情报与竞品检索

按关键词持续检索行业动态和竞品信息。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 4 个工具,职责相对集中,接入后不容易误操作。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude、Cursor,换客户端不用重新研究配置。
  • 资料标注无需鉴权,装好就能连。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在搜索检索场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
MCP Semantic Gateway当前 4 stdio · 本地进程 本地部署 有 2026-05-17
Brave Search 433812ff 2 未标注 未标注 无 2026-05-17
Sequentialthinking 1 SSE · 服务端推送 远程部署 有 2026-05-18
Baidu Netdisk 未标注 未标注 未标注 无 2026-05-17
ragflow 未标注 stdio · 本地进程 本地部署 有 2026-04-11
mindsdb (430e18) 未标注 未标注 未标注 有 2026-05-17

服务器档案

搜索检索
字段来自项目仓库与公开索引,中文说明由本站标注
提供方codeninja上游标注的维护方 codeninja
分类搜索检索本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式无需鉴权远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

14.6 KB
来自项目仓库与上游目录的原文,未做删改

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驱动的代理。


快速开始

安装```bash

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.初始化```bash
mcp-semantic-gateway init

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

2.连接你的消息来源

编辑 ~/.mcp_semantic_gateway/config.toml:```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.构建索引```bash
mcp-semantic-gateway index

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

4.(可选)综合技能```bash

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客户端:**```json
"mcpServers": {
"mcp-semantic-gateway": {
"command": "mcp-semantic-gateway",
"args": ["proxy"]
}
}

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


让你的编码代理(一个命令)上车

除了原始的MCP布线,网关还提供了一个代理技能规范库
SKILL.md 教导编码代理的包 如何使用这个东西 —
配置源、语义查询、生成技能、回馈。
单个CLI将它们放置在代理已经发现的目录中
启动时:```bash
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`:```bash
mcp-semantic-gateway onboard claude --include consumer       # end users
mcp-semantic-gateway onboard claude --include development    # contributors

项目级别(与您的回购一起提交,而不是在$HOME):```bash
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` 经过。```bash
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参考

|命令|它的作用|
|---|---|
| `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、远程嵌入提供商——都是开放的。
  • 告诉我们它在哪里产生幻觉。 使用查询和
    目录,我们将修复检索。```bash

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.

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
MCP Semantic Gateway 怎么安装?

在客户端按下面的安装命令接入:pip install mcp-semantic-gateway。装完在客户端配置里引用同一个包或端点。

MCP Semantic Gateway 怎么在 Claude Desktop、Claude、Cursor 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

MCP Semantic Gateway 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

MCP Semantic Gateway 需要 API Key 吗?

资料标注为无需认证,装好就能连;如果实际调用时报鉴权错误,按官方文档补上凭据。

MCP Semantic Gateway 支持哪些客户端?

资料标注支持 Claude Desktop、Claude、Cursor;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

MCP Semantic Gateway 能提供哪些能力?

资料显示约 4 个工具;能力标签包括 搜索、工具发现、Python、Claude。具体工具清单以官方文档为准。

MCP Semantic Gateway 需要什么运行环境?

属于本地进程,需要在本机装好运行环境。

MCP Semantic Gateway 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。