apipost-mcp-server-simple 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joey Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# Apipost MCP Server
+
+这是一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 实现的 Apipost 服务端。它允许 AI Agent（如 Claude Desktop、Cursor、Cline、Antigravity 等）直接读取您在 Apipost 中的接口定义，并能够发起 API 请求以获取实时响应。
+
+## 🚀 功能特性
+
+- **自动同步接口**: 通过 Apipost 的 OpenAPI 3.0 分享链接，自动加载最新的接口定义。
+- **资源浏览**: 提供 `apipost://apis` 资源，方便 AI 了解所有可用的端点、方法及功能描述。
+- **动态执行**: 提供 `run_api_request` 工具，AI 可以根据需求构造参数并直接调用接口，获取真实业务数据。
+- **灵活配置**: 支持通过环境变量自定义 API 基础路径（Base URL），解决接口定义中缺少服务器地址的问题。
+
+## ⚙️ 配置说明
+
+在使用本服务前，通常需要配置以下环境变量：
+
+| 变量名 | 描述 | 示例 |
+| :--- | :--- | :--- |
+| `APIPOST_OPENAPI_URL` | **(必填)** Apipost 项目的 OpenAPI 分享链接 | `https://openapi.apipost.net/swagger/v3/...` |
+| `APIPOST_API_BASE_URL` | **(推荐)** 接口执行的实际后端基础 URL | `https://api.example.com` |
+| `APIPOST_HEADERS` | **(可选)** 全局鉴权 Headers，必须为 JSON 字符串 | `{"Authorization":"Bearer token"}` |
+
+## 🛠️ 使用方式
+
+### 方式一：直接通过 npx 运行 (推荐)
+
+这是最简单的方式，无需下载代码，直接在您的 AI 客户端配置中添加即可。
+
+以 **Claude Desktop** 或 **Cursor** 为例，在 MCP 设置中添加如下配置：
+
+```json
+{
+  "mcpServers": {
+    "apipost": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "apipost-mcp-server-simple"
+      ],
+      "env": {
+        "APIPOST_OPENAPI_URL": "您的 OpenAPI 分享链接",
+        "APIPOST_API_BASE_URL": "您的后端服务地址",
+        "APIPOST_HEADERS": "{\"Authorization\":\"Bearer your_token\"}"
+      }
+    }
+  }
+}
+```
+
+### 方式二：本地开发运行
+
+如果您需要修改代码或在本地调试运行：
+
+1. **克隆并安装依赖**：
+   ```bash
+   git clone <your-repo-url>
+   cd ApipostMcpServer
+   npm install
+   ```
+
+2. **配置本地环境**：
+   在项目根目录创建 `.env` 文件，参照上述“配置说明”填写内容。
+
+3. **编译并启动**：
+   ```bash
+   npm run build
+   npm start
+   ```
+
+4. **客户端配置**：
+   在 AI 客户端配置中指向本地路径：
+   ```json
+   "apipost": {
+     "command": "node",
+     "args": ["/绝对路径/到/项目/dist/index.js"],
+     "env": { ... }
+   }
+   ```
+
+## 🔒 鉴权说明
+
+本 Server 支持两种鉴权模式：
+1. **隐式注入 (推荐)**：在环境变量中设置 `APIPOST_HEADERS`，AI 客户端无需感知 Token，服务端自动补全，更安全。
+2. **显式传递**：AI 可以在调用工具时，通过 `headers` 参数手动传递 Token，适用于需要动态切换身份的场景。
+   - 注意：显式传递的 Header 优先级高于隐式注入。
+
+## 📝 暴露的接口
+
+### 资源 (Resources)
+- `apipost://apis`: 返回 JSON 格式的接口列表，包含所有可用接口的 Method、Path 和 Summary。
+
+### 工具 (Tools)
+- `run_api_request`:
+  - `method`: HTTP 方法 (GET, POST, PUT, DELETE 等)。
+  - `path`: 接口路径。
+  - `params`: Query 参数对象。
+  - `body`: 请求体 JSON。
+  - `headers`: 自定义请求头。
+
+## 📄 许可证
+MIT

