Codebase MCP Server

Un motor de búsqueda de código inteligente que transforma bases de código locales en una base de conocimiento consultable en lenguaje natural.

GitHubPrueba este MCPPatrocinado

Documentación

Servidor MCP de Codebase

Codebase MCP Server es un motor de búsqueda inteligente de codebases diseñado específicamente para desarrolladores. Basado en el Protocolo de Contexto de Modelos (MCP), transforma tu codebase local en una base de conocimiento inteligente consultable mediante lenguaje natural. A diferencia de la exploración tradicional de archivos y la búsqueda de texto, esta herramienta utiliza capacidades avanzadas de comprensión semántica para ayudar a los desarrolladores a localizar fragmentos de código de manera rápida y precisa, mejorando significativamente la eficiencia del desarrollo y la comprensión del código.

Valor Principal

Di adiós a la búsqueda tediosa de código: Ya no necesitas revisar manualmente cientos o miles de archivos; simplemente describe la funcionalidad que buscas en lenguaje natural y obtén el código más relevante.
Comprende proyectos rápidamente: Domina rápidamente la lógica central de nuevos proyectos o módulos complejos, ya sea implementación de funcionalidades, manejo de errores o algoritmos específicos.
Aumenta la eficiencia del desarrollo: Dedica más tiempo a programar en lugar de perderte en el mar del código.

Características

Soporte para múltiples codebases: Administra y busca índices de múltiples codebases simultáneamente.
Indexación incremental y actualización automática: Supervisa los cambios en el sistema de archivos y actualiza automáticamente el índice para garantizar que los resultados de búsqueda estén siempre actualizados.
Soporte para múltiples modelos de embeddings: Admite varios proveedores de modelos de embeddings (como DashScope, Ollama, etc.) para adaptarse flexiblemente a diferentes necesidades.
Análisis inteligente de código: Analiza en profundidad código C#, identificando estructuras clave como clases, métodos y propiedades.
Gestión de tareas persistente: Las tareas de indexación se ejecutan en segundo plano de forma persistente y pueden reanudarse incluso después de reiniciar el servidor.
Protocolo estándar MCP: Como servidor MCP estándar, se integra sin problemas con cualquier cliente MCP compatible (como Claude Desktop).

Requisitos del Sistema

.NET 9.0 o superior
Base de datos vectorial Qdrant (localhost:6334)
Clave API de DashScope

Instalación y Configuración

1. Clonar el Proyecto

git clone <项目地址>
cd CodebaseMcpServer

2. Configurar Ajustes

Edita el archivo 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 la Base de Datos Qdrant

Inicia Qdrant usando Docker:

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

4. Compilar el Proyecto

dotnet build

Uso: Flujo de Trabajo Principal

El flujo de uso típico es el siguiente, diseñado para transformar tu codebase en una base de conocimiento buscable.

Paso 1: Crear un Índice para tu Codebase

Primero, necesitas crear un índice vectorial para el codebase objetivo. Esta es la base de todas las funcionalidades de búsqueda.

Herramienta: CreateIndexLibrary
Ejemplo: Supón que tu proyecto está ubicado en D:\Projects\MyApp.

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

El servidor iniciará una tarea en segundo plano para escanear, analizar e indexar tu código.

Paso 2: Verificar el Estado del Índice

La creación del índice lleva algún tiempo, dependiendo del tamaño del codebase. Puedes usar la herramienta GetIndexingStatus para monitorear el progreso.

Herramienta: GetIndexingStatus

Ejemplo:

Ver una descripción general de todos los índices:
```
{ "tool_name": "GetIndexingStatus" }
```

Ver el estado detallado de un codebase específico:

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

Paso 3: Realizar Búsqueda Semántica de Código

Una vez completada la indexación, puedes comenzar a buscar usando lenguaje natural.

Herramienta: SemanticCodeSearch
Ejemplo: Buscar lógica relacionada con la autenticación de usuarios.

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

El servidor devolverá los fragmentos de código más relevantes, rutas de archivo, puntuaciones de similitud, etc.

Paso 4: Administrar tus Índices (Opcional)

Puedes reconstruir o eliminar índices según sea necesario.

Reconstruir índice: Úsalo cuando ocurran cambios importantes en el codebase o sospeches que el índice está dañado.
- Herramienta: RebuildIndex
Eliminar índice: Úsalo cuando ya no necesites el índice de un codebase.
- Herramienta: DeleteIndexLibrary (requiere confirmación secundaria)

Explicación Detallada de las Herramientas MCP

El servidor proporciona dos tipos de herramientas: búsqueda de código y gestión de índices.

Búsqueda de Código

1. `SemanticCodeSearch`

Herramienta principal de consulta de código. Localiza con precisión fragmentos de código relevantes según descripciones en lenguaje natural. Evita la lectura y exploración completa de archivos al encontrar directamente el código objetivo mediante similitud semántica, mejorando enormemente la eficiencia de búsqueda y comprensión del código.

Parámetros:
- query (string, obligatorio): Consulta de búsqueda en lenguaje natural.
  - Ejemplo eficiente: '用户登录验证逻辑', '数据库连接池管理', 'JWT令牌生成'.
  - Evitar: Consultas demasiado amplias, como '函数', '类'.
- codebasePath (string, obligatorio): Ruta absoluta del directorio raíz del codebase a buscar.
  - Ejemplo: 'd:/VSProject/MyApp', './src'.
