CodeFundi

Code Fundi

O Mapa de Codebase para Agentes de IA, Equipes e Aplicações.

Servidor MCP Code-Fundi

Um servidor Model Context Protocol (MCP) de nível de produção para a API Code-Fundi: um mapa de codebase e mecanismo de raio de impacto para agentes de codificação de IA. Permite que qualquer assistente de IA compatível com MCP (Claude, Claude Code, Cursor, Windsurf, VS Code Copilot e outros) pesquise, investigue, indexe e analise repositórios de código por meio de linguagem natural, e veja o que uma alteração quebra antes de ser publicada.

Construído com FastMCP (TypeScript) e Zod para validação de esquema.

Primeiros passos para agentes de IA

Se você é um agente de IA (ou está configurando um) e nenhum CODEFUNDI_API_KEY está definido, você deve se autenticar antes de usar ferramentas de busca, repositórios, chat ou outras ferramentas autenticadas. As ferramentas de autenticação (code-fundi-auth-*) funcionam sem uma chave pré-existente.

Qual caminho usar

Situação	Ação
CODEFUNDI_API_KEY está definido na configuração do MCP	Use qualquer ferramenta imediatamente — o servidor a envia como X-API-Key em cada requisição
Nenhuma chave de API configurada	Execute o fluxo de autenticação OTP abaixo (recomendado) ou o login com senha

Configuração MCP sem configuração (sem chave de API)

Você pode iniciar o servidor MCP sem CODEFUNDI_API_KEY e autenticar em tempo de execução:

{
  "mcpServers": {
    "code-fundi": {
      "command": "npx",
      "args": ["-y", "@codefundi/code-fundi-mcp"]
    }
  }
}

Autentique-se com OTP (recomendado)

Code-Fundi usa autenticação baseada em Supabase (POST /v2/auth/authenticate, /v2/auth/verify, /v2/auth/resend). Os e-mails de OTP contêm um código de 6 dígitos — links mágicos não são suportados neste caminho.

1. Pergunte ao usuário humano pelo endereço de e-mail dele.
2. Chame code-fundi-auth-authenticate com:
   • auth_mode: "otp"
   • email: o e-mail do usuário
   • should_create_user: true para uma conta nova, false para um usuário existente
3. Diga ao usuário para verificar a caixa de entrada em busca de um código de 6 dígitos. A API pode retornar verification_required: true e api_key.key_state: "agent_pending" até que a verificação seja concluída.
4. Pergunte ao usuário pelo OTP de 6 dígitos (humano no circuito — você não pode adivinhar ou contornar esta etapa).
5. Chame code-fundi-auth-verify com o mesmo email e o token (6 dígitos).
6. Em caso de sucesso, o servidor MCP configura automaticamente a chave de API na memória para todas as chamadas de ferramentas subsequentes nesta sessão.

Se o código expirou ou não foi recebido, chame code-fundi-auth-resend com o mesmo email e repita a etapa 5.

Exemplo de diálogo:

Agent: What email should I use to sign in to Code-Fundi?
User:  dev@example.com
Agent: [calls code-fundi-auth-authenticate] I've sent a 6-digit code to dev@example.com. Please paste it here.
User:  482913
Agent: [calls code-fundi-auth-verify] You're signed in. I can now search and index your repositories.

Login com senha (alternativa)

Para contas existentes com senha, chame code-fundi-auth-authenticate com auth_mode: "password", o email do usuário, should_create_user: false e o parâmetro password. O cliente MCP envia a senha apenas no cabeçalho X-CodeFundi-Auth-Password (nunca no corpo JSON). A produção exige HTTPS. Usuários existentes podem receber uma chave de API ativa imediatamente, sem uma etapa de verificação separada.

Após a autenticação

