AI导哈

API文档查询工具

基于Swagger/OpenAPI规范的API文档查询工具，提供API列表和详细信息的检索功能。

  • by koseha
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 koseha/api-mcp

使用说明

API MCP服务器

基于Swagger/OpenAPI规范的Model Context Protocol（MCP）服务器。提供通过OpenAPI文档查询API列表和详细信息的工具。

功能

“工具”（Tools）

  • getApiList -查看API列表

    • 在OpenAPI规范中查看所有API端点的列表。
    • 返回类型：每个路径的HTTP方法和 tags, operationId, summary 信息

  • getApiDetail -查看API详细信息

    • 查询特定API的详细信息。
    • 参数： requestUrl （字符串）， httpMethod （获取|发布|放置|删除|补丁）
    • 返回类型： parameters, requestBody, responses 信息

资源（Resources）

  • greeting://{name} -动态问候语生成资源

安装

安装为NPM软件包

npm install @koseha/api-mcp

或者

npm install @koseha/api-mcp@latest

使用方法

方法1:在Cursor IDE中使用

添加到Cursor设置文件：

{
  "mcpServers": {
    "api-mcp": {
      "command": "node",
      "args": ["./node_modules/@koseha/api-mcp/dist/index.js"],
      "env": {
        "OPENAPI_URL": <your swagger.json url ex.'https://petstore3.swagger.io/api/v3/openapi.json'>
      }
    }
  }
}

方法2:在Claude Desktop中使用

添加到Claude Desktop配置文件：

macOS：

~/Library/Application Support/Claude/claude_desktop_config.json

窗户：

%APPDATA%\Claude\claude_desktop_config.json

设置示例：

{
  "mcpServers": {
    "api-mcp": {
      "command": "npx",
      "args": ["-y", "@koseha/api-mcp"],
      "env": {
        "OPENAPI_URL": "https://api.example.com/openapi.json"
      }
    }
  }
}

或使用本地路径：

{
  "mcpServers": {
    "api-mcp": {
      "command": "node",
      "args": ["/path/to/api-mcp/dist/index.js"],
      "env": {
        "OPENAPI_URL": "https://api.example.com/openapi.json"
      }
    }
  }
}

方法3:直接在Node.js项目中使用

import { spawn } from "child_process";

const mcpServer = spawn("npx", ["-y", "@koseha/api-mcp"], {
  stdio: ["pipe", "pipe", "pipe"],
});

// JSON-RPC 요청 보내기
function sendRequest(method, params) {
  const request = {
    jsonrpc: "2.0",
    id: Date.now(),
    method,
    params: params || {},
  };
  mcpServer.stdin?.write(JSON.stringify(request) + "\n");
}

// API 목록 조회
sendRequest("tools/call", {
  name: "getApiList",
  arguments: {},
});

// API 상세 조회
sendRequest("tools/call", {
  name: "getApiDetail",
  arguments: {
    requestUrl: "/pet/{petId}/uploadImage",
    httpMethod: "post",
  },
});

方法4:在本地开发中使用

使用npm link

在当前项目中：

npm link

在其他项目中：

npm link @koseha/api-mcp

使用相对路径

其他项目的 package.json添加到：

{
  "dependencies": {
    "@koseha/api-mcp": "file:../api-mcp"
  }
}

开发

前提条件

  • Node.js 18或更高版本
  • npm或yarn

安装

npm install

构建

npm run build

执行

npm start

或开发模式：

npm run dev

项目结构

api-mcp/
├── src/
│   ├── index.ts              # MCP 서버 엔트리포인트
│   ├── server.ts             # 서버 생성 로직
│   ├── tools/                # 도구 모듈
│   │   ├── index.ts
│   │   ├── getApiList.tool.ts    # API 목록 조회 도구
│   │   └── getApiDetail.tool.ts  # API 상세 조회 도구
│   ├── resources/            # 리소스 모듈
│   │   ├── index.ts
│   │   └── greeting.resource.ts
│   └── swagger/              # Swagger 로더 및 변환기
│       ├── swaggerLoader.ts
│       ├── apiTransformer.ts
│       ├── schemaResolver.ts
│       └── types.ts
├── dist/                     # 빌드된 파일
├── openapi.json             # OpenAPI 스펙 파일
├── package.json
├── tsconfig.json
└── README.md

OpenAPI规格设置

OPENAPI_URL 必须通过环境变量设置OpenAPI文档的URL。如果在服务器启动时未设置此环境变量，服务器将无法启动。

示例：

export OPENAPI_URL=https://api.example.com/openapi.json

依赖性

生产依赖性

  • @modelcontextprotocol/sdk：MCP SDK（^1.25.1）
  • zod：模式验证（^4.2.1）

开发依赖性

  • typescript：类型脚本编译器（^5.9.3）
  • @types/node：Node.js类型定义（^25.0.3）
  • ts-node：TypeScript执行工具（^10.9.2）

版本

当前版本： 0.0.10

历史

版本日期更改 | ------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | 0.0.10 KST2025.12.31-将OpenAPI文档更改为按HTTP请求加载
-添加OPENAPI_URL环境变量必需验证
-API详细查询逻辑重构（apiTransformer模块化）| 0.0.7 KST2025.12.31--tool请求时，仅提取并使用openapi.json文档的特定部分
>>禁用整个openapi.json文档内容。节省token |

许可证

国际学生委员会

参考资料

贡献

热点或完整请求 GitHub存储库欢迎。

相关 MCP