YAPI MCP PRO

Um servidor MCP para a plataforma de gerenciamento de interfaces YApi, permitindo operação direta e gerenciamento completo do ciclo de vida dentro de editores de IA.

GitHub
22
Experimente este MCPPatrocinado

Documentação

🚀 YAPI MCP PRO - Ferramenta profissional de gerenciamento de API YApi

License: MIT Node.js Version TypeScript

Um servidor Model Context Protocol (MCP) poderoso, projetado especificamente para a plataforma de gerenciamento de interfaces YApi. Suporta operação direta do YApi em editores de IA como Cursor, Claude Desktop, oferecendo gerenciamento completo do ciclo de vida de interfaces.

🚨 Solução rápida para problemas comuns

⚠️ Importante: Problema de cache NPM (leia primeiro!)

Se você encontrar problemas de conexão, verifique isto primeiro:

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

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

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

🔍 Critérios de avaliação:

  • ✅ Normal: Exibe número de versão como 0.2.1
  • ❌ Anormal: Exibe mensagem de erro, comando não encontrado ou fica travado

💡 Por que isso acontece? O cache NPM pode estar corrompido ou desatualizado, impedindo o download ou execução correta do pacote. Limpar o cache resolve a maioria dos problemas de conexão.

🔧 Lista rápida de verificação de falhas

Item de verificaçãoEstado normalTratamento de anomalia
🔥 Versão do pacote NPMnpx yapi-mcp-pro --version tem saídaDeve executar: npm cache clean --force
Serviço YApi acessívelcurl -I {YAPI_URL} retorna 200Verificar status do serviço YApi, conexão de rede
Validade do TokenConsegue acessar a API YApi normalmenteObter novo Token ou verificar permissões
Variáveis de ambienteYAPI_BASE_URL e YAPI_TOKEN configuradasVerificar variáveis de ambiente ou arquivo de configuração

🚦 Explicação do indicador de status do Cursor

StatusSignificadoSolução
🟢 Luz verdeConexão normalPode usar normalmente
🔴 Luz vermelhaFalha na conexão1. Execute primeiro npm cache clean --force
2. Verifique o arquivo de configuração
3. Valide a conexão YApi
🟡 Luz amarelaTempo de conexão esgotadoVerificar rede, configurações de firewall
⚫ Sem exibiçãoErro de configuraçãoVerificar sintaxe JSON, reconfigurar

💊 Script de correção com um clique

Se encontrar problemas, copie o comando abaixo para corrigir com um clique:

# 清理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"

🚀 Quer começar imediatamente?

Você só precisa de 2 coisas:

  1. 📍 O endereço do seu servidor YApi
  2. 🍪 O Cookie do seu navegador

⏱️ Tempo de configuração: menos de 5 minutos

👉 Clique aqui para começar a configurar

⚡ Início rápido em 5 minutos

🎯 Forma recomendada: Use o modo stdio do pacote NPM, sem necessidade de build local, pronto para usar!

📦 Atualização automática: Use npx -y yapi-mcp-pro para garantir sempre a versão mais recente

🔒 Seguro e conveniente: Autenticação por Cookie descobre automaticamente todos os projetos, configuração simples

🚀 Totalmente iniciante? Resolva em 3 passos!

Se esta é a sua primeira vez, siga esta ordem:

  1. 📥 Instalar Node.js → Clique para ver o guia detalhado de instalação
  2. 🔧 Configurar Cursor → Continue com os passos de configuração abaixo
  3. 🎉 Começar a usar → Testar conexão e uso

💡 Já tem Node.js? Comece direto do passo 2!

🎯 Primeiro passo: Obter informações de autenticação YApi

1. Obter o endereço do servidor YApi

Copie o endereço do servidor YApi da barra de endereços do navegador, por exemplo: http://your-yapi-server.com

2. Obter informações de autenticação por Cookie (forma recomendada)

  1. Acesse o YApi: Faça login normalmente no seu sistema YApi no navegador
  2. Abra as ferramentas do desenvolvedor: Pressione F12 ou clique com o botão direito e selecione "Inspecionar"
  3. Mude para o painel Network: Clique na aba "Network" (Rede)
  4. Dispare uma requisição de rede: Clique em qualquer funcionalidade na página YApi (como atualizar a página)
  5. Veja os detalhes da requisição: Clique em qualquer requisição de rede (como mostrado no quadro vermelho abaixo)
  6. Encontre o campo Cookie: No painel à direita, encontre "Request Headers"
  7. Copie o valor do Cookie: Encontre o campo "Cookie" e copie o valor completo do Cookie (como mostrado no quadro vermelho abaixo)

Cookie获取示例

💡 Dica importante:

  • O Cookie deve conter os dois campos-chave _yapi_token e _yapi_uid
  • Formato completo como: _yapi_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...; _yapi_uid=1413; 其他cookie值
  • Copie a string completa do Cookie, sem omitir nenhuma parte

🔍 Exemplo de conteúdo do Cookie:

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

🔧 Segundo passo: Configurar o Cursor

Forma 1: Configuração no nível do projeto (recomendada)

