内容
<!-- mcp-name: io.github.TeodorMCP/universal-connector-mcp -->
<div align="center">
# 通用 API 连接器 MCP
### 任意 API，一个 MCP 服务器
停止为每个服务安装一个新的 MCP 服务器：将此服务器指向任何 OpenAPI/Swagger、GraphQL、gRPC 或 SOAP 规范 - 或从内置的 **2500+ 公共 API** 目录中选择一个 - 您的 AI 代理可以调用它。安全地，步骤更少，令牌更少。
[](https://github.com/TeodorMCP/universal-connector-mcp/actions)
[](https://pypi.org/project/universal-connector-mcp/)
[](pyproject.toml)
[](LICENSE)
[](cursor://anysphere.cursor-deeplink/mcp/install?name=universal-connector&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJ1bml2ZXJzYWwtY29ubmVjdG9yLW1jcCJdfQ==)
[安装](#installation) · [元工具](#meta-tools) · [API 目录](#built-in-api-catalog) · [示例](#example-session) · [配置](#configuration) · [安全模型](#security-model)
</div>
## 为什么又是另一个？
大多数“通用 API”MCP 服务器只支持 REST/OpenAPI。本项目围绕三个差异化优势构建：
1. **真正通用** - 一个规范化的 `Operation` 模型，带有可插拔的规范适配器（OpenAPI、GraphQL、gRPC、SOAP）。工具和执行器永远不会关心哪个协议产生了操作。
2. **安全第一/本地优先** - 对供应链攻击（如 *AgentBaiting / FakeGit* 活动）的直接响应。出站请求被限制在允许列表中，秘密从不触及日志，响应被限制大小，并且每个调用都被审计记录。没有任意代码执行，没有二进制下载，没有遥测。
3. **为上下文效率而构建** - 字段级响应过滤、链式和并行执行以及响应缓存意味着整个工作流都可以在一个工具调用中完成，并且响应保持较小。
## 它是如何工作的
代理探索 API 就像文件系统一样，而不是一次加载数百个工具（这将会在大型 API（如 Stripe）上炸毁上下文窗口）。它搜索操作，检查所需的操作，然后执行它们。
<details>
<summary>架构（点击展开）</summary>
```mermaid
flowchart TD
Agent["AI 代理"] -->|"MCP 标准输入输出"| Server["FastMCP 服务器"]
Server --> Tools["元工具"]
Tools --> Registry["操作注册表（规范化）"]
Adapters["规范适配器"] --> Registry
Tools --> Guard["安全防护"]
Guard --> Executor["协议执行器"]
Executor --> Auth["身份验证管理器"]
Executor --> UpstreamAPI["上游 API"]
```
</details>
## 元工具
| 工具 | 用途 |
| --- | --- |
| `search_catalog` | 查找现成的公共 API（精选列表 + APIs.guru 目录，2500+ 规范） |
| `load_api` | 从规范 URL/文件注册 API（自动检测协议） |
| `list_apis` | 列出已加载的 API |
| `search_operations` | 跨已加载的 API 模糊搜索操作 |
| `get_operation` | 获取一个操作的完整参数/响应模式 |
| `execute` | 调用操作（应用身份验证 + 安全防护）；`extract` 只返回您要求的字段 |
| `execute_chained` | 在一个调用中运行一系列操作，将结果从一个步骤传递到下一个步骤；嵌套列表并行运行 |
| `execute_graph` | 运行操作依赖图；顺序由 `${id.path}` 引用推断，独立节点自动并行运行 |
| `unload_api` | 删除已加载的 API |
| `audit_log` | 最近的出站调用（方法、主机、路径、状态） |
## 为什么更少的步骤（和更少的令牌）
对于每个 API 的 MCP 服务器，需要一个工具往返调用 - 每个调用都返回一个完整的 JSON 有效载荷到代理的上下文中 - 而此服务器则将整个工作流压缩：
- **`extract`** - `execute(..., extract=["items.*.name", "total_count"])` 只返回那些字段而不是多千字节的响应。`*` 扩展到数组上。
- **链式** - `execute_chained` 将步骤结果通过 `${save_as.path}` 引用传递到后续参数中：一个工具调用代替 N 个。
- **并行组** - 嵌套列表中的步骤并行运行，因此“查询三个 API 并组合”仍然是一个调用：
```text
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 目录
您不需要搜索规范 URL。`search_catalog` 搜索两个来源：
1. **精选列表** - 验证的免费/流行 API：GitHub、GitLab、Stripe、OpenAI、Wikipedia、Open-Meteo（天气，无需密钥）、GraphQL API，用于国家/地区、httpbin 和 Swagger Petstore。条目带有工作规范 URL、基准 URL 覆盖和身份验证提示（例如“可选的 GITHUB_TOKEN”）。
2. [APIs.guru](https://apis.guru) 目录 - 2500+ 社区索引的 OpenAPI 规范（Google、AWS、Microsoft、Twilio、NASA 等），每会话获取一次并在本地搜索。
```text
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`](https://docs.astral.sh/uv/) 在任何 MCP 主机上运行 - 无需手动安装，软件包从 [PyPI](https://pypi.org/project/universal-connector-mcp/) 自动获取（添加 `[all]` 以支持 GraphQL/gRPC/SOAP）：
```json
{
"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
[](cursor://anysphere.cursor-deeplink/mcp/install?name=universal-connector&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJ1bml2ZXJzYWwtY29ubmVjdG9yLW1jcCJdfQ==)
单击上面的徽章，或将 JSON 块添加到项目中的 `.cursor/mcp.json`（与团队共享）或 `~/.cursor/mcp.json`（个人，所有项目）。参见 [`examples/mcp.json`](examples/mcp.json) 以获取完整的配置和凭证。
### Claude Desktop
将相同的 `mcpServers` 块添加到 `claude_desktop_config.json`（设置 > 开发者 > 编辑配置）。
### Claude 代码
```bash
claude mcp add universal-connector -- uvx universal-connector-mcp
```
### VS Code (Copilot)
在 `.vscode/mcp.json` 中的 `"servers"` 下添加服务器：
```json
{
"servers": {
"universal-connector": { "command": "uvx", "args": ["universal-connector-mcp"] }
}
}
```
### Windsurf / Cline / 其他
所有主要的 MCP 主机都接受上面所示的相同 `mcpServers` 块，在它们各自的配置文件中（`~/.codeium/windsurf/mcp_config.json`，Cline 的 MCP 设置等）。
> 为用户安装此服务器的 AI 代理：遵循 [llms-install.md](llms-install.md)。
### 预加载 API
将 `UCMCP_APIS_CONFIG` 指向一个 YAML 文件，以在启动时自动加载 API - 参见 [`examples/apis.example.yaml`](examples/apis.example.yaml)。
### 从聊天管理 API
您永远不会编辑配置文件来管理 API - 只需告诉您的代理：
- *"连接 Stripe API"* - 代理在目录中找到它并加载它。
- *"哪些 API 已连接？"* - `list_apis` 显示它们。
- *"忘记 GitHub"* - `unload_api` 删除它（以及记住的状态）。
当 API 需要凭证时，`load_api` 告诉代理确切的环境变量要设置（例如 `STRIPE_API_KEY`），它是否已配置，以及代理转发复制粘贴指令 - 您将变量添加到 MCP 配置的 `env` 块并重启。秘密永远不会输入聊天。
### 会话持久性
服务器在 `UCMCP_STATE_FILE` 中记住已加载的 API（它们的规范位置 - 永远不会是凭证或数据）并在下次启动时自动恢复，因此代理可以从停止的地方继续。设置 `UCMCP_STATE_FILE=off` 以禁用。
## 支持的协议
| 协议 | 规范源 | 备注 |
| --- | --- | --- |
| OpenAPI / Swagger | OpenAPI 3.x 或 Swagger 2.0（JSON/YAML），URL/文件/原始 | 核心安装。本地 `$ref` 解析，所有 HTTP 方法。 |
| GraphQL | Introspection JSON 或 SDL | `pip install '.[graphql]'`。自动生成选择集；`execute` 接受 `fields` 覆盖。 |
| gRPC | 服务器反射 (`grpc://host:port`) | `pip install '.[grpc]'`。Unary-unary 方法；服务器端必须启用反射。 |
| SOAP | WSDL（URL/文件/原始） | `pip install '.[soap]'`。每个操作只有一个 `body` 对象参数。 |
每个加载的操作都会获得一个命名为 `<api>.<operation>` 的 ID（例如 `github.repos_get`）。
## 示例会话
> 更多演练（天气，带有身份验证的 GitHub，GraphQL，并行多 API 工作流程，内部 API）：[docs/EXAMPLES.md](docs/EXAMPLES.md)
```text
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：
```text
load_api(spec="https://countries.trevorblades.com/", protocol="graphql", name="countries")
execute(operation_id="countries.country", params={"code": "US", "fields": "name capital currency"})
```
链式（将一个结果馈入下一个；将步骤包装在嵌套列表中以并行运行）：
```text
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_` 为前缀的环境变量：
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `UCMCP_ALLOWED_HOSTS` | （空） | 额外允许的出站调用主机列表。以 `.` 为前缀进行后缀匹配。 |
| `UCMCP_DENIED_HOSTS` | （空） | 始终阻止的主机列表（胜过 allow）。 |
| `UCMCP_ALLOW_ALL_HOSTS` | `false` | 完全禁用 allow 列表（不推荐）。不禁用私有 IP 阻止。 |
| `UCMCP_BLOCK_PRIVATE_IPS` | `true` | 阻止出站调用解析为私有/环回/链路本地/保留或云元数据地址（SSRF 防护）。 |
| `UCMCP_MAX_REDIRECTS` | `5` | 要遵循的最大 HTTP 重定向次数；每个跳转都会重新检查防护。 |
| `UCMCP_MAX_RESPONSE_BYTES` | `100000` | 发送回代理的响应正文上限。 |
| `UCMCP_HTTP_TIMEOUT` | `30` | 请求超时（秒）。 |
| `UCMCP_MAX_RETRIES` | `2` | 暂态 HTTP 失败时的重试次数（429/502/503/504）。 |
| `UCMCP_CACHE_TTL` | `60` | 成功 GET/查询响应的缓存秒数（`0` 禁用）。 |
| `UCMCP_AUDIT_ENABLED` | `true` | 切换审计日志。 |
| `UCMCP_AUDIT_FILE` | （无） | 将审计条目追加到此文件（JSON 行）。 |
| `UCMCP_USE_KEYRING` | `false` | 还从 OS 密钥环解析秘密。 |
| `UCMCP_APIS_CONFIG` | （无） | 指向启动时预加载的 API 的 YAML 文件。 |
| `UCMCP_STATE_FILE` | `~/.universal-connector-mcp/state.json` | 加载的 API 在重启之间被记住（仅规范位置 - 永远不会是秘密或数据）。设置为 `off` 以禁用。 |
凭证按照约定从 `<API_NAME>_TOKEN`、`<API_NAME>_API_KEY`、`<API_NAME>_CLIENT_ID` / `<API_NAME>_CLIENT_SECRET`（OAuth2 客户端凭证）等查找。
## 开发
```bash
pip install -e ".[all,dev]"
pytest # 运行测试套件
ruff check . # 校验
```
测试套件（60+ 测试）和校验在 CI 上运行 Ubuntu 和 Windows，Python 3.10 和 3.12 在每次推送时 [.github/workflows/ci.yml](.github/workflows/ci.yml)；标记 `v*` 会构建并发布到 PyPI via 信任发布 [.github/workflows/release.yml](.github/workflows/release.yml)。
欢迎贡献 - 参见 [CONTRIBUTING.md](CONTRIBUTING.md)。安全报告通过 [private reporting](SECURITY.md) 进行。
发布是自动的：标记 `v*` 通过信任发布发布到 PyPI（参见 [docs/RELEASING.md](docs/RELEASING.md)）。
## 安全模型
- **出站 allow 列表** - 默认情况下，仅显式加载规范的主机可达。可以扩展/限制通过 `UCMCP_ALLOWED_HOSTS` / `UCMCP_DENIED_HOSTS`。
- **SSRF 防护** - 解析为私有、环回、链路本地、保留或云元数据地址的请求被阻止（包括规范获取、GraphQL 内省和 SOAP 导入）。每个重定向跳转都会重新验证。达到内部地址需要明确的 `UCMCP_ALLOWED_HOSTS` 条目。
- **秘密处理** - 凭证来自环境变量或 OS 密钥环，仅在请求时注入，并在审计日志和错误中被遮蔽。
- **响应上限** - 响应被截断为可配置的字节限制以保护上下文窗口。
- **审计日志** - 每次出站调用的方法、主机、路径和状态（永远不会是秘密或正文）都被记录。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器