package/dist/apipost-client.js

@@ -0,0 +1,134 @@
+import axios from 'axios';
+import fs from 'fs/promises';
+export class ApipostClient {
+    openApiUrl;
+    openApiFilePath;
+    apiBaseUrl;
+    globalHeaders = {};
+    spec = null;
+    constructor(config) {
+        this.openApiUrl = config.openApiUrl;
+        this.openApiFilePath = config.openApiFilePath;
+        this.apiBaseUrl = config.apiBaseUrl;
+        // 解析全局 Headers 字符串，例如: "{"Authorization":"Bearer xxx","X-Key":"yyy"}"
+        if (config.globalHeaders) {
+            try {
+                this.globalHeaders = JSON.parse(config.globalHeaders);
+            }
+            catch (e) {
+                console.error('解析 APIPOST_HEADERS 失败，请确保它是正确的 JSON 字符串:', e);
+            }
+        }
+    }
+    /**
+     * 加载 OpenAPI 定义
+     * 根据配置决定从 URL 下载还是读取本地文件。
+     */
+    async loadDefinition() {
+        if (this.openApiUrl) {
+            try {
+                console.error(`正在从 URL 获取 OpenAPI 定义: ${this.openApiUrl}...`);
+                const response = await axios.get(this.openApiUrl);
+                // 显式断言类型
+                this.spec = response.data;
+            }
+            catch (error) {
+                throw new Error(`无法从 URL 获取 OpenAPI 定义: ${error?.message || error}`);
+            }
+        }
+        else if (this.openApiFilePath) {
+            try {
+                console.error(`正在从文件读取 OpenAPI 定义: ${this.openApiFilePath}...`);
+                const content = await fs.readFile(this.openApiFilePath, 'utf-8');
+                this.spec = JSON.parse(content);
+            }
+            catch (error) {
+                throw new Error(`无法从文件读取 OpenAPI 定义: ${error?.message || error}`);
+            }
+        }
+        else {
+            throw new Error('未提供 OpenAPI URL 或文件路径。');
+        }
+        if (!this.spec) {
+            throw new Error('OpenAPI 规范为空。');
+        }
+        return this.spec;
+    }
+    /**
+     * 获取 API 列表
+     * 提取可用的端点 (Endpoints) 和方法 (Methods)。
+     */
+    getApiList() {
+        if (!this.spec || !this.spec.paths)
+            return [];
+        const apis = [];
+        for (const [path, pathItem] of Object.entries(this.spec.paths)) {
+            const methods = ['get', 'post', 'put', 'delete', 'patch'];
+            for (const method of methods) {
+                if (pathItem[method]) {
+                    const operation = pathItem[method];
+                    apis.push({
+                        method: method.toUpperCase(),
+                        path,
+                        summary: operation.summary,
+                        description: operation.description,
+                    });
+                }
+            }
+        }
+        return apis;
+    }
+    /**
+     * 确定执行的基础 URL (Base URL)。
+     * 优先级:
+     * 1. 环境变量 APIPOST_API_BASE_URL
+     * 2. OpenAPI 规范中的第一个 servers URL
+     * 3. 如果都未找到或无效，抛出错误。
+     */
+    getBaseUrl() {
+        if (this.apiBaseUrl) {
+            return this.apiBaseUrl;
+        }
+        if (this.spec?.servers && this.spec.servers.length > 0 && this.spec.servers[0].url) {
+            return this.spec.servers[0].url;
+        }
+        throw new Error('未配置 Base URL。请在 .env 中设置 APIPOST_API_BASE_URL 或确保 OpenAPI 规范包含有效的 server URL。');
+    }
+    /**
+     * 执行 API 请求
+     */
+    async executeApi(method, path, params, body, headers) {
+        if (!this.spec) {
+            await this.loadDefinition();
+        }
+        const baseUrl = this.getBaseUrl();
+        const url = `${baseUrl}${path}`;
+        console.error(`正在执行 API: ${method} ${url}`);
+        try {
+            const response = await axios({
+                method: method,
+                url,
+                params,
+                data: body,
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...this.globalHeaders, // 注入环境变量中的全局 Header
+                    ...headers, // 注入 AI 传递的临时 Header (优先级更高)
+                },
+            });
+            return response.data;
+        }
+        catch (error) {
+            if (axios.isAxiosError(error)) {
+                return {
+                    status: error.response?.status,
+                    statusText: error.response?.statusText,
+                    data: error.response?.data,
+                    headers: error.response?.headers,
+                    message: error.message
+                };
+            }
+            throw error;
+        }
+    }
+}

