Codebase MCP Server

Um mecanismo de busca inteligente de código-fonte que transforma bases de código locais em uma base de conhecimento consultável em linguagem natural.

GitHubExperimente este MCPPatrocinado

Documentação

Servidor MCP Codebase

Codebase MCP Server é um mecanismo de busca inteligente de código-fonte projetado para desenvolvedores. Baseado no Protocolo de Contexto de Modelo (MCP), ele transforma o repositório de código local em uma base de conhecimento inteligente que pode ser consultada por meio de linguagem natural. Diferente da navegação tradicional de arquivos e da busca por texto, esta ferramenta utiliza recursos avançados de compreensão semântica para ajudar desenvolvedores a localizar trechos de código de forma rápida e precisa, aumentando significativamente a eficiência do desenvolvimento e a profundidade da compreensão do código.

Valor principal

Adeus à busca tediosa de código: Não é mais necessário navegar manualmente por centenas ou milhares de arquivos; basta descrever em linguagem natural a funcionalidade que você procura para obter o código mais relevante.
Compreensão rápida do projeto: Assimile rapidamente a lógica central de novos projetos ou módulos complexos, seja implementação de funcionalidades, tratamento de erros ou algoritmos específicos.
Aumento da eficiência de desenvolvimento: Gaste mais tempo codificando, em vez de se perder no oceano de código.

Recursos

Suporte a múltiplos repositórios de código: Gerencia e pesquisa índices de vários repositórios de código simultaneamente.
Indexação incremental e atualização automática: Monitora alterações no sistema de arquivos e atualiza o índice automaticamente, garantindo que os resultados da busca estejam sempre atualizados.
Suporte a múltiplos modelos de incorporação: Suporta vários provedores de modelos de incorporação (como DashScope, Ollama, etc.), adaptando-se de forma flexível a diferentes necessidades.
Análise inteligente de código: Analisa profundamente o código C#, identificando estruturas-chave como classes, métodos, propriedades, etc.
Gerenciamento persistente de tarefas: As tarefas de indexação são executadas em segundo plano de forma persistente, podendo ser retomadas mesmo após a reinicialização do servidor.
Protocolo padrão MCP: Como um servidor MCP padrão, integra-se perfeitamente a qualquer cliente MCP compatível (como Claude Desktop).

Requisitos do sistema

.NET 9.0 ou superior
Banco de dados vetorial Qdrant (localhost:6334)
Chave de API DashScope

Instalação e configuração

1. Clonar o projeto

git clone <项目地址>
cd CodebaseMcpServer

2. Configurar as definições

Edite o arquivo appsettings.json:

{
  "CodeSearch": {
    "DashScopeApiKey": "your-dashscope-api-key",
    "QdrantConfig": {
      "Host": "localhost",
      "Port": 6334,
      "CollectionName": "codebase_embeddings"
    },
    "DefaultCodebasePath": "D:\\Path\\To\\Your\\Codebase",
    "SearchConfig": {
      "DefaultLimit": 10,
      "MaxTokenLength": 8192,
      "BatchSize": 10
    }
  }
}

3. Iniciar o banco de dados Qdrant

Inicie o Qdrant usando Docker:

docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant

4. Compilar o projeto

dotnet build

Como usar: fluxo de trabalho principal

O fluxo de uso típico é o descrito abaixo, projetado para transformar seu repositório de código em uma base de conhecimento pesquisável.

Etapa 1: Criar um índice para seu repositório de código

Primeiro, crie um índice vetorial para o repositório de código de destino. Esta é a base de todos os recursos de busca.

Ferramenta: CreateIndexLibrary
Exemplo: suponha que seu projeto esteja localizado em D:\Projects\MyApp.

{
  "tool_name": "CreateIndexLibrary",
  "arguments": {
    "codebasePath": "D:\\Projects\\MyApp",
    "friendlyName": "My Awesome App"
  }
}

O servidor iniciará uma tarefa em segundo plano para digitalizar, analisar e indexar seu código.

Etapa 2: Verificar o status do índice

A criação do índice leva algum tempo, dependendo do tamanho do repositório de código. Você pode usar a ferramenta GetIndexingStatus para monitorar o progresso.

Ferramenta: GetIndexingStatus

Exemplos:

Visualizar a visão geral de todos os índices:
```
{ "tool_name": "GetIndexingStatus" }
```

Visualizar o status detalhado de um repositório específico:

{
  "tool_name": "GetIndexingStatus",
  "arguments": { "codebasePath": "D:\\Projects\\MyApp" }
}

Etapa 3: Executar busca semântica de código

Após a conclusão da indexação, você pode começar a pesquisar usando linguagem natural.

Ferramenta: SemanticCodeSearch
Exemplo: localizar a lógica relacionada à autenticação do usuário.

