YAPI MCP PRO

Un servidor MCP para la plataforma de gestión de interfaces YApi, que permite la operación directa y la gestión completa del ciclo de vida dentro de editores de IA.

GitHub
22
Prueba este MCPPatrocinado

Documentación

🚀 YAPI MCP PRO - Herramienta profesional de gestión de interfaces YApi

License: MIT Node.js Version TypeScript

Un potente servidor Model Context Protocol (MCP) diseñado específicamente para la plataforma de gestión de interfaces YApi. Permite operar YApi directamente desde editores de IA como Cursor, Claude Desktop, etc., ofreciendo gestión completa del ciclo de vida de las interfaces.

🚨 Solución rápida de problemas comunes

⚠️ Importante: Problema de caché de NPM (¡imprescindible!)

Si tiene problemas de conexión, revise esto primero:

# 1. 检查版本命令是否正常
npx yapi-mcp-pro --version

# 2. 如果上面命令没有正常输出版本号，执行清缓存：
npm cache clean --force

# 3. 然后重新测试
npx yapi-mcp-pro --version

🔍 Criterios de diagnóstico:

  • ✅ Normal: Muestra un número de versión como 0.2.1
  • ❌ Anomalía: Muestra mensaje de error, comando no encontrado, o se queda bloqueado

💡 ¿Por qué ocurre este problema? La caché de NPM puede estar dañada o desactualizada, impidiendo la descarga o ejecución correcta del paquete. Limpiar la caché resuelve la mayoría de los problemas de conexión.

🔧 Lista rápida de resolución de problemas

Elemento a verificarEstado normalSolución ante anomalía
🔥 Versión del paquete NPMnpx yapi-mcp-pro --version produce salidaObligatorio ejecutar: npm cache clean --force
Accesibilidad del servicio YApicurl -I {YAPI_URL} devuelve 200Verificar estado del servicio YApi, conexión de red
Validez del TokenPuede acceder a las interfaces de YApi normalmenteObtener un nuevo Token o verificar permisos
Variables de entornoYAPI_BASE_URL y YAPI_TOKEN configuradasVerificar variables de entorno o archivo de configuración

🚦 Explicación de los indicadores de estado de Cursor

EstadoSignificadoSolución
🟢 Luz verdeConexión normalPuede usarse con normalidad
🔴 Luz rojaFallo de conexión1. Ejecute primero npm cache clean --force
2. Verifique el archivo de configuración
3. Valide la conexión con YApi
🟡 Luz amarillaTiempo de espera agotadoVerifique red, configuración del firewall
⚫ Sin indicadorError de configuraciónVerifique la sintaxis JSON, reconfigúrelo

💊 Script de reparación con un clic

Si encuentra problemas, copie el siguiente comando para reparar de una vez:

# 清理NPM缓存并重新安装
npm cache clean --force && npx clear-npx-cache 2>/dev/null || true

# 验证安装
npx yapi-mcp-pro --version

# 测试YApi连接（替换为您的实际地址）
curl -I "http://your-yapi-server.com"

🚀 ¿Quiere empezar de inmediato?

Solo necesita 2 cosas:

  1. 📍 La dirección de su servidor YApi
  2. 🍪 La Cookie del navegador

⏱️ Tiempo de configuración: menos de 5 minutos

👉 Haga clic aquí para comenzar la configuración

⚡ Inicio rápido en 5 minutos

🎯 Método recomendado: Use el modo stdio del paquete NPM, sin necesidad de compilación local, ¡listo para usar!

📦 Actualización automática: Use npx -y yapi-mcp-pro para asegurarse de usar siempre la versión más reciente

🔒 Seguro y conveniente: La autenticación por Cookie descubre automáticamente todos los proyectos, configuración sencilla

🚀 ¿Totalmente principiante? ¡Resuélvalo en 3 pasos!

Si es su primera vez, siga este orden:

  1. 📥 Instale Node.js → Haga clic para ver la guía de instalación detallada
  2. 🔧 Configure Cursor → Continúe con los pasos de configuración siguientes
  3. 🎉 Empiece a usarlo → Pruebe la conexión y el uso

💡 ¿Ya tiene Node.js? ¡Empiece directamente desde el paso 2!

🎯 Primer paso: Obtener la información de autenticación de YApi

1. Obtener la dirección del servidor YApi

Copie la dirección de su servidor YApi desde la barra de direcciones del navegador, por ejemplo: http://your-yapi-server.com

2. Obtener la información de autenticación por Cookie (método recomendado)

  1. Inicie sesión en YApi: Inicie sesión normalmente en su sistema YApi desde el navegador
  2. Abra las herramientas de desarrollador: Pulse F12 o haga clic derecho y seleccione "Inspeccionar"
  3. Cambie al panel Network: Haga clic en la pestaña "Network" (Red)
  4. Active una solicitud de red: Haga clic en cualquier función de la página YApi (como actualizar la página)
  5. Vea los detalles de la solicitud: Haga clic en cualquier solicitud de red (como se muestra en el recuadro rojo)
  6. Busque el campo Cookie: En el panel derecho, busque "Request Headers"
  7. Copie el valor de Cookie: Busque el campo "Cookie" y copie el valor completo de la Cookie (como se muestra en el recuadro rojo)

Cookie获取示例

💡 Nota importante:

  • La Cookie debe incluir los dos campos clave _yapi_token y _yapi_uid
  • Formato completo como: _yapi_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...; _yapi_uid=1413; 其他cookie值
  • Copie la cadena completa de la Cookie, sin omitir ninguna parte

🔍 Ejemplo de contenido de Cookie:

_yapi_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...(您的完整token); _yapi_uid=您的用户ID; keep-alive

🔧 Segundo paso: Configurar Cursor

Método 1: Configuración a nivel de proyecto (recomendado)

Pasos:

  1. Cree la carpeta .cursor en la raíz de su proyecto (si no existe)
  2. Cree el archivo mcp.json dentro de la carpeta .cursor
  3. Copie el siguiente contenido de configuración en el archivo:

💻 Creación rápida desde terminal:

# 创建目录和文件
mkdir -p .cursor
touch .cursor/mcp.json

# 然后编辑文件内容

{
  "mcpServers": {
    "yapi-mcp-pro": {
      "command": "npx",
      "args": ["-y", "yapi-mcp-pro"],
      "env": {
        "YAPI_BASE_URL": "http://your-yapi-server.com",
        "YAPI_TOKEN": "_yapi_token=您的真实token; _yapi_uid=您的用户ID",
        "NODE_ENV": "cli"
      }
    }
  }
}

📝 Ejemplo de configuración (reemplace con su información real):

{
  "mcpServers": {
    "yapi-mcp-pro": {
      "command": "npx",
      "args": ["-y", "yapi-mcp-pro"],
      "env": {
        "YAPI_BASE_URL": "http://your-yapi-server.com",
        "YAPI_TOKEN": "_yapi_token=您的真实token值; _yapi_uid=您的用户ID",
        "NODE_ENV": "cli"
      }
    }
  }
}

Método 2: Configuración global

Edite el archivo de configuración global de Cursor:

  • macOS: ~/Library/Application Support/Cursor/User/settings.json
  • Windows: %APPDATA%\Cursor\User\settings.json
  • Linux: ~/.config/Cursor/User/settings.json

Añada el mismo contenido de configuración.

🚀 Tercer paso: Empezar a usar

  1. Reinicie Cursor - Para que la configuración MCP surta efecto
  2. Pruebe la conexión - Escriba el siguiente comando en Cursor para probar:
