OpenAPI Services

mcp-openapix

一个MCP服务，通过四个通用工具为任何OpenAPI 服务提供代理。

Agent 会在每个部署的 OpenAPI 文档中查找操作并调用它们；服务负责解析 URL、获取 bearer token 并构建请求。发现操作使用 list_platforms、list_endpoints 和 describe_endpoint；执行操作则使用通用代理 call_endpoint。

example / us / items / prod
  │     │     │      └── env ......... which deployment URL a call reaches
  │     │     └───────── service ..... one backend, one OpenAPI spec
  │     └─────────────── region ...... a geographic deployment
  └───────────────────── platform .... the product or API family

环境要求

• Python 3.13+ 和 uv
• 一个描述你持有凭据的部署的 config.json

快速开始

设置配置（参见配置），然后运行服务：

# Run directly with uvx (no clone needed)
npx -y @modelcontextprotocol/inspector@latest uvx mcp-openapix

# Or run from source
npx -y @modelcontextprotocol/inspector@latest uv run mcp-openapix

配置

config.json 必须位于 ~/.config/mcp-openapix/config.json （Windows 上为 %USERPROFILE%\.config\…）。config.example.json 是完整模板。

{
  "headers": { "accept": "application/json" },
  "defaults": { "platform": "example", "region": "us", "service": "items", "env": "prod" },
  "platforms": {
    "example": {
      "regions": {
        "us": {
          "services": {
            "token_helper": "us",
            "items": {
              "desc": "Catalogue and inventory API",
              "spec_path": "/swagger/v1/swagger.json",
              "canonical_env": "prod",
              "envs": {
                "prod": { "url": "https://api.example.com/items" },
                "dev":  { "url": "https://api-dev.example.com/items" }
              }
            }
          }
        }
      }
    }
  },
  "token_helpers": {
    "us": {
      "command": "token-helper",
      "args": ["issue"]
    }
  }
}

platforms

层级结构为 platform → region → services → service → env。每个服务都声明：

services 对象还可以包含一个 token_helper 默认值，应用于该 region 中的所有服务。服务或环境可以覆盖此值。

token_helpers

命名的 token helper，结构与 MCP 服务条目相同：

配置中只包含命令名称，不包含其他内容，因此 config.json 不含任何密钥。完整的 helper 调用和输出约定见docs/token-protocol.md。

一次调用使用哪个 helper，将按从最具体到最宽泛的顺序解析：

env.token_helper → service.token_helper → services.token_helper
→ region.token_helper → platform.token_helper → defaults.token_helper

如果没有任何层级声明 helper，则该部署无需身份验证。对于公开部署，请省略 token_helper。

headers

添加到每次 API 调用的固定请求头 — 适用于要求提供租户、产品或区域设置请求头的 API：

"headers": { "accept": "application/json", "x-product": "example" }

defaults

使每个工具参数都变为可选：省略参数时，调用会回退到 defaults.platform、.region、.service、.env、.username 和 .token_helper。

顶层选项

拆分配置

编辑某个平台时多出的一个逗号，就可能让所有平台都无法使用：解析失败发生在逐个平台验证之前。因此，配置 MAY 拆分成 config.d/ 下的多个即插即用文件，类似于 nginx 的 conf.d。推荐的布局是将服务器级设置保留在 config.json 中，并为每个平台提供一个以平台名命名的文件：

~/.config/mcp-openapix/
├── config.json      # defaults, headers, token_helpers, top-level options
└── config.d/
    ├── acme.json    # {"platforms": {"acme": …}}
    └── public.json  # {"platforms": {"public": …}}

这样，拼写错误只会影响一个平台；平台也可以作为单个文件交接或移除。Token 辅助程序保留在 config.json 中，因为它们通常由多个平台共用；某个平台专用的辅助程序 MAY 放在该平台的文件中。

这种布局是一种约定，而非规则：

• 首先读取 config.json，然后按排序顺序读取 config.d/ 下的所有 *.json 文件。子目录、.bak 文件和编辑器交换文件会被忽略；没有 config.d/ 时，行为不会改变。
• 即插即用文件 MAY 声明 config.json 可以声明的任何内容，而 config.json MAY 几乎为空。
• 文件按顺序合并，效果如同依次粘贴到一个配置文件中：对象按键合并，后面的标量或列表会替换前面的值。因此，后续文件可以覆盖单个 envs.prod.url 或某个 defaults 字段。

文件解析失败时，仅其声明的内容会受到影响；其余部分仍会正常工作。任何文件中的格式错误的平台 MUST NOT 阻止其他平台加载；它所引用的 Token 辅助程序缺失也不会阻止加载：错误信息会列出所有已跳过的文件，因为辅助程序可能在其中某个文件中声明。list_platforms 会显示加载失败的平台，其区域为空，并包含加载器的 error；被跳过的文件则显示为 {"file", "error"}；调用失败的平台时会返回相同的消息。指向失败平台的默认值会被忽略。platforms 以外的无效设置仍会导致服务器停止，错误消息会指出设置该值的文件。

修复后需要重启。启动服务器前先检查配置；检查结果还会列出后续文件覆盖的所有值：

uvx mcp-openapix --check-config

工具

操作 ID

许多 OpenAPI 文档会省略 operationId，因此服务器会合成一个 ID，格式为 "<METHOD> <path>"：

POST /api/items
└─┬─┘ └───┬───┘
method  path as the spec declares it

如果规范声明了 operationId，则优先使用该值。

规范

规范不会随程序打包。每次部署的文档都会按需获取——通过未经身份验证的 GET 请求——并缓存到 ~/.cache/mcp-openapix/{platform}/{region}/{service}.json。

只有声明了至少一个操作的文档才会被安装，因此，即使某个部署返回 200 和错误正文，也不会用一个无法提供任何内容的文档替换可正常工作的快照。

缓存的规范会在后台刷新：启动时刷新一次，此后每隔 spec_refresh.interval 天刷新一次。将 auto 设为 false 可停止自动刷新；仍可手动刷新：

uvx mcp-openapix --refresh

MCP 资源

两者都会在调用后 response_cache_ttl 秒过期。curl 命令可能包含短时有效的 Token。

静态 Token

Token 会缓存在内存中；如果有过期元数据，也会以 0600 模式缓存在 ~/.cache/mcp-openapix/tokens/ 下，键由 Token 辅助程序声明和用户名组成。这样，客户端会话可以共用一次登录，无需每个会话都启动一个辅助程序。收到 401 时，缓存的 Token 会被移除，以便下一次调用获取新的 Token。若要清除所有 Token：

uvx mcp-openapix --logout

MCP 主机示例

{
  "mcpServers": {
    "openapi": { "command": "uvx", "args": ["mcp-openapix"] }
  }
}

[mcp_servers.openapi]
command = "uvx"
args = ["mcp-openapix"]

uv sync --extra dev
uv run ruff check .
uv run ruff format --check .
uv run pyright
uv run pytest

这四项测试都必须通过；请参阅 AGENTS.md。测试使用 respx 模拟 HTTP，并为令牌辅助程序启动真实子进程， 因此无需访问在线 API。

许可证

MIT.