Passos:

  1. Crie a pasta .cursor na raiz do seu projeto (se não existir)
  2. Crie o arquivo mcp.json dentro da pasta .cursor
  3. Copie o seguinte conteúdo de configuração para o arquivo:

💻 Criação rápida pelo 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"
      }
    }
  }
}

📝 Exemplo de configuração (substitua pelas suas informações reais):

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

Forma 2: Configuração global

Edite o arquivo de configuração global do Cursor:

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

Adicione o mesmo conteúdo de configuração.

🚀 Terceiro passo: Começar a usar

  1. Reinicie o Cursor - Para que a configuração MCP tenha efeito
  2. Teste a conexão - Digite o seguinte comando no Cursor para testar:
请获取我的YApi用户信息
请列出所有YApi项目
请搜索用户相关的接口
  1. Comece a gerenciar APIs - Agora você pode gerenciar interfaces YApi através do assistente de IA!

🆘 Solução rápida de problemas

❓ Mensagem "Falha na comunicação com o servidor YApi"?

  • Verifique se YAPI_BASE_URL está correto
  • Garanta que a rede consiga acessar o servidor YApi
  • Verifique se o servidor YApi está rodando normalmente

❓ Mensagem "Por favor, faça login" ou "Falha na autenticação"?

  • Obtenha um novo Cookie, garantindo que contenha _yapi_token e _yapi_uid
  • Verifique se o Cookie está completo e não foi truncado
  • Confirme se o status de login do YApi é válido

❓ Não vê as ferramentas MCP no Cursor?

  • Confirme se o Cursor foi reiniciado
  • Verifique se o caminho e o formato do arquivo de configuração estão corretos
  • Veja o status da conexão MCP no Cursor

❓ Precisa de mais ajuda?

🔧 Requisitos de ambiente e verificação de compatibilidade

📋 Requisitos mínimos do sistema

Antes de começar a configuração, garanta que seu sistema atenda aos seguintes requisitos:

Item de requisitoVersão mínimaVersão recomendadaComando de verificação
Node.js16.0.0+18.0.0+node --version
npm7.0.0+9.0.0+npm --version
Acesso à rede--Conseguir acessar o servidor YApi e o NPM Registry

🚀 Guia completo de instalação do Node.js (obrigatório para iniciantes)

💡 Se você já tem o Node.js instalado, pode pular esta parte

Verifique se está instalado: Digite node --version no terminal/prompt de comando

  • Se exibir um número de versão (como v18.17.0), está instalado
  • Se aparecer "command not found" ou erro semelhante, é necessário instalar

🎯 Forma 1: Instalador oficial (recomendado para iniciantes)

Primeiro passo: Acessar o site oficial para download

  1. Abra o navegador e acesse https://nodejs.org/
  2. A página detecta automaticamente seu sistema operacional
  3. Clique no botão verde "Download Node.js (LTS)"

Node.js官网下载

Segundo passo: Escolha de acordo com seu sistema operacional

Sistema operacionalArquivo para downloadForma de instalação
Windowsnode-v18.x.x-x64.msiClique duas vezes para executar, siga o assistente
macOSnode-v18.x.x.pkgClique duas vezes para executar, siga o assistente
Linuxnode-v18.x.x-linux-x64.tar.xzDescompacte ou use o gerenciador de pacotes

Terceiro passo: Processo de instalação

🪟 Usuários Windows:

  1. Clique duas vezes no arquivo .msi baixado
  2. Clique em "Next" para aceitar o contrato de licença
  3. Escolha o caminho de instalação (recomenda-se usar o padrão)
  4. Importante: Garanta que a opção "Add to PATH" esteja marcada
  5. Clique em "Install" para começar a instalação
  6. Após a instalação, reinicie o prompt de comando

🍎 Usuários macOS:

  1. Clique duas vezes no arquivo .pkg baixado
  2. Siga as instruções do assistente de instalação
  3. Digite a senha de administrador (se necessário)
  4. Após a instalação, reinicie o terminal

🐧 Usuários 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

⚡ Forma 2: Instalação via gerenciador de pacotes (para usuários experientes)

🪟 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 gerenciador de pacotes):

# 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

🔍 Verificação da instalação

Após a instalação, execute os seguintes comandos para verificar:

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

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

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

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

✅ Sinais de instalação bem-sucedida:

  • node --version exibe número de versão (como: v18.17.0)
  • npm --version exibe número de versão (como: 9.6.7)
  • npx --version exibe número de versão (como: 9.6.7)

⚠️ Problemas comuns de instalação

❌ "node: command not found"

  • Windows: Reinicie o prompt de comando ou verifique a variável de ambiente PATH
  • macOS/Linux: Reinicie o terminal ou adicione manualmente ao PATH: 
    echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

❌ Versão muito antiga

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

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

❌ Problemas de permissão

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

❌ Problemas de rede (usuários na China)

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

# 验证镜像源
npm config get registry

🎉 Configurações recomendadas após a instalação

# 设置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环境变量

🚀 Verificar a disponibilidade do YApi MCP Pro

Após instalar o Node.js, teste nossa ferramenta imediatamente:

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

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

Ver uma saída semelhante indica sucesso:

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

