Servidor MCP

Servidor Model Context Protocol para Mapfolio - Permite que assistentes de IA interajam com dados do Mapfolio

Visão Geral

O Servidor MCP Mapfolio é um servidor Model Context Protocol (MCP) que permite que assistentes de IA e outros clientes compatíveis com MCP interajam com os dados e operações do Mapfolio. Fornece acesso programático a empresas, projetos, usuários, perfis do LinkedIn e funções administrativas.

O que é MCP?

Model Context Protocol (MCP) é um protocolo aberto que permite que assistentes de IA acessem com segurança fontes de dados e ferramentas externas. Os servidores MCP expõem capacidades através de uma interface padronizada, permitindo que assistentes de IA:

  • Consultar e recuperar dados
  • Realizar operações
  • Acessar recursos
  • Integrar com sistemas externos

Funcionalidades

O Servidor MCP Mapfolio fornece funcionalidade abrangente:

Dados de Empresas

  • Pesquisar empresas com filtros avançados
  • Obter detalhes da empresa por ID
  • Recuperar empresas por cantão e letra inicial
  • Obter empresas aleatórias para amostragem
  • Acessar estatísticas de visitas de empresas

Gerenciamento de Projetos

  • Criar e gerenciar projetos
  • Listar e filtrar projetos do usuário
  • Atualizar detalhes do projeto
  • Excluir projetos
  • Adicionar e remover empresas de projetos

Perfis de Usuário

  • Obter informações do perfil do usuário
  • Atualizar configurações do perfil
  • Listar projetos do usuário
  • Gerenciar chaves API

Integração LinkedIn

  • Obter dados do perfil do LinkedIn
  • Pesquisar perfis do LinkedIn
  • Acessar informações de conexão
  • Ver histórico de versões do perfil
  • Obter dados de empresas do LinkedIn

Operações Administrativas

  • Listar todos os usuários (apenas admin)
  • Criar novos usuários (apenas admin)
  • Gerenciar chaves API (apenas admin)
  • Acessar estatísticas do painel administrativo

Estatísticas

  • Obter estatísticas agregadas de empresas
  • Ver contagens por nível de cantão
  • Acessar contagens baseadas em letras
  • Obter estatísticas de combinações de duas letras

Instalação

Pré-requisitos

  • Node.js >= 20.0.0
  • npm >= 10.0.0
  • Acesso à instância Supabase do Mapfolio

Configuração

  1. Instalar dependências:
cd mcp-server
npm install
  1. Configurar variáveis de ambiente:
cp .env.example .env

Edite .env e configure:

# URL da API Mapfolio (padrão: https://mapfolio.app)
MAPFOLIO_API_URL=https://mapfolio.app

# Tipo de transporte: 'stdio' (padrão) ou 'http' para acesso remoto
MCP_TRANSPORT=stdio

# Porta HTTP (usada apenas quando MCP_TRANSPORT=http)
MCP_HTTP_PORT=3001

# Opcional: Autenticação padrão (pode ser fornecida via contexto MCP ou cabeçalhos HTTP)
MAPFOLIO_API_KEY=mapf_your_api_key_here
MAPFOLIO_JWT_TOKEN=your-jwt-token-here
  1. Compilar o servidor:
npm run build

Uso

Executando o Servidor

Desenvolvimento Local (transporte stdio)

O servidor MCP usa transporte stdio por padrão (protocolo MCP padrão):

npm start

Para desenvolvimento com recarregamento automático:

npm run dev

Transporte HTTP (para acesso remoto)

Para executar o servidor com transporte HTTP para testes locais:

MCP_TRANSPORT=http MCP_HTTP_PORT=3001 npm start

Isso inicia um servidor HTTP na porta 3001 que aceita solicitações JSON-RPC 2.0 via HTTP POST.

Implantação Vercel (Acesso Remoto)

O servidor MCP está automaticamente disponível via HTTP quando implantado no Vercel:

  • Endpoint: https://your-app.vercel.app/api/mcp
  • Protocolo: JSON-RPC 2.0 via HTTP POST
  • Autenticação: Via cabeçalho X-API-Key ou cabeçalho Authorization: Bearer <token>

Exemplo de solicitação:

curl -X POST https://your-app.vercel.app/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mapf_your_api_key" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

Configuração do Cliente MCP

Claude Desktop

Implantação local:

{
  "mcpServers": {
    "mapfolio": {
      "command": "node",
      "args": ["/path/to/mapfolio/mcp-server/dist/index.js"],
      "env": {
        "MAPFOLIO_API_URL": "https://mapfolio.app",
        "MAPFOLIO_API_KEY": "mapf_your_api_key_here"
      }
    }
  }
}

Cursor

Configure via configurações MCP:

  • Comando: node
  • Args: ["/path/to/mapfolio/mcp-server/dist/index.js"]
  • Variáveis de ambiente:
    • MAPFOLIO_API_URL: https://mapfolio.app
    • MAPFOLIO_API_KEY: Sua chave API (opcional)

Autenticação

O servidor suporta dois métodos de autenticação:

Autenticação por Chave API

As chaves API têm o prefixo mapf_ e podem:

  • Ser definidas via variável de ambiente MAPFOLIO_API_KEY
  • Ser passadas por solicitação via parâmetro apiKey em chamadas de ferramentas

Autenticação por Token JWT

Os tokens JWT do Supabase podem:

  • Ser definidos via variável de ambiente MAPFOLIO_JWT_TOKEN
  • Ser passados por solicitação via parâmetro jwtToken em chamadas de ferramentas

