Caitlyn OpenAPI MCP服务器

MCP服务器，它将OpenAPI规范作为LLM的可查询文档资源公开，并带有Scalar深度链接。

特性

基于URL的OpenAPI规范加载：从任何URL加载规格，而不仅仅是本地文件
$ref决议：自动解析所有 $ref 使用Prance的引用（包括远程引用）
语义搜索：使用句子变换器进行基于向量的端点搜索，以更好地理解查询
标量深度链接：每个端点、模式和安全方案都包含一个 docs_url 指向Scalar文档
MCP资源：暴露规范结构以进行内省
MCP工具：搜索和查询端点、架构和安全方案
可流式传输的HTTP：专为基岩试剂核心集成而设计

安装

使用uvx（推荐）

对于没有全局安装的隔离执行：

uvx caitlyn-openapi-mcp

使用pip

从PyPI安装：

pip install caitlyn-openapi-mcp

来源

对于本地开发或测试：

git clone https://github.com/caitlyn-ai/caitlyn-openapi-mcp.git
cd caitlyn-openapi-mcp
pip install -e ".[dev]"

配置

服务器是通过环境变量配置的：

必需

OPENAPI_SPEC_URL：OpenAPI JSON/YAML规范的完整URL

- 例子： https://api.example.com/openapi.json - 例子： https://raw.githubusercontent.com/org/repo/main/openapi.yaml

可选的

DOCS_RENDERER：文档呈现器类型（默认值： "scalar")

- 目前仅 "scalar" 支持

DOCS_BASE_URL：标量文档UI的基本URL

- 例子： https://api.example.com/docs - 例子： https://api.example.com/scalar - 如果没有提供， docs_url 字段将是 null

MCP_TRANSPORT：传输模式（默认值： "stdio")

- "stdio"：用于本地开发和Claude Desktop（默认） - "streamable-http"：用于AWS Bedrock AgentCore部署

开放遥测（可选）

用于生产环境中的可观察性。 看遥测.md 获取完整的文档，包括与Jaeger的本地开发设置。

地方发展：

这 make dev 命令会自动启动带有Jaeger UI的OTEL收集器，以可视化跟踪：

# Start dev environment with OTEL collector + Jaeger
make dev

# View traces and logs in Jaeger UI
open http://localhost:16686

通用OTEL配置：

ENABLE_TELEMETRY：启用/禁用遥测（默认值： "true")
OTEL_SERVICE_NAME：用于跟踪的服务名称（默认值： "caitlyn-openapi-mcp")
OTEL_EXPORTER_OTLP_ENDPOINT：迹线的OTLP端点（例如。， "http://localhost:4317")

AWS基岩代理核心（ADOT）：

Docker镜像包括用于本地AgentCore集成的AWS Distro for OpenTetry（ADOT）。部署到AgentCore时，跟踪会自动导出到CloudWatch。

预配置的环境变量（已在Dockerfile中设置）：

OTEL_PYTHON_DISTRO=aws_distro
OTEL_PYTHON_CONFIGURATOR=aws_configurator
OTEL_TRACES_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

非AgentCore托管部署的其他变量：

AWS_DEFAULT_REGION, AWS_REGION：AWS区域
AWS_ACCOUNT_ID, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY：AWS凭据
ENABLE_TELEMETRY=true：启用OpenTetry可观察性

仪表化操作：

OpenAPI规范加载（具有粒度缓存/获取/解析/提取跨度）
矢量搜索（模型加载、嵌入生成、缓存操作）
语义搜索查询（编码、相似度计算、排名）
MCP协议（列表工具、列表资源、调用工具）
所有Python日志记录都被捕获为OTEL日志记录

客户端配置

1.带uvx的克劳德桌面（推荐）

将此服务器与Claude Desktop一起使用的最简单方法。无需安装-uvx会自动下载并运行该软件包。

配置文件位置：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "openapi-docs": {
      "command": "uvx",
      "args": ["caitlyn-openapi-mcp"],
      "env": {
        "OPENAPI_SPEC_URL": "https://api.example.com/openapi.json",
        "DOCS_BASE_URL": "https://api.example.com/docs"
      }
    }
  }
}

2.克劳德桌面与本地开发

用于测试服务器代码的本地更改。

先决条件：克隆仓库并在开发模式下安装（请参阅本地开发)

{
  "mcpServers": {
    "openapi-docs": {
      "command": "python",
      "args": ["-m", "openapi_mcp.server"],
      "env": {
        "OPENAPI_SPEC_URL": "https://api.example.com/openapi.json",
        "DOCS_BASE_URL": "https://api.example.com/docs"
      }
    }
  }
}

备注：如果不在path中，请使用Python的完整路径： "/usr/local/bin/python3.11"

3.MCP地方发展检查员

用于在部署到Claude Desktop之前使用web UI进行交互式测试。

先决条件:

