# API Skill MCP

[English](https://unpkg.com/apiskill@latest/docs/mcp.md) / [中文](https://unpkg.com/apiskill@latest/docs/mcp.zh.md) / [한국어](https://unpkg.com/apiskill@latest/docs/mcp.ko.md) / [日本語](https://unpkg.com/apiskill@latest/docs/mcp.ja.md)

MCP 服务是面向 AI Agent 的原生接口，用于查询和维护与 Web、CLI 共用的 OpenAPI 文档。

## 本地 Codex 配置

API Skill 以 stdio MCP 服务运行：

```bash
node /Users/dobby/dev/apiskill/scripts/mcp-server.mjs
```

把下面配置加入 `/Users/dobby/.codex/config.toml`。如果你的 Codex 客户端会读取项目配置，也可以保留项目级 `.codex/config.toml`：

```toml
[mcp_servers.apiskill]
command = "node"
args = ["/Users/dobby/dev/apiskill/scripts/mcp-server.mjs"]
cwd = "/Users/dobby/dev/apiskill"
startup_timeout_sec = 10
tool_timeout_sec = 60
enabled = true
```

不配置缓存环境变量时，MCP 与 Web、CLI 一样默认使用 `~/.apiskill/cache`。需要按项目隔离时，设置一个绝对路径 `APISKILL_CACHE_DIR`，并确保三个进程使用完全相同的值。

重启 Codex 后运行 `/mcp`，应该能看到 `apiskill` 和下面的工具。

## 只读工具

- `apiskill_check`：检查是否有可用的 OpenAPI 缓存文档；如果没有，会返回导入示例。
- `apiskill_help`：展示 MCP 帮助、可用工具和导入示例。
- `apiskill_list_versions`：列出缓存版本。
- `apiskill_search_endpoints`：搜索接口摘要。
- `apiskill_query_api`：等价于 CLI query。单条匹配时可以返回 JSON、raw endpoint 或 CLI config。
- `apiskill_get_endpoint`：获取单个接口的参数、请求体、响应字段、手动配置和可选 raw operation。
- `apiskill_get_ai_context`：获取适合 AI 使用的接口 Markdown。
- `apiskill_get_schema`：展开指定 schema。

## 写入工具

以下工具会修改 `cache/latest-import.json` 和 `cache/versions/`：

- `apiskill_import_url`：导入直接 OpenAPI JSON/YAML 地址。
- `apiskill_crawl_openapi`：爬取 Swagger UI / Knife4j / Redoc 并导入识别到的文档。
- `apiskill_import_file`：导入本地 JSON/YAML 文件。
- `apiskill_import_curl`：执行 curl 命令并导入其 OpenAPI 响应。
- `apiskill_create_document`：创建空白 OpenAPI 文档版本，用于从零编写接口文档。
- `apiskill_create_api`：创建手动接口。
- `apiskill_edit_api`：编辑/替换手动接口。
- `apiskill_delete_api`：删除接口。

## 从零编写

如果项目还没有上游文档，可以先让 AI 调用 `apiskill_create_document`：

```json
{
  "title": "My API",
  "version": "1.0.0",
  "description": "Internal service contract"
}
```

然后用 `apiskill_create_api` 追加接口，用 `apiskill_edit_api` 修改接口，并用 `apiskill_get_endpoint` 或 `apiskill_query_api` 查询确认。这样即使没有第三方 OpenAPI 来源，也可以先通过 AI 工具生成并持续维护本地接口契约。

## 验证

```bash
npm run mcp
```

协议级验证可以依次调用 initialize、`tools/list`、`apiskill_check`、`apiskill_list_versions`。服务应返回 `serverInfo.name = apiskill-mcp`，并列出 `apiskill_*` 工具。

## 未来服务器部署

当前方案是本地 stdio。未来服务器部署可以先通过 SSH/远程执行器启动同一个 stdio 服务，并把服务器上的 `APISKILL_ROOT` 和 `APISKILL_CACHE_DIR` 配好；长期多人使用时再增加 Streamable HTTP MCP 包装层，继续调用同一个 shared core 模块，并保持工具名称和参数语义稳定。