API Docs MCP

API Docs MCP

Model Context Protocol（MCP）服务，提供用于与 API 文档交互的工具。支持 GraphQL、OpenAPI/Swagger 和 gRPC 规范，可从各种来源（本地文件或远程 URL）获取架构定义、缓存这些定义，并通过一组工具提供访问。

目录

• API Docs MCP
  • 目录
  • MCP 平台
  • 功能
  • 示例用例
    • 获取 OpenAPI Petstore 文档
    • 获取 GraphQL 文档
    • 获取多个来源的文档
  • 架构
  • 安装
  • 配置
    • FileSource 示例
    • UrlSource 示例
    • 设置 API_SOURCES 环境变量
  • 使用方法
    • API 文档工具
    • API 搜索工具
  • 开发
    • 在本地运行服务
    • 项目结构
  • 贡献
  • 许可证

MCP 平台

功能

• 动态注册工具：自动发现并注册指定目录中的工具。
• 获取 API 文档：提供用于列出可用 API 方法（api_docs）和获取特定方法详细文档（api_search）的工具。
• 架构缓存：缓存 API 架构信息，以减少重复获取并提升性能。
• 支持多个来源：
  • GraphQL：支持从 graphql / gql 文件或 json 内省结果（本地文件或远程 URL）加载 GraphQL 架构。
  • OpenAPI/Swagger：支持从本地文件或远程 URL 加载 OpenAPI/Swagger yaml / yml / json 架构。
  • gRPC：支持从 proto 文件加载 gRPC 架构，或通过远程 URL 使用 gRPC 反射获取架构。
• 基于环境变量的配置：通过 API_SOURCES 环境变量配置 API 来源，从而灵活部署和管理。
• 自动刷新缓存：定期刷新缓存的架构数据，确保文档保持最新。

示例用例

获取 OpenAPI Petstore 文档

获取 GraphQL 文档

获取多个来源的文档

架构

api-docs-mcp 项目旨在作为 MCP 服务，与各种 API 文档来源集成。

graph TD
    mcpServer[MCP Server] e1@--> tools(Tools:<br/>api_docs / api_search);
    tools e2@--> cacheManager{Cache Manager};
    cacheManager e3@--> configuration[Configuration:<br/>API_SOURCES env var];
    configuration e4@--> schemaSources{Schema Sources};
    schemaSources e5@-- FileSource--> localFiles(Local Files:<br/>.graphql, .json, .yaml, .proto);
    schemaSources e6@-- UrlSource--> remoteUrls(Remote URLs:<br/>GraphQL Endpoints, OpenAPI/Swagger Endpoints, gRPC Endpoints);
    localFiles e7@--> processor[Schema Processors];
    remoteUrls e8@--> processor;
    processor e9@--> cacheManager;
    processor e10@--> openAPIProcessor(OpenAPI Processor:<br/>OpenAPI/Swagger);
    processor e11@--> graphQLProcessor(GraphQL Processor);
    processor e12@--> grpcProcessor(gRPC Processor)
    cacheManager e13@--Cached Data--> tools;

    subgraph Core Components
        mcpServer
        tools
        cacheManager
        configuration
    end

    subgraph Data Flow
        schemaSources
        localFiles
        remoteUrls
        processor
        openAPIProcessor
        graphQLProcessor
        grpcProcessor
    end

    e1@{ animate: true }
    e2@{ animate: true }
    e3@{ animate: true }
    e4@{ animate: true }
    e5@{ animate: true }
    e6@{ animate: true }
    e7@{ animate: true }
    e8@{ animate: true }
    e9@{ animate: true }
    e10@{ animate: true }
    e11@{ animate: true }
    e12@{ animate: true }
    e13@{ animate: true }

操作流程：

1. 服务器初始化：入口文件 index.ts 初始化 MCP 服务，并动态注册 src/tools 目录中定义的工具。
2. 加载配置：CacheManager 通过 src/utils/config.ts 从 API_SOURCES 环境变量加载 API 来源配置。
3. 获取并缓存架构：
   • 根据已配置的来源（基于文件或基于 URL），CacheManager 获取 API 架构。
   • 对于文件来源，它会读取本地文件（graphql、gql、json、yaml、yml、proto）。
   • 对于 URL 来源，它会向 GraphQL、OpenAPI 或 gRPC 端点发送 HTTP 请求。
   • 随后，专用处理程序会处理这些架构（OpenAPI 使用 src/api/api.ts，GraphQL 使用 src/gql/gql.ts，gRPC 使用 src/grpc/grpc.ts）。
   • 处理后的文档会存储在内存缓存（src/utils/cache.ts）中，并设有指定的 TTL（生存时间）。
   • 缓存会定期刷新。
4. 使用工具：
   • 调用 api_docs 时，该工具会从缓存中获取所有可用 API 资源的列表；如果提供了 source，则会按其筛选。
   • 使用 detailName 调用 api_search 时，该工具会从缓存中提供特定 API 资源的详细文档（请求、响应和错误结构）。

安装

按照以下步骤设置 api-docs-mcp 服务：

1. 克隆仓库：

   git clone https://github.com/EliFuzz/api-docs-mcp.git
   cd api-docs-mcp
   

2. 安装依赖项：

   pnpm install
   

3. 构建项目：

   pnpm build
   

配置

服务的行为由 API_SOURCES 环境变量控制。此变量应包含一个 JSON 字符串，表示由 SchemaSource 对象组成的数组。每个 SchemaSource 可以是 FileSource 或 UrlSource。

FileSource 示例

本地 GraphQL 架构：

{
  "name": "MyGraphQLFile",
  "path": "/path/to/your/schema.graphql",
  "type": "gql"
}

本地 OpenAPI JSON 架构：