请获取我的YApi用户信息
请列出所有YApi项目
请搜索用户相关的接口
  1. Empiece a gestionar APIs - ¡Ahora puede gestionar las interfaces de YApi mediante el asistente de IA!

🆘 Resolución rápida de problemas

❓ ¿Aparece "Fallo de comunicación con el servidor YApi"?

  • Verifique que YAPI_BASE_URL sea correcto
  • Asegúrese de que la red pueda acceder al servidor YApi
  • Verifique que el servidor YApi esté funcionando correctamente

❓ ¿Aparece "Inicie sesión" o "Fallo de autenticación"?

  • Obtenga una nueva Cookie, asegurándose de que incluya _yapi_token y _yapi_uid
  • Verifique que la Cookie esté completa y no haya sido truncada
  • Confirme que el estado de inicio de sesión en YApi sea válido

❓ ¿No ve las herramientas MCP en Cursor?

  • Confirme que ha reiniciado Cursor
  • Verifique que la ruta y el formato del archivo de configuración sean correctos
  • Consulte el estado de conexión MCP de Cursor

❓ ¿Necesita más ayuda?

🔧 Requisitos del entorno y verificación de compatibilidad

📋 Requisitos mínimos del sistema

Antes de comenzar la configuración, asegúrese de que su sistema cumpla los siguientes requisitos:

RequisitoVersión mínimaVersión recomendadaComando de verificación
Node.js16.0.0+18.0.0+node --version
npm7.0.0+9.0.0+npm --version
Acceso a red--Poder acceder al servidor YApi y al registro NPM

🚀 Guía completa de instalación de Node.js (imprescindible para principiantes)

💡 Si ya tiene Node.js instalado, puede omitir esta sección

Compruebe si está instalado: escriba node --version en la terminal/símbolo del sistema

  • Si muestra un número de versión (como v18.17.0), ya está instalado
  • Si aparece "command not found" o un error similar, debe instalarlo

🎯 Método 1: Instalador oficial (recomendado para principiantes)

Primer paso: Visite el sitio web para descargar

  1. Abra el navegador y visite https://nodejs.org/
  2. La página detectará automáticamente su sistema operativo
  3. Haga clic en el botón verde "Download Node.js (LTS)"

Node.js官网下载

Segundo paso: Elija según su sistema operativo

Sistema operativoArchivo de descargaMétodo de instalación
Windowsnode-v18.x.x-x64.msiDoble clic para ejecutar, siga el asistente
macOSnode-v18.x.x.pkgDoble clic para ejecutar, siga el asistente
Linuxnode-v18.x.x-linux-x64.tar.xzDescomprima o use el gestor de paquetes

Tercer paso: Proceso de instalación

🪟 Usuarios de Windows:

  1. Haga doble clic en el archivo .msi descargado
  2. Haga clic en "Next" para aceptar el acuerdo de licencia
  3. Elija la ruta de instalación (se recomienda usar la ruta predeterminada)
  4. Importante: Asegúrese de marcar la opción "Add to PATH"
  5. Haga clic en "Install" para comenzar la instalación
  6. Tras la instalación, reinicie el símbolo del sistema

🍎 Usuarios de macOS:

  1. Haga doble clic en el archivo .pkg descargado
  2. Siga las instrucciones del asistente de instalación
  3. Introduzca la contraseña de administrador (si es necesario)
  4. Tras la instalación, reinicie la terminal

🐧 Usuarios de Linux:

# 下载并解压（以Ubuntu为例）
wget https://nodejs.org/dist/v18.17.0/node-v18.17.0-linux-x64.tar.xz
tar -xf node-v18.17.0-linux-x64.tar.xz

# 移动到系统目录
sudo mv node-v18.17.0-linux-x64 /opt/nodejs

# 创建软链接
sudo ln -s /opt/nodejs/bin/node /usr/local/bin/node
sudo ln -s /opt/nodejs/bin/npm /usr/local/bin/npm
sudo ln -s /opt/nodejs/bin/npx /usr/local/bin/npx

⚡ Método 2: Instalación mediante gestor de paquetes (para usuarios con experiencia)

🪟 Windows (usando Chocolatey):

# 首先安装Chocolatey (如果没有)
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# 安装Node.js
choco install nodejs

# 验证安装
node --version
npm --version

🍎 macOS (usando Homebrew):

# 首先安装Homebrew (如果没有)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装Node.js
brew install node

# 验证安装
node --version
npm --version

🐧 Linux (usando gestor de paquetes):

# Ubuntu/Debian
sudo apt update
sudo apt install nodejs npm

# CentOS/RHEL (使用dnf)
sudo dnf install nodejs npm

# CentOS/RHEL (使用yum)
sudo yum install nodejs npm

# Arch Linux
sudo pacman -S nodejs npm

# 验证安装
node --version
npm --version

🔍 Verificación de la instalación

Tras la instalación, ejecute los siguientes comandos para verificar:

# 检查Node.js版本（应显示 v16.0.0 或更高版本）
node --version

# 检查npm版本（应显示 7.0.0 或更高版本）
npm --version

# 检查npx是否可用
npx --version

# 测试npm连接（可选）
npm ping

✅ Señales de instalación correcta:

  • node --version muestra el número de versión (por ejemplo: v18.17.0)
  • npm --version muestra el número de versión (por ejemplo: 9.6.7)
  • npx --version muestra el número de versión (por ejemplo: 9.6.7)

⚠️ Problemas comunes de instalación

❌ "node: command not found"

  • Windows: Reinicie el símbolo del sistema o verifique la variable de entorno PATH
  • macOS/Linux: Reinicie la terminal o añádalo manualmente al PATH: 
    echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

❌ Versión demasiado antigua

# 更新到最新版本
npm install -g npm@latest

# 或重新下载安装最新版Node.js

❌ Problemas de permisos

# macOS/Linux: 修复npm权限
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

❌ Problemas de red (usuarios en China)

# 切换到国内镜像源
npm config set registry https://registry.npmmirror.com

# 验证镜像源
npm config get registry

🎉 Configuración recomendada tras la instalación

# 设置npm全局安装目录（避免权限问题）
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

# 添加到环境变量（macOS/Linux）
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
source ~/.profile

# Windows用户需要手动添加 %USERPROFILE%\.npm-global 到PATH环境变量

🚀 Verifique la disponibilidad de YApi MCP Pro

Tras instalar Node.js, pruebe nuestra herramienta de inmediato:

# 测试YApi MCP Pro是否可以正常运行
npx -y yapi-mcp-pro --help

# 如果看到帮助信息，说明环境配置成功！

Ver una salida similar indica éxito:

选项：
  --version            显示版本号
  --yapi-base-url      YApi服务器基础URL
  --yapi-token         YApi服务器授权Token
  --help               显示帮助信息

🔍 Script de verificación del entorno

Compruebe todos los requisitos del entorno de una sola vez:

# Windows (PowerShell)
echo "=== YApi MCP Pro 环境检查 ===" && echo "Node.js版本:" && node --version && echo "NPM版本:" && npm --version && echo "网络连通性:" && npm ping

# macOS/Linux
echo "=== YApi MCP Pro 环境检查 ===" && echo "Node.js版本:" && node --version && echo "NPM版本:" && npm --version && echo "测试NPM连接:" && npm ping

# 检查NPX可用性
npx --version

⚠️ Problemas comunes del entorno

❌ "node: command not found"

