universal-connector-mcp

为什么还要做一个？

大多数“通用 API” MCP 服务只支持 REST/OpenAPI。本项目围绕三大差异化优势构建：

1. 真正通用——采用标准化的 Operation 模型，并支持可插拔的规范适配器（OpenAPI、GraphQL、gRPC、SOAP）。工具和执行器无需关心操作所使用的协议。
2. 安全优先／本地优先——直接应对 AgentBaiting / FakeGit 活动等供应链攻击。出站请求仅允许访问白名单中的目标，机密信息绝不会写入日志，响应大小设有限制，且每次调用都会记录审计日志。不执行任意代码、不下载二进制文件、不进行遥测。
3. 专为提高上下文效率而构建——字段级响应筛选、链式和并行执行，以及响应缓存，让完整工作流只需一次工具调用，且响应保持精简。

工作原理

Agent 像浏览文件系统一样探索 API，而不是一次加载数百个工具（对于 Stripe 这类大型 API，这会撑爆上下文窗口）。它会搜索操作、查看所需操作，然后执行它们。

flowchart TD
    Agent["AI Agent"] -->|"MCP stdio"| Server["FastMCP Server"]
    Server --> Tools["Meta-tools"]
    Tools --> Registry["Operation Registry (normalized)"]
    Adapters["Spec Adapters"] --> Registry
    Tools --> Guard["Security Guard"]
    Guard --> Executor["Protocol Executors"]
    Executor --> Auth["Auth Manager"]
    Executor --> UpstreamAPI["Upstream API"]

元工具

为什么步骤更少，Token 也更少

按 API 拆分的 MCP 服务每次调用都需要一次工具往返，每次都会将完整的 JSON 负载写入 Agent 的上下文；而本服务可以将整个工作流整合起来：

• extract - execute(..., extract=["items.*.name", "total_count"]) 只返回指定字段，而不是数千字节的响应。* 会遍历数组中的所有项。
• 链式调用 - execute_chained 通过 ${save_as.path} 引用将步骤结果传入后续参数：一次工具调用即可完成，无需调用 N 次。
• 并行组 - 嵌套列表中的步骤会并发运行，因此“查询三个 API 并合并结果”仍只需一次调用：

execute_chained(steps=[
  [
    {"operation_id": "github.repos_get", "params": {"owner": "o", "repo": "r"},
     "save_as": "gh", "extract": ["stargazers_count"]},
    {"operation_id": "open_meteo.get_v1_forecast", "params": {"latitude": 52.5, "longitude": 13.4},
     "save_as": "weather", "extract": ["current_weather.temperature"]}
  ],
  {"operation_id": "github.issues_list_for_repo",
   "params": {"owner": "o", "repo": "r"}, "extract": ["*.title"]}
])

• 响应缓存 - 成功的 GET / 查询结果会缓存 UCMCP_CACHE_TTL 秒（默认值为 60），因此重复查询即时完成且无需额外开销；传入 fresh: true 可跳过缓存。成功的修改操作会使该 API 的缓存读取失效。

内置 API 目录

无需费力查找规范 URL。search_catalog 会搜索两个来源：

1. 精选列表，包含已验证的免费 / 热门 API：GitHub、GitLab、Stripe、OpenAI、Wikipedia、Open-Meteo（天气，无需密钥）、国家 / 地区 GraphQL API、httpbin 和 Swagger Petstore。条目包含可用的规范 URL、基础 URL 覆盖项和身份验证提示（例如“可选的 GITHUB_TOKEN”）。
2. APIs.guru 目录，包含 2,500 多个由社区索引的 OpenAPI 规范（Google、AWS、Microsoft、Twilio、NASA 等），每个会话仅获取一次，然后在本地搜索。

search_catalog(query="weather forecast")
  -> [{"name": "open_meteo", "spec": "https://...forecast.yml", "base_url": "https://api.open-meteo.com", ...}]
load_api(spec="https://...forecast.yml", name="open_meteo", base_url="https://api.open-meteo.com")
execute(operation_id="open_meteo.get_v1_forecast", params={"latitude": 52.52, "longitude": 13.41, "hourly": "temperature_2m"})

目录仅用于发现：它会返回规范 URL，但不会自行加载或执行任何内容，因此安全防护仍适用于从中加载的所有内容。

安装

该服务可通过 uvx 在任何 MCP 宿主中运行，无需手动安装；系统会自动从 PyPI 获取软件包（添加 [all] 以支持 GraphQL / gRPC / SOAP）：

{
  "mcpServers": {
    "universal-connector": {
      "command": "uvx",
      "args": ["universal-connector-mcp"],
      "env": { "UCMCP_ALLOWED_HOSTS": "api.github.com" }
    }
  }
}

从源代码安装（开发）：运行 pip install -e ".[all,dev]"，并改用 "command": "universal-connector-mcp"。可选扩展：graphql、grpc、soap、keyring、all、dev；核心安装仅支持 OpenAPI / REST。

Cursor

