Bling Docs MCP

Servidor MCP (Model Context Protocol) que dá a assistentes de IA acesso especializado à documentação da API do Bling ERP. Em vez de carregar toda a especificação OpenAPI no contexto, a IA descobre e busca apenas o que precisa — endpoints, schemas, autenticação e guias — através de 6 ferramentas otimizadas.

✨ Funcionalidades

• 6 ferramentas especializadas — describe, search_endpoints, get_endpoint_details, get_schema, read_documentation_page, search_documentation
• Auto-descoberta — encontra automaticamente a URL da spec OpenAPI mais recente no portal Bling (sem URLs hardcoded que quebram)
• Busca semântica — embeddings Google AI (text-embedding-004) opcionais para busca em linguagem natural
• 53 docs pré-incluídos — guias, webhooks, changelogs, FAQs, migração JWT e mais — tudo disponível offline
• Cache inteligente — spec cacheada em disco por 15 dias; embeddings cacheados para evitar regeneração a cada startup
• Zero configuração — funciona direto via npx, nenhuma API key obrigatória (busca semântica é opcional)

🚀 Início Rápido

# Clonar e buildar
git clone https://github.com/joaovitorlabiak-byte/bling-docs-mcp.git
cd bling-docs-mcp
npm install
npm run build

Ou instale direto do GitHub via npm:

npm install -g github:joaovitorlabiak-byte/bling-docs-mcp

⚙️ Configuração

Adicione o servidor na configuração MCP do seu cliente de IA:

Claude Desktop

Edite ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "bling-docs": {
      "command": "node",
      "args": ["/caminho/para/bling-docs-mcp/dist/index.js"]
    }
  }
}

VS Code (Copilot)

Adicione em .vscode/mcp.json no seu workspace:

{
  "servers": {
    "bling-docs": {
      "command": "node",
      "args": ["/caminho/para/bling-docs-mcp/dist/index.js"]
    }
  }
}

Cursor

Adicione em ~/.cursor/mcp.json:

{
  "mcpServers": {
    "bling-docs": {
      "command": "node",
      "args": ["/caminho/para/bling-docs-mcp/dist/index.js"]
    }
  }
}

Windsurf / Codeium

Adicione em ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "bling-docs": {
      "command": "node",
      "args": ["/caminho/para/bling-docs-mcp/dist/index.js"]
    }
  }
}

Com Busca Semântica (opcional)

Para habilitar busca em linguagem natural nos endpoints, defina sua Google AI API key:

{
  "mcpServers": {
    "bling-docs": {
      "command": "node",
      "args": ["/caminho/para/bling-docs-mcp/dist/index.js"],
      "env": {
        "GOOGLE_API_KEY": "sua-google-api-key"
      }
    }
  }
}

Obtenha uma API key gratuita em Google AI Studio.

🛠️ Ferramentas

| Ferramenta | Descrição | |------------|-----------| | describe | Visão geral da API: título, versão, URL base, autenticação OAuth2, todos os módulos com contagem de endpoints. Chame primeiro. | | search_endpoints | Busca endpoints por palavra-chave, linguagem natural (com busca semântica), tag ou método HTTP. | | get_endpoint_details | Detalhes completos do endpoint: parâmetros, schema do request body, respostas, escopos de segurança e payload de exemplo gerado automaticamente. | | get_schema | Lista todos os schemas ou retorna um schema específico com definições completas de propriedades e JSON de exemplo. | | read_documentation_page | Lê uma página específica da documentação Bling (guias, webhooks, limites, changelogs, migração JWT, FAQs). | | search_documentation | Busca full-text em todas as 53 páginas de documentação incluídas. |

Exemplos de Uso

Após configurar o servidor MCP, pergunte ao seu assistente de IA:

• "Quais endpoints existem para gerenciar produtos no Bling?"
• "Como faço para criar um pedido de venda? Mostre os campos obrigatórios."
• "Qual é o schema do ProdutoDTO?"
• "Como funciona a autenticação OAuth2 na API do Bling?"
• "Quais são os limites de requisição da API?"
• "Mostre a estrutura do payload de webhook para pedidos"

