使用说明

API文档MCP服务器

一个模型上下文协议（MCP）服务器，它提供了从OpenAPI/Swagger JSON文件中探索和查询API定义的工具。

概述

此MCP服务器从目录中读取API定义文件 D:\My works\DauTuCong\Frontend\src\assets\api-definitions 并提供各种工具来搜索、探索和检索有关这些文件中定义的API的信息。

特性

列出所有API：获取所有可用API定义的概述
按标签搜索：查找按功能标记分组的端点
按路径搜索：使用路径模式匹配查找端点（支持正则表达式）
获取端点详细信息：检索有关特定端点的完整信息，包括参数、请求正文和响应
获取架构详细信息：探索API规范中定义的数据模型和架构
列出架构：查看特定API定义中的所有可用架构

安装

安装依赖项：

npm install

人工智能代理的MCP设置

此MCP服务器可以与各种AI编码助手和代理一起使用。以下是常见平台的设置说明。

克劳德代码（克劳德桌面）

打开克劳德桌面设置
导航到MCP服务器配置
添加以下配置：

{
  "mcpServers": {
    "api-docs": {
      "command": "node",
      "args": ["d:/My works/api-docs-mcp/index.js"],
      "env": {
        "API_DEFINITIONS_DIR": "D:/My works/DauTuCong/Frontend/src/assets/api-definitions"
      }
    }
  }
}

保存配置并重新启动Claude Desktop
MCP服务器工具现在将在Claude Code中可用

Cline（VS代码扩展）

从VS代码市场安装Cline扩展
打开VS代码设置（Ctrl/Cmd+，）
搜索“临床：MCP服务器”
添加MCP服务器配置：

{
  "cline.mcpServers": [
    {
      "name": "api-docs",
      "command": "node",
      "args": ["d:/My works/api-docs-mcp/index.js"],
      "env": {
        "API_DEFINITIONS_DIR": "D:/My works/DauTuCong/Frontend/src/assets/api-definitions"
      }
    }
  ]
}

保存设置并重新加载VS代码
MCP工具将在Cline中提供

千码

打开千码设置
导航到MCP服务器配置
添加服务器配置：

{
  "mcpServers": {
    "api-docs": {
      "command": "node",
      "args": ["d:/My works/api-docs-mcp/index.js"],
      "env": {
        "API_DEFINITIONS_DIR": "D:/My works/DauTuCong/Frontend/src/assets/api-definitions"
      }
    }
  }
}

保存并重新启动Kilo Code
MCP服务器将自动连接

风帆冲浪（Codeium）

打开Windsurf设置
导航到扩展→ MCP
添加具有以下配置的新MCP服务器：

名字：api文档
命令：节点
参数：d:/我的作品/api-docs mcp/index.js
环境变量:
- API_DEFINITIONS_DIR=D:/我的作品/DauTuCong/Frontend/src/assets/API-DEFINITIONS

保存配置
重新启动Windsurf以激活MCP服务器

光标

打开光标设置（Ctrl/Cmd+，）
导航到MCP服务器部分
添加以下配置：

{
  "cursor.mcpServers": {
    "api-docs": {
      "command": "node",
      "args": ["d:/My works/api-docs-mcp/index.js"],
      "env": {
        "API_DEFINITIONS_DIR": "D:/My works/DauTuCong/Frontend/src/assets/api-definitions"
      }
    }
  }
}

保存设置
重新加载光标以应用更改

通用MCP配置说明

路径调整：更新上述配置中的文件路径，以匹配您的实际项目位置
环境变量：The API_DEFINITIONS_DIR 环境变量应指向API定义目录
权限：确保AI代理有权执行MCP服务器
故障排除：如果MCP服务器未连接，请检查：
- Node.js已安装并可访问
- 文件路径正确
- API定义目录存在并且包含有效的JSON文件
- 检查代理的日志是否存在连接错误

验证MCP连接

使用任何AI代理设置MCP服务器后，您可以通过以下方式验证连接：

要求AI代理列出可用的工具
请求使用列出所有API list_apis 工具
正在检查代理是否可以访问API定义和架构

如果成功，AI代理应该能够使用MCP工具查询API定义、搜索端点和检索模式信息。

用法

运行服务器

启动MCP服务器：

npm start

服务器在stdio上运行，可以通过任何兼容MCP的客户端连接。

可用工具

1. `list_apis`

列出所有可用的API定义及其标题和版本。

参数： 无

示例响应：

[
  {
    "name": "auth",
    "title": "Authentication API",
    "version": "v1",
    "filename": "auth.swagger.json"
  }
]

2. `get_api_details`

获取有关特定API定义的详细信息。

参数：

name （必需）：API名称（如“auth”、“projects”、“users”）

例子：

{
  "name": "auth"
}

3. `list_tags`

列出所有API定义中的所有标记。

参数： 无

示例响应：

["Auth", "Projects", "Users"]

4. `search_by_tag`

按标记名称搜索端点。

参数：

tag （必填）：要搜索的标签名称

例子：

{
  "tag": "Auth"
}

5. `search_by_path`

按路径模式搜索端点（支持正则表达式）。

参数：

pattern （必填）：要搜索的路径模式（例如，“/api/Auth”、“/api/.*”）