• A chave de API é mantida na memória durante toda a vida útil do processo do servidor MCP. Ela não é persistida entre reinicializações do IDE ou do MCP.
• Recomende que o usuário adicione a chave à configuração do MCP como CODEFUNDI_API_KEY para que sessões futuras iniciem autenticadas.
• Uma conta de nível GRATUITO e uma chave de API são criadas automaticamente no primeiro cadastro.

Erros

Status HTTP	O que fazer
401 Não autorizado	Sem chave válida — execute o fluxo OTP acima ou defina CODEFUNDI_API_KEY
429 Muitas requisições	Os endpoints de autenticação são limitados por IP; aguarde Retry-After segundos e tente novamente

Recursos

Cada ferramenta abaixo é suportada pelo mesmo mapa de codebase: dependências estruturais, grafo de chamadas e raio de impacto, indexados uma vez e consultados em milissegundos.

• 🔍 Busca semântica e grep de código no seu mapa de codebase indexado
• 🧠 Pesquisa com IA: busca mais análise de IA em uma única chamada
• 📦 Gerenciamento de repositórios: indexação, status, README, listagem, catálogo público
• 🛰️ Inteligência de repositórios: mapa de dependências entre repositórios, blueprint, Guarda de Raio de Impacto (análise de impacto antes do merge)
• 📄 Documentação de arquivos: documentação gerada por IA para qualquer arquivo indexado
• 📊 Estatísticas de uso: consultas de uso, atividade, distribuição por linguagem
• 🔐 Autenticação orientada por agente: cadastro/login via OTP sem chaves pré-configuradas
• 💬 Chat de IA e insights de modelos: conversa direta com a IA do Code-Fundi, catálogo de modelos e limites por nível

Início rápido

Instalar a partir do npm (recomendado)

Instale o pacote (inclui um dist/ pré-construído). O binário code-fundi-mcp está no seu PATH quando instalado globalmente, ou disponível via npx sem clonar o repositório:

npm install -g @codefundi/code-fundi-mcp

Ou adicione-o a um projeto:

npm install @codefundi/code-fundi-mcp

Instalar a partir do código-fonte (este repositório)

git clone https://github.com/Code-Fundi/code-fundi-mcp.git
cd code-fundi-mcp
npm install
npm run build

Configurar

Opção A — chave de API (mais rápida): defina sua chave como uma variável de ambiente:

export CODEFUNDI_API_KEY=your_api_key_here

Opção B — sem chave de API: pule a variável de ambiente e deixe o agente se autenticar em tempo de execução. Veja Primeiros passos para agentes de IA.

Exemplo de MCP sem configuração (sem bloco env):

{
  "mcpServers": {
    "code-fundi": {
      "command": "npx",
      "args": ["-y", "@codefundi/code-fundi-mcp"]
    }
  }
}

Usar com Claude Desktop

Após uma instalação global (npm i -g @codefundi/code-fundi-mcp), aponte o MCP para o binário publicado (sem caminho para dist/index.js necessário):

