@wllcyg001/yapi-mcp 0.1.0

package/dist/yapi.js

@@ -0,0 +1,154 @@
+import axios from "axios";
+import { AppError } from "./errors.js";
+export class YApiClient {
+    client;
+    retryCount;
+    constructor(options) {
+        this.client = axios.create({
+            baseURL: options.baseUrl,
+            timeout: options.timeoutMs,
+        });
+        this.retryCount = options.retryCount;
+    }
+    async searchInterfaces(args) {
+        const menuData = await this.requestWithRetry("/api/interface/list_menu", {
+            project_id: args.projectId,
+            token: args.token,
+        });
+        const flat = flattenMenuInterfaces(menuData, args.projectId);
+        const keyword = args.keyword.trim().toLowerCase();
+        const method = args.method?.toUpperCase();
+        const pathHint = args.pathHint?.toLowerCase();
+        const scored = flat
+            .filter((item) => {
+            if (method && (item.method || "").toUpperCase() !== method)
+                return false;
+            return true;
+        })
+            .map((item) => {
+            const title = (item.name || "").toLowerCase();
+            const path = (item.path || "").toLowerCase();
+            let score = 0;
+            if (title.includes(keyword))
+                score += 50;
+            if (path.includes(keyword))
+                score += 40;
+            if (pathHint && path.includes(pathHint))
+                score += 30;
+            if (title.startsWith(keyword))
+                score += 20;
+            if ((item.method || "").toUpperCase() === method)
+                score += 10;
+            return {
+                ...item,
+                score,
+            };
+        })
+            .filter((item) => item.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, args.limit);
+        return scored;
+    }
+    async getInterfaceDetail(args) {
+        const detail = await this.requestWithRetry("/api/interface/get", {
+            id: args.interfaceId,
+            token: args.token,
+        });
+        if (!detail || typeof detail !== "object") {
+            throw new AppError({
+                code: "INTERFACE_NOT_FOUND",
+                message: `Interface ${args.interfaceId} not found`,
+            });
+        }
+        if (!args.includeMock && "mock" in detail) {
+            const copy = { ...detail };
+            delete copy.mock;
+            return copy;
+        }
+        return detail;
+    }
+    async requestWithRetry(url, params) {
+        let attempt = 0;
+        const maxAttempts = Math.max(1, this.retryCount + 1);
+        while (attempt < maxAttempts) {
+            try {
+                const res = await this.client.get(url, { params });
+                const payload = res.data;
+                if (payload?.errcode === 0) {
+                    return payload.data;
+                }
+                const errcode = payload?.errcode;
+                const errmsg = payload?.errmsg || "Unknown YApi error";
+                if (errcode === 40011 || errcode === 40012) {
+                    throw new AppError({
+                        code: "PROJECT_NOT_ACCESSIBLE",
+                        message: errmsg,
+                    });
+                }
+                throw new AppError({
+                    code: "UPSTREAM_ERROR",
+                    message: errmsg,
+                    context: { errcode },
+                });
+            }
+            catch (error) {
+                const status = error?.response?.status;
+                if (status === 429) {
+                    throw new AppError({
+                        code: "RATE_LIMITED",
+                        message: "YApi rate limited",
+                    });
+                }
+                if (error instanceof AppError) {
+                    throw error;
+                }
+                if (error?.code === "ECONNABORTED") {
+                    if (attempt + 1 < maxAttempts) {
+                        attempt += 1;
+                        continue;
+                    }
+                    throw new AppError({
+                        code: "UPSTREAM_TIMEOUT",
+                        message: "YApi request timed out",
+                    });
+                }
+                if (attempt + 1 < maxAttempts) {
+                    attempt += 1;
+                    continue;
+                }
+                throw new AppError({
+                    code: "UPSTREAM_ERROR",
+                    message: error?.message || "Failed to request YApi",
+                });
+            }
+        }
+        throw new AppError({
+            code: "UPSTREAM_ERROR",
+            message: "Unexpected request state",
+        });
+    }
+}
+function flattenMenuInterfaces(menuData, projectId) {
+    if (!Array.isArray(menuData))
+        return [];
+    const out = [];
+    for (const category of menuData) {
+        const list = category?.list;
+        if (!Array.isArray(list))
+            continue;
+        for (const item of list) {
+            const interfaceId = Number(item?._id ?? item?.id);
+            if (!Number.isFinite(interfaceId))
+                continue;
+            out.push({
+                interfaceId,
+                name: String(item?.title ?? item?.name ?? ""),
+                method: item?.method ? String(item.method) : undefined,
+                path: item?.path ? String(item.path) : undefined,
+                projectId,
+                score: 0,
+            });
+        }
+    }
+    return out;
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@wllcyg001/yapi-mcp",
+  "version": "0.1.0",
+  "private": false,
+  "description": "MCP server for querying YApi interfaces by project-level token map",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "yapi-mcp-server": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "axios": "^1.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.9",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  }
+}

