transn-yapi-mcp 0.1.0

package/README.md

@@ -0,0 +1,106 @@
+# transn-yapi-mcp
+
+An MCP (Model Context Protocol) server that connects to a YAPI instance and exposes
+its API definitions as tools for AI agents or MCP-compatible clients.
+
+## Features
+
+- Query YAPI interface definitions by **interfaceId**.
+- Query YAPI interface definitions by **path + projectId**.
+- Return structured metadata that is easy to consume in tooling:
+  - name, path, method, description
+  - request query & body schema
+  - response schema
+
+## Installation
+
+```bash
+npm install transn-yapi-mcp
+# or
+pnpm add transn-yapi-mcp
+```
+
+## Usage
+
+The package is designed to be run as an MCP server over **stdio**.
+Typical MCP client configuration (example):
+
+```jsonc
+{
+  "mcpServers": {
+    "yapi-mcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["transn-yapi-mcp"],
+      "env": {
+        "YAPI_BASE": "https://your-yapi-domain.com",
+        "YAPI_TOKEN": "your_yapi_openapi_token"
+      }
+    }
+  }
+}
+```
+
+### Required environment variables
+
+- `YAPI_BASE`  
+  Base URL of your YAPI instance, without a trailing slash.  
+  Example: `https://yapi.example.com`
+
+- `YAPI_TOKEN`  
+  YAPI openapi token for the target project(s). It is passed as `token` query parameter.
+
+## Exposed tools
+
+### `yapi.get_api_context`
+
+Get structured API context from a YAPI interface.
+
+**Input**
+
+```ts
+{
+  interfaceId: number;      // required
+  projectId?: number;       // optional, for disambiguation
+}
+```
+
+**Output (shape, simplified)**
+
+```ts
+{
+  name: string;
+  path: string;
+  method: string;
+  description: string;
+  request: {
+    query: unknown;
+    body: unknown;
+  };
+  response: unknown;
+}
+```
+
+### `yapi.get_api_context_by_path`
+
+Get API context by path within a YAPI project.
+
+**Input**
+
+```ts
+{
+  projectId: number;        // required
+  path: string;             // required, e.g. "/busi/patient/detail_by_openid"
+  method?: string;          // optional, e.g. "GET"
+}
+```
+
+**Output**
+
+Same shape as `yapi.get_api_context`.
+
+## License
+
+MIT
+
+

package/dist/index.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { tools } from "./tools.js";
+const server = new McpServer({
+    name: "@transn/yapi-mcp",
+    version: "0.1.0"
+});
+// 注册工具
+for (const tool of tools) {
+    server.registerTool(tool.name, {
+        description: tool.description,
+        inputSchema: tool.inputSchema
+    }, tool.handler);
+}
+const transport = new StdioServerTransport();
+await server.connect(transport);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,kBAAkB;IACxB,OAAO,EAAE,OAAO;CACjB,CAAC,CAAC;AAEH,OAAO;AACP,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;IACzB,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE;QAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;KAC9B,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;AACnB,CAAC;AAED,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;AAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC"}

