@wllcyg001/yapi-mcp 0.1.0 → 0.1.8

package/README.md

@@ -1,116 +1,116 @@
-# @wllcyg001/yapi-mcp
-
-YApi MCP Server（Node.js + MCP SDK），提供按需查询的两个核心工具：
-
-- `search_yapi_interfaces`
-- `get_yapi_interface_detail`
-
-> Token 仅支持 **project 级**。`group` 级 URL 不支持鉴权。
-
-## 1. 安装与构建
-
-```bash
-npm install
-npm run build
-```
-
-本地开发：
-
-```bash
-npm run dev
-```
-
-## 2. 配置
-
-### 环境变量
-
-- `YAPI_BASE_URL`（必填）
-- `YAPI_TOKEN_FILE`（可选，默认 `~/.yapi-mcp-tokens.json`）
-- `YAPI_TIMEOUT_MS`（可选，默认 `8000`）
-- `YAPI_RETRY_COUNT`（可选，默认 `1`）
-- `YAPI_TOKEN`（可选，单项目临时兜底）
-
-### Token 文件
-
-路径：`~/.yapi-mcp-tokens.json`
-
-```json
-{
-  "695": "token_for_project_695",
-  "703": "token_for_project_703"
-}
-```
-
-## 3. MCP 客户端配置示例（Cursor）
-
-```json
-{
-  "mcpServers": {
-    "yapi": {
-      "command": "node",
-      "args": ["D:/self/yapi-mcp/dist/index.js"],
-      "env": {
-        "YAPI_BASE_URL": "http://10.255.30.245:3000"
-      }
-    }
-  }
-}
-```
-
-如果你后续发布 npm 包，也可改为：
-
-```json
-{
-  "mcpServers": {
-    "yapi": {
-      "command": "npx",
-      "args": ["-y", "@wllcyg001/yapi-mcp"],
-      "env": {
-        "YAPI_BASE_URL": "http://10.255.30.245:3000"
-      }
-    }
-  }
-}
-```
-
-## 4. 工具定义
-
-### `search_yapi_interfaces`
-
-输入：
-
-- `keyword: string`（必填）
-- `projectId?: number`
-- `projectUrl?: string`（如 `.../project/695/interface/api`）
-- `method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH"`
-- `pathHint?: string`
-- `limit?: number`（默认 10，最大 50）
-
-输出：
-
-- 匹配接口列表：`interfaceId / name / method / path / projectId / score`
-
-### `get_yapi_interface_detail`
-
-输入：
-
-- `interfaceId: number`（必填）
-- `projectId?: number`
-- `projectUrl?: string`
-- `includeMock?: boolean`（默认 false）
-
-输出：
-
-- 接口详情（request/response schema，默认不返回 mock）
-
-## 5. 错误码
-
-- `INVALID_ARGUMENT`
-- `PROJECT_ID_REQUIRED`
-- `PROJECT_TOKEN_REQUIRED`
-- `TOKEN_SCOPE_UNSUPPORTED`
-- `PROJECT_NOT_ACCESSIBLE`
-- `INTERFACE_NOT_FOUND`
-- `UPSTREAM_TIMEOUT`
-- `UPSTREAM_ERROR`
-- `RATE_LIMITED`
+# @wllcyg001/yapi-mcp
+
+YApi MCP Server（Node.js + MCP SDK），提供按需查询的两个核心工具：
+
+- `search_yapi_interfaces`
+- `get_yapi_interface_detail`
+
+> Token 仅支持 **project 级**。`group` 级 URL 不支持鉴权。
+
+## 1. 安装与构建
+
+```bash
+npm install
+npm run build
+```
+
+本地开发：
+
+```bash
+npm run dev
+```
+
+## 2. 配置
+
+### 环境变量
+
+- `YAPI_BASE_URL`（必填）
+- `YAPI_TOKEN_FILE`（可选，默认 `~/.yapi-mcp-tokens.json`）
+- `YAPI_TIMEOUT_MS`（可选，默认 `8000`）
+- `YAPI_RETRY_COUNT`（可选，默认 `1`）
+- `YAPI_TOKEN`（可选，单项目临时兜底）
+
+### Token 文件
+
+路径：`~/.yapi-mcp-tokens.json`
+
+```json
+{
+  "695": "token_for_project_695",
+  "703": "token_for_project_703"
+}
+```
+
+## 3. MCP 客户端配置示例（Cursor）
+
+```json
+{
+  "mcpServers": {
+    "yapi": {
+      "command": "node",
+      "args": ["D:/self/yapi-mcp/dist/index.js"],
+      "env": {
+        "YAPI_BASE_URL": "http://10.255.30.245:3000"
+      }
+    }
+  }
+}
+```
+
+如果你后续发布 npm 包，也可改为：
+
+```json
+{
+  "mcpServers": {
+    "yapi": {
+      "command": "npx",
+      "args": ["-y", "@wllcyg001/yapi-mcp"],
+      "env": {
+        "YAPI_BASE_URL": "http://10.255.30.245:3000"
+      }
+    }
+  }
+}
+```
+
+## 4. 工具定义
+
+### `search_yapi_interfaces`
+
+输入：
+
+- `keyword: string`（必填）
+- `projectId?: number`
+- `projectUrl?: string`（如 `.../project/695/interface/api`）
+- `method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH"`
+- `pathHint?: string`
+- `limit?: number`（默认 10，最大 50）
+
+输出：
+
+- 匹配接口列表：`interfaceId / name / method / path / projectId / score`
+
+### `get_yapi_interface_detail`
+
+输入：
+
+- `interfaceId: number`（必填）
+- `projectId?: number`
+- `projectUrl?: string`
+- `includeMock?: boolean`（默认 false）
+
+输出：
+
+- 接口详情（request/response schema，默认不返回 mock）
+
+## 5. 错误码
+
+- `INVALID_ARGUMENT`
+- `PROJECT_ID_REQUIRED`
+- `PROJECT_TOKEN_REQUIRED`
+- `TOKEN_SCOPE_UNSUPPORTED`
+- `PROJECT_NOT_ACCESSIBLE`
+- `INTERFACE_NOT_FOUND`
+- `UPSTREAM_TIMEOUT`
+- `UPSTREAM_ERROR`
+- `RATE_LIMITED`

