yapi-tool

yapi-tool 是一个命令行工具和 MCP Server，用于在 AI 编码助手（Codex、Claude Code、Qoder、Cursor 等）中一键拉取公司内部 YApi 平台的接口数据，自动封装为大模型可直接消费的 Markdown API 文档或结构化 JSON。

安装

全局安装（推荐）

npm install -g @shendu-sdt/yapi-tool
# 或
pnpm add -g @shendu-sdt/yapi-tool

即用即走（npx）

npx @shendu-sdt/yapi-tool login
npx @shendu-sdt/yapi-tool fetch <url>
npx @shendu-sdt/yapi-tool fetch-md <url>
npx @shendu-sdt/yapi-tool install-command

从源码

git clone <repo-url>
cd yapi-tool
pnpm install
pnpm build

快速开始

1. 登录 YApi

yapi-tool login

交互式输入邮箱/用户名和密码。会话凭证存储在 ~/.yapi-tool/credentials.json，有效期 30 分钟，过期需重新登录。

2. 拉取 Markdown API 文档

yapi-tool fetch-md http://yapi.sdpjw.com/project/1437/interface/api/100591

输出示例：

# 分页查询

**URL:** `/client/aiAcquireCustomerTask/page`
**方法:** POST

## 请求头

| Header | 值 | 必须 |
|--------|-----|------|
| `Content-Type` | application/json | 是 |

## 请求体 (JSON)

```json
{
  "pageNum": "number",
  "pageSize": "number"
}
```

## 响应体

```json
{
  "success": "boolean",
  "code": "string"
}
```

如需给业务网关补前缀：

yapi-tool fetch-md http://yapi.sdpjw.com/project/1437/interface/api/100591 \
  --base-path /gateway/api/business-service-web

3. 拉取结构化 JSON

yapi-tool fetch http://yapi.sdpjw.com/project/1437/interface/api/100591

JSON 输出示例：

{
  "name": "获取用户信息",
  "method": "GET",
  "path": "/api/user/info",
  "description": "获取用户详细信息",
  "projectId": 1437,
  "requestParams": [
    { "name": "userId", "description": "用户ID", "required": true }
  ],
  "requestQueryParams": [
    { "name": "page", "description": "页码", "required": false }
  ],
  "requestHeaders": [
    { "name": "Authorization", "value": "", "required": true }
  ],
  "requestBodyFields": [],
  "requestBodySchema": "{\"type\":\"object\",\"properties\":{...}}",
  "responseSchema": "{\"type\":\"object\",\"properties\":{...}}",
  "responseType": "json",
  "markdown": ""
}

4. 在 AI 工具中使用（MCP）

在 Codex、Claude Desktop 或 Cursor 的 MCP 配置中添加：

{
  "mcpServers": {
    "yapi-tool": {
      "command": "yapi-tool-mcp",
      "args": []
    }
  }
}

全局安装后 yapi-tool-mcp 命令自动可用。如果用 npx：npx -y --package @shendu-sdt/yapi-tool yapi-tool-mcp

然后在 AI 中即可调用：

get_api_detail(url: "http://yapi.sdpjw.com/project/1437/interface/api/100591")
get_api_markdown(url: "http://yapi.sdpjw.com/project/1437/interface/api/100591", basePath: "/gateway/api/business-service-web")

get_api_markdown 返回 Markdown API 文档，适合直接注入 LLM 上下文；get_api_detail 返回结构化 JSON。

5. 安装 /yapi 命令模板

MCP 工具注册成功后，Codex 的 MCP 面板会显示 yapi-tool，但这不会自动生成 slash command。/yapi 是 AI 工具的本地命令模板，需要额外安装到用户目录或项目目录。

默认安装到当前用户全局目录：

npx @shendu-sdt/yapi-tool install-command

只安装 Codex：

npx @shendu-sdt/yapi-tool install-command --tool codex

安装到当前项目目录：

npx @shendu-sdt/yapi-tool install-command --scope project

预览将写入哪些路径：

npx @shendu-sdt/yapi-tool install-command --dry-run

安装路径：

| 工具 | 模板 | |------|------| | Codex 全局 | ~/.codex/skills/yapi/SKILL.md | | Claude Code 全局 | ~/.claude/commands/yapi.md | | Qoder 全局 | ~/.qoder/commands/yapi.md | | Codex 项目 | <project>/.codex/skills/yapi/SKILL.md | | Claude Code 项目 | <project>/.claude/commands/yapi.md | | Qoder 项目 | <project>/.qoder/commands/yapi.md |

安装后可在对应 AI 工具里使用：

/yapi http://yapi.sdpjw.com/project/1437/interface/api/100591
/yapi http://yapi.sdpjw.com/project/1437/interface/api/100591 --base-path /gateway/api/business-service-web
/yapi http://yapi.sdpjw.com/project/1437/interface/api/100591 --json

命令行参考

| 命令 | 说明 | |------|------| | yapi-tool login | 交互式登录 YApi，持久化凭证 | | yapi-tool fetch <url> | 拉取指定接口的完整数据并输出 LLM 适配 JSON | | yapi-tool fetch-md <url> | 拉取指定接口并输出 LLM 适配 Markdown API 文档 | | yapi-tool fetch <url> --format md | 与 fetch-md 等价 | | yapi-tool install-command | 安装 /yapi 命令模板，默认安装到用户全局 | | yapi-tool help | 显示帮助信息 | | yapi-tool-mcp | 启动 MCP Server（仅全局安装后可用） |

脚本方式

pnpm start -- login
pnpm start -- fetch <url>
pnpm start -- fetch-md <url>
pnpm start -- install-command --dry-run
pnpm start:mcp     # 启动 MCP Server

技术架构

src/
├── types/     — 共享类型定义（YApiCredentials, YApiApiDetail, LLMApiDetail）
├── auth/      — 认证模块（交互式登录、凭证持久化、过期缓存）
├── core/      — 核心业务（URL 解析、HTTP 客户端、错误处理）
├── format/    — 纯函数转换（YApi 原始数据 → LLM Markdown / JSON）
├── cli/       — CLI 入口（login / fetch 命令）
├── mcp/       — MCP Server 薄封装（get_api_detail 工具）
└── index.ts   — barrel export

设计原则

• MCP + CLI 双层架构：CLI 核心实现全部业务逻辑，MCP Server 做薄封装层，最大化跨 AI 工具复用
• 单向依赖：types ← auth ← core ← format ← {cli, mcp}，cli/ 和 mcp/ 互不依赖
• 纯函数模块：format/ 零副作用，完全可测试
• 类型安全：TypeScript strict mode

安全说明

• 凭证存储在 ~/.yapi-tool/credentials.json（明文 cookie），仅建议在受信内网环境使用
• HTTP 协议 URL 会输出安全警告
• 仅允许请求配置的白名单主机名（默认 yapi.sdpjw.com）
• 不支持存储密码（安全考虑），会话过期后需重新登录

开发

# 安装依赖
pnpm install

# 编译
pnpm build

# 运行测试
pnpm test           # vitest run
pnpm test:watch     # vitest watch

# 开发模式（自动重编译）
pnpm dev

发布到 npm

# 确保已登录
npm login

# 构建
pnpm build

# 发布
npm publish

许可证

MIT