#!/usr/bin/env node
// 引入必要的模块
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
// 创建 MCP 服务器实例，并声明其支持工具能力[1,4](@ref)
const server = new McpServer({
name: "swagger-doc-server",
version: "1.0.0",
capabilities: {
tools: { listChanged: true }, // 告知客户端本服务器支持工具
},
});
// 配置您的 Swagger 文档信息
const SWAGGER_CONFIG = {
url: "https://your-api-server.com/v2/api-docs", // 请替换为您的 Swagger 文档 JSON 地址
username: "your_username", // 请替换为您的账号
password: "your_password", // 请替换为您的密码
};
// 注册一个核心工具：获取 Swagger 接口详情[1,5](@ref)
server.tool(
"get_swagger_definition", // 工具名称，Trae 将通过此名称调用
{
// 定义工具的参数和验证规则
path: z.string().describe("API接口路径，例如 /api/resource/{id}"),
method: z.enum(["GET", "POST", "PUT", "DELETE"]).describe("HTTP 方法"),
},
async ({ path, method }) => {
try {
// 1. 准备认证信息（HTTP Basic Auth）[6](@ref)
const authHeader = "Basic " + Buffer.from(`${SWAGGER_CONFIG.username}:${SWAGGER_CONFIG.password}`).toString("base64");
// 2. 携带认证信息请求 Swagger 文档
const response = await fetch(SWAGGER_CONFIG.url, {
headers: { Authorization: authHeader },
});
if (!response.ok) {
throw new Error(`获取Swagger文档失败: ${response.status} ${response.statusText}`);
}
const swaggerJson = await response.json();
// 3. 从 Swagger JSON 中查找目标接口
let targetEndpoint = null;
if (swaggerJson.paths && swaggerJson.paths[path]) {
targetEndpoint = swaggerJson.paths[path][method.toLowerCase()];
}
// 4. 组织并返回找到的接口信息
if (targetEndpoint) {
let resultText = `接口路径: ${method} ${path}\n`;
resultText += `简介: ${targetEndpoint.summary || "无"}\n\n`;
resultText += `描述: ${targetEndpoint.description || "无"}\n\n`;
// 处理请求参数
if (targetEndpoint.parameters) {
resultText += `请求参数:\n`;
targetEndpoint.parameters.forEach(param => {
resultText += ` - ${param.name} (${param.in}, ${param.required ? "必选" : "可选"}): ${param.description || "无描述"}\n`;
});
}
// 处理响应体
if (targetEndpoint.responses) {
resultText += `\n响应:\n`;
Object.entries(targetEndpoint.responses).forEach(([code, response]) => {
resultText += ` - ${code}: ${response.description || "无描述"}\n`;
});
}
return {
content: [{ type: "text", text: resultText }],
};
} else {
return {
content: [{ type: "text", text: `在Swagger文档中未找到接口: ${method} ${path}` }],
isError: true,
};
}
} catch (error) {
console.error("MCP Server Error:", error);
return {
content: [{ type: "text", text: `查询Swagger时发生错误: ${error.message}` }],
isError: true,
};
}
}
);
// 启动服务器，使用标准输入/输出（stdio）与 Trae IDE 通信[3](@ref)
async function main() {
const transport = new StdioServerTransport();
await server.connect(transport);
console.error("Swagger MCP 服务器已启动，等待 Trae IDE 连接...");
}
main().catch(console.error);