package/dist/tools.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { getInterface, getInterfaceByPath } from "./yapi.js";
+export const tools = [
+    {
+        name: "yapi.get_api_context",
+        description: "Get structured API context from YAPI",
+        inputSchema: z.object({
+            projectId: z.number().optional(),
+            interfaceId: z.number()
+        }),
+        handler: async ({ projectId, interfaceId }) => {
+            const api = projectId
+                ? await getInterface(projectId, interfaceId)
+                : await getInterface(interfaceId);
+            return {
+                name: api.title,
+                path: api.path,
+                method: api.method,
+                description: api.desc,
+                request: {
+                    query: api.req_query,
+                    body: api.req_body_other
+                },
+                response: api.res_body
+            };
+        }
+    },
+    {
+        name: "yapi.get_api_context_by_path",
+        description: "Get API context by path within a YAPI project",
+        inputSchema: z.object({
+            projectId: z.number(),
+            path: z.string(),
+            method: z.string().optional()
+        }),
+        handler: async ({ projectId, path, method }) => {
+            const api = await getInterfaceByPath(projectId, path, method);
+            return {
+                name: api.title,
+                path: api.path,
+                method: api.method,
+                description: api.desc,
+                request: {
+                    query: api.req_query,
+                    body: api.req_body_other
+                },
+                response: api.res_body
+            };
+        }
+    }
+];
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE7D,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB;QACE,IAAI,EAAE,sBAAsB;QAC5B,WAAW,EAAE,sCAAsC;QACnD,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;YACpB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;YAChC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;SACxB,CAAC;QACF,OAAO,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,WAAW,EAA+C,EAAE,EAAE;YACzF,MAAM,GAAG,GAAG,SAAS;gBACnB,CAAC,CAAC,MAAM,YAAY,CAAC,SAAS,EAAE,WAAW,CAAC;gBAC5C,CAAC,CAAC,MAAM,YAAY,CAAC,WAAW,CAAC,CAAC;YAEpC,OAAO;gBACL,IAAI,EAAE,GAAG,CAAC,KAAK;gBACf,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,WAAW,EAAE,GAAG,CAAC,IAAI;gBACrB,OAAO,EAAE;oBACP,KAAK,EAAE,GAAG,CAAC,SAAS;oBACpB,IAAI,EAAE,GAAG,CAAC,cAAc;iBACzB;gBACD,QAAQ,EAAE,GAAG,CAAC,QAAQ;aACvB,CAAC;QACJ,CAAC;KACF;IACD;QACE,IAAI,EAAE,8BAA8B;QACpC,WAAW,EAAE,+CAA+C;QAC5D,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;YACpB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;YACrB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;YAChB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;SAC9B,CAAC;QACF,OAAO,EAAE,KAAK,EACZ,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAwD,EACjF,EAAE;YACF,MAAM,GAAG,GAAG,MAAM,kBAAkB,CAAC,SAAS,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;YAE9D,OAAO;gBACL,IAAI,EAAE,GAAG,CAAC,KAAK;gBACf,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,WAAW,EAAE,GAAG,CAAC,IAAI;gBACrB,OAAO,EAAE;oBACP,KAAK,EAAE,GAAG,CAAC,SAAS;oBACpB,IAAI,EAAE,GAAG,CAAC,cAAc;iBACzB;gBACD,QAAQ,EAAE,GAAG,CAAC,QAAQ;aACvB,CAAC;QACJ,CAAC;KACF;CACF,CAAC"}

package/dist/yapi.js

@@ -0,0 +1,61 @@
+import fetch from "node-fetch";
+// YAPI 基础地址，末尾不要加斜杠，必填通过环境变量提供
+const YAPI_BASE = process.env.YAPI_BASE;
+// YAPI 的 openapi token（从环境变量读取，放在查询参数 token），避免依赖登录态 Cookie
+const YAPI_TOKEN = process.env.YAPI_TOKEN;
+export async function getInterface(projectIdOrInterfaceId, maybeInterfaceId) {
+    // 兼容两种调用：仅传接口 ID；或传 projectId + 接口 ID
+    const interfaceId = maybeInterfaceId ?? projectIdOrInterfaceId;
+    const projectId = maybeInterfaceId ? projectIdOrInterfaceId : undefined;
+    const params = new URLSearchParams({
+        id: String(interfaceId),
+        token: YAPI_TOKEN
+    });
+    if (projectId !== undefined) {
+        params.set("project_id", String(projectId));
+    }
+    const url = `${YAPI_BASE}/api/interface/get?${params.toString()}`;
+    const res = await fetch(url);
+    const json = await res.json();
+    if (json.errcode !== 0) {
+        throw new Error(json.errmsg);
+    }
+    return json.data;
+}
+async function listInterfaces(projectId) {
+    const pageSize = 200;
+    const result = [];
+    let page = 1;
+    // 分页拉取，直到达到总数或无更多数据
+    while (true) {
+        const url = `${YAPI_BASE}/api/interface/list?project_id=${projectId}&page=${page}&limit=${pageSize}&token=${YAPI_TOKEN}`;
+        const res = await fetch(url);
+        const json = await res.json();
+        if (json.errcode !== 0) {
+            throw new Error(json.errmsg);
+        }
+        result.push(...json.data.list);
+        if (result.length >= json.data.count || json.data.list.length === 0) {
+            break;
+        }
+        page += 1;
+    }
+    return result;
+}
+export async function getInterfaceByPath(projectId, path, method) {
+    const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+    const interfaces = await listInterfaces(projectId);
+    const matches = interfaces.filter((item) => item.path === normalizedPath);
+    const filtered = method
+        ? matches.filter((item) => item.method.toUpperCase() === method.toUpperCase())
+        : matches;
+    const target = filtered[0];
+    if (!target) {
+        const reason = matches.length === 0
+            ? `未找到路径为 ${normalizedPath} 的接口`
+            : `路径匹配到 ${matches.length} 条，但没有匹配到方法 ${method ?? "N/A"}`;
+        throw new Error(reason);
+    }
+    return getInterface(projectId, target._id);
+}
+//# sourceMappingURL=yapi.js.map

