API 建议服务器

概要

API 建议服务器是一个 MCP（模型上下文协议）服务器，它基于 OpenAPI 规范来建议合适的 API 端点。该服务器根据用户的目的和需求，从可用的 API 端点中推荐最佳的端点。

功能

• 从多个 OpenAPI 规范（YAML 或 JSON 格式）收集 API 端点信息
• 根据用户的目的推荐相关的 API 端点
• 通过 MCP 协议与 AI 模型协作

前提条件

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

安装

# 克隆仓库
git clone https://github.com/yourusername/api-mcp-server.git
cd api-mcp-server

# 安装依赖
npm install

配置

服务器的配置在 server.config.ts 文件中管理。您可以如下所示修改配置：

import { ServerConfig } from "./src/types.ts";

export const config: ServerConfig = {
  name: "api-suggestion-server",
  version: "1.0.0",
  services: [
    {
      name: "服务名称",
      // 指定 OpenAPI 规范的 URL
      openApiUrl: "https://example.com/api/openapi.json"
    },
    {
      name: "另一个服务",
      // 指定本地文件路径（YAML 或 JSON）
      openApiFilePath: "./schemas/your-api.yaml"
    }
  ]
};

使い方 (使用方法)

サーバーの起動 (启动服务器)

npm start

服务器通过标准输入/输出（stdio）以 MCP 协议进行通信。

実行例 (执行示例)

以下是实际使用 API 建议服务器的示例：

1. 启动服务器：

# 在终端中启动服务器
npm start

2. 与 MCP 兼容的 AI 模型（例如：Claude）协作：

// 使用 MCP 协议设置与 AI 模型的对话
const conversation = await anthropic.messages.create({
  model: "claude-3-sonnet-20240229",
  max_tokens: 1000,
  messages: [{ role: "user", content: "是否有获取用户信息的 API？" }],
  tools: [
    {
      // API 建议服务器的工具配置
      name: "suggest_api",
      description: "建议适合指定用途的 API 端点。",
      input_schema: {
        type: "object",
        properties: {
          purpose: {
            type: "string",
            description: "想要使用 API 端点的用途或目的的说明。",
          },
        },
        required: ["purpose"],
      }
    }
  ],
  tool_choice: "auto"
});

// 处理来自 AI 模型响应的工具调用
if (conversation.content[0].type === "tool_use") {
  const toolUse = conversation.content[0];
  
  // 将工具调用转发到 MCP 服务器
  // 这里进行了简化，但实际上需要按照 MCP 协议的规范进行通信
  const result = await mcpClient.callTool(toolUse.name, toolUse.input);
  
  // 将工具的结果返回给 AI 模型
  const followUp = await anthropic.messages.create({
    model: "claude-3-sonnet-20240229",
    max_tokens: 1000,
    messages: [
      { role: "user", content: "是否有获取用户信息的 API？" },
      { role: "assistant", content: toolUse },
      { 
        role: "user", 
        content: [
          { type: "tool_result", tool_use_id: toolUse.id, content: JSON.stringify(result) }
        ]
      }
    ]
  });
  
  console.log(followUp.content);
}

3. 执行结果示例：

AI 模型将使用从服务器提供的 API 端点信息生成如下响应：

是的，有一些 API 端点可以用来获取用户信息：

1. GET /users/{userId}
   - 说明：获取指定 ID 的用户信息
   - 服务：示例 API

2. GET /users
   - 说明：获取所有已注册用户的列表
   - 服务：示例 API

要获取特定用户的信息，请使用 "GET /users/{userId}" 并将用户 ID 指定为路径参数。要一次获取多个用户信息，可以使用 "GET /users"。

### AIモデルとの連携 (与 AI 模型协作)

该服务器实现了 MCP 协议，可以与 Claude、GPT-4 等 AI 模型协作。AI 模型可以调用以下工具：

#### suggest_api

建议适合指定用途的 API 端点。

**输入参数**:
- `purpose`: 想要使用 API 端点的用途或目的的说明（字符串）

**输出**:
- 相关 API 端点的列表（包括服务名称、路径、方法和说明）

**使用例**:
```json
{
  "name": "suggest_api",
  "arguments": {
    "purpose": "获取用户信息"
  }
}

応答例 (响应示例):

{
  "toolResult": [
    {
      "service": "示例 API",
      "path": "/users/{userId}",
      "method": "GET",
      "description": "获取指定 ID 的用户信息"
    },
    {
      "service": "示例 API",
      "path": "/users",
      "method": "GET",
      "description": "获取所有已注册用户的列表"
    }
  ]
}

カスタマイズ (自定义)

新しいOpenAPI仕様の追加 (添加新的 OpenAPI 规范)

1. 将 OpenAPI 规范文件（YAML 或 JSON）添加到 schemas 目录，或准备一个公共 URL
2. 编辑 server.config.ts 文件以添加新服务

サポートされるフォーマット (支持的格式)

• YAML 格式的 OpenAPI 规范（.yaml 或 .yml 扩展名）
• JSON 格式的 OpenAPI 规范（.json 扩展名）
• URL 指定的 OpenAPI 规范（根据内容类型自动解析）

開発 (开发)

ビルド (构建)

npm run build

テスト (测试)

您可以使用以下命令运行测试：

# 运行所有测试
npm test

# 在观察模式下运行测试（在开发期间很有用）
npm run test:watch

# 生成覆盖率报告
npm run test:coverage

测试分为以下几类：

• utils.test.ts: OpenAPI 文档解析功能的测试
• server.test.ts: 服务器初始化测试
• suggest-api.test.ts: API 建议功能测试

如果要添加新测试，请在 src/tests 目录中创建一个 *.test.ts 文件。

ディレクトリ構造 (目录结构)

api-mcp-server/
├── src/
│   ├── index.ts        # 主服务器代码
│   ├── utils.ts        # 实用程序函数
│   ├── types.ts        # 类型定义
│   └── tests/          # 测试文件
├── schemas/            # OpenAPI 规范文件
├── server.config.ts    # 服务器配置
├── tsconfig.json       # TypeScript 配置
└── package.json        # 项目配置

ライセンス (许可证)

MIT

貢献 (贡献)

请通过 GitHub 的 Issue 跟踪器提交错误报告或功能请求。欢迎提交 Pull Request。