🏗️ Como Funciona

┌─────────────────────────────────────────────────────────────┐
│                     Bling Docs MCP Server                   │
│                                                             │
│  1. DESCOBERTA  Encontra a URL da spec OpenAPI mais         │
│                 recente em developer.bling.com.br/referencia │
│                                                             │
│  2. CARGA       Baixa + resolve $refs da spec               │
│                 (cacheado em disco por 15 dias)              │
│                                                             │
│  3. INDEXAÇÃO   Constrói índices de busca em memória:        │
│                 • Endpoints por tag, path, método            │
│                 • Schemas por nome                           │
│                 • Embeddings vetoriais (opcional)            │
│                                                             │
│  4. SERVE       Responde às chamadas MCP do assistente      │
│                                                             │
│  📄 docs/       53 arquivos markdown pré-incluídos para     │
│                 guias, webhooks, changelogs, FAQs            │
└─────────────────────────────────────────────────────────────┘

As páginas de documentação em docs/ são pré-incluídas — vêm no pacote e são lidas localmente em runtime. Nenhum crawling ou fetch externo é necessário.

💻 Desenvolvimento

Pré-requisitos

• Node.js 18+
• npm

Setup

# Clonar o repositório
git clone https://github.com/joavitorlabiak-byte/bling-docs-mcp.git
cd bling-docs-mcp

# Instalar dependências
npm install

# Build
npm run build

# Executar localmente
npm start

Testes

# Executar todos os testes
npm test

# Modo watch
npm run test:watch

Estrutura do Projeto

bling-docs-mcp/
├── src/
│   ├── index.ts              # Entry point do servidor
│   ├── lib/
│   │   ├── loader.ts         # Auto-descoberta + carregamento da spec OpenAPI
│   │   ├── indexer.ts         # Engine de indexação da spec
│   │   ├── schema-resolver.ts # Resolução de $ref + achatamento de schemas
│   │   ├── embeddings.ts      # Integração Google AI embeddings
│   │   ├── vector-store.ts    # Busca por similaridade de cosseno em memória
│   │   └── types.ts           # Definições de tipos TypeScript
│   └── tools/
│       ├── describe.ts
│       ├── search-endpoints.ts
│       ├── get-endpoint-details.ts
│       ├── get-schema.ts
│       ├── read-documentation-page.ts
│       └── search-documentation.ts
├── docs/                      # 53 páginas de documentação pré-incluídas
├── scripts/
│   └── fetch-bling-docs.js    # Crawler de documentação (ferramenta de manutenção)
├── package.json
├── tsconfig.json
└── vitest.config.ts

Atualizando as Páginas de Documentação

A pasta docs/ contém markdown pré-extraído do Portal do Desenvolvedor Bling. Para atualizar esses docs, use o script crawler (requer uma instância Crawl4AI):

# Defina a URL da sua instância Crawl4AI
export CRAWL4AI_URL=http://localhost:11235

# Buscar todos os docs (pula existentes por padrão)
npm run fetch-docs

# Forçar re-fetch de tudo
npm run fetch-docs -- --force

# Buscar apenas uma seção específica
npm run fetch-docs -- --section=webhooks

🤝 Contribuindo

Contribuições são bem-vindas! Por favor:

1. Faça um fork do repositório
2. Crie uma branch para sua feature (git checkout -b feature/minha-feature)
3. Commit suas alterações (git commit -am 'Adiciona minha feature')
4. Push para a branch (git push origin feature/minha-feature)
5. Abra um Pull Request

📄 Licença

MIT © João Vitor Labiak

⚠️ Aviso

Este projeto não é afiliado, endossado ou oficialmente conectado ao Bling. Ele utiliza a especificação OpenAPI e documentação para desenvolvedores publicamente disponíveis.