🔍 Script de verificação de ambiente

Verifique todos os requisitos de ambiente com um clique:

# 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 comuns de ambiente

❌ "node: command not found"

Problema: Node.js não está instalado no sistema Solução:

  • Acesse nodejs.org para baixar e instalar a versão LTS mais recente
  • Ou use o gerenciador de pacotes: 
    # 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 não foi instalado corretamente Solução:

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

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

❌ "EACCES: permission denied"

Problema: Permissões insuficientes Solução:

# 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 conexão de rede

Problema: Não foi possível baixar o pacote NPM Solução:

# 检查NPM Registry连接
npm config get registry

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

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

🌍 Configuração detalhada para diferentes plataformas

🍎 Guia de configuração para macOS

Primeiro passo: Instalar dependências

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

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

Segundo passo: Configurar o Cursor

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

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

Terceiro passo: Adicionar configuração MCP Em settings.json, adicione:

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

🪟 Guia de configuração para Windows

Primeiro passo: Instalar dependências

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

# 或使用Chocolatey
choco install nodejs

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

Segundo passo: Configurar o Cursor

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

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

Terceiro passo: Adicionar configuração MCP Crie ou 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"
      }
    }
  }
}

🐧 Guia de configuração para Linux

Primeiro passo: Instalar dependências

# 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 passo: Configurar o Cursor

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

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

Terceiro passo: Adicionar configuração 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"
      }
    }
  }
}

🧪 Verificação da configuração

Após concluir a configuração, use os seguintes passos para verificar:

  1. Teste a executabilidade do servidor MCP:
# 在任意目录运行
npx -y yapi-mcp-pro --help

  1. Verifique a configuração do Cursor:

    • Reinicie o Cursor
    • Abra qualquer projeto
    • No chat, digite: "Por favor, obtenha minhas informações de usuário do YApi"

  2. Verifique o status da conexão:

    • Sucesso: Retorna informações do usuário
    • Falha: Verifique a mensagem de erro e consulte a seção Solução de problemas

📊 Indicadores de configuração bem-sucedida

✅ Sinais de configuração bem-sucedida:

  • npx -y yapi-mcp-pro --help consegue exibir informações de ajuda normalmente
  • Após reiniciar o Cursor, o status da conexão MCP mostra yapi-mcp-pro
  • O assistente de IA responde normalmente a solicitações relacionadas ao YApi
  • Consegue obter informações do usuário e lista de projetos com sucesso

📋 Índice

✨ Recursos principais

🎯 Gerenciamento abrangente de interfaces

  • CRUD de interfaces: Criar, ler, atualizar, excluir interfaces
  • Busca inteligente: Busca multidimensional de interfaces (nome, caminho, projeto)
  • Operações em lote: Suporte a copiar interfaces, importação/exportação em lote
  • Sincronização em tempo real: Sincronização de dados em tempo real com o servidor YApi

🏗️ Gerenciamento de projetos e categorias

  • Gerenciamento de projetos: Criar, atualizar informações do projeto
  • Gerenciamento de categorias: Gerenciamento completo do ciclo de vida de categorias de interfaces
  • Controle de permissões: Acesso seguro baseado no sistema de permissões do YApi

👥 Colaboração de usuários e equipes

  • Informações do usuário: Obter informações detalhadas do usuário atual
  • Gerenciamento de equipes: Visualizar grupos e permissões do usuário

🧪 Testes e garantia de qualidade

  • Conjuntos de testes: Gerenciar conjuntos de casos de teste de interfaces
  • Importação/exportação de dados: Suporte a formatos Swagger, JSON, etc.

⚡ Desempenho e experiência

  • Cache inteligente: Mecanismo de cache em múltiplas camadas para melhorar a velocidade de resposta
  • Comunicação em tempo real: Suporte a SSE, atualização de dados em tempo real
  • Autenticação dupla: Dois métodos de autenticação: Cookie e Token
  • Logs detalhados: Logs completos de operações e rastreamento de erros

🎯 Editores de IA suportados

EditorStatus de suporteForma de configuração
Cursor✅ Suporte completoConfiguração MCP
Claude Desktop✅ Suporte completoConfiguração MCP
VS Code🔄 Em desenvolvimentoForma de plugin
Outras ferramentas compatíveis com MCP✅ Suporte teóricoProtocolo MCP padrão

🔧 Guia de configuração detalhado

1. Requisitos de ambiente

  • Node.js: >= 16.0.0
  • npm/pnpm: Versão mais recente
  • Servidor YApi: Instância YApi acessível

2. Instalação e implantação

Forma 1: Instalação via npm (recomendada)

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

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

Forma 2: Instalação a partir do código-fonte

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

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

# 构建项目
npm run build

3. Configuração rápida

📁 Explicação do arquivo de configuração

Todas as informações sensíveis do projeto estão concentradas no arquivo .env. Este arquivo não será enviado para o Git, garantindo a privacidade dos seus dados.

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

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

💡 Dica: O arquivo .env.example contém um guia de configuração superdetalhado, incluindo:

  • 🍪 Método passo a passo para obter autenticação por Cookie (recomendado)
  • 🔑 Fluxo completo de operação para autenticação por Token
  • 📋 Exemplos de configuração em formato real
  • ✅ Métodos de verificação e teste de configuração