在开发模式下克隆和安装（请参阅本地开发)
已安装Node.js（npx随Node.js一起提供）

快速启动：

make dev

或者手动设置您自己的API：

npx @modelcontextprotocol/inspector \
  -e OPENAPI_SPEC_URL="https://api.example.com/openapi.json" \
  -e DOCS_BASE_URL="https://api.example.com/docs" \
  python -m openapi_mcp.server

看 MCP检验员测试了解更多详情。

4.AWS基岩代理核心

部署为具有流式http传输和AWS Distro for OpenTetry（ADOT）的容器化服务，以实现本地可观察性。

特征：

🚀 快速冷启动 -预缓存的嵌入用于快速初始化
📊 ADOT集成 -原生CloudWatch跟踪
🔒 安全 -非root用户，多阶段构建
📦 生产准备就绪 -健康检查和资源优化

快速启动：

复制 .env.example 到 .env 并配置：

   cp .env.example .env
   # Edit .env with your OPENAPI_SPEC_URL and AWS credentials

使用docker compose运行：

   docker-compose up openapi-mcp-bedrock

查看完整示例：

-使用ADOT自动仪器进行多级构建
-完整的服务定义
.env.示例 -所有配置选项

构建并运行：

docker build -t openapi-mcp .
docker run -p 8000:8000 openapi-mcp

配置您的Bedrock代理以连接到HTTP端点。

5.Claude Desktop提供多种API

通过运行单独的服务器实例同时连接到多个OpenAPI规范。

{
  "mcpServers": {
    "production-api": {
      "command": "uvx",
      "args": ["caitlyn-openapi-mcp"],
      "env": {
        "OPENAPI_SPEC_URL": "https://api.prod.example.com/openapi.json",
        "DOCS_BASE_URL": "https://docs.prod.example.com"
      }
    },
    "staging-api": {
      "command": "uvx",
      "args": ["caitlyn-openapi-mcp"],
      "env": {
        "OPENAPI_SPEC_URL": "https://api.staging.example.com/openapi.json",
        "DOCS_BASE_URL": "https://docs.staging.example.com"
      }
    },
    "caitlyn-api": {
      "command": "uvx",
      "args": ["caitlyn-openapi-mcp"],
      "env": {
        "OPENAPI_SPEC_URL": "https://betty.getcaitlyn.ai/docs/openapi-v1.json",
        "DOCS_BASE_URL": "https://betty.getcaitlyn.ai/api/docs"
      }
    }
  }
}

每个服务器都使用自己的OpenAPI规范独立运行。

故障排除

服务器无法在Claude Desktop中启动

验证Python是否在您的PATH中： which python （macOS/Linux）或 where python （Windows）
使用Python的完整路径： "/usr/local/bin/python3.11"
检查克劳德桌面日志： ~/Library/Logs/Claude/mcp*.log （macOS）
确保 OPENAPI_SPEC_URL 可从您的计算机访问

“ModuleNotFoundError:没有名为'openapi_mcp'的模块”

对于uvx：这不应该发生-uvx会自动安装
对于本地Python：运行 pip install caitlyn-openapi-mcp 或 pip install -e ".[dev]" 在回购中
验证安装： python -m openapi_mcp.server --help

工具未出现在Claude Desktop中

完全重新启动Claude Desktop（退出并重新打开）
验证JSON配置是否有效（使用JSON验证器）
检查服务器是否在活动监视器（macOS）或任务管理器（Windows）中运行
检查Claude Desktop日志是否有错误

OpenAPI规范加载失败

验证URL是否可访问： curl https://your-api.com/openapi.json
检查服务器日志以获取详细的错误消息
确保规范是有效的OpenAPI 3.x格式
如果规格不符合要求 $ref 引用时，服务器仍将加载它并发出警告

MCP资源

服务器公开了一个静态资源：

`api-specification`

JSON格式的完整OpenAPI 3.x规范（在所有$ref扩展后完全解析）。可以与OpenAPI验证工具、代码生成器一起使用，或作为参考。

MCP工具

服务器提供的工具旨在帮助LLM回答用户关于API的问题。每个工具都包含上下文描述，以指导何时使用。

`list_api_endpoints`

用途： 概述API的功能，或按类别查找终结点。

参数：

tag （可选）：按API类别/标签筛选（例如，“用户”、“帖子”、“授权”）
search （可选）：查找端点的搜索词（搜索路径、描述、摘要）

退货： 包含路径、方法、摘要、描述、标签和docs_url的端点列表

示例用例：

用户问：“这个API能做什么？”
用户询问：“显示所有与用户相关的端点”

`get_endpoint_details`

用途： 获取特定端点的详细信息，包括参数、请求正文和响应。

参数：

method：HTTP方法（GET、POST、PUT、DELETE、PATCH等）
path：API路径（例如，“/API/v1/用户”或“/users/｛userId｝”）

退货： 完整的端点详细信息，包括参数、请求体模式、响应模式和docs_url

