youjiekou-mcp-server 0.1.9

package/README.md

@@ -0,0 +1,180 @@
+# youjiekou-mcp-server
+
+友接口 MCP Server：面向 AI 编程助手，提供项目接口文档的**读取**与**推写**（create / update / upsert）能力。
+
+> 一期能力：在同一套 MCP 中完成接口文档查询与接口定义同步，配置通用、无需本机路径。
+
+## 前置
+
+- Node.js ≥ 18
+- 友接口后端已部署 MCP 相关能力（PAT + 读写 API）
+- 已生成 PAT（推接口需 scopes 含 `apis:write`）
+
+## 生成 PAT（curl）
+
+登录态 token 放在 Header `token`：
+
+```bash
+# 只读
+curl -X POST -H "token: <LOGIN_TOKEN>" -H "Content-Type: application/json" \
+  -d '{"name":"ide-read","scopes":["docs:read"]}' \
+  "https://<HOST>/api/mcp/token/create"
+
+# 读写（推荐日常推接口）
+curl -X POST -H "token: <LOGIN_TOKEN>" -H "Content-Type: application/json" \
+  -d '{"name":"ide-rw","scopes":["docs:read","apis:write"]}' \
+  "https://<HOST>/api/mcp/token/create"
+```
+
+明文 token **只返回一次**，请立即写入本地 MCP 配置中的 `YOUJK_ACCESS_TOKEN`。
+
+## MCP 客户端配置（无本地路径）
+
+```json
+{
+  "mcpServers": {
+    "youjk-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "youjiekou-mcp-server@latest",
+        "--project-id=<PROJECT_ID>"
+      ],
+      "env": {
+        "YOUJK_ACCESS_TOKEN": "<刚才拿到的 yjk_... PAT>",
+        "YOUJK_BASE_URL": "https://<HOST>"
+      }
+    }
+  }
+}
+```
+
+Windows 若 `npx` 起不来，改用：
+
+```json
+{
+  "mcpServers": {
+    "youjk-mcp": {
+      "command": "cmd",
+      "args": [
+        "/c",
+        "npx",
+        "-y",
+        "youjiekou-mcp-server@latest",
+        "--project-id=<PROJECT_ID>"
+      ],
+      "env": {
+        "YOUJK_ACCESS_TOKEN": "<刚才拿到的 yjk_... PAT>",
+        "YOUJK_BASE_URL": "https://<HOST>"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | 类型 | 说明 |
+|------|------|------|
+| `list_apis` | 只读 | 列接口摘要 |
+| `get_api_detail` | 只读 | 单接口详情（含 params/body/responses） |
+| `search_apis` | 只读 | 按关键词搜索 |
+| `create_api` | **写** | 新建接口（请带 params/body） |
+| `update_api` | **写** | 按 id merge 更新 |
+| `upsert_api` | **写** | 按 method+url 有则改无则建（推荐） |
+| `refresh_cache` | 本地 | 清空进程内缓存 |
+
+### 推接口：params / body 完整落库
+
+`create_api` / `update_api` / `upsert_api` 支持完整 `params`、`body`、`responses`。推送后用 `get_api_detail` 回读校验。
+
+友接口格式（推荐）：
+
+```json
+{
+  "name": "创建用户",
+  "method": "POST",
+  "url": "/users",
+  "description": "创建用户",
+  "sourcePath": "src/user/controller.ts:42",
+  "params": [
+    {
+      "name": "X-Request-Id",
+      "type": "string",
+      "location": "HEADER",
+      "required": true,
+      "example": "req-1"
+    },
+    {
+      "name": "id",
+      "type": "integer",
+      "location": "PATH",
+      "required": true,
+      "example": 1
+    }
+  ],
+  "body": {
+    "type": "RAW_JSON",
+    "example": { "name": "tom", "age": 18 },
+    "jsonSchema": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "age": { "type": "integer" }
+      },
+      "required": ["name"]
+    }
+  },
+  "responses": [
+    {
+      "name": "成功",
+      "statusCode": 200,
+      "schema": {
+        "type": "object",
+        "properties": { "id": { "type": "integer" } }
+      }
+    }
+  ]
+}
+```
+
+说明：
+
+- `params[].location`：`QUERY` | `PATH` | `HEADER` | `COOKIE`（兼容小写或 OpenAPI `in`）
+- `body.type`：`RAW_JSON` | `FORM_DATA` | `X_WWW_FORM_URLENCODED` | `RAW_XML` | `RAW_TEXT` | `BINARY`（兼容 `json` / OpenAPI `content`）
+- `body.example` 可为对象，服务端会按 JSON 字符串落库；**仅有 jsonSchema 无 example 时会自动生成示例**，写入调试/请求体区域
+- `sourcePath`：**必填**（create/upsert）。传代码文件路径；服务端落库为 `2026-09-14 11:18 张三 通过 MCP 导入 src/xxx.ts:42`，文档「接口说明 → 来源」展示
+- `moduleName`：仅对话明确「推到 xxx 模块」时传入——有则归入、无则新建；**省略则归入「默认模块」**，勿自行编造模块名
+- `folderPath`：仅对话明确指定目录时传入（如 `["订单","支付"]`）；**省略则按 url 自动建外层文件夹**（对标 Apifox，接口不摊平在一层）
+- merge 更新时：未传的 `params`/`body` 保留原值；要改就传完整对象/列表
+
+## 本地开发
+
+```bash
+cd youjk-mcp-server
+npm install
+npm run build
+set YOUJK_ACCESS_TOKEN=...
+set YOUJK_BASE_URL=http://127.0.0.1:端口
+node dist/index.js --project-id=1
+```
+
+临时用本地路径接入 MCP 客户端（仅开发；正式环境须 `npx`）：
+
+```json
+"youjk-mcp-local": {
+  "command": "node",
+  "args": ["D:/workspace/youjk-mcp-server/dist/index.js", "--project-id=1"],
+  "env": {
+    "YOUJK_ACCESS_TOKEN": "...",
+    "YOUJK_BASE_URL": "http://127.0.0.1:端口"
+  }
+}
+```
+
+## 常见问题
+
+- **401 / 未授权**：PAT 无效、已吊销或过期
+- **403 缺少权限: apis:write**：PAT 未包含写 scope
+- **无写入权限**：项目成员仅为只读
+- **空列表**：projectId 错误或项目尚无接口

package/bin/youjk-mcp-server.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/index.js";

package/dist/cache.d.ts

@@ -0,0 +1,11 @@
+import type { ApiSummary } from "./types.js";
+export declare class MemoryCache {
+    private list;
+    private details;
+    getList(): ApiSummary[] | null;
+    setList(list: ApiSummary[]): void;
+    getDetail(id: number): unknown | undefined;
+    setDetail(id: number, detail: unknown): void;
+    invalidateAfterWrite(apiId?: number): void;
+    clear(): void;
+}

package/dist/cache.js

@@ -0,0 +1,29 @@
+export class MemoryCache {
+    list = null;
+    details = new Map();
+    getList() {
+        return this.list;
+    }
+    setList(list) {
+        this.list = list;
+    }
+    getDetail(id) {
+        return this.details.get(id);
+    }
+    setDetail(id, detail) {
+        this.details.set(id, detail);
+    }
+    invalidateAfterWrite(apiId) {
+        this.list = null;
+        if (apiId != null && apiId > 0) {
+            this.details.delete(apiId);
+        }
+        else {
+            this.details.clear();
+        }
+    }
+    clear() {
+        this.list = null;
+        this.details.clear();
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,17 @@
+import type { ApiSummary, ApiWriteBody, ApiWriteResult, YoujkConfig } from "./types.js";
+export declare class YoujkHttpError extends Error {
+    readonly status?: number | undefined;
+    readonly code?: number | undefined;
+    constructor(message: string, status?: number | undefined, code?: number | undefined);
+}
+export declare class YoujkClient {
+    private readonly cfg;
+    constructor(cfg: YoujkConfig);
+    private url;
+    private request;
+    listApis(): Promise<ApiSummary[]>;
+    getApiDetail(apiId: number | string): Promise<unknown>;
+    createApi(body: ApiWriteBody): Promise<ApiWriteResult>;
+    updateApi(apiId: number | string, body: Record<string, unknown>): Promise<ApiWriteResult>;
+    upsertApi(body: ApiWriteBody): Promise<ApiWriteResult>;
+}

package/dist/client.js

@@ -0,0 +1,74 @@
+export class YoujkHttpError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "YoujkHttpError";
+    }
+}
+export class YoujkClient {
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    url(path) {
+        const base = this.cfg.baseUrl.replace(/\/+$/, "");
+        const p = path.startsWith("/") ? path : `/${path}`;
+        return `${base}${p}`;
+    }
+    async request(method, path, body) {
+        const headers = {
+            Accept: "application/json",
+            Authorization: `Bearer ${this.cfg.accessToken}`,
+        };
+        const init = { method, headers };
+        if (body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            init.body = JSON.stringify(body);
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 30_000);
+        let res;
+        try {
+            res = await fetch(this.url(path), { ...init, signal: controller.signal });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new YoujkHttpError(`请求友接口失败: ${msg}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        let data;
+        try {
+            data = (await res.json());
+        }
+        catch {
+            throw new YoujkHttpError(`友接口返回非 JSON (HTTP ${res.status})`, res.status);
+        }
+        if (!res.ok) {
+            throw new YoujkHttpError(data.message || `HTTP ${res.status}`, res.status, data.code);
+        }
+        if (data.code !== 0) {
+            throw new YoujkHttpError(data.message || `业务错误 code=${data.code}`, res.status, data.code);
+        }
+        return data.result;
+    }
+    listApis() {
+        return this.request("GET", `/api/mcp/projects/${this.cfg.projectId}/apis`);
+    }
+    getApiDetail(apiId) {
+        return this.request("GET", `/api/mcp/apis/${apiId}`);
+    }
+    createApi(body) {
+        return this.request("POST", `/api/mcp/projects/${this.cfg.projectId}/apis`, body);
+    }
+    updateApi(apiId, body) {
+        return this.request("PUT", `/api/mcp/apis/${apiId}`, body);
+    }
+    upsertApi(body) {
+        return this.request("POST", `/api/mcp/projects/${this.cfg.projectId}/apis/upsert`, body);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { createYoujkMcpServer } from "./server.js";
+function printUsage() {
+    console.error(`youjiekou-mcp-server — 友接口 MCP（读文档 + 推写接口）
+
+用法:
+  youjiekou-mcp-server --project-id=<PROJECT_ID>
+
+环境变量（必填）:
+  YOUJK_ACCESS_TOKEN   PAT（推接口需含 apis:write）
+  YOUJK_BASE_URL       友接口后端根地址，如 https://api.example.com
+
+可选参数:
+  --project-id= / --project=   默认项目 ID
+  --help                       显示帮助
+`);
+}
+function parseArgs(argv) {
+    let projectId;
+    let help = false;
+    for (const raw of argv) {
+        if (raw === "--help" || raw === "-h") {
+            help = true;
+            continue;
+        }
+        const m = /^--project(?:-id)?=(.+)$/i.exec(raw);
+        if (m) {
+            projectId = m[1].trim();
+            continue;
+        }
+        if (raw === "--project" || raw === "--project-id") {
+            console.error("请使用 --project-id=<id> 形式（等号赋值）");
+            process.exit(1);
+        }
+    }
+    return { projectId, help };
+}
+function loadConfig() {
+    const { projectId, help } = parseArgs(process.argv.slice(2));
+    if (help) {
+        printUsage();
+        process.exit(0);
+    }
+    const accessToken = (process.env.YOUJK_ACCESS_TOKEN || "").trim();
+    const baseUrl = (process.env.YOUJK_BASE_URL || "").trim();
+    const pid = (projectId || "").trim();
+    const missing = [];
+    if (!accessToken)
+        missing.push("环境变量 YOUJK_ACCESS_TOKEN");
+    if (!baseUrl)
+        missing.push("环境变量 YOUJK_BASE_URL");
+    if (!pid)
+        missing.push("参数 --project-id=<PROJECT_ID>");
+    if (missing.length) {
+        console.error(`启动失败，缺少: ${missing.join("；")}`);
+        printUsage();
+        process.exit(1);
+    }
+    return { accessToken, baseUrl, projectId: pid };
+}
+async function main() {
+    const cfg = loadConfig();
+    const server = createYoujkMcpServer(cfg);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});