É fortemente recomendado ler as instruções detalhadas no arquivo .env.example primeiro!

🔐 Itens de configuração obrigatórios

Abra o arquivo .env e preencha os seguintes campos obrigatórios:

# === 必填项 ===
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

🎯 Duas formas de obter informações de autenticação

Forma 1: Autenticação por Cookie (recomendada) ⭐

Vantagens: Descobre automaticamente todos os projetos com permissão, configuração simples

Passos:

  1. Abra o navegador e faça login no seu sistema YApi
  2. Pressione F12 para abrir as ferramentas do desenvolvedor
  3. Mude para o painel Network (Rede)
  4. Clique em qualquer funcionalidade na página YApi (como atualizar a página)
  5. Encontre qualquer requisição nas requisições de rede e clique para ver os detalhes
  6. Encontre o campo Cookie em Request Headers
  7. Copie o valor completo do Cookie
# Cookie认证示例（复制您自己的Cookie）
YAPI_TOKEN=_yapi_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...; _yapi_uid=1234; other_cookies=values
Forma 2: Autenticação por Token

Vantagens: Válido por longo período, mais seguro

Passos:

  1. Faça login no YApi e entre no projeto que deseja gerenciar
  2. Clique em 设置 do projeto → Token配置
  3. Copie o Token do projeto e o ID do projeto
  4. Configure vários projetos conforme o formato (se necessário)
# 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

📋 Exemplo completo de configuração

# ================================
# 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 o serviço

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

# 或手动启动
npm run dev

🔧 Guia de configuração

Escolha do método de autenticação

🍪 Autenticação por Cookie (recomendada)

Vantagens: Descobre automaticamente todos os projetos, configuração simples, permissões completas

Passos para obter:

  1. Faça login no YApi pelo navegador
  2. Abra as ferramentas do desenvolvedor (F12)
  3. No painel de rede, copie o Cookie de qualquer requisição
  4. Configure no arquivo .env
# Cookie认证配置
YAPI_BASE_URL=http://your-yapi-server.com
YAPI_TOKEN=_yapi_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...; _yapi_uid=YOUR_USER_ID

🔑 Autenticação por Token

Vantagens: Válido por longo período, alta segurança, adequado para produção

Passos para obter:

  1. Projeto YApi → Configurações → Configuração de Token
  2. Copie o Token do projeto e o ID do projeto
  3. Configure vários projetos conforme o formato
# Token认证配置
YAPI_BASE_URL=http://your-yapi-server.com
YAPI_TOKEN=PROJECT_ID:YOUR_PROJECT_TOKEN,ANOTHER_PROJECT_ID:ANOTHER_TOKEN

Parâmetros completos de configuração

# === 基础配置 ===
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（创建项目时使用）

🔗 Configuração MCP para editores de IA

YAPI MCP PRO suporta múltiplas formas de conexão MCP para atender às necessidades de diferentes cenários de uso.

🎯 Configuração no Cursor

Localização do arquivo de configuração
  • Configuração no nível do projeto (recomendada): .cursor/mcp.json
  • Configuração global:
    • macOS: ~/Library/Application Support/Cursor/User/settings.json
    • Windows: %APPDATA%\Cursor\User\settings.json
    • Linux: ~/.config/Cursor/User/settings.json
🚀 Forma 1: Modo pacote NPM (recomendado) ⭐

Vantagens:

  • ✅ Baixa automaticamente a versão mais recente, sem necessidade de build local
  • ✅ Configuração simples, pronta para uso
  • ✅ Suporte a múltiplos projetos, configuração flexível
  • ✅ Gerenciamento automático de dependências

Configuração no nível do projeto .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"
      }
    }
  }
}

Configuração 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"
      }
    }
  }
}
🔧 Forma 2: Modo servidor local (HTTP/SSE)

Vantagens:

  • ✅ Melhor desempenho, menor tempo de inicialização
  • ✅ Suporte a push de dados em tempo real
  • ✅ Facilita depuração e desenvolvimento
  • ✅ Suporte a compartilhamento entre múltiplos clientes

Passos:

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

# 检查状态
./start-mcp.sh status
  1. Configure a conexão no Cursor
{
  "mcpServers": {
    "yapi-mcp-pro": {
      "url": "http://localhost:3388/sse"
    }
  }
}
🛠️ Forma 3: Modo build local

Cenário de uso: Necessidade de modificar o código-fonte 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"
      }
    }
  }
}

🖥️ Configuração no Claude Desktop

Edite claude_desktop_config.json:

Modo pacote 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 build 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"
      }
    }
  }
}

🔄 Outros clientes MCP

Qualquer ferramenta compatível com o protocolo MCP pode se conectar, basta seguir o formato de configuração MCP da ferramenta correspondente.

📊 Comparação das formas de configuração