{
  "name": "MyOpenAPIFile",
  "path": "/path/to/your/openapi.json",
  "type": "api"
}

本地 gRPC proto 文件：

{
  "name": "MyGrpcFile",
  "path": "/path/to/your/service.proto",
  "type": "grpc"
}

UrlSource 示例

远程 GraphQL 端点：

{
  "name": "GitHubGraphQL",
  "method": "POST",
  "url": "https://api.github.com/graphql",
  "headers": {
    "Authorization": "Bearer YOUR_GITHUB_TOKEN"
  },
  "type": "gql"
}

远程 OpenAPI 端点：

{
  "name": "PetstoreAPI",
  "method": "GET",
  "url": "https://petstore.swagger.io/v2/swagger.json",
  "type": "api"
}

启用了反射的远程 gRPC 端点：

{
  "name": "MyGrpcService",
  "url": "grpc://localhost:9090",
  "type": "grpc"
}

设置 API_SOURCES 环境变量

运行服务前，可以在 shell 中设置此变量：

export API_SOURCES='[{"name": "MyGraphQLFile", "path": "./example/fixtures/graphql/graphql-schema.graphql", "type": "gql"}, {"name": "PetstoreAPI", "method": "GET", "url": "https://petstore.swagger.io/v2/swagger.json", "type": "api"}]'

也可以在用于 MCP 执行的 mcp.json 中设置：

"api-docs-mcp": {
    "type": "stdio",
    "command": "npx",
    "args": [ "api-docs-mcp" ],
    "env": {
        "API_SOURCES": "[{\"name\": \"MyGraphQLFile\", \"path\": \"./example/fixtures/graphql/graphql-schema.graphql\", \"type\": \"gql\"}, {\"name\": \"PetstoreAPI\", \"method\": \"GET\", \"url\": \"https://petstore.swagger.io/v2/swagger.json\", \"type\": \"api\"}]"
    }
}

使用方法

配置并运行后，api-docs-mcp 服务会提供两个主要工具：api_docs 和 api_search。

API 文档工具

此工具会列出已配置来源中的所有可用 API 方法。

名称：api_docs 描述：获取所有可用 API 方法的列表。 输入架构：

{
    sourceName?: string; // The name of the API source (e.g., "GitHub") from MCP configuration environment variables. If not provided, docs from all sources will be returned.
}

输出架构：

{
  sources: Array<{
    sourceName: string; // The name of the source API
    resources: Array<{
      resourceName: string; // The name of the API resource
      resourceType: string; // The type of the API resource (e.g., "POST", "GET", "mutation", "query")
      resourceDescription: string; // A brief description of the API resource
    }>;
  }>;
}

输出示例：

{
  "sources": [
    {
      "sourceName": "GitHubGraphQL",
      "resources": [
        {
          "resourceName": "getUser",
          "resourceType": "query",
          "resourceDescription": "Fetch a user by username"
        },
        {
          "resourceName": "createIssue",
          "resourceType": "mutation",
          "resourceDescription": "Create a new issue in a repository"
        }
      ]
    },
    {
      "sourceName": "PetstoreAPI",
      "resources": [
        {
          "resourceName": "getPetById",
          "resourceType": "GET",
          "resourceDescription": "Find pet by ID"
        },
        {
          "resourceName": "addPet",
          "resourceType": "POST",
          "resourceDescription": "Add a new pet to the store"
        }
      ]
    }
  ]
}

API 搜索工具

此工具会提供特定 API 方法的详细文档。

名称：api_search 描述：按名称搜索特定 API 方法并获取其完整定义。 输入架构：

{
  resourceName: string; // The exact resource name of the API method to search for that was provided in `api_docs` tool's output
}

输出架构：

{
  details: Array<{
    sourceName: string; // The name of the source API
    resources: Array<{
      resourceName: string; // The name of the resource
      resourceType: "query" | "mutation" | "subscription"; // The type of GraphQL resource
      resourceDescription: string; // Context or description of the resource
      details: {
        request?: string; // The request structure or input parameters for the API method
        response?: string; // The response structure or output format for the API method
        error?: string; // Error information or error handling details for the API method
      };
    }>;
  }>;
}

输出示例：

{
  "details": [
    {
      "sourceName": "GitHubGraphQL",
      "resources": [
        {
          "resourceName": "getUser",
          "resourceType": "query",
          "resourceDescription": "Fetch a user by username",
          "details": {
            "request": "{ username: String! }",
            "response": "{ id: ID!, login: String!, name: String }",
            "error": "{ message: String!, code: Int! }"
          }
        }
      ]
    }
  ]
}

开发

在本地运行服务

1. 按照配置部分中的说明设置 API_SOURCES 环境变量。

2. 启动服务：

   pnpm start
   

服务将连接到 StdioServerTransport，即通过标准输入/输出进行通信。

项目结构

.
├── src/
│ ├── api/ # OpenAPI/Swagger schema processing
│ │ └── api.ts
│ ├── gql/ # GraphQL schema processing
│ │ └── gql.ts
│ ├── grpc/ # gRPC schema processing
│ │ └── grpc.ts
│ ├── tools/ # MCP tools definitions
│ │ ├── api_docs.ts
│ │ └── api_search.ts
│ ├── utils/ # Utility functions (cache, config, fetch, file, source)
│ │ ├── cache.ts
│ │ ├── config.ts
│ │ ├── fetch.ts
│ │ ├── file.ts
│ │ └── source.ts
│ ├── index.ts # Main entry point
│ └── server.ts # MCP server setup and tool registration
└── package.json # Project dependencies and scripts
└── README.md # This file

贡献

欢迎贡献！欢迎提出问题或提交拉取请求。

许可证

本项目采用 Apache 2.0 许可证授权。详情请参阅 LICENSE 文件。