package/package.json

@@ -1,28 +1,39 @@
-{
-  "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"
-  }
-}
+{
+  "name": "@wllcyg001/yapi-mcp",
+  "version": "0.1.8",
+  "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"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wllcyg/yapi-mcp.git"
+  },
+  "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/.github/workflows/ci.yml

@@ -1,26 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: npm
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Build
-        run: npm run build

package/.github/workflows/release.yml

@@ -1,32 +0,0 @@
-name: Release
-
-on:
-  push:
-    tags:
-      - "v*"
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      id-token: write
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          registry-url: "https://registry.npmjs.org"
-          cache: npm
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Build
-        run: npm run build
-
-      - name: Publish to npm (Trusted Publishing)
-        run: npm publish --access public --provenance

package/YApi-MCP-Server-PRD.md

@@ -1,111 +0,0 @@
-# 产品需求文档 (PRD)：YApi MCP Server
-
-## 1. 背景与痛点 (Background & Pain points)
-
-在日常前端开发中，团队通常依赖 YApi 作为接口管理工具。当前的工作流存在以下痛点：
-1. **冗余的批量生成**：现有的 `yapi-codegen` 脚本会一次性拉取整个项目的所有接口，生成大量可能永远不会用到的本地 `.js` 文件，导致项目体积膨胀。
-2. **人工上下文割裂**：开发者需要离开 IDE，去 YApi 网页端搜索接口，然后再回到代码中引入对应的方法，来回切换打断心流。
-3. **接口同步滞后**：后端修改接口后，前端往往不知道，或者忘记重新跑脚本，导致联调时参数报错。
-
-## 2. 解决方案 (Solution Overview)
-
-利用 **MCP (Model Context Protocol)** 技术，开发一个独立的 `yapi-mcp-server`。
-该方案的核心在于**颠覆传统的“提前全量生成”模式，走向“AI 按需动态获取”模式**。
-
-把 YApi 变成 AI 助手（Cursor / Claude Desktop）的外挂大脑。开发者只需用自然语言描述需求（如“帮我接一下新增工单的接口”），AI 即可在后台自动调用 MCP Server 实时查阅 YApi 文档，并在当前组件中精确生成包含正确类型定义的代码。
-
-## 3. 核心功能特性 (Core Features)
-
-### 3.1 基于自然语言的接口搜索
-- **描述**：AI 可根据开发者口语化的需求，在指定的 YApi 项目中搜索匹配的接口。
-- **MCP 工具定义**：`search_yapi_interfaces`
-- **入参（建议 Schema）**：
-  - `keyword: string`（必填，如“工单详情”）
-  - `projectId?: number`（可选，优先显式传入）
-  - `projectUrl?: string`（可选，如 `.../project/695/interface/api`，可自动解析 projectId）
-  - `method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH"`（可选）
-  - `pathHint?: string`（可选，如 `/api/work-order`）
-  - `limit?: number`（可选，默认 `10`，最大 `50`）
-- **出参**：匹配的接口列表（包含接口 ID、名称、Method、Path、所属项目 ID、匹配分数摘要）。
-
-### 3.2 接口详情与契约精准获取
-- **描述**：获取具体某个接口的详细定义，包括 Request Query、Request Body 结构，以及完整的 Response JSON Schema。
-- **MCP 工具定义**：`get_yapi_interface_detail`
-- **入参（建议 Schema）**：
-  - `interfaceId: number`（必填，从搜索结果中获得）
-  - `projectId?: number`（可选，建议传入以避免跨项目歧义）
-  - `projectUrl?: string`（可选，可自动解析 projectId）
-  - `includeMock?: boolean`（可选，默认 `false`，为 Phase 2 预留）
-- **出参**：精确到每个字段是否必填、数据类型、默认值/示例值（若有）的完整接口定义。
-
-### 3.3 多项目环境下的 Token 管理（仅 Project 级）
-- **关键事实**：YApi 的 Token 是基于「项目级别 (Project)」的，不是 Group 级别。
-  - 示例：`/group/896` 没有可用 token；`/project/695/...` 才有对应 token。
-- **解决方案 (Token Map)**：不支持单一全局 Token，而是采用 **Token 映射表**。
-  - **本地配置文件**：MCP Server 启动时，读取本机 `~/.yapi-mcp-tokens.json`，格式：`{ "695": "token_A", "703": "token_B" }`。
-  - **动态调用**：优先从 `projectId` / `projectUrl` 解析出项目 ID，再去映射表读取对应 token。
-  - **不支持 group 级鉴权**：传入 `groupUrl` 时直接返回结构化错误，提示补充 `projectId` 或 `projectUrl`。
-
-## 4. 典型用户故事 (User Stories)
-
-- **场景 A（新功能开发）**：前端接手一个新页面，在 Cursor 里输入：“帮我写一下用户配置表单，对接保存配置的接口”。Cursor 自动通过 MCP 查到接口参数，并把完整的 `axios.post` 及 React/Vue 表单组件全部写好。
-- **场景 B（接口变更修复）**：联调时后端提示增加了一个必填字段。前端在代码中对 AI 说：“查一下目前获取详情接口最新的返回体，同步更新一下本地的 TypeScript Interface”。
-
-## 5. 技术架构与选型 (Architecture)
-
-- **运行时环境**：Node.js (v18+)
-- **核心依赖**：
-  - `@modelcontextprotocol/sdk`：实现标准 MCP 协议
-  - `axios`：用于与公司内部的 YApi 服务器通信
-- **通信方式**：Stdio Transport (标准输入输出，适配绝大部分本地 IDE)
-- **配置管理（统一口径）**：
-  - `process.env.YAPI_BASE_URL`：必填
-  - `~/.yapi-mcp-tokens.json`：必填（projectId -> token）
-  - `process.env.YAPI_TOKEN`：仅作为单项目/临时兜底，不作为主流程依赖
-- **安全与稳定性要求**：
-  - Token 不写入日志；日志中对凭证字段统一脱敏
-  - `~/.yapi-mcp-tokens.json` 建议仅当前用户可读写（如 `600` 权限）
-  - 请求超时（建议 5~10s）+ 有限重试（建议 1~2 次，仅幂等查询）
-  - 仅允许访问 `YAPI_BASE_URL` 所属域名，避免 SSRF 风险
-
-## 6. 错误模型与返回规范 (Error Model)
-
-为保证 AI 可恢复调用，所有失败返回统一结构：
-- `code: string`
-- `message: string`
-- `suggestion?: string`
-- `context?: object`
-
-建议错误码：
-- `INVALID_ARGUMENT`：参数非法或缺失
-- `PROJECT_ID_REQUIRED`：无法从参数中确定 projectId
-- `PROJECT_TOKEN_REQUIRED`：缺少指定项目 token
-- `TOKEN_SCOPE_UNSUPPORTED`：仅提供了 group 信息，当前仅支持 project 级 token
-- `PROJECT_NOT_ACCESSIBLE`：项目不存在或无权限
-- `INTERFACE_NOT_FOUND`：接口不存在
-- `UPSTREAM_TIMEOUT`：YApi 请求超时
-- `UPSTREAM_ERROR`：YApi 返回非预期错误
-- `RATE_LIMITED`：触发限流
-
-## 7. 演进路线 (Roadmap)
-
-- **Phase 1: 核心查询能力（MVP）**
-  - 完成 MCP Server 基础骨架
-  - 实现 `search_yapi_interfaces` 和 `get_yapi_interface_detail`
-  - 打通 `projectId/projectUrl -> token map -> YApi` 主链路
-  - 实现统一错误码与结构化返回
-  - 在 Cursor 或 Claude Desktop 本地配置跑通
-- **Phase 2: 上下文感知增强**
-  - 支持直接提供当前打开文件的代码片段，让 AI 判断是否需要根据 YApi 更新代码
-  - 解析 YApi 中的 Mock 数据并直接返回，供 AI 自动生成 Mock Server 脚本
-- **Phase 3: 团队工程化发布**
-  - 封装为 NPM 私有包，提供 `npx yapi-mcp-server` 的一键启动能力
-  - 编写团队内部操作手册，全员推广“无代码生成”开发模式
-
-## 8. Phase 1 验收标准 (Acceptance Criteria)
-
-- 在至少 2 个不同项目（如 `695`、`703`）下可正确读取各自 token 并查询成功
-- 对仅提供 `groupUrl` 的请求，返回 `TOKEN_SCOPE_UNSUPPORTED`，且提示可执行的下一步操作
-- 搜索接口结果默认返回前 10 条，且包含 `interfaceId/name/method/path/projectId`
-- 详情接口返回请求参数、响应 Schema、必填信息，不丢关键字段
-- 网络异常和上游超时场景下，服务不崩溃，返回统一错误结构

