Api MCP Server

🚀 API MCP Server

API MCP Server 是一个轻量级且可扩展的服务器，用于使用 MCP 协议 定义和执行 API 工具。它支持动态 HTTP 请求、类型化参数以及多种传输方式（stdio、sse）。

🚀 快速开始

本部分将引导你完成 API MCP Server 的安装和基本使用。

📦 安装指南

你可以通过以下两种方式安装该服务器：

1. 通过 go install 安装

如果你已经安装了 Go，可以运行以下命令：

go install github.com/AdamShannag/api-mcp-server/cmd/api-mcp-server@v0.2.0

2. 下载预构建的二进制文件

你可以从 发布页面 下载二进制文件。

📚 详细文档

CLI 标志

环境变量

工具配置占位符

工具配置文件支持使用以下语法进行环境变量替换：

{{env VAR_NAME:default_value}}

在运行时，占位符将被相应的环境变量替换。如果未设置该变量，则使用 default_value。

示例

"host": "{{env API_HOST:jsonplaceholder.typicode.com}}"

如果设置了 API_HOST，则使用其值，否则使用默认值。

"Authorization": "Bearer {{env API_KEY:not-set}}"

使用 API_KEY 的值，如果未定义，则使用 "not-set"。

在运行服务器之前，请设置所需的环境变量：

export API_HOST=myapi.example.com
export API_KEY=supersecret123

身份验证

使用 SSE 传输时，你可以通过设置 API_MCP_SSE_API_KEY 环境变量，可选地使用 Bearer 令牌来保护端点。

示例：

export API_MCP_SSE_API_KEY="your-secret-key"
api-mcp-server --transport sse --config ./demo.tools.json

传入的 SSE 连接必须在 Authorization 头中提供匹配的令牌。

工具配置（JSON）

服务器接受一个 JSON 配置文件，该文件定义了一个或多个工具。每个工具包括元数据（name、description）、HTTP 请求信息以及一个 args 列表，用于定义从大语言模型（LLM）所需的输入值。

每个工具配置包括：

• 唯一的 name
• 显示给 LLM 的 description
• 描述 HTTP 调用的 request 对象
• 定义预期输入的 args 列表

工具参数（args）

参数是从 LLM 收集的输入。每个参数可以在请求的一个或多个部分中使用：

• 路径参数 → 直接替换 endpoint 中的变量
• 查询参数 → 自动添加到 URL 中
• 请求体 → 作为原始请求体字符串插入

主机（host）

host 是目标 API 域（例如，gitlab.com）。

"host": "{{env GITLAB_API_HOST:gitlab.com}}"

方法（method）

HTTP 方法（GET、POST、PUT 等）。

"method": "POST"

路径参数（pathParams）

用于替换 endpoint 中的变量。例如：

"endpoint": "/api/v4/projects/:project_id/pipeline",
"pathParams": ["project_id"]

当 project_id = "MyProject/test" 时，最终的端点变为：

/api/v4/projects/MyProject%2Ftest/pipeline

查询参数（queryParams）

此处列出的键将自动作为查询字符串参数附加到端点：

"endpoint": "/api/v4/projects/:project_id/pipeline",
"queryParams": ["ref"]

当 ref = "main" 时，结果为：

/api/v4/projects/MyProject%2Ftest/pipeline?ref=main

请求体（body）

body 字段映射到单个参数名称。其值将作为原始请求体字符串使用。

示例：

"body": "issue_payload"

给定以下参数：

{
  "name": "issue_payload",
  "type": "string",
  "required": true,
  "description": "一个 JSON 对象，如 {\"title\": \"Bug report\"}"
}

发送到服务器的请求体将是 issue_payload 的精确字符串值。

头信息（headers）

定义要包含在请求中的静态或动态 HTTP 头信息，例如令牌或内容类型：

"headers": {
  "PRIVATE-TOKEN": "{{env GITLAB_TOKEN:not-set}}",
  "Content-Type": "application/json"
}

安全（secure）

如果 secure: true，则请求使用 https。如果省略或 false，则使用 http。

完整示例

{
  "name": "TriggerPipeline",
  "description": "在 GitLab 中为特定项目和分支触发管道。",
  "request": {
    "host": "{{env GITLAB_API_HOST:gitlab.com}}",
    "method": "POST",
    "secure": true,
    "endpoint": "/api/v4/projects/:project_id/pipeline",
    "headers": {
      "PRIVATE-TOKEN": "{{env GITLAB_TOKEN:not-set}}"
    },
    "queryParams": [
      "ref"
    ],
    "pathParams": [
      "project_id"
    ]
  },
  "args": [
    {
      "name": "project_id",
      "type": "string",
      "required": true,
      "description": "..."
    },
    {
      "name": "ref",
      "type": "string",
      "required": true,
      "description": "..."
    }
  ]
}

如果 project_id = "MyProject/test" 且 ref = "main"，则最终的 HTTP 请求为：

POST https://gitlab.com/api/v4/projects/MyProject%2Ftest/pipeline?ref=main
头信息:
  PRIVATE-TOKEN: <GITLAB_TOKEN 的值>

💻 使用示例

本仓库包含多个示例工具配置，用于演示不同的用例。这些不是可直接使用的 API，而是作为参考：

GitLab 问题

用于列出和创建 GitLab 项目中的问题的工具。 请参阅 examples/gitlab

JSONPlaceholder 待办事项

与 JSONPlaceholder 公共 API 交互的工具。 请参阅 examples/jsonplaceholder

📄 许可证

本项目采用 MIT 许可证。

💪 贡献

如果你有任何问题或想要贡献代码，请随时打开问题或提交拉取请求。