- limit (int, opcional, predeterminado 5): Número de fragmentos de código más relevantes a devolver.
  - Sugerencia: Usa 5-10 para búsquedas rápidas y 15-20 para análisis detallados.

Ejemplo de uso:

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

Gestión de Índices

1. `CreateIndexLibrary`

Crea un índice semántico para el directorio del codebase especificado. La indexación es un requisito previo para implementar SemanticCodeSearch. Este proceso se ejecuta en segundo plano y habilita automáticamente la supervisión de archivos para actualizaciones incrementales.

Parámetros:
- codebasePath (string, obligatorio): Ruta absoluta completa del directorio del codebase a indexar.
- friendlyName (string, opcional): Especifica un nombre fácil de reconocer para el índice. Si no se proporciona, se usa el nombre del directorio por defecto.

Ejemplo de uso:

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

2. `GetIndexingStatus`

Consulta el estado, las estadísticas y el progreso de indexación de uno o todos los codebases.

Parámetros:
- codebasePath (string, opcional): Si se proporciona, muestra el estado detallado de ese codebase específico.
- taskId (string, opcional): Si se proporciona, consulta el estado de una tarea de indexación específica.
- Nota: Si no se proporciona ninguno de los dos parámetros, se muestra una descripción general del estado de todos los índices.

Ejemplo de uso:

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

3. `RebuildIndex`

Cuando ocurren cambios estructurales importantes en el código o se sospecha que los datos del índice están dañados, esta herramienta se puede usar para limpiar el índice antiguo y reconstruirlo desde cero.

Parámetros:
- codebasePath (string, obligatorio): Ruta del codebase cuyo índice se va a reconstruir.

Ejemplo de uso:

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

4. `DeleteIndexLibrary`

Elimina permanentemente los datos del índice y la configuración relacionada del codebase especificado. Esta es una operación peligrosa que requiere confirmación secundaria.

Parámetros:
- codebasePath (string, obligatorio): Ruta del codebase cuyo índice se va a eliminar.
- confirm (bool, obligatorio, predeterminado false): Este parámetro debe establecerse en true para ejecutar la eliminación. La primera llamada (sin o con false) devuelve un mensaje de confirmación.

Ejemplo de uso (eliminación segura):

Primera llamada (obtener mensaje de confirmación):

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

Segunda llamada (confirmar eliminación):

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

Configuración del Cliente MCP

Configuración de Claude Desktop

Agrega lo siguiente al archivo de configuración de Claude Desktop:

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

Otros Clientes MCP

Cualquier cliente que admita el protocolo MCP puede comunicarse con este servidor a través de la entrada/salida estándar.

Explicación de la Arquitectura

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

Stack Tecnológico

.NET 9.0: Entorno de ejecución
ModelContextProtocol: Implementación del protocolo MCP
Qdrant.Client: Cliente de base de datos vectorial
Newtonsoft.Json: Serialización JSON
DashScope API: Servicio de embeddings de texto
Microsoft.Extensions.Hosting: Host de aplicaciones

Desarrollo y Extensión

Agregar Nuevas Herramientas

Crea una nueva clase de herramienta en el directorio Tools/
Usa los atributos [McpServerToolType] y [McpServerTool]
Registra la nueva herramienta en Program.cs

Soporte para Nuevos Lenguajes

Extiende la lógica de análisis de código en CodeSemanticSearch.cs
Agrega patrones de expresiones regulares para el lenguaje correspondiente
Actualiza la configuración de patrones de archivos

Solución de Problemas

Problemas Comunes

Fallo de conexión con Qdrant
- Asegúrate de que el servicio Qdrant esté en ejecución
- Verifica que el puerto 6334 sea accesible
Error de API de DashScope
- Verifica que la clave API sea correcta
- Comprueba la conexión de red
Fallo en la indexación del codebase
- Asegúrate de que la ruta del codebase sea correcta
- Verifica los permisos de lectura de archivos

Registro de Actividades

El servidor genera información de depuración detallada, que incluye:

Progreso del análisis de archivos
Estadísticas de extracción de fragmentos de código
Registros de consultas de búsqueda
Detalles de errores

Licencia

[Agrega información de licencia según sea necesario]

Contribuciones

Se aceptan Issues y Pull Requests para mejorar este proyecto.

Codebase MCP Server

Documentación

Servidor MCP de Codebase

Valor Principal

Características

Requisitos del Sistema

Instalación y Configuración

1. Clonar el Proyecto

2. Configurar Ajustes

3. Iniciar la Base de Datos Qdrant

4. Compilar el Proyecto

Uso: Flujo de Trabajo Principal

Paso 1: Crear un Índice para tu Codebase

Paso 2: Verificar el Estado del Índice

Paso 3: Realizar Búsqueda Semántica de Código

Paso 4: Administrar tus Índices (Opcional)

Explicación Detallada de las Herramientas MCP

Búsqueda de Código

1. SemanticCodeSearch

Gestión de Índices

1. CreateIndexLibrary

2. GetIndexingStatus

3. RebuildIndex

4. DeleteIndexLibrary

Configuración del Cliente MCP

Configuración de Claude Desktop

Otros Clientes MCP

Explicación de la Arquitectura

Stack Tecnológico

Desarrollo y Extensión

Agregar Nuevas Herramientas

Soporte para Nuevos Lenguajes

Solución de Problemas

Problemas Comunes

Registro de Actividades

Licencia

Contribuciones

1. `SemanticCodeSearch`

1. `CreateIndexLibrary`

2. `GetIndexingStatus`

3. `RebuildIndex`

4. `DeleteIndexLibrary`