点击上方徽章即可一键添加，或者将 JSON 配置块添加到项目中的 .cursor/mcp.json（与团队共享）或 ~/.cursor/mcp.json（个人配置，适用于所有项目）。完整凭据配置示例请参阅 examples/mcp.json。

Claude Desktop

将相同的 mcpServers 配置块添加到 claude_desktop_config.json（Settings > Developer > Edit Config）。

Claude Code

claude mcp add universal-connector -- uvx universal-connector-mcp

VS Code（Copilot）

在 .vscode/mcp.json 的 "servers" 下添加该服务：

{
  "servers": {
    "universal-connector": { "command": "uvx", "args": ["universal-connector-mcp"] }
  }
}

Windsurf / Cline / 其他

所有主流 MCP 宿主都接受上文所示的相同 mcpServers 配置块，请将其添加到各自的配置文件中（~/.codeium/windsurf/mcp_config.json、Cline 的 MCP 设置等）。

为用户安装此服务的 AI Agent：请遵循 llms-install.md。

预加载 API

将 UCMCP_APIS_CONFIG 指向一个 YAML 文件，即可在启动时自动加载 API，详见 examples/apis.example.yaml。

在聊天中管理 API

管理 API 时无需编辑配置文件，只需告诉你的 Agent：

• “连接 Stripe API”——Agent 会在目录中找到它并加载。
• “已连接哪些 API？”——list_apis 会显示这些 API。
• “忘掉 GitHub”——unload_api 会将其移除（也会从记忆状态中移除）。

当 API 需要凭据时，load_api 会准确告知 Agent 需要设置哪个环境变量（例如 STRIPE_API_KEY）以及该变量是否已配置；Agent 会转达可直接复制粘贴的说明——你只需将变量添加到 MCP 配置的 env 块中，然后重启。绝不会在聊天中输入密钥。

会话持久化

服务会在 UCMCP_STATE_FILE 中记住你加载过的 API（仅保存其规范位置，不会保存凭据或响应数据），并在下次启动时自动恢复，让 Agent 可以从上次中断的地方继续。设置 UCMCP_STATE_FILE=off 可禁用此功能。

支持的协议

每个已加载的操作都会获得一个以 <api>.<operation> 命名空间限定的 ID（例如 github.repos_get）。

会话示例

更多演练示例（天气、带身份验证的 GitHub、GraphQL、并行多 API 工作流、内部 API）：docs/EXAMPLES.md

search_catalog(query="github")
load_api(spec="https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json", name="github")
search_operations(query="list repositories for user", api="github")
get_operation(operation_id="github.repos_list_for_user")
execute(operation_id="github.repos_list_for_user", params={"username": "torvalds"},
        extract=["*.name", "*.stargazers_count"])

使用字段选择的 GraphQL：

load_api(spec="https://countries.trevorblades.com/", protocol="graphql", name="countries")
execute(operation_id="countries.country", params={"code": "US", "fields": "name capital currency"})

链式调用（将一个结果传入下一个操作；将步骤放入嵌套列表中即可并行运行）：

execute_chained(steps=[
  {"operation_id": "github.repos_list_for_user", "params": {"username": "torvalds"}, "save_as": "repos"},
  {"operation_id": "github.repos_get", "params": {"owner": "torvalds", "repo": "${repos.data.0.name}"},
   "extract": ["description", "stargazers_count"]}
])

配置

所有设置均为以 UCMCP_ 为前缀的环境变量：

凭据会按照约定从 <API_NAME>_TOKEN、<API_NAME>_API_KEY、<API_NAME>_CLIENT_ID / <API_NAME>_CLIENT_SECRET（OAuth2 客户端凭据）等变量中查找。

开发

pip install -e ".[all,dev]"
pytest          # run the test suite
ruff check .    # lint

测试套件（60 多项测试）和 lint 会在每次推送时，于 Ubuntu 和 Windows 上使用 Python 3.10 和 3.12 在 CI 中运行（见 .github/workflows/ci.yml）；标记 v* 会通过可信发布构建并发布到 PyPI（见 .github/workflows/release.yml）。

欢迎贡献，详情请参阅 CONTRIBUTING.md。安全问题请通过私密报告渠道提交。

发布流程已自动化：标记 v* 会通过可信发布发布到 PyPI（见 docs/RELEASING.md）。

安全模型

• 出站允许列表 - 默认情况下，只能访问已明确加载的规范所对应的主机。可通过 UCMCP_ALLOWED_HOSTS / UCMCP_DENIED_HOSTS 扩展或限制访问范围。
• SSRF 防护 - 会阻止解析到私有、环回、链路本地、保留或云元数据地址的请求（包括规范获取、GraphQL 内省和 SOAP 导入）。每次重定向都会重新验证。只有在 UCMCP_ALLOWED_HOSTS 中明确添加条目，才能访问内部地址。
• 密钥处理 - 凭据来自环境变量或操作系统密钥环，仅在请求时注入，并会从审计日志和错误中删去。
• 响应上限 - 响应会截断至可配置的字节数上限，以保护上下文窗口。
• 审计日志 - 记录每次出站调用的方法、主机、路径和状态（绝不记录密钥或正文）。

许可证

MIT