Problema: Node.js no está instalado en el sistema Solución:

  • Visite nodejs.org para descargar e instalar la última versión LTS
  • O use el gestor de paquetes: 
    # macOS (使用Homebrew)
brew install node

# Ubuntu/Debian
sudo apt update && sudo apt install nodejs npm

# Windows (使用Chocolatey)
choco install nodejs

❌ "npx: command not found"

Problema: NPX no está instalado correctamente Solución:

# 重新安装NPM (NPX包含在NPM中)
npm install -g npm@latest

# 或单独安装NPX
npm install -g npx

❌ "EACCES: permission denied"

Problema: Permisos insuficientes Solución:

# macOS/Linux: 修复NPM权限
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

# 或配置NPM使用不同目录
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

❌ Problemas de conexión de red

Problema: No se pueden descargar paquetes NPM Solución:

# 检查NPM Registry连接
npm config get registry

# 切换到国内镜像（如果在中国）
npm config set registry https://registry.npmmirror.com

# 测试网络连接
curl -I https://registry.npmjs.org

🌍 Configuración detallada por plataforma

🍎 Guía de configuración para macOS

Primer paso: Instalar dependencias

# 安装Node.js (推荐使用Homebrew)
brew install node

# 验证安装
node --version && npm --version

Segundo paso: Configurar Cursor

# 创建配置目录
mkdir -p ~/.config/Cursor/User

# 编辑配置文件
code ~/.config/Cursor/User/settings.json
# 或使用任意文本编辑器

Tercer paso: Añadir la configuración MCP En settings.json añada:

{
  "mcpServers": {
    "yapi-mcp-pro": {
      "command": "npx",
      "args": ["-y", "yapi-mcp-pro"],
      "env": {
        "YAPI_BASE_URL": "http://your-yapi-server.com",
        "YAPI_TOKEN": "您的完整Cookie字符串",
        "NODE_ENV": "cli"
      }
    }
  }
}

🪟 Guía de configuración para Windows

Primer paso: Instalar dependencias

# 使用官方安装器
# 访问 https://nodejs.org/ 下载Windows安装包

# 或使用Chocolatey
choco install nodejs

# 验证安装
node --version; npm --version

Segundo paso: Configurar Cursor

# 打开配置目录
explorer %APPDATA%\Cursor\User\

# 编辑settings.json文件
# 如果文件不存在，创建它

Tercer paso: Añadir la configuración MCP Cree o edite %APPDATA%\Cursor\User\settings.json:

{
  "mcpServers": {
    "yapi-mcp-pro": {
      "command": "npx",
      "args": ["-y", "yapi-mcp-pro"],
      "env": {
        "YAPI_BASE_URL": "http://your-yapi-server.com",
        "YAPI_TOKEN": "您的完整Cookie字符串",
        "NODE_ENV": "cli"
      }
    }
  }
}

🐧 Guía de configuración para Linux

Primer paso: Instalar dependencias

# Ubuntu/Debian
sudo apt update
sudo apt install nodejs npm

# CentOS/RHEL/Fedora
sudo dnf install nodejs npm  # Fedora
sudo yum install nodejs npm  # CentOS/RHEL

# Arch Linux
sudo pacman -S nodejs npm

# 验证安装
node --version && npm --version

Segundo paso: Configurar Cursor

# 创建配置目录
mkdir -p ~/.config/Cursor/User

# 编辑配置文件
nano ~/.config/Cursor/User/settings.json
# 或使用您喜欢的编辑器

Tercer paso: Añadir la configuración MCP

{
  "mcpServers": {
    "yapi-mcp-pro": {
      "command": "npx",
      "args": ["-y", "yapi-mcp-pro"],
      "env": {
        "YAPI_BASE_URL": "http://your-yapi-server.com",
        "YAPI_TOKEN": "您的完整Cookie字符串",
        "NODE_ENV": "cli"
      }
    }
  }
}

🧪 Verificación de la configuración

Tras completar la configuración, use los siguientes pasos para verificar:

  1. Pruebe la ejecutabilidad del servidor MCP:
# 在任意目录运行
npx -y yapi-mcp-pro --help

  1. Compruebe la configuración de Cursor:

    • Reinicie Cursor
    • Abra cualquier proyecto
    • En el chat escriba: "Por favor, obtenga mi información de usuario de YApi"

  2. Verifique el estado de la conexión:

    • Éxito: Devuelve la información del usuario
    • Fallo: Revise el mensaje de error y consulte la sección de solución de problemas

📊 Indicadores de configuración correcta

✅ Señales de configuración correcta:

  • npx -y yapi-mcp-pro --help puede mostrar la información de ayuda correctamente
  • Tras reiniciar Cursor, el estado de conexión MCP muestra yapi-mcp-pro
  • El asistente de IA responde correctamente a las solicitudes relacionadas con YApi
  • Puede obtener correctamente la información del usuario y la lista de proyectos

📋 Índice

✨ Características principales

🎯 Gestión integral de interfaces

  • CRUD de interfaces: Crear, leer, actualizar y eliminar interfaces
  • Búsqueda inteligente: Búsqueda multidimensional de interfaces (nombre, ruta, proyecto)
  • Operaciones por lotes: Soporte para copiar interfaces, importación y exportación masiva
  • Sincronización en tiempo real: Sincronización de datos en tiempo real con el servidor YApi

🏗️ Gestión de proyectos y categorías

  • Gestión de proyectos: Crear y actualizar información de proyectos
  • Gestión de categorías: Gestión completa del ciclo de vida de las categorías de interfaces
  • Control de permisos: Acceso seguro basado en el sistema de permisos de YApi

👥 Usuarios y colaboración en equipo

  • Información de usuario: Obtener información detallada del usuario actual
  • Gestión de equipos: Ver los grupos y permisos a los que pertenece el usuario

🧪 Pruebas y garantía de calidad

  • Colecciones de pruebas: Gestión de colecciones de casos de prueba de interfaces
  • Importación y exportación de datos: Soporte para formatos Swagger, JSON, etc.

⚡ Rendimiento y experiencia

  • Caché inteligente: Mecanismo de caché multicapa para mejorar la velocidad de respuesta
  • Comunicación en tiempo real: Soporte SSE para actualizaciones de datos en tiempo real
  • Doble autenticación: Dos métodos de autenticación: Cookie y Token
  • Registros detallados: Registro completo de operaciones y seguimiento de errores

🎯 Editores de IA compatibles

EditorEstado de soporteMétodo de configuración
Cursor✅ Soporte completoConfiguración MCP
Claude Desktop✅ Soporte completoConfiguración MCP
VS Code🔄 En desarrolloForma de complemento
Otras herramientas compatibles con MCP✅ Soporte teóricoProtocolo MCP estándar

🔧 Guía de configuración detallada

1. Requisitos del entorno

  • Node.js: >= 16.0.0
  • npm/pnpm: Última versión
  • Servidor YApi: Instancia de YApi accesible

2. Instalación e implementación

Método 1: Instalación mediante npm (recomendado)

# 全局安装
npm install -g yapi-mcp

# 或使用pnpm
pnpm add -g yapi-mcp

Método 2: Instalación desde el código fuente

# 克隆项目
git clone https://github.com/your-username/yapi-mcp.git
cd yapi-mcp

# 安装依赖
npm install
# 或使用 pnpm (推荐)
pnpm install

# 构建项目
npm run build

3. Configuración rápida

📁 Explicación del archivo de configuración