package/dist/yapi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yapi.js","sourceRoot":"","sources":["../src/yapi.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "transn-yapi-mcp",
+  "version": "0.1.0",
+  "description": "An MCP server that fetches structured API metadata from YAPI and exposes it as tools.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "transn-yapi-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "package.json",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "author": {
+    "name": "merrick",
+    "email": "merrick.hu@transn.com"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "node-fetch": "^3.3.2",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.3.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { tools } from "./tools.js";
+
+const server = new McpServer({
+  name: "transn-yapi-mcp",
+  version: "0.1.0"
+});
+
+// 注册工具
+for (const tool of tools) {
+  server.registerTool(tool.name, {
+    description: tool.description,
+    inputSchema: tool.inputSchema
+  }, tool.handler);
+}
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/tools.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import { getInterface, getInterfaceByPath } from "./yapi.js";
+
+export const tools = [
+  {
+    name: "yapi.get_api_context",
+    description: "Get structured API context from YAPI",
+    inputSchema: z.object({
+      projectId: z.number().optional(),
+      interfaceId: z.number()
+    }),
+    handler: async ({ projectId, interfaceId }: { projectId?: number; interfaceId: number }) => {
+      const api = projectId
+        ? await getInterface(projectId, interfaceId)
+        : await getInterface(interfaceId);
+
+      return {
+        name: api.title,
+        path: api.path,
+        method: api.method,
+        description: api.desc,
+        request: {
+          query: api.req_query,
+          body: api.req_body_other
+        },
+        response: api.res_body
+      };
+    }
+  },
+  {
+    name: "yapi.get_api_context_by_path",
+    description: "Get API context by path within a YAPI project",
+    inputSchema: z.object({
+      projectId: z.number(),
+      path: z.string(),
+      method: z.string().optional()
+    }),
+    handler: async (
+      { projectId, path, method }: { projectId: number; path: string; method?: string }
+    ) => {
+      const api = await getInterfaceByPath(projectId, path, method);
+
+      return {
+        name: api.title,
+        path: api.path,
+        method: api.method,
+        description: api.desc,
+        request: {
+          query: api.req_query,
+          body: api.req_body_other
+        },
+        response: api.res_body
+      };
+    }
+  }
+];

package/src/types.d.ts

@@ -0,0 +1,25 @@
+// 类型声明：为通配符导出路径提供类型支持
+declare module "@modelcontextprotocol/sdk/server/mcp.js" {
+  // 使用相对路径从 node_modules 导入类型
+  export {
+    McpServer,
+    ResourceTemplate,
+    type RegisteredTool,
+    type RegisteredResource,
+    type RegisteredPrompt,
+    type ToolCallback,
+    type PromptCallback,
+    type ReadResourceCallback,
+    type ReadResourceTemplateCallback,
+    type ListResourcesCallback,
+    type CompleteResourceTemplateCallback,
+    type ResourceMetadata
+  } from "../node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js";
+}
+
+declare module "@modelcontextprotocol/sdk/server/stdio.js" {
+  export {
+    StdioServerTransport
+  } from "../node_modules/@modelcontextprotocol/sdk/dist/esm/server/stdio.js";
+}
+

package/src/yapi.ts

@@ -0,0 +1,119 @@
+import fetch from "node-fetch";
+
+// YAPI 基础地址，末尾不要加斜杠，必填通过环境变量提供
+const YAPI_BASE = process.env.YAPI_BASE!;
+// YAPI 的 openapi token（从环境变量读取，放在查询参数 token），避免依赖登录态 Cookie
+const YAPI_TOKEN = process.env.YAPI_TOKEN!;
+
+interface YapiResponse<T = unknown> {
+  errcode: number;
+  errmsg: string;
+  data: T;
+}
+
+interface YapiInterface {
+  title: string;
+  path: string;
+  method: string;
+  desc: string;
+  req_query: unknown;
+  req_body_other: unknown;
+  res_body: unknown;
+}
+
+interface YapiInterfaceListItem {
+  _id: number;
+  path: string;
+  method: string;
+  title: string;
+  catid: number;
+  project_id: number;
+}
+
+interface YapiInterfaceList {
+  count: number;
+  list: YapiInterfaceListItem[];
+}
+
+export async function getInterface(
+  projectId: number,
+  interfaceId: number
+): Promise<YapiInterface>;
+export async function getInterface(
+  interfaceId: number
+): Promise<YapiInterface>;
+export async function getInterface(
+  projectIdOrInterfaceId: number,
+  maybeInterfaceId?: number
+): Promise<YapiInterface> {
+  // 兼容两种调用：仅传接口 ID；或传 projectId + 接口 ID
+  const interfaceId = maybeInterfaceId ?? projectIdOrInterfaceId;
+  const projectId = maybeInterfaceId ? projectIdOrInterfaceId : undefined;
+
+  const params = new URLSearchParams({
+    id: String(interfaceId),
+    token: YAPI_TOKEN
+  });
+  if (projectId !== undefined) {
+    params.set("project_id", String(projectId));
+  }
+
+  const url = `${YAPI_BASE}/api/interface/get?${params.toString()}`;
+  const res = await fetch(url);
+
+  const json = await res.json() as YapiResponse<YapiInterface>;
+  if (json.errcode !== 0) {
+    throw new Error(json.errmsg);
+  }
+
+  return json.data;
+}
+
+async function listInterfaces(projectId: number): Promise<YapiInterfaceListItem[]> {
+  const pageSize = 200;
+  const result: YapiInterfaceListItem[] = [];
+  let page = 1;
+
+  // 分页拉取，直到达到总数或无更多数据
+  while (true) {
+    const url = `${YAPI_BASE}/api/interface/list?project_id=${projectId}&page=${page}&limit=${pageSize}&token=${YAPI_TOKEN}`;
+    const res = await fetch(url);
+    const json = await res.json() as YapiResponse<YapiInterfaceList>;
+    if (json.errcode !== 0) {
+      throw new Error(json.errmsg);
+    }
+
+    result.push(...json.data.list);
+    if (result.length >= json.data.count || json.data.list.length === 0) {
+      break;
+    }
+
+    page += 1;
+  }
+
+  return result;
+}
+
+export async function getInterfaceByPath(
+  projectId: number,
+  path: string,
+  method?: string
+): Promise<YapiInterface> {
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  const interfaces = await listInterfaces(projectId);
+
+  const matches = interfaces.filter((item) => item.path === normalizedPath);
+  const filtered = method
+    ? matches.filter((item) => item.method.toUpperCase() === method.toUpperCase())
+    : matches;
+
+  const target = filtered[0];
+  if (!target) {
+    const reason = matches.length === 0
+      ? `未找到路径为 ${normalizedPath} 的接口`
+      : `路径匹配到 ${matches.length} 条，但没有匹配到方法 ${method ?? "N/A"}`;
+    throw new Error(reason);
+  }
+
+  return getInterface(projectId, target._id);
+}