Moatless MCP Server

Un servidor avanzado de análisis y edición de código con capacidades de búsqueda semántica mediante incrustaciones vectoriales.

GitHub
1
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Moatless

Python 3.10+ MCP License

Un servidor avanzado de análisis y edición de código basado en el Protocolo de Contexto de Modelo (MCP), con soporte para búsqueda semántica mediante embeddings vectoriales. Este servidor proporciona a los asistentes de IA la capacidad de ejecutar operaciones complejas sobre código a través de una interfaz estandarizada.

Arquitectura central: Protocolo de Contexto de Modelo (MCP)

Este servidor es una implementación de un servidor MCP. MCP es un protocolo abierto diseñado para actuar como middleware estándar entre modelos de lenguaje (LLM) y herramientas o fuentes de datos externas. Permite que clientes como IDE o aplicaciones de chat (clientes MCP) interactúen de forma segura y dinámica con las capacidades ofrecidas por el servidor (como acceso al sistema de archivos o análisis de código).

Flujo de arquitectura

Cuando un cliente MCP (como Claude Desktop o cline) se conecta a este servidor, la interacción sigue el siguiente flujo:

+------------------+     1. Request (e.g., call_tool)     +-----------------------+
|   MCP Client     | -----------------------------------> |     MCP Server        |
| (IDE, cline etc.)|                                      |     (This Project)    |
+------------------+     6. Response (JSON-RPC)           +-----------+-----------+
        ^          <-----------------------------------          | 2. Dispatch
        |                                                        |
        |                                                        v
        |                                              +-----------------------+
        |                                              |     Tool Registry     |
        |                                              +-----------+-----------+
        |                                                        | 3. Execute Tool
        |                                                        |
        |                                                        v
        |                                              +-----------------------+
        |                                              |      Specific Tool    |
        |                                              | (e.g., ReadFileTool)  |
        |                                              +-----------+-----------+
        |                                                        | 4. Access Data
        |                                                        |
        |   +----------------------------------------------------+
        |   |
        v   v
+-----------------------+     5. Return Data/Result      +-----------------------+
|     Workspace         | <----------------------------- |    Workspace Adapter  |
| (File System, .git)   |                                | (Manages Project State) |
+-----------------------+                                +-----------------------+
  1. Solicitud (Request): El cliente envía una solicitud JSON-RPC al servidor, por ejemplo tool_run, solicitando la ejecución de una herramienta llamada read_file.
  2. Distribución (Dispatch): El núcleo del servidor MCP en server.py recibe la solicitud y la distribuye a ToolRegistry.
  3. Ejecución (Execute): ToolRegistry localiza la instancia de la herramienta registrada llamada read_file e invoca su método execute.
  4. Acceso a datos (Access Data): La herramienta solicita acceso a los archivos del proyecto a través de WorkspaceAdapter.
  5. Devolución de datos (Return Data): WorkspaceAdapter lee los datos del sistema de archivos y los devuelve a la herramienta. La herramienta envuelve el resultado en un objeto ToolResult.
  6. Respuesta (Response): El núcleo del servidor formatea ToolResult como una respuesta JSON-RPC y la envía de vuelta al cliente.

Detalle de componentes

  • Núcleo del servidor (server.py):

    • Responsabilidad: Actúa como punto de entrada principal del servidor, escuchando y respondiendo a las conexiones de los clientes MCP.
    • Implementación: Utiliza la librería mcp.server para gestionar la comunicación JSON-RPC subyacente. Define manejadores de protocolo como list_tools y call_tool, y delega la lógica concreta en ToolRegistry.

  • Registro de herramientas (tools/registry.py):

    • Responsabilidad: Gestiona el ciclo de vida de las herramientas. Al iniciar, instancia todas las herramientas disponibles y las almacena en un diccionario para acceso rápido.
    • Implementación: La clase ToolRegistry contiene un método _register_default_tools para registrar todas las herramientas de forma centralizada. Cuando se invoca execute_tool, busca y ejecuta la herramienta correspondiente.

  • Adaptador de espacio de trabajo (adapters/workspace.py):

    • Responsabilidad: Actúa como capa de abstracción para el sistema de archivos y el estado del proyecto. Todas las operaciones de lectura, escritura y búsqueda sobre archivos del proyecto deben pasar por este adaptador.
    • Implementación: La clase WorkspaceAdapter proporciona interfaces de acceso a archivos, repositorios Git e índices semánticos de Moatless, aplicando además políticas de seguridad (como restricciones de tipo de archivo y rutas).

  • Herramientas (tools/*.py):

    • Responsabilidad: Implementan las unidades de lógica de negocio específicas. Cada herramienta es una clase independiente responsable de una tarea concreta, como leer o escribir archivos, buscar código o ejecutar pruebas.
    • Implementación: Todas las herramientas heredan de la clase base MCPTool (tools/base.py) e implementan el método execute. Reciben una instancia de WorkspaceAdapter a través del constructor para interactuar con los datos del proyecto.

  • Sistema vectorial y Tree-sitter (vector/, treesitter/):

    • Responsabilidad: Proporcionan capacidades avanzadas de comprensión de código. El Sistema Vectorial se encarga de convertir código en vectores y realizar búsquedas semánticas. Tree-sitter se utiliza para analizar con precisión la estructura sintáctica del código (AST).
    • Implementación: Estos módulos son utilizados por herramientas avanzadas (como SemanticSearchTool y FindClassTool) para ofrecer funcionalidades más potentes que la simple coincidencia de texto.

Características técnicas clave

1. Implementación de búsqueda semántica

  • Embeddings vectoriales: Utiliza embeddings de 1024 dimensiones de Jina AI (recomendado) o embeddings de OpenAI (obsoletos).
  • Construcción bajo demanda: El índice vectorial solo se construye cuando es necesario mediante la herramienta build_vector_index, evitando retrasos innecesarios en el arranque.
  • Segmentación de código: División inteligente de bloques de código basada en la librería Moatless.
  • Búsqueda de similitud: Utiliza la base de datos vectorial FAISS para una búsqueda eficiente.

2. Modelo de seguridad flexible

  • Política de lista blanca: Por defecto, permite el acceso a una amplia variedad de tipos de archivos comunes de código, configuración y documentación.
  • Filtrado inteligente de rutas: Solo bloquea directorios de dependencias principales y caché (node_modules, .venv, __pycache__, etc.).
  • Configurabilidad: La configuración de seguridad se puede ajustar fácilmente mediante la clase Config.

3. Sistema de herramientas modular y extensible

  • Clase base de herramientas: MCPTool proporciona una interfaz clara para crear nuevas herramientas personalizadas.
  • Registro centralizado: ToolRegistry facilita la adición y gestión de nuevas herramientas.

Ejemplos de uso

Operaciones básicas con archivos

{
  "tool": "read_file",
  "arguments": {
    "file_path": "src/moatless_mcp/server.py",
    "start_line": 1,
    "end_line": 10
  }
}

Búsqueda semántica

{
  "tool": "semantic_search",
  "arguments": {
    "query": "user authentication and login validation",
    "max_results": 5
  }
}

Análisis de estructura de código

{
  "tool": "find_class",
  "arguments": {
    "class_name": "ToolRegistry",
    "file_pattern": "**/registry.py"
  }
}

Despliegue y desarrollo

Para obtener instrucciones detalladas sobre cómo ejecutar este servidor, realizar el despliegue y cómo desarrollar y añadir nuevas herramientas, consulta README_deploy.md.

Documentación relacionada