Toda la información sensible del proyecto se concentra en el archivo .env, que no se envía a Git, garantizando la privacidad de sus datos.

# 1. 复制配置模板
cp .env.example .env

# 2. 编辑配置文件（选择您喜欢的编辑器）
vim .env
# 或者
nano .env
# 或者
code .env

💡 Consejo: El archivo .env.example contiene una guía de configuración extremadamente detallada, que incluye:

  • 🍪 Método paso a paso para obtener la autenticación por Cookie (recomendado)
  • 🔑 Proceso completo de autenticación por Token
  • 📋 Ejemplos de configuración con formato real
  • ✅ Métodos de verificación y prueba de la configuración

¡Se recomienda encarecidamente leer primero las instrucciones detalladas del archivo .env.example!

🔐 Elementos de configuración obligatorios

Abra el archivo .env y complete los siguientes campos obligatorios:

# === 必填项 ===
YAPI_BASE_URL=http://your-yapi-server.com    # 替换为您的YApi服务器地址
YAPI_TOKEN=your_auth_token                   # 替换为您的认证信息（见下方获取方法）

# === 可选项（有默认值）===
PORT=3388                                    # MCP服务端口，默认3388
YAPI_CACHE_TTL=10                           # 缓存时间（分钟），默认10分钟
YAPI_LOG_LEVEL=info                         # 日志级别，默认info

🎯 Dos formas de obtener la información de autenticación

Método 1: Autenticación por Cookie (recomendado) ⭐

Ventajas: Descubre automáticamente todos los proyectos con permisos, configuración sencilla

Pasos:

  1. Abra el navegador e inicie sesión en su sistema YApi
  2. Pulse F12 para abrir las herramientas de desarrollador
  3. Cambie al panel Network (Red)
  4. Haga clic en cualquier función de la página YApi (como actualizar la página)
  5. En las solicitudes de red, haga clic en cualquier solicitud para ver los detalles
  6. Busque el campo Cookie dentro de Request Headers
  7. Copie el valor completo de la Cookie
# Cookie认证示例（复制您自己的Cookie）
YAPI_TOKEN=_yapi_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...; _yapi_uid=1234; other_cookies=values
Método 2: Autenticación por Token

Ventajas: Válido a largo plazo, más seguro

Pasos:

  1. Inicie sesión en YApi y entre en el proyecto que desea gestionar
  2. Haga clic en 设置 → Token配置 del proyecto
  3. Copie el Token del proyecto y el ID del proyecto
  4. Configure varios proyectos según el formato (si es necesario)
# Token认证示例
# 格式：项目ID:项目Token,项目ID:项目Token
YAPI_TOKEN=PROJECT_ID_1:your_project_token_1,PROJECT_ID_2:your_project_token_2

# 单个项目示例
YAPI_TOKEN=PROJECT_ID:your_project_token

📋 Ejemplo de configuración completo

# ================================
# YAPI MCP PRO 配置文件
# ================================
# ⚠️ 重要：此文件包含敏感信息，不要提交到Git仓库！

# === 基础配置（必填）===
YAPI_BASE_URL=http://yapi.yourcompany.com
YAPI_TOKEN=_yapi_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...; _yapi_uid=1234

# === 服务配置（可选）===
PORT=3388
YAPI_CACHE_TTL=10
YAPI_LOG_LEVEL=info

# === 高级配置（可选）===
# YAPI_GROUP_ID=YOUR_GROUP_ID      # 默认分组ID（创建项目时使用）
# YAPI_ENABLE_CACHE=true          # 是否启用缓存，默认true

4. Iniciar el servicio

# 使用项目管理脚本（推荐）
./start-mcp.sh start

# 或手动启动
npm run dev

🔧 Guía de configuración

Selección del método de autenticación

🍪 Autenticación por Cookie (recomendado)

Ventajas: Descubre automáticamente todos los proyectos, configuración sencilla, permisos completos

Pasos para obtenerla:

  1. Inicie sesión en YApi desde el navegador
  2. Abra las herramientas de desarrollador (F12)
  3. En el panel de red, copie la Cookie de cualquier solicitud
  4. Configúrela en el archivo .env
# Cookie认证配置
YAPI_BASE_URL=http://your-yapi-server.com
YAPI_TOKEN=_yapi_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...; _yapi_uid=YOUR_USER_ID

🔑 Autenticación por Token

Ventajas: Válido a largo plazo, alta seguridad, adecuado para entornos de producción

Pasos para obtenerlo:

  1. Proyecto YApi → Configuración → Configuración de Token
  2. Copie el Token del proyecto y el ID del proyecto
  3. Configure varios proyectos según el formato
# Token认证配置
YAPI_BASE_URL=http://your-yapi-server.com
YAPI_TOKEN=PROJECT_ID:YOUR_PROJECT_TOKEN,ANOTHER_PROJECT_ID:ANOTHER_TOKEN

Parámetros de configuración completos

# === 基础配置 ===
YAPI_BASE_URL=http://your-yapi-server.com    # YApi服务器地址
PORT=3388                                     # MCP服务端口

# === 认证配置 ===
YAPI_TOKEN=your_auth_info                     # 认证信息（Cookie或Token）

# === 性能配置 ===
YAPI_CACHE_TTL=10                            # 缓存时间（分钟）
YAPI_LOG_LEVEL=info                          # 日志级别

# === 可选配置 ===
YAPI_GROUP_ID=YOUR_GROUP_ID                  # 默认分组ID（创建项目时使用）

🔗 Configuración MCP para editores de IA

YAPI MCP PRO admite múltiples métodos de conexión MCP para satisfacer las necesidades de diferentes escenarios de uso.

🎯 Configuración de Cursor

Ubicación del archivo de configuración
  • Configuración a nivel de proyecto (recomendada): .cursor/mcp.json
  • Configuración global:
    • macOS: ~/Library/Application Support/Cursor/User/settings.json
    • Windows: %APPDATA%\Cursor\User\settings.json
    • Linux: ~/.config/Cursor/User/settings.json
🚀 Método 1: Modo paquete NPM (recomendado) ⭐

Ventajas:

  • ✅ Descarga automáticamente la última versión, sin compilación local
  • ✅ Configuración sencilla, listo para usar
  • ✅ Soporte para múltiples proyectos, configuración flexible
  • ✅ Gestión automática de dependencias

Configuración a nivel de proyecto .cursor/mcp.json:

{
  "mcpServers": {
    "yapi-mcp-pro": {
      "command": "npx",
      "args": ["-y", "yapi-mcp-pro"],
      "env": {
        "YAPI_BASE_URL": "http://your-yapi-server.com",
        "YAPI_TOKEN": "_yapi_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...; _yapi_uid=YOUR_USER_ID",
        "NODE_ENV": "cli",
        "YAPI_LOG_LEVEL": "info",
        "YAPI_CACHE_TTL": "10"
      }
    }
  }
}

Configuración global settings.json:

{
  "mcpServers": {
    "yapi-mcp-pro": {
      "command": "npx",
      "args": ["-y", "yapi-mcp-pro"],
      "env": {
        "YAPI_BASE_URL": "http://your-yapi-server.com",
        "YAPI_TOKEN": "your_cookie_or_token_here",
        "NODE_ENV": "cli"
      }
    }
  }
}
🔧 Método 2: Modo servidor local (HTTP/SSE)

Ventajas:

  • ✅ Mejor rendimiento, menor tiempo de inicio
  • ✅ Soporte para envío de datos en tiempo real
  • ✅ Facilita la depuración y el desarrollo
  • ✅ Soporte para múltiples clientes compartidos