Forma de configuraçãoVantagensDesvantagensCenário de uso
Modo pacote NPM🟢 Configuração simples
🟢 Atualização automática
🟢 Sem necessidade de build		🔴 Primeira inicialização um pouco mais lenta🎯 Recomendado, adequado para a maioria dos usuários
Modo HTTP/SSE🟢 Melhor desempenho
🟢 Suporte a push em tempo real
🟢 Compartilhamento entre múltiplos clientes		🔴 Necessário iniciar o serviço
🔴 Ocupa porta		🎯 Uso intenso, colaboração em múltiplos projetos
Modo build local🟢 Controle total
🟢 Personalização possível		🔴 Necessário build
🔴 Alto custo de manutenção		🎯 Desenvolvedores, necessidade de funcionalidades personalizadas

⚙️ Explicação detalhada das variáveis de ambiente

Variável de ambienteDescriçãoValor padrãoExemplo
YAPI_BASE_URLEndereço do servidor YApiNenhumhttp://yapi.example.com
YAPI_TOKENToken ou Cookie de autenticaçãoNenhum_yapi_token=xxx; _yapi_uid=123
NODE_ENVAmbiente de execuçãoproductioncli, development
YAPI_LOG_LEVELNível de loginfodebug, warn, error
YAPI_CACHE_TTLTempo de validade do cache (minutos)1030
YAPI_ENABLE_CACHESe o cache está habilitadotruefalse

🔧 Verificação da configuração

Após concluir a configuração, teste a conexão no editor de IA:

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

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

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

📚 Detalhes das ferramentas MCP

YAPI MCP PRO oferece 19 ferramentas profissionais, cobrindo o ecossistema completo de funcionalidades do YApi:

🔧 Gerenciamento básico de interfaces (5 ferramentas)

1. yapi_get_api_desc - Obter informações detalhadas da interface

Função: Obter a definição completa de uma interface específica Parâmetros:

  • projectId (string): ID do projeto
  • apiId (string): ID da interface

Informações retornadas:

  • Informações básicas da interface (nome, caminho, método)
  • Parâmetros de requisição (parâmetros de URL, parâmetros de consulta, cabeçalhos de requisição, corpo da requisição)
  • Informações de resposta (tipo de resposta, conteúdo da resposta)
  • Documentação e descrição da interface

2. yapi_save_api - Adicionar ou atualizar interface

Função: Criar nova interface ou atualizar interface existente Parâmetros:

  • projectId (string): ID do projeto
  • catid (string): ID da categoria
  • title (string): Título da interface
  • path (string): Caminho da interface
  • method (string): Método de requisição
  • id (string, opcional): ID da interface (obrigatório para atualização)
  • desc (string, opcional): Descrição da interface
  • req_* (opcional): Várias configurações de parâmetros de requisição
  • res_* (opcional): Configuração de resposta

3. yapi_search_apis - Buscar interfaces

Função: Busca multidimensional de interfaces Parâmetros:

  • nameKeyword (string, opcional): Palavra-chave do nome da interface
  • pathKeyword (string, opcional): Palavra-chave do caminho da interface
  • projectKeyword (string, opcional): Palavra-chave do projeto
  • limit (number, opcional): Limite de resultados retornados

Capacidades de busca:

  • Suporte a correspondência difusa
  • Busca entre projetos
  • Ordenação inteligente e deduplicação

4. yapi_delete_interface - Excluir interface

Função: Excluir uma interface específica Parâmetros:

  • interfaceId (string): ID da interface
  • projectId (string): ID do projeto

5. yapi_copy_interface - Copiar interface

Função: Copiar interface para uma categoria específica Parâmetros:

  • interfaceId (string): ID da interface de origem
  • projectId (string): ID do projeto
  • catId (string, opcional): ID da categoria de destino

📊 Gerenciamento de projetos (3 ferramentas)

6. yapi_list_projects - Listar projetos

Função: Obter a lista de todos os projetos acessíveis Informações retornadas:

  • ID e nome do projeto
  • Descrição do projeto
  • Caminho base
  • Informações do grupo ao qual pertence

7. yapi_create_project - Criar Projeto

Função: Criar um novo projeto YApi Parâmetros:

  • name (string): Nome do projeto
  • basepath (string): Caminho base
  • group_id (number): ID do grupo ao qual pertence
  • desc (string, opcional): Descrição do projeto
  • color (string, opcional): Cor do projeto
  • icon (string, opcional): Ícone do projeto

8. yapi_update_project - Atualizar Projeto

Função: Atualizar informações do projeto Parâmetros:

  • id (number): ID do projeto
  • name (string, opcional): Nome do projeto
  • basepath (string, opcional): Caminho base
  • desc (string, opcional): Descrição do projeto
  • color (string, opcional): Cor do projeto
  • icon (string, opcional): Ícone do projeto

📁 Gerenciamento de Categorias (4 ferramentas)

9. yapi_get_categories - Obter Lista de Categorias

Função: Obter todas as categorias de interfaces de um projeto Parâmetros:

  • projectId (string): ID do projeto

Informações retornadas:

  • Informações básicas da categoria
  • Lista de interfaces de cada categoria
  • Data de criação e atualização da categoria

10. yapi_create_category - Criar Categoria