示例用例：

用户问：“如何调用创建用户端点？”
用户问：“GET/用户端点需要哪些参数？”
用户问：“创建帖子的请求正文是什么？”

`get_schema_definition`

用途： 了解请求/响应数据模型的结构。

参数：

schema_name：架构的名称（例如，“用户”、“CreateUserRequest”、“分页响应”）

退货： 具有属性、类型、必填字段和docs_url的模式定义

示例用例：

用户问：“用户对象有哪些字段？”
用户问：“CreatePostRequest的结构是什么？”
用户问：“响应是什么样子的？”

`search_api_endpoints`

用途： 当你不知道确切的路径时，按功能查找端点。

参数：

query：用户想要做什么（例如，“创建知识库”、“上传文件”、“获取用户资料”）
max_results （可选，默认值：20）：返回的最大结果数

退货： 将端点与路径、方法、摘要、描述、标签和docs_url进行匹配

示例用例：

用户提问：“如何通过API创建知识库？”
用户问：“我可以上传文件吗？”
用户问：“是否有用户身份验证的端点？”

`list_api_tags`

用途： 了解如何将API组织到功能类别中。

参数： 无

退货： 带有端点计数的标签/类别列表

示例用例：

用户提问：“这个API涵盖了哪些功能领域？”
用户问：“这个API是如何组织的？”

标量深度链接

当 DOCS_BASE_URL 配置后，服务器会生成指向Scalar文档的深度链接：

端点链接

格式： {base_url}#tag/{tag}/{method}/{path}

例子： https://api.example.com/docs#tag/users/get/api/v1/users

tag：操作上的第一个标记（如果没有标记，则默认为“默认”）
method：小写HTTP方法（get、post等）
path：去掉前导斜线的OpenAPI路径

架构链接

格式： {base_url}#schema/{schemaName}

例子： https://api.example.com/docs#schema/User

安全方案链接

格式： {base_url}#security/{schemeName}

例子： https://api.example.com/docs#security/bearerAuth

本地开发

设置

克隆存储库并在开发模式下安装：

git clone https://github.com/caitlyn-ai/caitlyn-openapi-mcp.git
cd caitlyn-openapi-mcp
pip install -e ".[dev]"

安装程序会自动下载句子转换器模型（~80MB）到 ./models/ 用于语义搜索。

启动行为：

无阻塞启动：服务器立即启动，无需等待规格或型号加载
后台加载：OpenAPI规范和ML模型在并行后台线程中加载
首次请求处理：如果仍在加载中，则自动等待加载完成

缓存策略：

OpenAPI规范：缓存到磁盘，以便后续加载更快
ML模型文件：下载一次并在本地缓存
嵌入：根据API规范预计算和缓存
缓存失效：当API规范内容更改时自动
人工管理:

- 下载/更新型号： make setup-models - 清除所有缓存： make clean-models

注： Docker镜像包括用于即时启动容器的预下载模型。

MCP检验员测试

这 MCP检查员提供了一个基于web的UI，用于在本地测试您的MCP服务器，并具有完全的可观察性。

先决条件:

已安装Node.js（npx随Node.js一起提供）
Docker for OTEL收集器（可选但推荐）

快速开始使用Make：

make dev

这将启动：

酒店收藏家 -在本地主机4317上接收遥测数据
Jaeger用户界面 -可视化痕迹（自动打开http://localhost:16686)
MCP检查员 -交互式测试界面

检查员将打开一个web界面，您可以在其中：

交互式测试所有MCP工具
查看资源及其内容
检查端点详细信息、模式和安全方案
使用OpenTetry跟踪监控性能
部署前验证服务器行为

Jaeger UI将在浏览器中自动打开以查看跟踪和日志。

手动使用自定义API：

npx @modelcontextprotocol/inspector \
  -e OPENAPI_SPEC_URL="https://api.example.com/openapi.json" \
  -e DOCS_BASE_URL="https://api.example.com/docs" \
  -e OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317" \
  python -m openapi_mcp.server

有关完整的遥测文档，请参阅遥测.md.

运行测试

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test files
pytest tests/test_openapi_loader.py

代码质量

# Format code
black src tests

# Lint code
ruff check src tests

# Type checking
pyright

# Run all checks
black src tests && ruff check src tests && pyright && pytest

建筑

服务器由以下组件构建：

config.py：基于环境的配置
model.py：端点、模式和OpenAPI索引的数据模型
openapi_loader.py：使用Prance和OpenAPI核心加载基于URL的OpenAPI规范
docs_links.py：文档深度链接生成（目前仅Scalar）
resources.py：MCP资源定义
tools.py：MCP工具定义
服务器.py：主服务器接线和入口点

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

贡献

欢迎投稿！请看贡献.md 了解如何为这个项目做出贡献的指导方针。

有关安全问题，请参阅我们的安全策略.

Caitlyn Openapi MCP

快速接入

详细介绍