package/src/config.ts

@@ -1,115 +0,0 @@
-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

@@ -1,29 +0,0 @@
-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

@@ -1,254 +0,0 @@
-#!/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

@@ -1,42 +0,0 @@
-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;
-}

package/src/yapi.ts

@@ -1,192 +0,0 @@
-import axios, { type AxiosInstance } from "axios";
-import { AppError } from "./errors.js";
-import type { YApiInterfaceSummary } from "./types.js";
-
-interface YApiClientOptions {
-  baseUrl: string;
-  timeoutMs: number;
-  retryCount: number;
-}
-
-export class YApiClient {
-  private readonly client: AxiosInstance;
-  private readonly retryCount: number;
-
-  constructor(options: YApiClientOptions) {
-    this.client = axios.create({
-      baseURL: options.baseUrl,
-      timeout: options.timeoutMs,
-    });
-    this.retryCount = options.retryCount;
-  }
-
-  async searchInterfaces(args: {
-    projectId: number;
-    token: string;
-    keyword: string;
-    method?: string;
-    pathHint?: string;
-    limit: number;
-  }): Promise<YApiInterfaceSummary[]> {
-    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: {
-    interfaceId: number;
-    token: string;
-    includeMock?: boolean;
-  }): Promise<Record<string, unknown>> {
-    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 as Record<string, unknown>) };
-      delete copy.mock;
-      return copy;
-    }
-
-    return detail as Record<string, unknown>;
-  }
-
-  private async requestWithRetry(url: string, params: Record<string, unknown>): Promise<unknown> {
-    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 as any;
-
-        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: any) {
-        const status = error?.response?.status as number | undefined;
-
-        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: unknown, projectId: number): YApiInterfaceSummary[] {
-  if (!Array.isArray(menuData)) return [];
-
-  const out: YApiInterfaceSummary[] = [];
-
-  for (const category of menuData as any[]) {
-    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/tsconfig.json

@@ -1,14 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "outDir": "dist",
-    "rootDir": "src",
-    "strict": true,
-    "skipLibCheck": true,
-    "esModuleInterop": true,
-    "forceConsistentCasingInFileNames": true
-  },
-  "include": ["src/**/*.ts"]
-}