Pasos:

  1. Inicie el servidor MCP local
# 启动服务
./start-mcp.sh start

# 检查状态
./start-mcp.sh status
  1. Configure la conexión en Cursor
{
  "mcpServers": {
    "yapi-mcp-pro": {
      "url": "http://localhost:3388/sse"
    }
  }
}
🛠️ Método 3: Modo de compilación local

Escenario de uso: Necesita modificar el código fuente personalizado

{
  "mcpServers": {
    "yapi-mcp-pro": {
      "command": "node",
      "args": ["/path/to/yapi-mcp/dist/index.js"],
      "env": {
        "YAPI_BASE_URL": "http://your-yapi-server.com",
        "YAPI_TOKEN": "your_token"
      }
    }
  }
}

🖥️ Configuración de Claude Desktop

Edite claude_desktop_config.json:

Modo paquete NPM (recomendado)
{
  "mcpServers": {
    "yapi-mcp-pro": {
      "command": "npx",
      "args": ["-y", "yapi-mcp-pro"],
      "env": {
        "YAPI_BASE_URL": "http://your-yapi-server.com",
        "YAPI_TOKEN": "your_cookie_or_token",
        "NODE_ENV": "cli"
      }
    }
  }
}
Modo de compilación local
{
  "mcpServers": {
    "yapi-mcp-pro": {
      "command": "node",
      "args": ["/path/to/yapi-mcp/dist/index.js"],
      "env": {
        "YAPI_BASE_URL": "http://your-yapi-server.com",
        "YAPI_TOKEN": "your_token"
      }
    }
  }
}

🔄 Otros clientes MCP

Cualquier herramienta que admita el protocolo MCP puede conectarse, solo debe configurarse según el formato de configuración MCP de la herramienta correspondiente.

📊 Comparación de métodos de configuración

Método de configuraciónVentajasDesventajasEscenario de uso
Modo paquete NPM🟢 Configuración sencilla
🟢 Actualización automática
🟢 Sin compilación		🔴 Primer inicio algo más lento🎯 Recomendado, adecuado para la mayoría de usuarios
Modo HTTP/SSE🟢 Mejor rendimiento
🟢 Soporte de envío en tiempo real
🟢 Clientes múltiples compartidos		🔴 Requiere iniciar el servicio
🔴 Ocupa un puerto		🎯 Uso intensivo, colaboración en múltiples proyectos
Modo de compilación local🟢 Control total
🟢 Personalizable		🔴 Requiere compilación
🔴 Alto coste de mantenimiento		🎯 Desarrolladores, necesidad de funciones personalizadas

⚙️ Explicación detallada de las variables de entorno

Variable de entornoDescripciónValor predeterminadoEjemplo
YAPI_BASE_URLDirección del servidor YApiNingunohttp://yapi.example.com
YAPI_TOKENToken o Cookie de autenticaciónNinguno_yapi_token=xxx; _yapi_uid=123
NODE_ENVEntorno de ejecuciónproductioncli, development
YAPI_LOG_LEVELNivel de registroinfodebug, warn, error
YAPI_CACHE_TTLTiempo de validez de la caché (minutos)1030
YAPI_ENABLE_CACHESi se habilita la cachétruefalse

🔧 Verificación de la configuración

Tras completar la configuración, pruebe la conexión en el editor de IA:

# 测试连接
请获取我的YApi用户信息

# 测试项目列表
请列出所有YApi项目

# 测试接口搜索
请搜索用户相关的接口

📚 Explicación detallada de las herramientas MCP

YAPI MCP PRO ofrece 19 herramientas profesionales, que cubren el ecosistema completo de funcionalidades de YApi:

🔧 Gestión básica de interfaces (5 herramientas)

1. yapi_get_api_desc - Obtener información detallada de la interfaz

Función: Obtener la definición completa de una interfaz especificada Parámetros:

  • projectId (string): ID del proyecto
  • apiId (string): ID de la interfaz

Información devuelta:

  • Información básica de la interfaz (nombre, ruta, método)
  • Parámetros de solicitud (parámetros de URL, parámetros de consulta, cabeceras de solicitud, cuerpo de solicitud)
  • Información de respuesta (tipo de respuesta, contenido de respuesta)
  • Documentación y descripción de la interfaz

2. yapi_save_api - Añadir o actualizar una interfaz

Función: Crear una nueva interfaz o actualizar una existente Parámetros:

  • projectId (string): ID del proyecto
  • catid (string): ID de la categoría
  • title (string): Título de la interfaz
  • path (string): Ruta de la interfaz
  • method (string): Método de solicitud
  • id (string, opcional): ID de la interfaz (obligatorio al actualizar)
  • desc (string, opcional): Descripción de la interfaz
  • req_* (opcional): Varias configuraciones de parámetros de solicitud
  • res_* (opcional): Configuración de respuesta

3. yapi_search_apis - Buscar interfaces

Función: Búsqueda multidimensional de interfaces Parámetros:

  • nameKeyword (string, opcional): Palabra clave del nombre de la interfaz
  • pathKeyword (string, opcional): Palabra clave de la ruta de la interfaz
  • projectKeyword (string, opcional): Palabra clave del proyecto
  • limit (number, opcional): Límite de resultados devueltos

Capacidades de búsqueda:

  • Soporte de coincidencia difusa
  • Búsqueda entre proyectos
  • Ordenación inteligente y deduplicación

4. yapi_delete_interface - Eliminar una interfaz

Función: Eliminar una interfaz especificada Parámetros:

  • interfaceId (string): ID de la interfaz
  • projectId (string): ID del proyecto

5. yapi_copy_interface - Copiar una interfaz

Función: Copiar una interfaz a una categoría especificada Parámetros:

  • interfaceId (string): ID de la interfaz de origen
  • projectId (string): ID del proyecto
  • catId (string, opcional): ID de la categoría de destino

📊 Gestión de proyectos (3 herramientas)

6. yapi_list_projects - Listar proyectos

Función: Obtener la lista de todos los proyectos accesibles Información devuelta:

  • ID y nombre del proyecto
  • Descripción del proyecto
  • Ruta base
  • Información del grupo al que pertenece

7. yapi_create_project - Crear proyecto

Función: Crear un nuevo proyecto de YApi Parámetros:

  • name (string): Nombre del proyecto
  • basepath (string): Ruta base
  • group_id (number): ID del grupo al que pertenece
  • desc (string, opcional): Descripción del proyecto
  • color (string, opcional): Color del proyecto
  • icon (string, opcional): Icono del proyecto

8. yapi_update_project - Actualizar proyecto

Función: Actualizar la información del proyecto Parámetros:

  • id (number): ID del proyecto
  • name (string, opcional): Nombre del proyecto
  • basepath (string, opcional): Ruta base
  • desc (string, opcional): Descripción del proyecto
  • color (string, opcional): Color del proyecto
  • icon (string, opcional): Icono del proyecto

📁 Gestión de categorías (4 herramientas)

9. yapi_get_categories - Obtener lista de categorías

Función: Obtener todas las categorías de interfaces de un proyecto Parámetros:

  • projectId (string): ID del proyecto

Información devuelta:

  • Información básica de la categoría
  • Lista de interfaces en cada categoría
  • Fecha de creación y actualización de la categoría

10. yapi_create_category - Crear categoría