{
  "tool_name": "SemanticCodeSearch",
  "arguments": {
    "query": "用户登录验证逻辑",
    "codebasePath": "D:\\Projects\\MyApp",
    "limit": 5
  }
}

O servidor retornará os trechos de código mais relevantes, caminhos de arquivo, pontuações de similaridade, entre outras informações.

Etapa 4: Gerenciar seus índices (opcional)

Você pode reconstruir ou excluir índices conforme necessário.

Reconstruir índice: use quando houver alterações significativas no repositório de código ou suspeita de corrupção do índice.
- Ferramenta: RebuildIndex
Excluir índice: use quando o índice de um repositório de código não for mais necessário.
- Ferramenta: DeleteIndexLibrary (requer confirmação em duas etapas)

Detalhamento das ferramentas MCP

O servidor oferece dois tipos de ferramentas: busca de código e gerenciamento de índices.

Busca de código

1. `SemanticCodeSearch`

Ferramenta preferida para consultas de código. Localiza com precisão trechos de código relevantes com base em descrições em linguagem natural. Ela evita a leitura completa e a travessia de arquivos, encontrando diretamente o código-alvo por similaridade semântica, o que aumenta enormemente a eficiência da localização e compreensão do código.

Parâmetros:
- query (string, obrigatório): consulta de busca em linguagem natural.
  - Exemplos eficientes: '用户登录验证逻辑', '数据库连接池管理', 'JWT令牌生成'.
  - Evitar: consultas muito amplas, como '函数', '类'.
- codebasePath (string, obrigatório): caminho absoluto do diretório raiz do repositório a ser pesquisado.
  - Exemplos: 'd:/VSProject/MyApp', './src'.
- limit (int, opcional, padrão 5): número de trechos de código mais relevantes a retornar.
  - Sugestão: use 5-10 para buscas rápidas e 15-20 para análise detalhada.

Exemplo de uso:

{
  "tool_name": "SemanticCodeSearch",
  "arguments": {
    "query": "如何实现文件上传的错误处理",
    "codebasePath": "D:\\Projects\\WebApp",
    "limit": 3
  }
}

Gerenciamento de índices

1. `CreateIndexLibrary`

Cria um índice semântico para o diretório do repositório de código especificado. A indexação é um pré-requisito para usar o SemanticCodeSearch. Esse processo é executado em segundo plano e ativa automaticamente o monitoramento de arquivos para atualizações incrementais.

Parâmetros:
- codebasePath (string, obrigatório): caminho absoluto completo do diretório do repositório a ser indexado.
- friendlyName (string, opcional): nome de fácil identificação para o índice. Se não for fornecido, o nome do diretório será usado por padrão.

Exemplo de uso:

{
  "tool_name": "CreateIndexLibrary",
  "arguments": {
    "codebasePath": "C:\\Users\\Dev\\Documents\\MyProject",
    "friendlyName": "Main Project"
  }
}

2. `GetIndexingStatus`

Consulta o status, as estatísticas e o progresso da indexação de um ou de todos os repositórios.

Parâmetros:
- codebasePath (string, opcional): se fornecido, exibe o status detalhado desse repositório específico.
- taskId (string, opcional): se fornecido, consulta o status de uma tarefa de indexação específica.
- Observação: se nenhum dos dois parâmetros for fornecido, exibe a visão geral do status de todos os índices.

Exemplo de uso:

{
  "tool_name": "GetIndexingStatus",
  "arguments": {
    "codebasePath": "C:\\Users\\Dev\\Documents\\MyProject"
  }
}

3. `RebuildIndex`

Quando há mudanças estruturais significativas no código ou suspeita de corrupção dos dados do índice, esta ferramenta pode ser usada para limpar o índice antigo e reconstruí-lo do zero.

Parâmetros:
- codebasePath (string, obrigatório): caminho do repositório cujo índice será reconstruído.

Exemplo de uso:

{
  "tool_name": "RebuildIndex",
  "arguments": {
    "codebasePath": "C:\\Users\\Dev\\Documents\\MyProject"
  }
}

4. `DeleteIndexLibrary`

Exclui permanentemente os dados do índice e as configurações relacionadas do repositório especificado. Esta é uma operação perigosa e requer confirmação em duas etapas.

Parâmetros:
- codebasePath (string, obrigatório): caminho do repositório cujo índice será excluído.
- confirm (bool, obrigatório, padrão false): este parâmetro deve ser definido como true para executar a exclusão. A primeira chamada (sem ou com false) retorna uma solicitação de confirmação.

Exemplo de uso (exclusão segura):

Primeira chamada (obter solicitação de confirmação):

{
  "tool_name": "DeleteIndexLibrary",
  "arguments": { "codebasePath": "C:\\Path\\To\\OldProject" }
}

Segunda chamada (confirmar exclusão):

