使用说明

API文件MCP

模型上下文协议（MCP）服务器，提供与API文档交互的工具。支持GraphQL、OpenAPI/Swagger和gRPC规范，从各种来源（本地文件或远程URL）获取模式定义，缓存它们，并通过一组工具公开它们。

MCP平台

特性

动态工具注册：自动从指定目录中发现和注册工具。
API文档检索：提供列出可用API方法的工具(api_docs)并检索特定方法的详细文档(api_search).
架构缓存：缓存API架构信息，以减少冗余获取并提高性能。
多源支持:
- 图查询语言：支持从以下位置加载GraphQL模式 graphql / gql 文件或 json 自检结果（本地文件或远程URL）。
- OpenAPI/Swagger：支持加载OpenAPI/Swagger yaml / yml / json 本地文件或远程URL中的模式。
- gRPC：支持从以下位置加载gRPC架构 proto 文件或通过远程URL的gRPC反射。
基于环境的配置：通过配置API源 API_SOURCES 环境变量，允许灵活部署和管理。
自动缓存刷新：定期刷新缓存的架构数据，以确保文档是最新的。

示例用例

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 }

操作流程：

服务器初始化：The index.ts 入口点初始化MCP服务器并动态注册中定义的工具 src/tools 目录。
配置加载：The CacheManager 从加载API源配置 API_SOURCES 环境变量通过 src/utils/config.ts.
模式获取和缓存:
- 根据配置的源（基于文件或基于URL） CacheManager 获取API模式。
- 对于文件源，它读取本地文件(graphql, gql, json, yaml, yml, proto).
- 对于URL源，它向GraphQL、OpenAPI或gRPC端点发出HTTP请求。
- 然后，模式由专门的处理程序处理(src/api/api.ts 对于OpenAPI， src/gql/gql.ts 对于GraphQL， src/grpc/grpc.ts 适用于gRPC）。
- 处理后的文档存储在内存缓存中(src/utils/cache.ts)具有指定的TTL（生存时间）。
- 缓存会定期刷新。
工具使用:
- api_docs：调用时，此工具从缓存中检索所有可用API资源的列表，按 source 如果提供。
- api_search：当用a调用时 detailName，该工具提供了缓存中特定API资源的详细文档（请求、响应、错误结构）。

安装

要设置 api-docs-mcp 服务器，请按照以下步骤操作：

克隆存储库：

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

安装依赖项：
```
pnpm install
```
构建项目：
```
pnpm build
```

配置

服务器的行为由控制 API_SOURCES 环境变量。此变量应包含一个JSON字符串，表示以下数组 SchemaSource 物体。每 SchemaSource 可以是a FileSource 或a 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原型文件：

{
  "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.json 对于MCP执行：

"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! }"
          }
        }
      ]
    }
  ]
}

发展

在本地运行服务器

设置 API_SOURCES 环境变量 如所述配置部分。
启动服务器：
```
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

贡献

欢迎投稿！请随时打开问题或提交pull请求。

许可证

此项目根据Apache 2.0许可证获得许可。看许可证文件以获取详细信息。

使用说明

API文件MCP

目录

MCP平台

特性

示例用例

OpenAPI Petstore检索文档

GraphQL检索文档

多源检索文档

建筑

安装

配置

FileSource 示例

UrlSource 示例

设置 API_SOURCES 环境变量

用法

API文档工具

API搜索工具

发展

在本地运行服务器

项目结构

贡献

许可证

相关 MCP

GraphQL API交互服务

GraphQL模式分析工具

Swagger解析与代码生成工具

文档搜索服务

GraphQL协议服务器

模型上下文协议服务器

`FileSource` 示例

`UrlSource` 示例

设置 `API_SOURCES` 环境变量