package/dist/index.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { ApipostClient } from './apipost-client.js';
+import dotenv from 'dotenv';
+dotenv.config();
+const server = new McpServer({
+    name: 'Apipost MCP Server Simple',
+    version: '1.0.0',
+});
+const client = new ApipostClient({
+    openApiUrl: process.env.APIPOST_OPENAPI_URL,
+    openApiFilePath: process.env.APIPOST_OPENAPI_FILE,
+    apiBaseUrl: process.env.APIPOST_API_BASE_URL,
+    globalHeaders: process.env.APIPOST_HEADERS
+});
+// 资源: 获取 API 列表
+server.resource("apis", "apipost://apis", async (uri) => {
+    try {
+        await client.loadDefinition(); // 确保已加载
+        const apis = client.getApiList();
+        return {
+            contents: [{
+                    uri: uri.href,
+                    text: JSON.stringify(apis, null, 2),
+                    mimeType: "application/json"
+                }]
+        };
+    }
+    catch (error) {
+        return {
+            contents: [{
+                    uri: uri.href,
+                    text: `加载 API 列表失败: ${error.message}`,
+                    mimeType: "text/plain"
+                }]
+        };
+    }
+});
+// 工具: 执行 API 请求
+server.tool("run_api_request", "执行 Apipost 中定义的 API 请求。", {
+    method: z.string().describe("HTTP 方法 (GET, POST 等)"),
+    path: z.string().describe("API 路径 (例如: /users/1)"),
+    params: z.record(z.string(), z.any()).optional().describe("查询参数 (Query parameters)"),
+    body: z.any().optional().describe("请求体 (JSON)"),
+    headers: z.record(z.string(), z.string()).optional().describe("自定义 Header")
+}, async ({ method, path, params, body, headers }) => {
+    try {
+        // 确保定义已加载
+        await client.loadDefinition();
+        // 检查路径是否存在于规范中
+        const apis = client.getApiList();
+        const apiExists = apis.some(api => api.path === path && api.method === method.toUpperCase());
+        if (!apiExists) {
+            // 宽松检查: 有时路径可能包含变量如 {id}，如果用户传递了解析后的路径，精确匹配可能会失败。
+            // 目前我们继续执行，但可能需要记录警告。
+            // 实际上，axios execution 会处理提供的路径。
+            // 对于 MVP，我们跳过严格验证，相信用户/LLM 会选择正确的路径。
+        }
+        const result = await client.executeApi(method, path, params, body, headers);
+        return {
+            content: [{
+                    type: "text",
+                    text: typeof result === 'string' ? result : JSON.stringify(result, null, 2)
+                }]
+        };
+    }
+    catch (error) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `执行 API 失败: ${error.message}\n${JSON.stringify(error.response?.data || {}, null, 2)}`
+                }],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    try {
+        // 启动时预加载以验证配置
+        await client.loadDefinition();
+        console.error(`成功加载 OpenAPI 定义，包含 ${client.getApiList().length} 个 API。`);
+    }
+    catch (e) {
+        console.error(`警告: 启动时加载 OpenAPI 定义失败: ${e.message}`);
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Apipost MCP Server Simple 正在通过 stdio 运行");
+}
+main().catch((error) => {
+    console.error("main() 发生致命错误:", error);
+    process.exit(1);
+});

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "apipost-mcp-server-simple",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "ts-node src/index.ts"
+  },
+  "type": "module",
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "description": "Apipost MCP Server for AI Agents",
+  "bin": {
+    "apipost-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "axios": "^1.13.2",
+    "dotenv": "^17.2.3",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.7",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}