Função: Criar uma nova categoria de interface no projeto Parâmetros:

  • name (string): Nome da categoria
  • project_id (number): ID do projeto
  • desc (string, opcional): Descrição da categoria

11. yapi_update_category - Atualizar Categoria

Função: Atualizar informações da categoria Parâmetros:

  • catId (string): ID da categoria
  • name (string): Nome da categoria
  • desc (string, opcional): Descrição da categoria

12. yapi_delete_category - Excluir Categoria

Função: Excluir uma categoria específica Parâmetros:

  • catId (string): ID da categoria

👤 Gerenciamento de Usuários (2 ferramentas)

13. yapi_get_user_info - Obter Informações do Usuário

Função: Obter informações detalhadas do usuário atualmente conectado Informações retornadas:

  • ID do usuário e nome de usuário
  • Endereço de e-mail
  • Papel e permissões do usuário
  • Data de criação e atualização da conta

14. yapi_get_user_groups - Obter Grupos do Usuário

Função: Obter a lista de grupos aos quais o usuário pertence Informações retornadas:

  • ID e nome do grupo
  • Descrição do grupo
  • Número de membros
  • Data de criação do grupo

🧪 Coleções de Teste (2 ferramentas)

15. yapi_get_test_collections - Obter Coleções de Teste

Função: Obter a lista de coleções de teste do projeto Parâmetros:

  • projectId (string): ID do projeto

Informações retornadas:

  • Informações básicas da coleção de teste
  • Data de criação e atualização
  • Descrição da coleção

16. yapi_create_test_collection - Criar Coleção de Teste

Função: Criar uma nova coleção de teste Parâmetros:

  • name (string): Nome da coleção
  • project_id (number): ID do projeto
  • desc (string, opcional): Descrição da coleção

📥📤 Importação e Exportação de Dados (2 ferramentas)

17. yapi_import_swagger - Importar Dados Swagger

Função: Importar documentos Swagger para o projeto YApi Parâmetros:

  • projectId (string): ID do projeto de destino
  • catId (string): ID da categoria de destino
  • swaggerData (string): Dados JSON do Swagger
  • merge (string, opcional): Modo de mesclagem

Modos de mesclagem suportados:

  • normal: Modo normal
  • good: Mesclagem inteligente
  • merge: Substituição completa

18. yapi_export_project - Exportar Dados do Projeto

Função: Exportar dados do projeto em formato especificado Parâmetros:

  • projectId (string): ID do projeto
  • type (string, opcional): Formato de exportação

Formatos de exportação suportados:

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

🔄 Outras Funcionalidades (1 ferramenta)

19. yapi_run_interface - Executar Teste de Interface

Função: Executar requisições de teste de interface Parâmetros:

  • interface_id (string): ID da interface
  • project_id (string): ID do projeto
  • env_id (string, opcional): ID do ambiente
  • domain (string, opcional): Domínio de teste
  • headers (array, opcional): Cabeçalhos de requisição personalizados
  • params (object, opcional): Parâmetros da requisição
  • body (object, opcional): Corpo da requisição

💡 Exemplos de Uso

🔍 Pesquisa e Gerenciamento de Interfaces

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

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

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

🏗️ Inicialização de Projeto

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

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

📊 Operações em Lote

# 批量创建接口
请为用户模块创建以下接口，都放在项目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]

🧪 Testes e Validação

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

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

🛠️ Gerenciamento de Projeto

Scripts de Gerenciamento de Serviço

O projeto fornece scripts de gerenciamento 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

Gerenciamento de Logs

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

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

# 清理日志
> yapi-mcp.log

Gerenciamento de Cache

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

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

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

🔍 Solução de Problemas

Problemas Comuns

🍪 Problemas de Autenticação por Cookie

Problema: Erro "Por favor, faça login..."

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

Problema: "ID do projeto não configurado, não foi possível carregar as informações do projeto"

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

🔑 Problemas de Autenticação por Token

Problema: "Token não configurado para o ID do projeto xxx"

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

🌐 Problemas de Conexão de Rede

Problema: "Falha na comunicação com o servidor YApi"

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

🔧 Problemas de Inicialização do Serviço

Problema: Porta já em uso

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

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

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

Modo de Depuração

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

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

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

Otimização de Desempenho

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

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

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

📖 Uso Avançado

Desenvolvimento de Ferramentas 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) }]
    };
  }
);

Processamento de Dados em Lote

// 批量导入接口
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"
  });
}

Integração com 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 }}

🤝 Guia de Contribuição

Configuração do Ambiente de Desenvolvimento

# 克隆项目
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

Padrões de Commit

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

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

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

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

Padrões de Código

  • Usar TypeScript para desenvolvimento com segurança de tipos
  • Seguir as configurações de ESLint e Prettier
  • Escrever testes unitários cobrindo as funcionalidades principais
  • Adicionar comentários JSDoc detalhados

📄 Licença

Licença MIT - Consulte o arquivo LICENSE

🙋‍♂️ Suporte e Feedback

Obter Ajuda

  1. Documentação primeiro: Consulte este README e a documentação relacionada
  2. Análise de logs: Verifique o arquivo yapi-mcp.log
  3. Suporte da comunidade: Envie uma Issue no GitHub
  4. Suporte comercial: Entre em contato com os mantenedores do projeto