package/dist/normalize.d.ts

@@ -0,0 +1,6 @@
+/** 将 MCP 入参归一化为友接口 ParamDTO / BodyDTO，兼容 OpenAPI 形态。 */
+export declare function normalizeParam(input: unknown): Record<string, unknown> | null;
+export declare function normalizeParams(input: unknown): Record<string, unknown>[] | undefined;
+export declare function normalizeBody(input: unknown): Record<string, unknown> | undefined;
+export declare function normalizeResponse(input: unknown): Record<string, unknown> | null;
+export declare function normalizeResponses(input: unknown): Record<string, unknown>[] | undefined;

package/dist/normalize.js

@@ -0,0 +1,193 @@
+/** 将 MCP 入参归一化为友接口 ParamDTO / BodyDTO，兼容 OpenAPI 形态。 */
+const LOCATION_MAP = {
+    query: "QUERY",
+    path: "PATH",
+    header: "HEADER",
+    cookie: "COOKIE",
+    body: "QUERY",
+    QUERY: "QUERY",
+    PATH: "PATH",
+    HEADER: "HEADER",
+    COOKIE: "COOKIE",
+};
+const BODY_TYPE_MAP = {
+    FORM_DATA: "FORM_DATA",
+    "FORM-DATA": "FORM_DATA",
+    multipart: "FORM_DATA",
+    "multipart/form-data": "FORM_DATA",
+    X_WWW_FORM_URLENCODED: "X_WWW_FORM_URLENCODED",
+    "x-www-form-urlencoded": "X_WWW_FORM_URLENCODED",
+    "application/x-www-form-urlencoded": "X_WWW_FORM_URLENCODED",
+    RAW_JSON: "RAW_JSON",
+    json: "RAW_JSON",
+    "application/json": "RAW_JSON",
+    RAW_XML: "RAW_XML",
+    xml: "RAW_XML",
+    "application/xml": "RAW_XML",
+    RAW_TEXT: "RAW_TEXT",
+    text: "RAW_TEXT",
+    "text/plain": "RAW_TEXT",
+    BINARY: "BINARY",
+    "application/octet-stream": "BINARY",
+};
+function asRecord(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v)
+        ? v
+        : null;
+}
+function exampleToValue(example) {
+    if (example === undefined || example === null)
+        return undefined;
+    return example;
+}
+export function normalizeParam(input) {
+    const p = asRecord(input);
+    if (!p)
+        return null;
+    const name = String(p.name ?? "").trim();
+    if (!name)
+        return null;
+    const inLoc = String(p.in ?? "").trim();
+    const locationRaw = String(p.location ?? inLoc ?? "QUERY").trim();
+    const location = LOCATION_MAP[locationRaw] ||
+        LOCATION_MAP[locationRaw.toLowerCase()] ||
+        "QUERY";
+    const schema = asRecord(p.schema);
+    let type = String(p.type ?? schema?.type ?? "string").trim() || "string";
+    const out = {
+        name,
+        type,
+        location,
+        required: Boolean(p.required),
+        description: p.description != null ? String(p.description) : "",
+    };
+    const example = exampleToValue(p.example ?? schema?.example);
+    if (example !== undefined)
+        out.example = example;
+    if (p.mockScript != null)
+        out.mockScript = String(p.mockScript);
+    return out;
+}
+export function normalizeParams(input) {
+    if (input === undefined)
+        return undefined;
+    if (!Array.isArray(input))
+        return [];
+    return input.map(normalizeParam).filter((x) => x != null);
+}
+function convertOpenAPIContent(content) {
+    const formMedia = asRecord(content["multipart/form-data"]);
+    if (formMedia) {
+        const schema = asRecord(formMedia.schema);
+        const formData = [];
+        const props = asRecord(schema?.properties) || {};
+        const required = Array.isArray(schema?.required)
+            ? schema.required
+            : [];
+        for (const [name, propRaw] of Object.entries(props)) {
+            const prop = asRecord(propRaw) || {};
+            formData.push({
+                name,
+                type: String(prop.type ?? "string"),
+                required: required.includes(name),
+                example: prop.example ?? "",
+                description: prop.description != null ? String(prop.description) : "",
+            });
+        }
+        return { type: "FORM_DATA", formData };
+    }
+    const jsonMedia = asRecord(content["application/json"]) ||
+        Object.values(content)
+            .map(asRecord)
+            .find((m) => m && (m.schema != null || m.example != null));
+    if (jsonMedia) {
+        return {
+            type: "RAW_JSON",
+            example: jsonMedia.example ?? null,
+            jsonSchema: jsonMedia.schema ?? {
+                type: "object",
+                properties: {},
+                required: [],
+            },
+        };
+    }
+    return null;
+}
+export function normalizeBody(input) {
+    if (input === undefined)
+        return undefined;
+    if (input === null)
+        return undefined;
+    const b = asRecord(input);
+    if (!b)
+        return undefined;
+    // OpenAPI requestBody
+    const content = asRecord(b.content);
+    if (content && !b.type) {
+        const converted = convertOpenAPIContent(content);
+        if (converted)
+            return converted;
+    }
+    const typeRaw = String(b.type ?? "").trim();
+    let type = BODY_TYPE_MAP[typeRaw] ||
+        BODY_TYPE_MAP[typeRaw.toLowerCase()] ||
+        (typeRaw ? typeRaw.toUpperCase() : "");
+    if (!type) {
+        if (Array.isArray(b.formData) && b.formData.length > 0)
+            type = "FORM_DATA";
+        else if (b.jsonSchema != null || b.example != null)
+            type = "RAW_JSON";
+        else if (b.xmlSchema)
+            type = "RAW_XML";
+        else if (b.textContent)
+            type = "RAW_TEXT";
+        else if (b.binaryDescription)
+            type = "BINARY";
+        else
+            type = "RAW_JSON";
+    }
+    const out = { type };
+    if (b.example !== undefined)
+        out.example = b.example;
+    if (b.jsonSchema !== undefined)
+        out.jsonSchema = b.jsonSchema;
+    if (b.formData !== undefined)
+        out.formData = b.formData;
+    if (b.xmlSchema !== undefined)
+        out.xmlSchema = b.xmlSchema;
+    if (b.textContent !== undefined)
+        out.textContent = b.textContent;
+    if (b.binaryDescription !== undefined)
+        out.binaryDescription = b.binaryDescription;
+    return out;
+}
+export function normalizeResponse(input) {
+    const r = asRecord(input);
+    if (!r)
+        return null;
+    const out = {
+        name: r.name != null ? String(r.name) : "成功",
+        statusCode: typeof r.statusCode === "number"
+            ? r.statusCode
+            : Number(r.statusCode) || 200,
+        description: r.description != null ? String(r.description) : "",
+    };
+    if (r.schema !== undefined)
+        out.schema = r.schema;
+    if (r.example !== undefined)
+        out.example = r.example;
+    if (r.mockScript != null)
+        out.mockScript = String(r.mockScript);
+    if (r.headers !== undefined)
+        out.headers = r.headers;
+    return out;
+}
+export function normalizeResponses(input) {
+    if (input === undefined)
+        return undefined;
+    if (!Array.isArray(input))
+        return [];
+    return input
+        .map(normalizeResponse)
+        .filter((x) => x != null);
+}

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import type { YoujkConfig } from "./types.js";
+export declare function createYoujkMcpServer(cfg: YoujkConfig): McpServer;