Función: Crear una nueva categoría de interfaces en el proyecto Parámetros:

  • name (string): Nombre de la categoría
  • project_id (number): ID del proyecto
  • desc (string, opcional): Descripción de la categoría

11. yapi_update_category - Actualizar categoría

Función: Actualizar la información de la categoría Parámetros:

  • catId (string): ID de la categoría
  • name (string): Nombre de la categoría
  • desc (string, opcional): Descripción de la categoría

12. yapi_delete_category - Eliminar categoría

Función: Eliminar la categoría especificada Parámetros:

  • catId (string): ID de la categoría

👤 Gestión de usuarios (2 herramientas)

13. yapi_get_user_info - Obtener información del usuario

Función: Obtener información detallada del usuario actualmente conectado Información devuelta:

  • ID de usuario y nombre de usuario
  • Dirección de correo electrónico
  • Rol y permisos del usuario
  • Fecha de creación y actualización de la cuenta

14. yapi_get_user_groups - Obtener grupos del usuario

Función: Obtener la lista de grupos a los que pertenece el usuario Información devuelta:

  • ID y nombre del grupo
  • Descripción del grupo
  • Número de miembros
  • Fecha de creación del grupo

🧪 Colecciones de pruebas (2 herramientas)

15. yapi_get_test_collections - Obtener colecciones de pruebas

Función: Obtener la lista de colecciones de pruebas del proyecto Parámetros:

  • projectId (string): ID del proyecto

Información devuelta:

  • Información básica de la colección de pruebas
  • Fecha de creación y actualización
  • Descripción de la colección

16. yapi_create_test_collection - Crear colección de pruebas

Función: Crear una nueva colección de pruebas Parámetros:

  • name (string): Nombre de la colección
  • project_id (number): ID del proyecto
  • desc (string, opcional): Descripción de la colección

📥📤 Importación y exportación de datos (2 herramientas)

17. yapi_import_swagger - Importar datos Swagger

Función: Importar documentos Swagger al proyecto YApi Parámetros:

  • projectId (string): ID del proyecto de destino
  • catId (string): ID de la categoría de destino
  • swaggerData (string): Datos JSON de Swagger
  • merge (string, opcional): Modo de fusión

Modos de fusión admitidos:

  • normal: Modo normal
  • good: Fusión inteligente
  • merge: Sobrescritura completa

18. yapi_export_project - Exportar datos del proyecto

Función: Exportar datos del proyecto en el formato especificado Parámetros:

  • projectId (string): ID del proyecto
  • type (string, opcional): Formato de exportación

Formatos de exportación admitidos:

  • json: Formato JSON
  • markdown: Documento Markdown
  • swagger: Formato Swagger

🔄 Otras funciones (1 herramienta)

19. yapi_run_interface - Ejecutar prueba de interfaz

Función: Ejecutar solicitudes de prueba de interfaz Parámetros:

  • interface_id (string): ID de la interfaz
  • project_id (string): ID del proyecto
  • env_id (string, opcional): ID del entorno
  • domain (string, opcional): Dominio de prueba
  • headers (array, opcional): Cabeceras de solicitud personalizadas
  • params (object, opcional): Parámetros de solicitud
  • body (object, opcional): Cuerpo de la solicitud

💡 Ejemplos de uso

🔍 Búsqueda y gestión de interfaces

# 搜索登录相关接口
请搜索包含"登录"的接口

# 获取特定接口详情
请获取项目YOUR_PROJECT_ID中接口ID为123的详细信息

# 创建新接口
请在项目YOUR_PROJECT_ID的"用户管理"分类中创建一个用户注册接口：
- 路径：/api/user/register
- 方法：POST
- 描述：用户注册接口

🏗️ Inicialización del proyecto

# 创建新项目
请创建一个名为"电商系统"的项目，基础路径为"/api"

# 为项目创建分类结构
请为项目YOUR_PROJECT_ID创建以下分类：
1. 用户管理
2. 商品管理  
3. 订单管理
4. 支付管理

📊 Operaciones por lotes

# 批量创建接口
请为用户模块创建以下接口，都放在项目YOUR_PROJECT_ID的用户管理分类中：
1. GET /api/user/profile - 获取用户信息
2. PUT /api/user/profile - 更新用户信息
3. DELETE /api/user/account - 删除账户

# 导入Swagger文档
请将以下Swagger数据导入到项目YOUR_PROJECT_ID的API分类中：
[粘贴Swagger JSON]

🧪 Pruebas y verificación

# 创建测试集合
请为项目YOUR_PROJECT_ID创建一个名为"用户模块测试"的测试集合

# 运行接口测试
请测试项目YOUR_PROJECT_ID中接口ID为123的接口，使用测试环境

🛠️ Gestión del proyecto

Scripts de gestión del servicio

El proyecto proporciona scripts de gestión convenientes start-mcp.sh:

# 启动服务
./start-mcp.sh start

# 检查状态
./start-mcp.sh status

# 停止服务
./start-mcp.sh stop

# 重启服务
./start-mcp.sh restart

# 查看日志
./start-mcp.sh logs

# 查看实时日志
./start-mcp.sh logs -f

Gestión de registros

# 查看错误日志
grep "ERROR" yapi-mcp.log

# 查看特定时间的日志
grep "2024-01-01" yapi-mcp.log

# 清理日志
> yapi-mcp.log

Gestión de caché

# 查看缓存目录
ls -la .yapi-cache/

