mcp-asaas-server

suissa/mcp-asaas-server

3.1

If you are the rightful owner of mcp-asaas-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

MCP Server for Asaas documentation

MCP Server Asaas 🚀

Servidor MCP (Model Context Protocol) para a documentação da API do Asaas com busca semântica usando FAISS.

📋 Características

  • ✅ Busca Semântica: Busca inteligente na documentação usando embeddings e FAISS
  • ✅ Dual Interface: Suporte tanto para stdio (MCP) quanto REST API
  • ✅ Schema Estruturado: Dados organizados com JSON Schema otimizado
  • ✅ Scraping Automático: Coleta automática da documentação oficial
  • ✅ Indexação Vetorial: Indexação rápida com FAISS para buscas eficientes

🛠️ Tecnologias

  • Node.js - Runtime JavaScript
  • @modelcontextprotocol/sdk - SDK do MCP
  • FAISS - Busca vetorial de alta performance
  • OpenAI - Geração de embeddings
  • Express - Servidor REST
  • Cheerio - Web scraping
  • Axios - Cliente HTTP

📦 Instalação

# Clone o repositório
git clone https://github.com/suissa/mcp-asaas-server.git
cd mcp-asaas-server

# Instale as dependências
npm install

# Configure as variáveis de ambiente
cp .env.example .env
# Edite .env e adicione sua OPENAI_API_KEY

⚙️ Configuração

Crie um arquivo .env na raiz do projeto:

OPENAI_API_KEY=sk-your-api-key-here
PORT=3000

🚀 Uso

1. Indexação da Documentação

Primeiro, você precisa coletar e indexar a documentação:

npm run index

Este comando irá:

  1. Fazer scraping da documentação do Asaas
  2. Gerar embeddings para cada página
  3. Criar o índice FAISS
  4. Salvar tudo em data/

2. Iniciar o Servidor

Modo stdio (MCP)

Para usar com clientes MCP como Claude Desktop:

npm run start:stdio
Modo REST API

Para usar como API REST:

npm run start:rest
# ou simplesmente
npm start

O servidor estará disponível em http://localhost:3000

📚 API REST

Endpoints Disponíveis

GET /

Documentação da API

GET /health

Health check e estatísticas básicas

{
  "status": "ok",
  "timestamp": "2025-01-10T12:00:00.000Z",
  "stats": {
    "totalDocuments": 11,
    "dimension": 1536,
    "indexInitialized": true
  }
}
POST /search

Busca semântica na documentação

Body:

{
  "query": "como criar um cliente",
  "limit": 5
}

Response:

{
  "query": "como criar um cliente",
  "total": 5,
  "results": [
    {
      "document": {
        "id": "aHR0cHM6Ly9kb2Nz",
        "title": "Criar Cliente",
        "url": "https://docs.asaas.com/reference/clientes",
        "method": "POST",
        "endpoint": "/v3/customers",
        "description": "Endpoint para criar novos clientes...",
        "category": "clientes",
        "tags": ["cliente", "criar", "api"]
      },
      "score": 0.1234
    }
  ]
}
GET /documents

Lista todos os documentos

Query params:

  • limit (default: 50) - Número de documentos por página
  • offset (default: 0) - Offset para paginação
GET /documents/:id

Busca um documento específico por ID

GET /categories

Lista todas as categorias disponíveis

GET /categories/:category

Busca documentos de uma categoria específica

GET /tags

Lista todas as tags disponíveis

GET /tags/:tag

Busca documentos com uma tag específica

GET /stats

Retorna estatísticas detalhadas da base de conhecimento

🔧 Uso com MCP (stdio)

Configuração no Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "asaas-docs": {
      "command": "node",
      "args": [
        "/caminho/para/mcp-asaas-server/src/mcp/stdio-server.js"
      ],
      "env": {
        "OPENAI_API_KEY": "sua-chave-aqui"
      }
    }
  }
}

Ferramentas Disponíveis

search_asaas_docs

Busca semântica na documentação

Parâmetros:

  • query (obrigatório): Consulta em linguagem natural
  • limit (opcional): Número de resultados (padrão: 5)
get_asaas_stats

Retorna estatísticas da base de conhecimento

list_asaas_categories

Lista todas as categorias disponíveis

📊 Schema de Dados

Cada documento na base de conhecimento segue este schema:

{
  id: string;              // ID único
  title: string;           // Título da página
  content: string;         // Conteúdo completo
  url: string;             // URL original
  category?: string;       // Categoria (ex: "clientes")
  method?: "GET"|"POST"|"PUT"|"DELETE"|"PATCH";
  endpoint?: string;       // Path do endpoint
  description?: string;    // Descrição curta
  parameters?: Array<{     // Parâmetros do endpoint
    name: string;
    type: string;
    required: boolean;
    description: string;
  }>;
  examples?: Array<{       // Exemplos de código
    language: string;
    code: string;
  }>;
  tags?: string[];         // Tags para categorização
}

🔍 Exemplos de Uso

REST API

# Buscar informações sobre clientes
curl -X POST http://localhost:3000/search \
  -H "Content-Type: application/json" \
  -d '{"query": "como criar um cliente", "limit": 3}'

# Listar categorias
curl http://localhost:3000/categories

# Buscar por categoria
curl http://localhost:3000/categories/clientes

# Ver estatísticas
curl http://localhost:3000/stats

Com JavaScript

// Busca semântica
const response = await fetch('http://localhost:3000/search', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: 'como criar uma cobrança',
    limit: 5
  })
});

const data = await response.json();
console.log(data.results);

📁 Estrutura do Projeto

mcp-asaas-server/
├── src/
│   ├── schemas/
│   │   └── documentation.schema.json    # JSON Schema dos dados
│   ├── scraper/
│   │   └── asaas-scraper.js            # Scraper da documentação
│   ├── vectorstore/
│   │   └── faiss-store.js              # Gerenciador do índice FAISS
│   └── mcp/
│       ├── stdio-server.js             # Servidor MCP (stdio)
│       └── rest-server.js              # Servidor REST
├── scripts/
│   └── index-docs.js                   # Script de indexação
├── data/
│   ├── asaas-docs.json                 # Dados brutos
│   └── faiss/
│       ├── index.faiss                 # Índice FAISS
│       └── documents.json              # Documentos indexados
├── package.json
├── .env.example
└── README.md

🤝 Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para:

  1. Fazer fork do projeto
  2. Criar uma branch para sua feature (git checkout -b feature/MinhaFeature)
  3. Commit suas mudanças (git commit -m 'Adiciona MinhaFeature')
  4. Push para a branch (git push origin feature/MinhaFeature)
  5. Abrir um Pull Request

📝 License

ISC

🔗 Links

💡 Próximos Passos

  • Adicionar mais fontes de documentação
  • Implementar cache de embeddings
  • Adicionar testes automatizados
  • Criar interface web para busca
  • Suporte a múltiplos idiomas
  • Atualização automática da documentação

Feito com ❤️ para a comunidade de desenvolvedores