package/dist/server.js

@@ -0,0 +1,367 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import { MemoryCache } from "./cache.js";
+import { YoujkClient, YoujkHttpError } from "./client.js";
+import { normalizeBody, normalizeParams, normalizeResponses, } from "./normalize.js";
+function textResult(payload, isError = false) {
+    const text = typeof payload === "string" ? payload : JSON.stringify(payload, null, 2);
+    return { content: [{ type: "text", text }], isError };
+}
+function errResult(e) {
+    const msg = e instanceof YoujkHttpError
+        ? e.message
+        : e instanceof Error
+            ? e.message
+            : String(e);
+    return textResult(msg, true);
+}
+function matchesKeyword(item, keyword) {
+    const k = keyword.trim().toLowerCase();
+    if (!k)
+        return true;
+    return (item.name.toLowerCase().includes(k) ||
+        item.url.toLowerCase().includes(k) ||
+        item.method.toLowerCase().includes(k) ||
+        String(item.id).includes(k));
+}
+const paramSchema = z
+    .object({
+    name: z.string().min(1).describe("参数名"),
+    type: z
+        .string()
+        .optional()
+        .describe("参数类型，如 string/integer/number/boolean"),
+    location: z
+        .enum(["QUERY", "PATH", "HEADER", "COOKIE", "query", "path", "header", "cookie"])
+        .optional()
+        .describe("参数位置；也可用 OpenAPI 的 in 字段"),
+    in: z
+        .enum(["query", "path", "header", "cookie"])
+        .optional()
+        .describe("OpenAPI parameters[].in（与 location 二选一）"),
+    required: z.boolean().optional(),
+    example: z.unknown().optional(),
+    description: z.string().optional(),
+    mockScript: z.string().optional(),
+    schema: z.record(z.string(), z.unknown()).optional(),
+})
+    .passthrough();
+const bodySchema = z
+    .object({
+    type: z
+        .string()
+        .optional()
+        .describe("请求体类型：RAW_JSON / FORM_DATA / X_WWW_FORM_URLENCODED / RAW_XML / RAW_TEXT / BINARY；也可用 json"),
+    example: z.unknown().optional().describe("示例；对象会按 JSON 落库"),
+    jsonSchema: z.record(z.string(), z.unknown()).optional(),
+    formData: z.array(z.record(z.string(), z.unknown())).optional(),
+    xmlSchema: z.string().optional(),
+    textContent: z.string().optional(),
+    binaryDescription: z.string().optional(),
+    content: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("OpenAPI requestBody.content（可选，服务端/客户端会归一化）"),
+})
+    .passthrough();
+const responseSchema = z
+    .object({
+    name: z.string().optional(),
+    statusCode: z.union([z.number(), z.string()]).optional(),
+    description: z.string().optional(),
+    schema: z.record(z.string(), z.unknown()).optional(),
+    example: z.unknown().optional(),
+    mockScript: z.string().optional(),
+    headers: z.record(z.string(), z.string()).optional(),
+})
+    .passthrough();
+const UPSERT_EXAMPLE = `示例（推荐完整推送，推完可用 get_api_detail 回读）：
+{
+  "name": "创建用户",
+  "method": "POST",
+  "url": "/users",
+  "description": "创建用户",
+  "sourcePath": "src/user/controller.ts:42",
+  "params": [
+    {"name": "X-Request-Id", "type": "string", "location": "HEADER", "required": true, "example": "req-1"},
+    {"name": "id", "type": "integer", "location": "PATH", "required": true, "example": 1}
+  ],
+  "body": {
+    "type": "RAW_JSON",
+    "example": {"name": "tom", "age": 18},
+    "jsonSchema": {
+      "type": "object",
+      "properties": {
+        "name": {"type": "string"},
+        "age": {"type": "integer"}
+      },
+      "required": ["name"]
+    }
+  },
+  "responses": [
+    {"name": "成功", "statusCode": 200, "schema": {"type": "object", "properties": {"id": {"type": "integer"}}}}
+  ]
+}`;
+const writeFields = {
+    name: z.string().min(1).describe("接口名称"),
+    method: z.string().min(1).describe("HTTP 方法，如 GET/POST"),
+    url: z.string().min(1).describe("接口路径，如 /user/login"),
+    description: z.string().optional().describe("接口业务说明（展示在文档「接口说明」区）"),
+    sourcePath: z
+        .string()
+        .min(1)
+        .describe("【必填】代码侧来源路径，如 src/user/controller.ts:42。服务端落成「时间 操作人 通过 MCP 导入 该路径」，展示在文档「接口说明 → 来源」"),
+    moduleName: z
+        .string()
+        .optional()
+        .describe("目标模块名。仅当用户明确说「推到 xxx 模块」时传入：有则归入、无则新建。省略则归入「默认模块」（项目没有则自动创建），不要自行编造模块名"),
+    folderPath: z
+        .union([z.array(z.string()), z.string()])
+        .optional()
+        .describe('目标目录。仅当用户明确指定文件夹时传入，如 ["订单","支付"] 或 "订单/支付"。省略则服务端按 url 自动建外层文件夹（对标 Apifox，接口不摊平）；不要用代码目录名冒充业务文件夹'),
+    menuId: z.number().int().positive().optional().describe("目录 ID（已有目录时可用；与 folderPath 二选一）"),
+    moduleId: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("模块 ID；缺省用 moduleName，再否则归入「默认模块」（项目无模块时自动创建）"),
+    params: z
+        .array(paramSchema)
+        .optional()
+        .describe("请求参数列表（ParamDTO）。location=QUERY|PATH|HEADER|COOKIE；兼容 OpenAPI in。务必随接口一并推送以便落库回读。"),
+    body: bodySchema
+        .optional()
+        .describe("请求体（BodyDTO）。JSON 接口用 type=RAW_JSON + example + jsonSchema；无 example 时服务端会按 jsonSchema 生成示例写入调试区。"),
+    responses: z
+        .array(responseSchema)
+        .optional()
+        .describe("响应定义列表（含 statusCode / schema）"),
+    status: z
+        .string()
+        .optional()
+        .describe("接口状态：developing / testing / published（已完成）/ deprecated；省略时服务端默认 published"),
+    tags: z.array(z.string()).optional().describe("标签"),
+};
+function toWriteBody(args) {
+    const body = {
+        name: args.name,
+        method: args.method,
+        url: args.url,
+    };
+    if (args.description !== undefined)
+        body.description = args.description;
+    body.sourcePath = args.sourcePath;
+    if (args.moduleName !== undefined)
+        body.moduleName = args.moduleName;
+    if (args.folderPath !== undefined)
+        body.folderPath = args.folderPath;
+    if (args.menuId !== undefined)
+        body.menuId = args.menuId;
+    if (args.moduleId !== undefined)
+        body.moduleId = args.moduleId;
+    if (args.params !== undefined)
+        body.params = normalizeParams(args.params);
+    if (args.body !== undefined)
+        body.body = normalizeBody(args.body);
+    if (args.responses !== undefined) {
+        body.responses = normalizeResponses(args.responses);
+    }
+    if (args.status !== undefined)
+        body.status = args.status;
+    if (args.tags !== undefined)
+        body.tags = args.tags;
+    return body;
+}
+function toUpdatePatch(rest) {
+    const patch = {};
+    for (const [k, v] of Object.entries(rest)) {
+        if (v === undefined)
+            continue;
+        if (k === "params") {
+            patch.params = normalizeParams(v);
+            continue;
+        }
+        if (k === "body") {
+            const nb = normalizeBody(v);
+            if (nb !== undefined)
+                patch.body = nb;
+            continue;
+        }
+        if (k === "responses") {
+            patch.responses = normalizeResponses(v);
+            continue;
+        }
+        patch[k] = v;
+    }
+    return patch;
+}
+export function createYoujkMcpServer(cfg) {
+    const client = new YoujkClient(cfg);
+    const cache = new MemoryCache();
+    const server = new McpServer({
+        name: "youjk-mcp",
+        version: "0.1.9",
+    });
+    server.registerTool("list_apis", {
+        description: "列出当前友接口项目下的接口摘要（只读）。可选 keyword 按名称/路径/方法过滤。",
+        inputSchema: z.object({
+            keyword: z
+                .string()
+                .optional()
+                .describe("可选关键词，按名称/路径/方法/id 本地过滤"),
+        }),
+    }, async ({ keyword }) => {
+        try {
+            let list = cache.getList();
+            if (!list) {
+                list = await client.listApis();
+                cache.setList(list ?? []);
+                list = cache.getList();
+            }
+            const filtered = keyword
+                ? list.filter((i) => matchesKeyword(i, keyword))
+                : list;
+            return textResult(filtered);
+        }
+        catch (e) {
+            return errResult(e);
+        }
+    });
+    server.registerTool("get_api_detail", {
+        description: "获取友接口中单个接口的完整定义（只读）：params、body、responses 等，用于推送后回读校验。",
+        inputSchema: z.object({
+            apiId: z.union([z.string(), z.number()]).describe("接口 ID"),
+        }),
+    }, async ({ apiId }) => {
+        try {
+            const id = typeof apiId === "number" ? apiId : Number(apiId);
+            if (!Number.isFinite(id) || id <= 0) {
+                return textResult("apiId 无效", true);
+            }
+            const cached = cache.getDetail(id);
+            if (cached !== undefined) {
+                return textResult(cached);
+            }
+            const detail = await client.getApiDetail(id);
+            cache.setDetail(id, detail);
+            return textResult(detail);
+        }
+        catch (e) {
+            return errResult(e);
+        }
+    });
+    server.registerTool("search_apis", {
+        description: "在当前友接口项目中搜索接口（只读）。写接口前建议先搜索避免重复。按名称/路径/方法匹配。",
+        inputSchema: z.object({
+            keyword: z.string().min(1).describe("搜索关键词"),
+        }),
+    }, async ({ keyword }) => {
+        try {
+            let list = cache.getList();
+            if (!list) {
+                list = await client.listApis();
+                cache.setList(list ?? []);
+                list = cache.getList();
+            }
+            return textResult(list.filter((i) => matchesKeyword(i, keyword)));
+        }
+        catch (e) {
+            return errResult(e);
+        }
+    });
+    server.registerTool("create_api", {
+        description: "【会修改项目数据】在友接口项目中新建接口文档。请同时传 params/body/responses，推完后可用 get_api_detail 回读。需要 PAT 含 apis:write。\n\n" +
+            UPSERT_EXAMPLE,
+        inputSchema: z.object(writeFields),
+        annotations: {
+            title: "创建友接口",
+            destructiveHint: true,
+            readOnlyHint: false,
+        },
+    }, async (args) => {
+        try {
+            const result = await client.createApi(toWriteBody(args));
+            cache.invalidateAfterWrite(result?.id);
+            return textResult(result);
+        }
+        catch (e) {
+            return errResult(e);
+        }
+    });
+    server.registerTool("update_api", {
+        description: "【会修改项目数据】按 id 更新已有友接口文档（merge：未传字段保留原值）。更新 params/body 时请传完整列表/对象。需要 apis:write。\n\n" +
+            UPSERT_EXAMPLE,
+        inputSchema: z.object({
+            apiId: z.union([z.string(), z.number()]).describe("要更新的接口 ID"),
+            name: z.string().optional(),
+            method: z.string().optional(),
+            url: z.string().optional(),
+            description: z.string().optional(),
+            sourcePath: z
+                .string()
+                .optional()
+                .describe("接口来源路径；传了会更新文档「接口说明」的「来源」展示"),
+            moduleName: z
+                .string()
+                .optional()
+                .describe("仅用户明确指定模块时传入：有则归入、无则新建；省略归入「默认模块」"),
+            folderPath: z
+                .union([z.array(z.string()), z.string()])
+                .optional()
+                .describe('仅用户指定文件夹时传入；省略则按 url 自动建外层文件夹，不摊平'),
+            menuId: z.number().int().positive().optional(),
+            moduleId: z.number().int().positive().optional(),
+            params: z.array(paramSchema).optional(),
+            body: bodySchema.optional(),
+            responses: z.array(responseSchema).optional(),
+            status: z.string().optional(),
+            tags: z.array(z.string()).optional(),
+        }),
+        annotations: {
+            title: "更新友接口",
+            destructiveHint: true,
+            readOnlyHint: false,
+        },
+    }, async ({ apiId, ...rest }) => {
+        try {
+            const id = typeof apiId === "number" ? apiId : Number(apiId);
+            if (!Number.isFinite(id) || id <= 0) {
+                return textResult("apiId 无效", true);
+            }
+            const result = await client.updateApi(id, toUpdatePatch(rest));
+            cache.invalidateAfterWrite(id);
+            return textResult(result);
+        }
+        catch (e) {
+            return errResult(e);
+        }
+    });
+    server.registerTool("upsert_api", {
+        description: "【会修改项目数据】按 method+url 推送接口到友接口：存在则 merge 更新，不存在则创建。推荐作为从代码/OpenAPI 同步的主入口。请一并推送 params/body；省略 folderPath 时服务端按 url 自动建外层文件夹（对标 Apifox，不摊平），用户指定目录时再传 folderPath。需要 apis:write。\n\n" +
+            UPSERT_EXAMPLE,
+        inputSchema: z.object(writeFields),
+        annotations: {
+            title: "Upsert 友接口",
+            destructiveHint: true,
+            readOnlyHint: false,
+        },
+    }, async (args) => {
+        try {
+            const result = await client.upsertApi(toWriteBody(args));
+            cache.invalidateAfterWrite(result?.id);
+            return textResult(result);
+        }
+        catch (e) {
+            return errResult(e);
+        }
+    });
+    server.registerTool("refresh_cache", {
+        description: "清空本进程内的接口列表/详情缓存，下次 list/get 会重新请求后端。",
+        inputSchema: z.object({}),
+    }, async () => {
+        cache.clear();
+        return textResult({ ok: true, message: "缓存已清空" });
+    });
+    return server;
+}