Relatar Problemas

Ao enviar uma Issue, inclua:

  • Descrição detalhada do erro
  • Logs de erro completos
  • Informações do ambiente (versão do Node.js, sistema operacional, etc.)
  • Passos para reproduzir
  • Arquivo de configuração (ocultando informações sensíveis)

Sugestões de Funcionalidades

Sugestões de funcionalidades e melhorias são bem-vindas:

  • Descreva o cenário de uso específico
  • Explique o comportamento esperado da funcionalidade
  • Forneça materiais de referência relacionados

🎉 Modelo de Início Rápido

📦 Implantação em Um Clique (Pronto 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 Informações de Conexão do YApi

📖 Importante: Antes de editar o arquivo .env, consulte o arquivo .env.example, que contém o guia de configuração completo e os métodos de obtenção!

Edite o arquivo .env e preencha suas informações do YApi:

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

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

Exemplo de configuração 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

🔑 Obter Informações de Autenticação (escolha uma das opções)

Método 1: Autenticação por Cookie (recomendado)

  1. Faça login no YApi pelo navegador
  2. Pressione F12 → painel Network
  3. Execute qualquer funcionalidade e clique na requisição de rede
  4. Copie Request Headers de Cookie
  5. Cole após YAPI_TOKEN=

Método 2: Autenticação por Token

  1. Projeto YApi → Configurações → Configuração de Token
  2. Copie o ID do projeto e o Token
  3. Formato: YAPI_TOKEN=项目ID:Token

🚀 Iniciar o Serviço

# 构建项目
pnpm run build

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

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

🔗 Configurar o Editor de IA

🎯 Configuração do Cursor (várias formas)

Localização do arquivo de configuração
  • Configuração no nível do projeto (recomendado): .cursor/mcp.json
  • Configuração global: ~/.cursor/mcp.json
🚀 Forma 1: Modo Pacote NPM (recomendado) ⭐

Vantagens: Baixa automaticamente a versão mais recente, sem necessidade de build local, configuração simples

Configuração no nível do projeto .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"
      }
    }
  }
}
🔧 Forma 2: Modo Servidor Local (HTTP/SSE)

Vantagens: Melhor desempenho, suporte a push em tempo real, compartilhamento entre múltiplos clientes

Passos:

  1. Inicie o servidor MCP local
./start-mcp.sh start
  1. Configure a conexão no Cursor
{
  "mcpServers": {
    "yapi-mcp-pro": {
      "url": "http://localhost:3388/sse"
    }
  }
}
🛠️ Forma 3: Modo Build Local

Cenário de uso: Necessário personalizar o código-fonte

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

🖥️ Configuração do Claude Desktop

Modo Pacote 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 Build 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"
      }
    }
  }
}

📊 Comparação das Formas de Configuração

Forma de ConfiguraçãoVantagensDesvantagensCenário de Uso
Modo Pacote NPM🟢 Configuração simples
🟢 Atualização automática
🟢 Sem necessidade de build		🔴 Inicialização inicial um pouco mais lenta🎯 Recomendado, adequado para a maioria dos usuários
Modo HTTP/SSE🟢 Melhor desempenho
🟢 Suporte a push em tempo real
🟢 Compartilhamento entre múltiplos clientes		🔴 Requer iniciar o serviço
🔴 Ocupa uma porta		🎯 Uso intenso, colaboração em múltiplos projetos
Modo Build Local🟢 Controle total
🟢 Personalização possível		🔴 Requer build
🔴 Alto custo de manutenção		🎯 Desenvolvedores, necessidade de funcionalidades personalizadas

✅ Verificar a Instalação

Digite qualquer um dos seguintes comandos no editor de IA para testar:

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

🎯 Lista de Verificação de Configuração

  • Projeto clonado e dependências instaladas
  • Leu atentamente o guia de configuração detalhado do arquivo .env.example 📋
  • Arquivo .env criado (cp .env.example .env)
  • YAPI_BASE_URL configurado (endereço do servidor YApi)
  • YAPI_TOKEN configurado (Cookie ou Token, conforme o guia .env.example)
  • Projeto compilado (pnpm run build)
  • Serviço iniciado (./start-mcp.sh start)
  • Conexão MCP configurada no editor de IA
  • Funcionalidades básicas testadas

🔒 Aviso de Segurança

⚠️ Itens de segurança importantes:

  1. O arquivo .env contém informações sensíveis, nunca o envie para o repositório Git
  2. Troque o Token periodicamente, especialmente em projetos com colaboração de múltiplas pessoas
  3. Não codifique nenhum Token ou chave diretamente no código
  4. Pare o serviço imediatamente após o uso: ./start-mcp.sh stop

✅ O projeto já possui proteção de segurança configurada:

  • .gitignore já ignora todos os arquivos sensíveis
  • O código usa variáveis de ambiente, sem informações sensíveis codificadas
  • Suporte a exibição mascarada de Token, protegendo a segurança dos logs

🆘 Perguntas Frequentes

P: Mensagem "Falha na comunicação com o servidor YApi"? R: Verifique se YAPI_BASE_URL está correto e se a rede consegue acessar o servidor YApi