# 清理缓存
rm -rf .yapi-cache/*

# 重新构建缓存
./start-mcp.sh restart

🔍 Solución de problemas

Problemas comunes

🍪 Problemas de autenticación con Cookie

Problema: Error "Por favor, inicie sesión..."

# 解决方案
1. 重新登录YApi获取新Cookie
2. 检查Cookie格式是否完整
3. 确认YApi服务器地址正确

Problema: "No se ha configurado el ID del proyecto, no se puede cargar la información del proyecto"

# 解决方案
1. 确保Cookie包含 _yapi_token 和 _yapi_uid
2. 检查Cookie是否被截断
3. 重新复制完整的Cookie字符串

🔑 Problemas de autenticación con Token

Problema: "No se ha configurado el token para el ID de proyecto xxx"

# 解决方案
1. 检查 .env 中 YAPI_TOKEN 格式
2. 确认项目ID和Token匹配
3. 验证Token是否有效

🌐 Problemas de conexión de red

Problema: "Error de comunicación con el servidor YApi"

# 诊断步骤
1. ping your-yapi-server.com
2. curl -I http://your-yapi-server.com
3. 检查防火墙设置
4. 确认YApi服务器状态

🔧 Problemas de inicio del servicio

Problema: Puerto ocupado

# 查找占用进程
lsof -i :3388

# 修改端口
echo "PORT=3389" >> .env

# 重启服务
./start-mcp.sh restart

Modo de depuración

# 启用调试日志
echo "YAPI_LOG_LEVEL=debug" >> .env

# 重启服务
./start-mcp.sh restart

# 查看详细日志
./start-mcp.sh logs -f

Optimización del rendimiento

# 调整缓存时间
echo "YAPI_CACHE_TTL=30" >> .env

# 监控内存使用
ps aux | grep node

# 清理无用缓存
find .yapi-cache -name "*.json" -mtime +7 -delete

📖 Uso avanzado

Desarrollo de herramientas personalizadas

// 扩展新的MCP工具
this.server.tool(
  "yapi_custom_tool",
  "自定义工具描述",
  {
    param1: z.string().describe("参数描述")
  },
  async ({ param1 }) => {
    // 工具实现逻辑
    const result = await this.yapiService.customMethod(param1);
    return {
      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
    };
  }
);

Procesamiento de datos por lotes

// 批量导入接口
const interfaces = [
  { title: "接口1", path: "/api/test1", method: "GET" },
  { title: "接口2", path: "/api/test2", method: "POST" }
];

for (const interfaceData of interfaces) {
  await yapiService.saveInterface({
    ...interfaceData,
    project_id: "YOUR_PROJECT_ID",
    catid: "123"
  });
}

Integración con CI/CD

# GitHub Actions 示例
name: YApi Sync
on:
  push:
    branches: [main]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Setup Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '16'
      - name: Install dependencies
        run: npm install
      - name: Sync to YApi
        run: |
          npm run build
          node scripts/sync-to-yapi.js
        env:
          YAPI_BASE_URL: ${{ secrets.YAPI_BASE_URL }}
          YAPI_TOKEN: ${{ secrets.YAPI_TOKEN }}

🤝 Guía de contribución

Configuración del entorno de desarrollo

# 克隆项目
git clone git@github.com:guocong-bincai/YAPI_MCP_PRO.git
cd YAPI_MCP_PRO

# 安装依赖
pnpm install

# 启动开发模式
pnpm run dev

# 运行测试
pnpm test

# 代码格式化
pnpm run format

# 类型检查
pnpm run type-check

Normas de confirmación

# 功能开发
git commit -m "feat: 添加新的MCP工具"

# 问题修复
git commit -m "fix: 修复Cookie认证问题"

# 文档更新
git commit -m "docs: 更新使用指南"

# 性能优化
git commit -m "perf: 优化缓存机制"

Normas de código

  • Usar TypeScript para desarrollo con seguridad de tipos
  • Seguir la configuración de ESLint y Prettier
  • Escribir pruebas unitarias que cubran las funciones principales
  • Añadir comentarios JSDoc detallados

📄 Licencia

Licencia MIT - Consulte el archivo LICENSE

🙋‍♂️ Soporte y comentarios

Obtener ayuda

  1. Documentación primero: Consulte este README y la documentación relacionada
  2. Análisis de registros: Revise el archivo yapi-mcp.log
  3. Soporte de la comunidad: Envíe un Issue en GitHub
  4. Soporte comercial: Contacte con los mantenedores del proyecto

Informe de problemas

Al enviar un Issue, incluya:

  • Descripción detallada del error
  • Registro de errores completo
  • Información del entorno (versión de Node.js, sistema operativo, etc.)
  • Pasos para reproducir
  • Archivo de configuración (ocultando información sensible)

Sugerencias de funciones

Las sugerencias de funciones y mejoras son bienvenidas:

  • Describa el escenario de uso específico
  • Explique el comportamiento esperado de la función
  • Proporcione material de referencia relevante

🎉 Plantilla de inicio rápido

📦 Implementación con un clic (listo para usar)

# 1. 克隆项目
git clone git@github.com:guocong-bincai/YAPI_MCP_PRO.git
cd YAPI_MCP_PRO

# 2. 安装依赖
pnpm install
# 或者使用 npm
npm install

# 3. 创建配置文件
cp .env.example .env

⚙️ Configurar la información de conexión de YApi

📖 Importante: Antes de editar el archivo .env, consulte primero el archivo .env.example, que contiene la guía de configuración completa y los métodos de obtención.

Edite el archivo .env y complete su información de YApi:

# 首先查看详细配置指南
cat .env.example

# 然后使用任意编辑器打开配置文件
code .env        # VS Code
vim .env         # Vim
nano .env        # Nano

Ejemplo de configuración mínima:

# 必填项
YAPI_BASE_URL=http://your-yapi-server.com
YAPI_TOKEN=your_cookie_or_token

# 可选项（推荐保持默认）
PORT=3388
YAPI_CACHE_TTL=10
YAPI_LOG_LEVEL=info

🔑 Obtener información de autenticación (elija una de dos)

Método 1: Autenticación con Cookie (recomendado)

  1. Inicie sesión en YApi desde el navegador
  2. Pulse F12 → panel Network
  3. Realice cualquier operación y haga clic en la solicitud de red
  4. Copie Request Headers de Cookie
  5. Péguelo después de YAPI_TOKEN=

Método 2: Autenticación con Token

  1. Proyecto YApi → Configuración → Configuración de Token
  2. Copie el ID del proyecto y el Token
  3. Formato: YAPI_TOKEN=项目ID:Token

🚀 Iniciar el servicio

# 构建项目
pnpm run build

# 启动MCP服务
./start-mcp.sh start

# 检查状态
./start-mcp.sh status

🔗 Configurar el editor de IA

🎯 Configuración de Cursor (varios métodos)

Ubicación de los archivos de configuración
  • Configuración a nivel de proyecto (recomendado): .cursor/mcp.json
  • Configuración global: ~/.cursor/mcp.json
🚀 Método 1: Modo paquete NPM (recomendado) ⭐

Ventajas: Descarga automática de la última versión, sin necesidad de compilación local, configuración sencilla

Configuración a nivel de proyecto .cursor/mcp.json:

{
  "mcpServers": {
    "yapi-mcp-pro": {
      "command": "npx",
      "args": ["-y", "yapi-mcp-pro"],
      "env": {
        "YAPI_BASE_URL": "http://your-yapi-server.com",
        "YAPI_TOKEN": "_yapi_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...; _yapi_uid=YOUR_USER_ID",
        "NODE_ENV": "cli",
        "YAPI_LOG_LEVEL": "info",
        "YAPI_CACHE_TTL": "10"
      }
    }
  }
}
🔧 Método 2: Modo servidor local (HTTP/SSE)

Ventajas: Mejor rendimiento, soporte de notificaciones en tiempo real, uso compartido entre múltiples clientes

Pasos:

  1. Inicie el servidor MCP local
./start-mcp.sh start
  1. Configure la conexión de Cursor
{
  "mcpServers": {
    "yapi-mcp-pro": {
      "url": "http://localhost:3388/sse"
    }
  }
}
🛠️ Método 3: Modo de compilación local

Escenario aplicable: Necesita modificar el código fuente personalizado

{
  "mcpServers": {
    "yapi-mcp-pro": {
      "command": "node",
      "args": ["/path/to/YAPI_MCP_PRO/dist/index.js"],
      "env": {
        "YAPI_BASE_URL": "http://your-yapi-server.com",
        "YAPI_TOKEN": "your_token"
      }
    }
  }
}

🖥️ Configuración de Claude Desktop

Modo paquete NPM (recomendado)

Edite claude_desktop_config.json:

{
  "mcpServers": {
    "yapi-mcp-pro": {
      "command": "npx",
      "args": ["-y", "yapi-mcp-pro"],
      "env": {
        "YAPI_BASE_URL": "http://your-yapi-server.com",
        "YAPI_TOKEN": "your_cookie_or_token",
        "NODE_ENV": "cli"
      }
    }
  }
}
Modo de compilación local
{
  "mcpServers": {
    "yapi-mcp-pro": {
      "command": "node",
      "args": ["/path/to/YAPI_MCP_PRO/dist/index.js"],
      "env": {
        "YAPI_BASE_URL": "http://your-yapi-server.com",
        "YAPI_TOKEN": "your_token"
      }
    }
  }
}

📊 Comparación de métodos de configuración

Método de configuraciónVentajasDesventajasEscenario aplicable
Modo paquete NPM🟢 Configuración sencilla
🟢 Actualización automática
🟢 Sin compilación		🔴 Primer inicio ligeramente lento🎯 Recomendado, adecuado para la mayoría de usuarios
Modo HTTP/SSE🟢 Mejor rendimiento
🟢 Soporte de notificaciones en tiempo real
🟢 Uso compartido entre múltiples clientes		🔴 Requiere iniciar el servicio
🔴 Ocupa un puerto		🎯 Uso intensivo, colaboración en múltiples proyectos
Modo de compilación local🟢 Control total
🟢 Modificaciones personalizables		🔴 Requiere compilación
🔴 Alto coste de mantenimiento		🎯 Desarrolladores, necesidad de funciones personalizadas

✅ Verificar la instalación

Introduzca cualquiera de los siguientes comandos en el editor de IA para probar:

请列出所有YApi项目
请搜索用户相关的接口
请帮我创建一个新的接口分类

🎯 Lista de verificación de configuración

  • Ha clonado el proyecto e instalado las dependencias
  • Ha leído detenidamente la guía de configuración detallada del archivo .env.example 📋
  • Ha creado el archivo .env (cp .env.example .env)
  • Ha configurado YAPI_BASE_URL (dirección del servidor YApi)
  • Ha configurado YAPI_TOKEN (Cookie o Token, según la guía de .env.example)
  • Ha compilado el proyecto (pnpm run build)
  • Ha iniciado el servicio (./start-mcp.sh start)
  • Ha configurado la conexión MCP del editor de IA
  • Ha probado las funciones básicas

🔒 Recordatorio de seguridad

⚠️ Aspectos de seguridad importantes:

  1. El archivo .env contiene información sensible, nunca lo envíe al repositorio de Git
  2. Cambie el Token periódicamente, especialmente en proyectos con colaboración de varias personas
  3. No codifique de forma fija ningún Token o clave en el código
  4. Detenga el servicio a tiempo después de su uso: ./start-mcp.sh stop

✅ El proyecto incluye protección de seguridad:

  • .gitignore ignora todos los archivos sensibles
  • El código utiliza variables de entorno, sin información sensible codificada de forma fija
  • Soporte de visualización de Token enmascarado para proteger la seguridad de los registros

🆘 Preguntas frecuentes

P: ¿Aparece el mensaje "Error de comunicación con el servidor YApi"? R: Compruebe si YAPI_BASE_URL es correcto y asegúrese de que la red puede acceder al servidor YApi

P: ¿Aparece el mensaje "Por favor, inicie sesión" o "Token no configurado"? R: Vuelva a obtener la Cookie o el Token y asegúrese de que el formato es correcto

P: ¿El puerto 3388 está ocupado? R: Modifique PORT=3389 en .env y reinicie el servicio

P: ¿Cómo garantizar la seguridad de mi Token? R:

  • Use autenticación con Cookie (caduca automáticamente)
  • Cambie el Token periódicamente
  • No haga capturas de pantalla ni comparta configuraciones que contengan el Token
  • El .gitignore del proyecto ya protege los archivos sensibles

🚀 ¡Ahora tiene el asistente de IA de YApi más potente y seguro!

Variable de entornoDescripciónValor predeterminadoEjemplo
YAPI_BASE_URLDirección del servidor YApiNingunohttp://yapi.example.com
YAPI_TOKENToken o Cookie de autenticaciónNingunoToken: projectId:token o Cookie: _yapi_token=xxx; _yapi_uid=123
PORTPuerto del servidor MCP33883000
YAPI_CACHE_TTLTiempo de validez de caché (minutos)1030
YAPI_LOG_LEVELNivel de registroinfodebug, info, warn, error
YAPI_ENABLE_CACHESi se habilita la cachétruefalse deshabilita la caché, true habilita la caché

✨ Características

🔗 Múltiples métodos de conexión MCP

  • 📦 Modo paquete NPM: Use npx yapi-mcp-pro para descargar automáticamente la última versión (recomendado)
  • 🌐 Modo HTTP/SSE: Modo servidor local, soporte de notificaciones de datos en tiempo real
  • 🛠️ Modo de compilación local: Soporte de modificación y depuración personalizada del código fuente

🔐 Mecanismo de autenticación flexible

  • 🍪 Autenticación con Cookie: Descubre automáticamente todos los proyectos con permisos, configuración sencilla
  • 🔑 Autenticación con Token: Autenticación de Token a nivel de proyecto, válida a largo plazo, más segura
  • 👥 Soporte de múltiples proyectos: Gestione varios proyectos YApi simultáneamente

📋 Gestión completa del ciclo de vida de las interfaces

  • CRUD de interfaces: Crear, leer, actualizar, eliminar interfaces
  • 🔍 Búsqueda inteligente: Búsqueda multidimensional de interfaces (nombre, ruta, proyecto)
  • 📁 Gestión de categorías: Gestión completa del ciclo de vida de las categorías de interfaces
  • 🧪 Colecciones de pruebas: Gestión y ejecución de casos de prueba de interfaces

🚀 Alto rendimiento y caché inteligente

  • ⚡ Caché inteligente: Mecanismo de caché multicapa para mejorar la velocidad de respuesta
  • 🔄 Sincronización en tiempo real: Sincronización de datos en tiempo real con el servidor YApi
  • 🎯 Control flexible de caché: Soporte de actualización forzada y desactivación completa de la caché
  • 📊 Monitorización del rendimiento: Registros de operaciones detallados y estadísticas de rendimiento

🛠️ Amigable para desarrolladores

  • 📄 Importación y exportación de datos: Soporte de importación Swagger y exportación en múltiples formatos
  • 🔧 Configuración de variables de entorno: Gestión de configuración flexible
  • 🐛 Registros detallados: Registros de operaciones completos y seguimiento de errores
  • 🎨 Soporte de TypeScript: Definiciones de tipos completas y sugerencias inteligentes

🎊 Resumen

✅ YAPI MCP PRO ahora admite múltiples métodos de conexión

Método de conexiónCaracterísticasEscenario aplicable
📦 Modo paquete NPM🚀 Listo para usar, actualización automática🎯 Recomendado para todos los usuarios
🌐 Modo HTTP/SSE⚡ Alto rendimiento, notificaciones en tiempo real🎯 Uso intensivo, colaboración en múltiples proyectos
🛠️ Modo de compilación local🔧 Control total, personalizable🎯 Desarrolladores, necesidad de funciones personalizadas

🚀 Ruta de inicio rápido recomendada

  1. Nuevos usuarios → Elija el modo paquete NPM, configuración sencilla, listo para usar
  2. Usuarios intensivos → Elija el modo HTTP/SSE, mejor rendimiento, soporte de notificaciones en tiempo real
  3. Desarrolladores → Elija el modo de compilación local, puede personalizar y modificar el código fuente

💡 Puntos clave de configuración

  • Método de autenticación: La autenticación con Cookie es la más sencilla, la autenticación con Token es la más segura
  • Nivel de configuración: La configuración a nivel de proyecto tiene prioridad, la configuración global como respaldo
  • Variables de entorno: Soporte de configuración amplia de variables de entorno
  • Mecanismo de caché: La caché inteligente mejora el rendimiento, soporte de actualización forzada

🎯 Comience ahora

Elija el método de conexión adecuado para usted, siga la guía de configuración correspondiente y en unos minutos podrá empezar a usar el potente asistente de IA de YApi.

🔗 Enlaces relacionados

🎉 ¡Disfrute de su viaje con el asistente de IA de YApi!