{
  "tool_name": "DeleteIndexLibrary",
  "arguments": {
    "codebasePath": "C:\\Path\\To\\OldProject",
    "confirm": true
  }
}

Configuração do cliente MCP

Configuração do Claude Desktop

Adicione ao arquivo de configuração do Claude Desktop:

{
  "mcpServers": {
    "codebase-search": {
      "url": "http://localhost:5000/sse",
      "alwaysAllow": [
        "SemanticCodeSearch",
        "GetIndexingStatus"
      ],
      "timeout": 30
    }
  }
}

Outros clientes MCP

Qualquer cliente que suporte o protocolo MCP pode se comunicar com este servidor por meio de entrada e saída padrão.

Descrição da arquitetura

graph TD
    subgraph MCP Client
        A[User/Client Application]
    end

    subgraph CodebaseMcpServer
        B[MCP Protocol Layer]
        C[MCP Tools Layer]
        D[Service Layer]
        E[Data & Infrastructure]
    end

    A -- MCP Request --> B
    B -- Tool Call --> C
    C -- Calls --> D
    D -- Interacts with --> E

    subgraph C [MCP Tools Layer]
        C1[CodeSearchTools]
        C2[IndexManagementTools]
    end

    subgraph D [Service Layer]
        D1[EnhancedCodeSemanticSearch]
        D2[IndexLibraryService]
        D3[FileWatcherService]
        D4[BackgroundTaskService]
    end

    subgraph E [Data & Infrastructure]
        E1["Embedding Providers\n(DashScope, Ollama, etc.)"]
        E2["Qdrant DB\n(Vector Storage)"]
        E3["LiteDB\n(Metadata & Task Storage)"]
        E4[C# Code Parser]
    end

    C1 -- Uses --> D1
    C2 -- Uses --> D2
    
    D1 -- Needs --> E1
    D1 -- Needs --> E2
    D2 -- Manages --> E2
    D2 -- Manages --> E3
    D2 -- Uses --> D3
    D2 -- Uses --> D4
    D1 -- Uses --> E4

Pilha de tecnologias

.NET 9.0: ambiente de execução
ModelContextProtocol: implementação do protocolo MCP
Qdrant.Client: cliente do banco de dados vetorial
Newtonsoft.Json: serialização JSON
DashScope API: serviço de incorporação de texto
Microsoft.Extensions.Hosting: host de aplicação

Desenvolvimento e extensão

Adicionar novas ferramentas

Crie uma nova classe de ferramenta no diretório Tools/
Use os atributos [McpServerToolType] e [McpServerTool]
Registre a nova ferramenta em Program.cs

Suporte a novas linguagens

Estenda a lógica de análise de código em CodeSemanticSearch.cs
Adicione os padrões de expressão regular da linguagem correspondente
Atualize a configuração de padrões de arquivo

Solução de problemas

Problemas comuns

Falha de conexão com o Qdrant
- Certifique-se de que o serviço Qdrant esteja em execução
- Verifique se a porta 6334 está acessível
Erros da API DashScope
- Valide se a chave de API está correta
- Verifique a conexão de rede
Falha na indexação do repositório de código
- Certifique-se de que o caminho do repositório esteja correto
- Verifique as permissões de leitura de arquivos

Registro de logs

O servidor gera informações detalhadas de depuração, incluindo:

Progresso da análise de arquivos
Estatísticas de extração de trechos de código
Logs de consultas de busca
Detalhes de erros

Licença

[Adicione as informações de licença conforme necessário]

Contribuições

Sinta-se à vontade para enviar Issues e Pull Requests para melhorar este projeto.

Codebase MCP Server

Documentação

Servidor MCP Codebase

Valor principal

Recursos

Requisitos do sistema

Instalação e configuração

1. Clonar o projeto

2. Configurar as definições

3. Iniciar o banco de dados Qdrant

4. Compilar o projeto

Como usar: fluxo de trabalho principal

Etapa 1: Criar um índice para seu repositório de código

Etapa 2: Verificar o status do índice

Etapa 3: Executar busca semântica de código

Etapa 4: Gerenciar seus índices (opcional)

Detalhamento das ferramentas MCP

Busca de código

1. SemanticCodeSearch

Gerenciamento de índices

1. CreateIndexLibrary

2. GetIndexingStatus

3. RebuildIndex

4. DeleteIndexLibrary

Configuração do cliente MCP

Configuração do Claude Desktop

Outros clientes MCP

Descrição da arquitetura

Pilha de tecnologias

Desenvolvimento e extensão

Adicionar novas ferramentas

Suporte a novas linguagens

Solução de problemas

Problemas comuns

Registro de logs

Licença

Contribuições

1. `SemanticCodeSearch`

1. `CreateIndexLibrary`

2. `GetIndexingStatus`

3. `RebuildIndex`

4. `DeleteIndexLibrary`