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 許可證。

💪 貢獻

如果你有任何問題或想要貢獻代碼，請隨時打開問題或提交拉取請求。