{
  "mcpServers": {
    "code-fundi": {
      "command": "@codefundi/code-fundi-mcp",
      "env": {
        "CODEFUNDI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Se o binário não estiver no seu PATH, use npx (baixa ou usa o pacote local e executa o mesmo ponto de entrada):

{
  "mcpServers": {
    "code-fundi": {
      "command": "npx",
      "args": ["-y", "@codefundi/code-fundi-mcp"],
      "env": {
        "CODEFUNDI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Usar com Cursor

Mesmo padrão do Claude: command mais args opcional apenas, sem caminho manual para o repositório:

{
  "mcpServers": {
    "code-fundi": {
      "command": "npx",
      "args": ["-y", "@codefundi/code-fundi-mcp"],
      "env": {
        "CODEFUNDI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Ao desenvolver dentro deste repositório, você pode executar npm run dev ou npx tsx src/index.ts sem compilar antes.

Modo de desenvolvimento

npm run dev                          # Run with tsx (no build needed)
npx fastmcp inspect src/index.ts    # Open MCP Inspector UI
npx fastmcp dev src/index.ts        # Test with MCP CLI

Referência de ferramentas (27 ferramentas)

Cobre a API V2 do Code-Fundi para mapeamento de codebase e análise de raio de impacto: busca (incluindo busca com chat / pesquisa), repositórios (listar, indexar, status, readme, catálogo público), inteligência de repositórios (mapa, blueprint, raio), arquivos, histórico, estatísticas, chaves de API, autenticação, além do chat Fundi (POST /v1/fundi/chat) e o catálogo de modelos / limites V2 (GET /v2/models, GET /v2/models/limits).

Busca

Ferramenta	Descrição
code-fundi-search	Busca semântica e grep no seu mapa de codebase indexado, com filtros
code-fundi-research	Busca mais análise sintetizada por IA do código correspondente

Repositórios

Ferramenta	Descrição
code-fundi-list-repos	Lista repositórios indexados com paginação
code-fundi-index-repo	Indexa um novo repositório GitHub no seu mapa de codebase
code-fundi-repo-status	Verifica o status de indexação do repositório
code-fundi-repo-readme	Obtém a documentação README do repositório (obsoleto, prefira blueprint)
code-fundi-list-public-repos	Navega pelo catálogo global de repositórios públicos indexados (sem chave necessária)

Inteligência de repositórios

Ferramenta	Descrição
code-fundi-repo-map	Mapa de dependências entre repositórios: como serviços e pacotes realmente se conectam
code-fundi-repo-blueprint	README mais visão geral de dependências e convenções (sucessor do repo-readme)
code-fundi-repo-radius	Guarda de Raio de Impacto: todo arquivo e função que quebra antes do merge (PRO+)

Arquivos

Ferramenta	Descrição
code-fundi-list-files	Lista arquivos em um repositório
code-fundi-file-docs	Obtém documentação de arquivo gerada por IA

Histórico

Ferramenta	Descrição
code-fundi-list-history	Lista o histórico de consultas com filtros
code-fundi-history-item	Obtém detalhes completos de uma entrada de histórico
code-fundi-conversation	Obtém mensagens do tópico de conversa

Estatísticas

Ferramenta	Descrição
code-fundi-usage-stats	Distribuição de uso por tipo de consulta
code-fundi-activity-stats	Estatísticas de atividade diária
code-fundi-language-stats	Uso por linguagem de programação

Autenticação

Ferramenta	Descrição
code-fundi-auth-authenticate	Inicia o fluxo de autenticação OTP/senha (sem chave necessária)
code-fundi-auth-verify	Verifica o código OTP e obtém a chave de API
code-fundi-auth-resend	Reenvia o e-mail de verificação OTP
code-fundi-list-api-keys	Lista chaves de API (mascaradas)
code-fundi-regenerate-api-key	Regenera a chave de API
code-fundi-disable-api-key	Desativa uma chave de API por ID (DELETE /v2/keys/{key_id})

Chat e modelos

Ferramenta	Descrição
code-fundi-chat	Chat com a IA Fundi (POST /v1/fundi/chat; respostas em streaming são coletadas como texto)
code-fundi-list-models	Lista o catálogo de modelos de chat selecionados (GET /v2/models)
code-fundi-model-limits	Obtém limites de modelos de IA e configuração de nível (GET /v2/models/limits)

Autenticação

Dois modos: chave de API pré-configurada (CODEFUNDI_API_KEY na configuração do MCP) ou autenticação OTP/senha orientada por agente em tempo de execução. Instruções completas passo a passo, nomes de ferramentas e tratamento de erros estão em Primeiros passos para agentes de IA no topo deste README.

Variáveis de ambiente

Variável	Obrigatória	Padrão	Descrição
CODEFUNDI_API_KEY	Não*	—	Chave de API para autenticação
CODEFUNDI_BASE_URL	Não	https://api.codefundi.app	Substituição da URL base da API

* Obrigatória, a menos que use ferramentas de autenticação orientadas por agente.

Licença

MIT