YApi MCP Bridge

Сервер YApi на основе Model Context Protocol (MCP), позволяющий AI-клиентам с поддержкой MCP запрашивать, искать, создавать и обновлять интерфейсы YApi.

Возможности

В настоящее время предоставляются следующие инструменты:

Сервер не предоставляет инструментов удаления, чтобы AI-клиенты не могли случайно выполнить необратимые операции.

Related MCP server: YApi MCP Server

Установка через npm

Клонировать репозиторий не требуется, можно запустить напрямую:

npx -y yapi-mcp-bridge

Также можно установить глобально:

npm install -g yapi-mcp-bridge
yapi-mcp-bridge

После глобальной установки можно использовать следующую команду для просмотра статистики вызовов инструментов:

yapi-mcp-stats

Установка из исходного кода

Требования к окружению

• Node.js 18 или новее

• Работоспособный экземпляр YApi

• Cookie YApi с правами доступа к соответствующему проекту

Для запуска из исходного кода также требуется pnpm 10 или новее. В macOS можно установить Node.js и pnpm через Homebrew:

brew install node pnpm

Установка зависимостей

Перейдите в каталог проекта и выполните:

pnpm install

Настройка YApi

Скопируйте пример переменных окружения:

cp .env.example .env

Отредактируйте .env:

YAPI_HOST=https://yapi.example.com
YAPI_COOKIE=_yapi_token=xxx;_yapi_uid=xx;

Описание параметров:

• YAPI_HOST: адрес службы YApi, указывайте только протокол и домен, не включайте /api.

• YAPI_COOKIE: полная строка Cookie, используемая при доступе к YApi.

• YAPI_LOG_FILE: необязательный путь к файлу журнала, по умолчанию ~/.yapi-mcp/logs/yapi-mcp.log.

После входа в YApi можно открыть панель Network в инструментах разработчика браузера, выбрать любой запрос YApi и скопировать Cookie из Request Headers. Cookie равнозначен учётным данным для входа — не отправляйте его в Git и не сообщайте другим; в этом проекте .env уже по умолчанию игнорируется.

Запуск сервера

В корневом каталоге проекта выполните:

pnpm start

Это stdio MCP Server. После прямого запуска обычной HTTP-страницы нет, интерактивные подсказки не выводятся; он ожидает обмена данными с MCP-клиентом через стандартный ввод-вывод.

После успешного запуска сервер выводит похожую информацию через stderr, не загрязняя stdout, используемый для связи MCP:

[yapi-mcp] server started (stdio), tools=9, log=~/.yapi-mcp/logs/yapi-mcp.log

Запуск тестов:

pnpm test

Подключение MCP-клиента

При использовании npm-пакета добавьте в клиенте, поддерживающем stdio MCP Server, следующую конфигурацию:

{
  "mcpServers": {
    "yapi": {
      "command": "npx",
      "args": [
        "-y",
        "yapi-mcp-bridge"
      ],
      "env": {
        "YAPI_HOST": "https://yapi.example.com",
        "YAPI_COOKIE": "_yapi_token=xxx;_yapi_uid=xx;"
      }
    }
  }
}

Если используется запуск из исходного кода, можно продолжать использовать конфигурацию с абсолютным путём Node.js:

{
  "command": "node",
  "args": ["/absolute/path/to/yapi-mcp-server/src/index.js"],
  "env": {
    "YAPI_HOST": "https://yapi.example.com",
    "YAPI_COOKIE": "_yapi_token=xxx;_yapi_uid=xx;"
  }
}

После изменения конфигурации перезапустите или перезагрузите MCP-клиент. Клиент должен обнаружить 9 инструментов, начинающихся с yapi_.

Использование

После подключения можно напрямую давать AI-клиенту команды на естественном языке для работы с YApi.

Запрос проектов и интерфейсов

获取 YApi 项目 1922 的详情。

列出 YApi 项目 1922 的所有接口分类。

在 YApi 项目 1922 中搜索路径包含 /order 的接口，并获取匹配接口的常用定义。

yapi_get_interface по умолчанию возвращает только следующую часто используемую информацию:

• ID интерфейса, заголовок, HTTP-метод и путь

• Описание интерфейса

• Входные параметры Path, Query, Header и Body

• Тип ответа и содержимое ответа

Если необходимо проверить метаданные YApi или получить исходный ответ, можно явно указать full: true:

获取 YApi 接口 5001 的原始全量数据。

Создание категории интерфейсов

在 YApi 项目 1922 中创建一个名为“订单管理”的接口分类。

Создание интерфейса

在 YApi 项目 1922、分类 3001 中创建接口：
标题为“创建订单”，方法为 POST，路径为 /orders，
请求体类型为 JSON，请求示例为 {"productId": 1001, "quantity": 2}，
响应示例为 {"id": 9001, "status": "created"}。

Обязательные параметры при создании интерфейса:

requestBody и responseBody необходимо передавать в виде строк. Если содержимое является JSON или JSON Schema, его также нужно предварительно сериализовать в строку.

Обновление интерфейса

把 YApi 接口 5001 的标题修改为“查询订单详情”，状态修改为 done，并添加 order 标签。

Для обновления интерфейса достаточно указать ID интерфейса и поля, которые нужно изменить; не указанные поля не отправляются в YApi.

Журнал и статистика вызовов

Сервер по умолчанию записывает журнал в:

~/.yapi-mcp/logs/yapi-mcp.log

Журнал использует формат JSON Lines, по одному событию в строке. Например:

{"timestamp":"2026-08-21T08:00:00.000Z","event":"tool_call","tool":"yapi_get_interface","status":"success","durationMs":128}

Журнал инструментов записывает только имя инструмента, статус вызова и затраченное время; параметры вызова, содержимое интерфейсов, Cookie и другие учётные данные не записываются.

Если после добавления записей журнал превышает 1000 записей, сервер автоматически удаляет самые старые 300 записей, чтобы файл журнала не рос бесконечно.

Просмотр частоты вызовов инструментов, количества успешных и неудачных вызовов, а также среднего времени выполнения:

# 全局安装
yapi-mcp-stats

# 从源码运行
pnpm stats

С помощью YAPI_LOG_FILE можно изменить расположение журнала. При использовании относительного пути он разрешается относительно каталога запуска сервера; в MCP-клиенте рекомендуется указывать абсолютный путь.

Часто задаваемые вопросы

Возвращается «Пожалуйста, войдите» или нет прав доступа

Проверьте следующее:

• Полон ли YAPI_COOKIE, не истёк ли он.

• Имеет ли пользователь, соответствующий текущему Cookie, права доступа или редактирования проекта.

• Был ли MCP Server перезапущен после изменения Cookie.

Клиент не находит сервер

• Убедитесь, что src/index.js в конфигурации MCP использует абсолютный путь.

• Убедитесь, что command указывает на исполняемый Node.js.

• Выполните pnpm test в каталоге проекта, чтобы убедиться, что зависимости и среда выполнения в порядке.

Изменения .env не вступают в силу

.env по умолчанию загружается из текущего рабочего каталога сервера. При запуске из терминала выполняйте pnpm start в корневом каталоге проекта; при запуске из MCP-клиента рекомендуется явно передавать YAPI_HOST и YAPI_COOKIE через env в конфигурации.

Структура проекта

src/
├── handlers/       # MCP 工具 handler 与 YApi 方法映射
├── tools/          # 工具定义、Zod 输入输出 Schema
├── index.js        # stdio Server 入口
├── server.js       # McpServer 注册
└── yapi.js         # YApi HTTP API 封装
test/               # 单元测试与 MCP 注册测试

Предупреждения по безопасности

• Не отправляйте в Git .env или Cookie YApi.

• Инструменты записи реально изменяют данные YApi; перед выполнением следует убедиться в правильности ID проекта, ID категории и ID интерфейса.

• Рекомендуется использовать учётную запись YApi с максимально ограниченными правами.

• Журнал по умолчанию сохраняется в .yapi-mcp/logs/ в домашнем каталоге пользователя и не записывается в каталог установки npm.