YApi MCP Bridge

Ein YApi-Server basierend auf dem Model Context Protocol (MCP), der es MCP-fähigen KI-Clients ermöglicht, YApi-Schnittstellen abzufragen, zu durchsuchen, zu erstellen und zu aktualisieren.

Funktionen

Derzeit werden die folgenden Tools bereitgestellt:

Der Server stellt keine Lösch-Tools bereit, um zu vermeiden, dass KI-Clients versehentlich irreversible Operationen ausführen.

Related MCP server: YApi MCP Server

Installation mit npm

Kein Klonen des Repositories erforderlich, direkt ausführbar:

npx -y yapi-mcp-bridge

Auch eine globale Installation ist möglich:

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

Nach der globalen Installation können Sie mit dem folgenden Befehl die Tool-Aufrufstatistiken anzeigen:

yapi-mcp-stats

Installation aus dem Quellcode

Systemvoraussetzungen

• Node.js 18 oder höher

• Eine erreichbare YApi-Instanz

• Ein YApi-Cookie mit Zugriffsrechten für das entsprechende Projekt

Für die Ausführung aus dem Quellcode ist außerdem pnpm 10 oder höher erforderlich. Unter macOS können Node.js und pnpm mit Homebrew installiert werden:

brew install node pnpm

Abhängigkeiten installieren

Nach dem Wechsel in das Projektverzeichnis ausführen:

pnpm install

YApi konfigurieren

Die Beispiel-Umgebungsvariablen kopieren:

cp .env.example .env

.env bearbeiten:

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

Parameterbeschreibung:

• YAPI_HOST: Adresse des YApi-Dienstes, nur Protokoll und Domain angeben, nicht /api.

• YAPI_COOKIE: Die vollständige Cookie-Zeichenfolge für den Zugriff auf YApi.

• YAPI_LOG_FILE: Optionaler Pfad zur Logdatei, Standard ist ~/.yapi-mcp/logs/yapi-mcp.log.

Nach der Anmeldung bei YApi können Sie im Network-Panel der Browser-Entwicklertools eine beliebige YApi-Anfrage auswählen und das Cookie aus den Request Headers kopieren. Das Cookie entspricht den Anmeldeinformationen; es sollte nicht in Git committet oder mit anderen geteilt werden. Dieses Projekt ignoriert .env standardmäßig.

Server starten

Im Projektstammverzeichnis ausführen:

pnpm start

Dies ist ein stdio-MCP-Server. Nach dem direkten Start gibt es keine normale HTTP-Seite und es werden keine interaktiven Eingabeaufforderungen ausgegeben; er wartet darauf, dass MCP-Clients über die Standardeingabe/-ausgabe kommunizieren.

Nach erfolgreichem Start gibt der Server ähnliche Informationen über stderr aus, ohne das für die MCP-Kommunikation verwendete stdout zu beeinträchtigen:

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

Tests ausführen:

pnpm test

MCP-Clients anbinden

Bei Verwendung des npm-Pakets fügen Sie in einem Client, der stdio-MCP-Server unterstützt, die folgende Konfiguration hinzu:

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

Wenn Sie aus dem Quellcode starten, können Sie weiterhin die absolute Node.js-Pfadkonfiguration verwenden:

{
  "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;"
  }
}

Nach der Änderung der Konfiguration den MCP-Client neu starten oder neu laden. Der Client sollte 9 Tools finden, die mit yapi_ beginnen.

Verwendung

Nach der Anbindung können Sie den KI-Client direkt in natürlicher Sprache anweisen, YApi zu bedienen.

Projekte und Schnittstellen abfragen

获取 YApi 项目 1922 的详情。

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

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

yapi_get_interface gibt standardmäßig nur die folgenden häufig verwendeten Informationen zurück:

• Schnittstellen-ID, Titel, HTTP-Methode und Pfad

• Schnittstellenbeschreibung

• Path-, Query-, Header- und Body-Eingabeparameter

• Antworttyp und Antwortinhalt

Wenn Sie YApi-Metadaten untersuchen oder die Rohantwort abrufen möchten, können Sie ausdrücklich die Verwendung von full: true anfordern:

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

Schnittstellenkategorie erstellen

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

Schnittstelle erstellen

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

Pflichtparameter beim Erstellen einer Schnittstelle:

requestBody und responseBody müssen als Zeichenfolgen übergeben werden. Wenn der Inhalt JSON oder JSON Schema ist, muss er ebenfalls zuerst in eine Zeichenfolge serialisiert werden.

Schnittstelle aktualisieren

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

Zum Aktualisieren einer Schnittstelle müssen nur die Schnittstellen-ID und die zu ändernden Felder angegeben werden; nicht angegebene Felder werden nicht an YApi gesendet.

Protokollierung und Aufrufstatistiken

Der Server schreibt Protokolle standardmäßig in:

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

Die Protokolle verwenden das JSON-Lines-Format, ein Ereignis pro Zeile. Zum Beispiel:

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

Die Tool-Protokolle erfassen nur den Toolnamen, den Aufrufstatus und die Dauer, nicht die Aufrufparameter, Schnittstelleninhalte, Cookies oder andere Anmeldeinformationen.

Wenn die Protokolle nach dem Anhängen mehr als 1000 Einträge umfassen, löscht der Server automatisch die ältesten 300 Einträge, um ein unbegrenztes Wachstum der Protokolldatei zu vermeiden.

Häufigkeit, Erfolgszahl, Fehlerzahl und durchschnittliche Dauer der Tool-Aufrufe anzeigen:

# 全局安装
yapi-mcp-stats

# 从源码运行
pnpm stats

Über YAPI_LOG_FILE kann der Speicherort der Protokolle geändert werden. Bei relativen Pfaden wird relativ zum Startverzeichnis des Servers aufgelöst; in MCP-Clients wird die Konfiguration eines absoluten Pfads empfohlen.

Häufig gestellte Fragen

„Bitte anmelden“ oder keine Berechtigung

Überprüfen Sie Folgendes:

• Ob YAPI_COOKIE vollständig und nicht abgelaufen ist.

• Ob der Benutzer, dem das aktuelle Cookie gehört, Zugriffs- oder Bearbeitungsrechte für das Projekt hat.

• Ob der MCP-Server nach der Änderung des Cookies neu gestartet wurde.

Client findet den Server nicht

• Stellen Sie sicher, dass src/index.js in der MCP-Konfiguration einen absoluten Pfad verwendet.

• Stellen Sie sicher, dass command auf eine ausführbare Node.js-Instanz verweist.

• Führen Sie im Projektverzeichnis pnpm test aus, um zu bestätigen, dass Abhängigkeiten und Laufzeitumgebung in Ordnung sind.

Änderungen an .env werden nicht wirksam

.env wird standardmäßig aus dem aktuellen Arbeitsverzeichnis des Servers geladen. Beim Start im Terminal führen Sie pnpm start im Projektstammverzeichnis aus; beim Start über einen MCP-Client wird empfohlen, YAPI_HOST und YAPI_COOKIE explizit über env in der Konfiguration zu übergeben.

Projektstruktur

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

Sicherheitshinweise

• Committen Sie weder .env noch das YApi-Cookie.

• Schreib-Tools ändern tatsächlich YApi-Daten; vor der Ausführung sollten Projekt-ID, Kategorie-ID und Schnittstellen-ID bestätigt werden.

• Es wird empfohlen, ein YApi-Konto mit möglichst geringen Berechtigungen zu verwenden.

• Standardmäßig werden Protokolle unter .yapi-mcp/logs/ im Benutzerverzeichnis gespeichert, nicht im npm-Installationsverzeichnis.