package/src/config.ts

@@ -0,0 +1,115 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { AppError } from "./errors.js";
+
+export interface AppConfig {
+  baseUrl: string;
+  tokenFilePath: string;
+  timeoutMs: number;
+  retryCount: number;
+  fallbackToken?: string;
+}
+
+export function getConfig(): AppConfig {
+  const baseUrl = process.env.YAPI_BASE_URL?.trim();
+  if (!baseUrl) {
+    throw new AppError({
+      code: "INVALID_ARGUMENT",
+      message: "Missing required env: YAPI_BASE_URL",
+      suggestion: "Set YAPI_BASE_URL, e.g. http://10.255.30.245:3000",
+    });
+  }
+
+  return {
+    baseUrl,
+    tokenFilePath: process.env.YAPI_TOKEN_FILE?.trim() || path.join(os.homedir(), ".yapi-mcp-tokens.json"),
+    timeoutMs: Number(process.env.YAPI_TIMEOUT_MS || 8000),
+    retryCount: Number(process.env.YAPI_RETRY_COUNT || 1),
+    fallbackToken: process.env.YAPI_TOKEN?.trim() || undefined,
+  };
+}
+
+export function loadTokenMap(tokenFilePath: string): Record<string, string> {
+  if (!fs.existsSync(tokenFilePath)) {
+    return {};
+  }
+
+  const raw = fs.readFileSync(tokenFilePath, "utf8");
+  if (!raw.trim()) return {};
+
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (!parsed || typeof parsed !== "object") {
+      throw new Error("token file is not an object");
+    }
+
+    const result: Record<string, string> = {};
+    for (const [k, v] of Object.entries(parsed as Record<string, unknown>)) {
+      if (typeof v === "string" && v.trim()) {
+        result[k] = v.trim();
+      }
+    }
+    return result;
+  } catch {
+    throw new AppError({
+      code: "INVALID_ARGUMENT",
+      message: `Invalid token file JSON: ${tokenFilePath}`,
+      suggestion: "Ensure token file format is like: { \"695\": \"token_xxx\" }",
+    });
+  }
+}
+
+export function resolveProjectId(input: {
+  projectId?: number;
+  projectUrl?: string;
+  groupUrl?: string;
+}): number {
+  if (typeof input.projectId === "number" && Number.isFinite(input.projectId)) {
+    return input.projectId;
+  }
+
+  if (input.projectUrl) {
+    const matched = input.projectUrl.match(/\/project\/(\d+)/i);
+    if (matched) return Number(matched[1]);
+
+    if (/\/group\/\d+/i.test(input.projectUrl)) {
+      throw new AppError({
+        code: "TOKEN_SCOPE_UNSUPPORTED",
+        message: "Group URL is not supported for token resolution",
+        suggestion: "Provide projectId or projectUrl like /project/695/interface/api",
+      });
+    }
+  }
+
+  if (input.groupUrl) {
+    throw new AppError({
+      code: "TOKEN_SCOPE_UNSUPPORTED",
+      message: "Group URL is not supported for token resolution",
+      suggestion: "Provide projectId or projectUrl like /project/695/interface/api",
+    });
+  }
+
+  throw new AppError({
+    code: "PROJECT_ID_REQUIRED",
+    message: "Cannot determine projectId from input",
+    suggestion: "Provide projectId or projectUrl",
+  });
+}
+
+export function resolveToken(args: {
+  projectId: number;
+  tokenMap: Record<string, string>;
+  fallbackToken?: string;
+}): string {
+  const token = args.tokenMap[String(args.projectId)] || args.fallbackToken;
+  if (!token) {
+    throw new AppError({
+      code: "PROJECT_TOKEN_REQUIRED",
+      message: `Missing token for projectId=${args.projectId}`,
+      suggestion: `Add \"${args.projectId}\": \"<token>\" to ~/.yapi-mcp-tokens.json`,
+      context: { projectId: args.projectId },
+    });
+  }
+  return token;
+}