例子：

{
  "pattern": "/api/Auth"
}

6. `get_endpoint`

获取特定端点的详细信息。

参数：

api （必需）：API名称（例如“auth”、“projects”）
path （必填）：端点路径（例如，“/api/Auth/login”）
method （必填）：HTTP方法（GET、POST、PUT、DELETE等）

例子：

{
  "api": "auth",
  "path": "/api/Auth/login",
  "method": "POST"
}

7. `get_schema`

获取特定模式的详细信息。

参数：

api （必需）：API名称（例如“auth”、“projects”）
schemaName （必填）：架构名称（例如，“LoginCommand”、“AuthResponseDto”）

例子：

{
  "api": "auth",
  "schemaName": "LoginCommand"
}

8. `list_schemas`

列出特定API定义中的所有架构。

参数：

api （必需）：API名称（例如“auth”、“projects”）

例子：

{
  "api": "auth"
}

配置

API定义目录可以通过环境变量进行配置：

export API_DEFINITIONS_DIR="path/to/your/api-definitions"
npm start

或者将其设置为内联：

API_DEFINITIONS_DIR="path/to/your/api-definitions" npm start

如果未设置，则默认为 D:\My works\DauTuCong\Frontend\src\assets\api-definitions.

API定义结构

MCP服务器需要配置目录中的OpenAPI/Swagger JSON文件。每个文件都应该遵循OpenAPI 3.0规范格式。

目录结构示例

api-definitions/
├── auth.swagger.json
├── projects.swagger.json
├── users.swagger.json
└── ...

API定义文件结构示例

每个API定义文件应包含以下结构：

{
  "openapi": "3.0.0",
  "info": {
    "title": "Authentication API",
    "version": "v1",
    "description": "API for authentication operations"
  },
  "tags": [
    {
      "name": "Auth",
      "description": "Authentication endpoints"
    }
  ],
  "paths": {
    "/api/Auth/login": {
      "post": {
        "tags": ["Auth"],
        "summary": "User login",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoginCommand"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful login",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthResponseDto"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LoginCommand": {
        "type": "object",
        "properties": {
          "username": {
            "type": "string"
          },
          "password": {
            "type": "string"
          }
        },
        "required": ["username", "password"]
      },
      "AuthResponseDto": {
        "type": "object",
        "properties": {
          "token": {
            "type": "string"
          },
          "user": {
            "$ref": "#/components/schemas/UserDto"
          }
        }
      },
      "UserDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "username": {
            "type": "string"
          },
          "email": {
            "type": "string"
          }
        }
      }
    }
  }
}

关键组件

信息科：包含API元数据（标题、版本、说明）
标签：对端点进行分类，以便更好地组织
路径：定义所有API端点及其HTTP方法
组件/架构：定义可重用的数据模型和请求/响应结构

文件命名约定

使用描述性名称： auth.swagger.json, projects.swagger.json
保持名称小写，多单词名称使用连字符
文件名用作API标识符（没有 .swagger.json 扩展）

支持的功能

MCP服务器支持：

多种HTTP方法（GET、POST、PUT、DELETE、PATCH等）
路径参数（例如。， /api/users/{id})
查询参数
请求具有模式引用的主体
响应模式
多个响应状态代码
基于标签的端点分类

示例工作流

查找所有身份验证端点

使用 list_tags 查看可用标签
使用 search_by_tag 使用标签“Auth”查找所有身份验证端点
使用 get_endpoint 获取特定端点的详细信息

探索特定的API

使用 list_apis 查看所有可用的API
使用 get_api_details 获取特定API的概述
使用 list_schemas 查看该API中的所有数据模型
使用 get_schema 获取特定模式的详细信息

按路径搜索端点

使用 search_by_path 使用模式“/api/Auth”查找所有与身份验证相关的端点
使用 search_by_path 使用模式“/api/.*”查找所有端点
使用 get_endpoint 获取特定端点的详细信息

错误处理

在以下情况下，服务器会返回错误消息：

找不到API定义
端点未找到
未找到架构
无效的文件格式
文件读取错误

所有错误均以 isError: true 在响应中标记。

许可证

麻省理工学院

使用说明

API文档MCP服务器

概述

特性

安装

人工智能代理的MCP设置

克劳德代码（克劳德桌面）

Cline（VS代码扩展）

千码

风帆冲浪（Codeium）

光标

通用MCP配置说明

验证MCP连接

用法

运行服务器

可用工具

1. list_apis

2. get_api_details

3. list_tags

4. search_by_tag

5. search_by_path

6. get_endpoint

7. get_schema

8. list_schemas

配置

API定义结构

目录结构示例

API定义文件结构示例

关键组件

文件命名约定

支持的功能

示例工作流

查找所有身份验证端点

探索特定的API

按路径搜索端点

错误处理

许可证

相关 MCP

Swagger解析与代码生成工具

文档搜索服务

API转CLI命令行工具

OpenAPI工具服务器

文档获取服务器

OpenAPI规范服务

1. `list_apis`

2. `get_api_details`

3. `list_tags`

4. `search_by_tag`

5. `search_by_path`

6. `get_endpoint`

7. `get_schema`

8. `list_schemas`