package/dist/types.d.ts

@@ -0,0 +1,44 @@
+export type YoujkConfig = {
+    baseUrl: string;
+    accessToken: string;
+    projectId: string;
+};
+export type ApiSummary = {
+    id: number;
+    name: string;
+    method: string;
+    url: string;
+    menuId?: number;
+    moduleId?: number;
+};
+export type YoujkEnvelope<T> = {
+    code: number;
+    message?: string;
+    result?: T;
+};
+export type ApiWriteResult = {
+    action: "created" | "updated";
+    id: number;
+    name?: string;
+    method?: string;
+    url?: string;
+};
+export type ApiWriteBody = {
+    name: string;
+    method: string;
+    url: string;
+    description?: string;
+    /** 接口来源路径，文档预览「接口说明」区展示 */
+    sourcePath?: string;
+    /** 用户指定模块时：有则归入、无则新建；省略则归入「默认模块」 */
+    moduleName?: string;
+    /** 用户指定目录时使用；省略则按 url 自动建外层文件夹（不摊平） */
+    folderPath?: string | string[];
+    menuId?: number;
+    moduleId?: number;
+    params?: unknown;
+    body?: unknown;
+    responses?: unknown;
+    status?: string;
+    tags?: string[];
+};

package/dist/types.js

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

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "youjiekou-mcp-server",
+  "version": "0.1.9",
+  "description": "YouJK (友接口) MCP Server - read and push API definitions via MCP tools",
+  "type": "module",
+  "bin": {
+    "youjiekou-mcp-server": "bin/youjk-mcp-server.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc && node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "youjk",
+    "api"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.0.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  }
+}