mcp-api-connect

mcp-api-connect™

输入一个负载，调用任意 API。 mcp-api-connect 是一个与协议和身份验证方式无关的连接器引擎：只需描述一次目标服务（URL、协议、身份验证、请求/响应格式），然后向其发送标准化负载，即可获得标准化响应——无论目标是 REST/JSON API、传统 SOAP 服务，还是受 API 密钥、Basic 身份验证、Bearer 令牌或 OAuth2 客户端凭据保护的服务。

它基于同一核心引擎提供三种使用方式，因此无论你想如何使用，都可以：

• Python 库 — pip install mcp-api-connect，直接调用 MCPAPIConnectEngine，无需服务器。
• 独立 HTTP API — pip install mcp-api-connect[api]，运行 mcp-api-connect-api，向 /invoke 发送 POST 请求。
• MCP 服务 — pip install mcp-api-connect[mcp]，运行 mcp-api-connect，让任意 MCP 客户端（Claude 等）连接到它，以便 Agent 将已注册的连接器（或即时调用的任意服务）用作工具。

为什么要使用

每个集成项目都在重复造轮子：这里一个 REST 客户端，那里一个 SOAP 客户端；每个服务各自实现一种身份验证流程；请求/响应映射则零散地分布在整个代码库中。mcp-api-connect 将这些内容集中到一个声明式规范（InvokeSpec）和一个执行引擎中，因此添加新的目标服务只需配置，无需编写代码。

快速开始（库）

pip install mcp-api-connect

import asyncio
from mcp_api_connect import MCPAPIConnectEngine, InvokeSpec, Target, AuthSpec, AuthType, RequestFormat, ResponseFormat

spec = InvokeSpec(
    target=Target(base_url="https://api.example.com"),
    auth=AuthSpec(type=AuthType.API_KEY, config={"api_key": "secret", "header_name": "X-API-Key"}),
    request_format=RequestFormat(method="POST", path="/v1/orders", content_type="json"),
    response_format=ResponseFormat(content_type="json"),
)

async def main():
    async with MCPAPIConnectEngine() as engine:
        result = await engine.invoke(spec, {"customer": "jane"})
        print(result.success, result.data)

asyncio.run(main())

快速开始（HTTP API）

pip install "mcp-api-connect[api]"
mcp-api-connect-api   # serves on :8000, interactive docs at /docs

curl -X POST http://localhost:8000/invoke -H 'content-type: application/json' -d '{
  "spec": {
    "target": {"base_url": "https://api.example.com"},
    "auth": {"type": "api_key", "config": {"api_key": "secret"}},
    "request_format": {"method": "POST", "path": "/v1/orders"},
    "response_format": {"content_type": "json"}
  },
  "payload": {"customer": "jane"}
}'

只需注册一次可复用的连接器，之后即可按名称调用：

curl -X POST http://localhost:8000/connectors -d '{"name": "orders-api", "spec": {...}}'
curl -X POST http://localhost:8000/connectors/orders-api/invoke -d '{"customer": "jane"}'

快速开始（MCP）

pip install "mcp-api-connect[mcp]"

{
  "mcpServers": {
    "mcp-api-connect": { "command": "/path/to/.venv/bin/mcp-api-connect" }
  }
}

也可以在容器中运行（stdio 传输）：

docker build -t mcp-api-connect .
docker run --rm -i mcp-api-connect

提供以下工具：invoke（无状态，单次调用）、register_connector、list_connectors、invoke_connector（按名称调用）、delete_connector。Agent 可以先注册一个用于“Salesforce API”的连接器，之后只需说“使用这个负载调用它”即可。

➜ Claude Desktop / Claude Code / Cursor 的完整设置说明、持久化、安全须知和完整示例：docs/mcp-integration.md。

核心概念

• Target — 基础 URL、协议（rest | soap）、超时、默认请求头。
• AuthSpec — type（none、api_key、basic、bearer、oauth2_client_credentials）以及符合该类型要求的 config 字典。OAuth2 令牌会自动获取并缓存。
• RequestFormat / ResponseFormat — 内容类型（json、xml、soap），以及声明式 field_map（{"target.path": "$.source.jsonpath"}），用于在不编写代码的情况下重塑负载；也可以使用 Jinja2 body_template 完全控制格式（SOAP 信封必须使用此方式）。
• InvokeSpec — 将上述三项组合在一起，描述“如何访问一个服务”。可将其保存为命名的 Connector，也可在每次调用时内联传入。

完整架构请参阅 src/mcp_api_connect/core/models.py，各身份验证 type 所需的 config 格式请参阅 docs/auth-reference.md。

文档

• docs/mcp-integration.md — MCP 客户端完整设置说明（Claude Desktop、Claude Code、Cursor）、持久化、安全、工具参考、完整示例和故障排除
• docs/auth-reference.md — 各身份验证类型的 config 字段
• CONTRIBUTING.md — 开发环境设置、运行测试、PR 要求

扩展

• 新增身份验证类型：实现 AuthStrategy，并通过 engine.register_auth_strategy(...) 注册。
• 新增协议（例如 GraphQL）：实现 ProtocolAdapter，并通过 engine.register_adapter(...) 注册。
• 新增连接器存储后端：实现 ConnectorStore（项目提供 InMemoryConnectorStore 和 SqliteConnectorStore，凭据使用 Fernet 加密后静态存储）。

路线图

• OAuth2 授权码流程、mTLS、AWS SigV4 身份验证策略
• 由 WSDL 驱动的 SOAP（可选的基于 zeep 的适配器，无需手写信封）
• GraphQL 适配器
• 基于 Postgres 的 ConnectorStore
• 每个连接器的重试／退避和速率限制策略
• 面向公共部署的 SSRF 安全目标允许列表

开发

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,api,storage,mcp]"
pytest

许可证

Apache License 2.0——请参阅 LICENSE 和 NOTICE。

接受以相同许可证提交的贡献（传入 = 传出）；请参阅 CONTRIBUTING.md。

商标

mcp-api-connect™ 是 Balaji Venkatasubramaniyar 的商标。Apache 2.0 许可证涵盖版权和专利，但不授予任何商标权利。 您可以使用该名称指称此项目并说明兼容性，但不得用它为分支、产品或服务命名，也不得暗示获得背书。完整政策请参阅 TRADEMARKS.md。