Prioridade de Autenticação

  1. Transporte HTTP: Cabeçalhos (X-API-Key ou Authorization) têm precedência
  2. Credenciais por solicitação (apiKey ou jwtToken nos argumentos da ferramenta)
  3. Variáveis de ambiente (MAPFOLIO_API_KEY ou MAPFOLIO_JWT_TOKEN)

Autenticação de Transporte HTTP

Ao usar o endpoint HTTP (/api/mcp), a autenticação é fornecida via cabeçalhos HTTP:

  • Chave API: X-API-Key: mapf_your_api_key
  • Token JWT: Authorization: Bearer your_jwt_token

Ferramentas Disponíveis

O servidor fornece 30+ ferramentas em 6 categorias:

Ferramentas de Empresas

  • search_companies - Pesquisar com filtros
  • get_company - Obter empresa por ID
  • get_companies_by_canton_letter - Obter por cantão e letra
  • get_random_companies - Obter amostras aleatórias
  • get_company_visits - Obter estatísticas de visitas

Ferramentas de Projetos

  • create_project - Criar novo projeto
  • list_projects - Listar projetos do usuário
  • get_project - Obter detalhes do projeto
  • update_project - Atualizar projeto
  • delete_project - Excluir projeto
  • add_companies_to_project - Adicionar empresas
  • remove_companies_from_project - Remover empresas

Ferramentas de Usuário

  • get_user_profile - Obter perfil
  • update_user_profile - Atualizar perfil
  • get_user_projects - Listar projetos
  • get_user_api_keys - Listar chaves API

Ferramentas LinkedIn

  • get_linkedin_profile - Obter perfil
  • search_linkedin_profiles - Pesquisar perfis
  • get_linkedin_connections - Obter conexões
  • get_linkedin_profile_versions - Obter histórico de versões
  • get_linkedin_companies - Obter dados de empresas

Ferramentas Admin (Apenas Admin)

  • list_all_users - Listar todos os usuários
  • create_user - Criar usuário
  • get_user_details - Obter detalhes do usuário
  • list_api_keys - Listar todas as chaves API
  • create_api_key - Criar chave API
  • revoke_api_key - Revogar chave API
  • get_admin_stats - Obter estatísticas admin

Ferramentas de Estatísticas

  • get_company_stats - Obter estatísticas agregadas
  • get_canton_counts - Obter contagens de cantões
  • get_letter_counts - Obter contagens de letras
  • get_two_letter_counts - Obter contagens de duas letras

Recursos

O servidor fornece acesso baseado em recursos:

  • mapfolio://company/{id} - Dados da empresa
  • mapfolio://project/{id} - Dados do projeto
  • mapfolio://user/{id} - Perfil do usuário
  • mapfolio://linkedin-profile/{id} - Perfil do LinkedIn

Os recursos podem incluir autenticação via parâmetros de consulta:

  • mapfolio://company/{id}?apiKey=mapf_...
  • mapfolio://company/{id}?jwtToken=...

Exemplo de Uso

Pesquisar Empresas

{
  "tool": "search_companies",
  "arguments": {
    "query": "technology",
    "cantons": ["ZH", "BE"],
    "page": 1,
    "limit": 20
  }
}

Criar Projeto

{
  "tool": "create_project",
  "arguments": {
    "name": "Tech Companies Zurich",
    "searchType": "company",
    "searchQuery": "technology",
    "isPublic": false
  }
}

Obter Detalhes da Empresa

{
  "tool": "get_company",
  "arguments": {
    "companyId": "company-uuid-here"
  }
}

Tratamento de Erros

Todas as ferramentas retornam erros em um formato consistente:

{
  "error": "Mensagem de erro"
}

Cenários de erro comuns:

  • 401 Não Autorizado: Autenticação inválida ou ausente
  • 403 Proibido: Permissões insuficientes
  • 404 Não Encontrado: Recurso não encontrado
  • 500 Erro Interno do Servidor: Erro do lado do servidor

Arquitetura Apenas API

O servidor MCP usa solicitações HTTP para mapfolio.app em vez de acesso direto ao banco de dados. Isso significa:

  • ✅ Não são necessárias credenciais Supabase - Funciona apenas com URL da API e chave API
  • ✅ Implantação Vercel fácil - Implantar como função serverless
  • ✅ Seguro - Todas as solicitações passam pela API do Mapfolio com autenticação
  • ✅ Escalável - Beneficia-se do limite de taxa e cache da API do Mapfolio

Atualmente Disponível via API

  • ✅ Pesquisa e recuperação de empresas
  • ✅ Estatísticas de empresas (contagens de cantões, contagens de letras)
  • ✅ Empresas aleatórias
  • ✅ Visitas de empresas

Em Breve (Requer Endpoints de API)

  • ⏳ Gerenciamento de projetos (criar, listar, atualizar, excluir)
  • ⏳ Gerenciamento de perfis de usuário
  • ⏳ Acesso a perfis do LinkedIn
  • ⏳ Operações administrativas

Essas funcionalidades retornarão mensagens de erro úteis até que os endpoints da API sejam criados.

Considerações de Segurança

  1. Chaves API: Armazenar com segurança, nunca fazer commit no controle de versão
  2. Tokens JWT: Os tokens expiram, lidar com atualização adequadamente
  3. Limite de Taxa da API: Respeita os limites de taxa da API do Mapfolio
  4. Apenas HTTPS: Sempre usar HTTPS para solicitações de API
  5. Operações Admin: Requerem autenticação de admin explícita (quando os endpoints estiverem disponíveis)

Desenvolvimento

Verificação de Tipos

npm run type-check

Compilação

npm run build

Modo de Desenvolvimento

npm run dev

Documentação

Para documentação completa, consulte o README do Servidor MCP.

Suporte

Para problemas ou perguntas:

Licença

MIT