Simple YAPI MCP Server

中文 | English

一个简单的利用YAPI openapi能力的mcp server实现，让ai agents能够直接访问和操作YAPI中的API文档信息。

基于modelcontextprotocol sdk实现。

已实现功能

✅ 获取项目信息和接口数据
✅ 管理接口分类
✅ 添加新接口
✅ 更新已有接口

安装与使用

$3

YApi的token是项目粒度的，每个项目不同，获取位置在项目的「设置」→ 「token配置」中。

此菜单需要有项目「开发者」或「组长」的权限才可以看到，如果你没看到，请首先确认权限。

token具有新增/编辑接口的权限，请务必确认权限范围。

$3

baseUrl和token是必须参数，可以通过env变量控制或者在对话时提供给AI，0.0.3以上的版本已经支持MCP Elicitation，支持的客户端会询问用户。
调用成功后的baseUrl和token会被缓存起来，默认缓存时间为15分钟，可以通过env环境变量配置YAPI_CREDENTIAL_TTL_MINUTES控制。

#### 使用npx

增加mcpServers的配置，下列为cursor中的示例：

``json
{
"mcpServers": {
"simple-yapi-mcp": {
"command": "npx",
"args": [
"-y",
"simple-yapi-mcp"
],
"env": {
"YAPI_BASE_URL": "",
"YAPI_PROJECT_TOKEN": ""
}
}
}
}
`

其中env配置中的YAPI_BASE_URL和YAPI_PROJECT_TOKEN并非必填，你可以在调用agent时再告诉agent。根据配置的场景，比如全局使用时就可以不添加配置或者只添加YAPI_BASE_URL的配置。

如果是按项目维度做的mcp配置，那建议都用env来配置参数，因为单项目的baseUrl和token一般是固定的。

#### 全局安装
通过全局安装simple-yapi-mcp来增加mcp servers。
`bash
npm install -g simple-yapi-mcp
`

配置文件：
`json
{
"mcpServers": {
"simple-yapi-mcp": {
"command": "simple-yapi-mcp",
"args": [],
"env": {
"YAPI_BASE_URL": "",
"YAPI_PROJECT_TOKEN": ""
}
}
}
}
`

#### 本地clone项目

如果是本地clone的项目，那需要先安装相应的依赖并执行转译
`bash
cd ""
npm install
npm run build
`

再增加配置
`json
{
"mcpServers": {
"simple-yapi-mcp": {
"command": "node",
"args": [
"/dist/index.js"
],
"env": {
"YAPI_BASE_URL": "",
"YAPI_PROJECT_TOKEN": ""
}
}
}
}
`




$3


因为agent解析意图再调用工具，在声明意图时，建议直接强调YAPI。所有暴露的tool都添加了yapi_的前缀，也是用于更好的区分，避免与其他工具混淆。

用法示例

$3

`
"查询YAPI中标签管理接口，为当前ts文件增加types信息"
"根据YAPI项目中的用户信息接口为它编写测试用例"
`

$3

`
"在YAPI项目添加一个"用户系统"分类"
"为当前的接口代码增加YAPI接口信息并放在"用户系统"分类下"
"创建一个POST YAPI接口用于上传用户头像，需要支持文件上传"
"更新ID为12345的YAPI接口，添加一个新的查询参数"
`

具体tool信息

YAPI MCP提供以下工具，所有工具名称均以yapi_开头，以便于AI助手识别关键字：

- yapi_get_project: 获取YAPI项目信息，包括名称、描述、项目ID和基础路径
- yapi_get_interface_list: 获取项目中所有API接口的分页列表
- yapi_get_interface: 根据ID获取特定API接口的详细信息
- yapi_get_category_list: 获取项目中所有API分类/文件夹的列表
- yapi_get_category_interfaces: 获取特定分类中API接口的分页列表
- yapi_add_category: 在YAPI项目中创建新的API分类/文件夹（需要提供项目ID）
- yapi_get_interface_menu_list: 获取接口和分类的层次菜单结构
- yapi_add_interface: 在指定分类下添加一个新的接口，支持各种HTTP方法和请求参数
- yapi_update_interface: 更新已有接口的信息，可以修改接口的路径、方法、请求参数等


开发与调试

项目本身简单，就一个typescript项目，没有什么需要特殊说明的。

自行mcp server调试比较麻烦，推荐使用@modelcontextprotocol/inspector：
`bash
npx @modelcontextprotocol/inspector node dist/index.js

如果需要调试环境变量，使用 -e 参数，多个环境变量多次添加


npx @modelcontextprotocol/inspector -e YAPI_BASE_URL= -e YAPI_PROJECT_TOKEN= node dist/index.js
``

执行后按说明打开调试页面即可连接本地服务器和调试tools。