P: Mensagem "Por favor, faça login" ou "Token não configurado"? R: Obtenha novamente o Cookie ou Token, garantindo que o formato esteja correto

P: Porta 3388 já em uso? R: Altere PORT=3389 em .env e reinicie o serviço

P: Como garantir a segurança do meu Token? R:

  • Use autenticação por Cookie (expira automaticamente)
  • Troque o Token periodicamente
  • Não tire prints ou compartilhe configurações que contenham Token
  • O .gitignore do projeto já protege arquivos sensíveis

🚀 Agora você tem o assistente de IA YApi mais poderoso e seguro!

Variável de AmbienteDescriçãoValor PadrãoExemplo
YAPI_BASE_URLEndereço do servidor YApiNenhumhttp://yapi.example.com
YAPI_TOKENToken ou Cookie de autenticaçãoNenhumToken: projectId:token ou Cookie: _yapi_token=xxx; _yapi_uid=123
PORTPorta do servidor MCP33883000
YAPI_CACHE_TTLTempo de validade do cache (minutos)1030
YAPI_LOG_LEVELNível de loginfodebug, info, warn, error
YAPI_ENABLE_CACHESe o cache está habilitadotruefalse desabilita o cache, true habilita o cache

✨ Recursos e Funcionalidades

🔗 Múltiplas Formas de Conexão MCP

  • 📦 Modo Pacote NPM: Use npx yapi-mcp-pro para baixar automaticamente a versão mais recente (recomendado)
  • 🌐 Modo HTTP/SSE: Modo servidor local, suporte a push de dados em tempo real
  • 🛠️ Modo Build Local: Suporte a personalização do código-fonte e depuração

🔐 Mecanismo de Autenticação Flexível

  • 🍪 Autenticação por Cookie: Descobre automaticamente todos os projetos com permissão, configuração simples
  • 🔑 Autenticação por Token: Autenticação por Token no nível do projeto, validade longa, mais segura
  • 👥 Suporte a múltiplos projetos: Gerencie vários projetos YApi simultaneamente

📋 Gerenciamento Completo do Ciclo de Vida de Interfaces

  • CRUD de Interfaces: Criar, ler, atualizar e excluir interfaces
  • 🔍 Pesquisa Inteligente: Pesquisa multidimensional de interfaces (nome, caminho, projeto)
  • 📁 Gerenciamento de Categorias: Gerenciamento completo do ciclo de vida de categorias de interfaces
  • 🧪 Coleções de Teste: Gerenciar e executar casos de teste de interfaces

🚀 Alto Desempenho e Cache Inteligente

  • ⚡ Cache Inteligente: Mecanismo de cache em múltiplas camadas, melhora a velocidade de resposta
  • 🔄 Sincronização em Tempo Real: Sincronização de dados em tempo real com o servidor YApi
  • 🎯 Controle Flexível de Cache: Suporte a atualização forçada e desabilitação completa do cache
  • 📊 Monitoramento de Desempenho: Logs de operação detalhados e estatísticas de desempenho

🛠️ Amigável para Desenvolvedores

  • 📄 Importação e Exportação de Dados: Suporte a importação Swagger e exportação em múltiplos formatos
  • 🔧 Configuração por Variáveis de Ambiente: Gerenciamento de configuração flexível
  • 🐛 Logs Detalhados: Logs de operação completos e rastreamento de erros
  • 🎨 Suporte a TypeScript: Definições de tipos completas e sugestões inteligentes

🎊 Resumo

✅ YAPI MCP PRO agora suporta múltiplas formas de conexão

Forma de ConexãoCaracterísticasCenário de Uso
📦 Modo Pacote NPM🚀 Pronto para usar, atualização automática🎯 Recomendado para todos os usuários
🌐 Modo HTTP/SSE⚡ Alto desempenho, push em tempo real🎯 Uso intenso, colaboração em múltiplos projetos
🛠️ Modo Build Local🔧 Controle total, personalizável🎯 Desenvolvedores, necessidade de funcionalidades personalizadas

🚀 Caminho de Início Rápido Recomendado

  1. Novos usuários → Escolha o Modo Pacote NPM, configuração simples, pronto para usar
  2. Usuários intensos → Escolha o Modo HTTP/SSE, melhor desempenho, suporte a push em tempo real
  3. Desenvolvedores → Escolha o Modo Build Local, pode personalizar o código-fonte

💡 Pontos de Configuração

  • Método de autenticação: Autenticação por Cookie é a mais simples, autenticação por Token é a mais segura
  • Nível de configuração: Configuração no nível do projeto tem prioridade, configuração global como reserva
  • Variáveis de ambiente: Suporte a configuração rica por variáveis de ambiente
  • Mecanismo de cache: Cache inteligente melhora o desempenho, suporte a atualização forçada

🎯 Comece Agora

Escolha a forma de conexão adequada para você, siga o guia de configuração correspondente e em poucos minutos você poderá começar a usar o poderoso assistente de IA YApi!

🔗 Links Relacionados

🎉 Aproveite sua jornada com o assistente de IA YApi!