package/src/errors.ts

@@ -0,0 +1,29 @@
+import type { ApiErrorShape, ErrorCode } from "./types.js";
+
+export class AppError extends Error {
+  readonly code: ErrorCode;
+  readonly suggestion?: string;
+  readonly context?: Record<string, unknown>;
+
+  constructor(shape: ApiErrorShape) {
+    super(shape.message);
+    this.code = shape.code;
+    this.suggestion = shape.suggestion;
+    this.context = shape.context;
+  }
+
+  toShape(): ApiErrorShape {
+    return {
+      code: this.code,
+      message: this.message,
+      suggestion: this.suggestion,
+      context: this.context,
+    };
+  }
+}
+
+export function ensure(condition: unknown, shape: ApiErrorShape): asserts condition {
+  if (!condition) {
+    throw new AppError(shape);
+  }
+}

package/src/index.ts

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  type CallToolRequest,
+} from "@modelcontextprotocol/sdk/types.js";
+import {
+  getConfig,
+  loadTokenMap,
+  resolveProjectId,
+  resolveToken,
+} from "./config.js";
+import { AppError } from "./errors.js";
+import type { DetailInput, SearchInput } from "./types.js";
+import { YApiClient } from "./yapi.js";
+
+const config = getConfig();
+const tokenMap = loadTokenMap(config.tokenFilePath);
+const yapi = new YApiClient({
+  baseUrl: config.baseUrl,
+  timeoutMs: config.timeoutMs,
+  retryCount: config.retryCount,
+});
+
+const server = new Server(
+  {
+    name: "yapi-mcp-server",
+    version: "0.1.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "search_yapi_interfaces",
+        description:
+          "Search YApi interfaces by natural language keyword within a project. Token scope is project-level only.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            keyword: { type: "string", minLength: 1 },
+            projectId: { type: "number" },
+            projectUrl: { type: "string" },
+            method: {
+              type: "string",
+              enum: ["GET", "POST", "PUT", "DELETE", "PATCH"],
+            },
+            pathHint: { type: "string" },
+            limit: { type: "number", minimum: 1, maximum: 50 },
+          },
+          required: ["keyword"],
+          additionalProperties: false,
+        },
+      },
+      {
+        name: "get_yapi_interface_detail",
+        description:
+          "Get YApi interface detail including request/response schema. Token scope is project-level only.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            interfaceId: { type: "number" },
+            projectId: { type: "number" },
+            projectUrl: { type: "string" },
+            includeMock: { type: "boolean" },
+          },
+          required: ["interfaceId"],
+          additionalProperties: false,
+        },
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(
+  CallToolRequestSchema,
+  async (request: CallToolRequest) => {
+    try {
+      const { name, arguments: args } = request.params;
+
+      if (name === "search_yapi_interfaces") {
+        const input = (args ?? {}) as unknown as SearchInput;
+        if (!input.keyword?.trim()) {
+          throw new AppError({
+            code: "INVALID_ARGUMENT",
+            message: "keyword is required",
+            suggestion: "Pass keyword like '工单详情'",
+          });
+        }
+
+        const projectId = resolveProjectId({
+          projectId: input.projectId,
+          projectUrl: input.projectUrl,
+        });
+
+        const token = resolveToken({
+          projectId,
+          tokenMap,
+          fallbackToken: config.fallbackToken,
+        });
+
+        const limit = clampLimit(input.limit);
+        const result = await yapi.searchInterfaces({
+          projectId,
+          token,
+          keyword: input.keyword,
+          method: input.method,
+          pathHint: input.pathHint,
+          limit,
+        });
+
+        return ok({
+          projectId,
+          count: result.length,
+          items: result,
+        });
+      }
+
+      if (name === "get_yapi_interface_detail") {
+        const input = (args ?? {}) as unknown as DetailInput;
+        if (!Number.isFinite(input.interfaceId)) {
+          throw new AppError({
+            code: "INVALID_ARGUMENT",
+            message: "interfaceId is required and must be a number",
+          });
+        }
+
+        const projectId = resolveProjectId({
+          projectId: input.projectId,
+          projectUrl: input.projectUrl,
+        });
+
+        const token = resolveToken({
+          projectId,
+          tokenMap,
+          fallbackToken: config.fallbackToken,
+        });
+
+        const detail = await yapi.getInterfaceDetail({
+          interfaceId: input.interfaceId,
+          token,
+          includeMock: input.includeMock,
+        });
+
+        return ok({
+          projectId,
+          interfaceId: input.interfaceId,
+          detail,
+        });
+      }
+
+      throw new AppError({
+        code: "INVALID_ARGUMENT",
+        message: `Unknown tool: ${name}`,
+      });
+    } catch (error) {
+      return fail(error);
+    }
+  },
+);
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+function ok(data: unknown) {
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(
+          {
+            ok: true,
+            data,
+          },
+          null,
+          2,
+        ),
+      },
+    ],
+  };
+}
+
+function fail(error: unknown) {
+  if (error instanceof AppError) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text" as const,
+          text: JSON.stringify(
+            {
+              ok: false,
+              error: error.toShape(),
+            },
+            null,
+            2,
+          ),
+        },
+      ],
+    };
+  }
+
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(
+          {
+            ok: false,
+            error: {
+              code: "UPSTREAM_ERROR",
+              message: error instanceof Error ? error.message : "Unknown error",
+            },
+          },
+          null,
+          2,
+        ),
+      },
+    ],
+  };
+}
+
+function clampLimit(limit?: number): number {
+  if (!Number.isFinite(limit)) return 10;
+  return Math.min(50, Math.max(1, Number(limit)));
+}
+
+main().catch((error) => {
+  const payload =
+    error instanceof AppError
+      ? { ok: false, error: error.toShape() }
+      : {
+          ok: false,
+          error: {
+            code: "UPSTREAM_ERROR",
+            message:
+              error instanceof Error ? error.message : "Unknown startup error",
+          },
+        };
+
+  process.stderr.write(`${JSON.stringify(payload, null, 2)}\n`);
+  process.exit(1);
+});

package/src/types.ts

@@ -0,0 +1,42 @@
+export type ErrorCode =
+  | "INVALID_ARGUMENT"
+  | "PROJECT_ID_REQUIRED"
+  | "PROJECT_TOKEN_REQUIRED"
+  | "TOKEN_SCOPE_UNSUPPORTED"
+  | "PROJECT_NOT_ACCESSIBLE"
+  | "INTERFACE_NOT_FOUND"
+  | "UPSTREAM_TIMEOUT"
+  | "UPSTREAM_ERROR"
+  | "RATE_LIMITED";
+
+export interface ApiErrorShape {
+  code: ErrorCode;
+  message: string;
+  suggestion?: string;
+  context?: Record<string, unknown>;
+}
+
+export interface SearchInput {
+  keyword: string;
+  projectId?: number;
+  projectUrl?: string;
+  method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+  pathHint?: string;
+  limit?: number;
+}
+
+export interface DetailInput {
+  interfaceId: number;
+  projectId?: number;
+  projectUrl?: string;
+  includeMock?: boolean;
+}
+
+export interface YApiInterfaceSummary {
+  interfaceId: number;
+  name: string;
+  method?: string;
+  path?: string;
+  projectId: number;
+  score: number;
+}