Moatless MCP Server

Um servidor avançado de análise e edição de código com capacidades de busca semântica utilizando embeddings vetoriais.

GitHub
1
Experimente este MCPPatrocinado

Documentação

Servidor MCP Moatless

Python 3.10+ MCP License

Um servidor avançado de análise e edição de código baseado no Model Context Protocol (MCP), com suporte a busca semântica baseada em embeddings vetoriais. Este servidor fornece aos assistentes de IA a capacidade de executar operações complexas de código por meio de uma interface padronizada.

Arquitetura Central: Model Context Protocol (MCP)

Este servidor é uma implementação de um servidor MCP. O MCP é um protocolo aberto projetado para ser o middleware padrão entre modelos de linguagem (LLMs) e ferramentas externas e fontes de dados. Ele permite que clientes como IDEs ou aplicativos de chat (clientes MCP) interajam de forma segura e dinâmica com as capacidades fornecidas pelo servidor (como acesso ao sistema de arquivos, análise de código).

Fluxo da Arquitetura

Quando um cliente MCP (como o Claude Desktop ou cline) se conecta a este servidor, a interação segue o seguinte fluxo:

+------------------+     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. Solicitação (Request): O cliente envia uma solicitação JSON-RPC ao servidor, por exemplo, tool_run, solicitando a execução de uma ferramenta chamada read_file.
  2. Distribuição (Dispatch): O núcleo do servidor MCP em server.py recebe a solicitação e a distribui para ToolRegistry.
  3. Execução (Execute): ToolRegistry encontra a instância da ferramenta registrada chamada read_file e invoca seu método execute.
  4. Acesso a Dados (Access Data): A ferramenta solicita acesso aos arquivos do projeto por meio de WorkspaceAdapter.
  5. Retorno de Dados (Return Data): WorkspaceAdapter lê os dados do sistema de arquivos e os retorna para a ferramenta. A ferramenta encapsula o resultado em um objeto ToolResult.
  6. Resposta (Response): O núcleo do servidor formata ToolResult como uma resposta JSON-RPC e a envia de volta ao cliente.

Detalhamento dos Componentes

  • Núcleo do Servidor (server.py):

    • Responsabilidade: Atua como a entrada principal do servidor, escutando e respondendo às conexões dos clientes MCP.
    • Implementação: Usa a biblioteca mcp.server para lidar com a comunicação JSON-RPC subjacente. Define manipuladores de protocolo como list_tools e call_tool, delegando a lógica específica para ToolRegistry.

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

    • Responsabilidade: Gerencia o ciclo de vida das ferramentas. Instancia todas as ferramentas disponíveis na inicialização e as armazena em um dicionário para acesso rápido.
    • Implementação: A classe ToolRegistry contém um método _register_default_tools para registrar todas as ferramentas de forma centralizada. Quando execute_tool é chamado, ele localiza e executa a ferramenta correspondente.

  • Adaptador de Workspace (adapters/workspace.py):

    • Responsabilidade: Atua como uma camada de abstração para o sistema de arquivos e o estado do projeto. Todas as operações de leitura, escrita e busca nos arquivos do projeto devem passar por este adaptador.
    • Implementação: A classe WorkspaceAdapter fornece interfaces de acesso a arquivos, repositórios Git e o índice semântico Moatless, ao mesmo tempo em que aplica políticas de segurança (como restrições de tipo de arquivo e caminho).

  • Ferramentas (tools/*.py):

    • Responsabilidade: Implementam unidades de lógica de negócios específicas. Cada ferramenta é uma classe independente responsável por uma tarefa específica, como ler/escrever arquivos, busca de código ou execução de testes.
    • Implementação: Todas as ferramentas herdam da classe base MCPTool (tools/base.py) e implementam o método execute. Elas recebem uma instância de WorkspaceAdapter por meio do construtor para interagir com os dados do projeto.

  • Sistema Vetorial e Tree-sitter (vector/, treesitter/):

    • Responsabilidade: Fornecem capacidades avançadas de compreensão de código. O Sistema Vetorial é responsável por converter código em vetores e realizar busca semântica. O Tree-sitter é usado para analisar com precisão a estrutura sintática do código (AST).
    • Implementação: Esses módulos são usados por ferramentas avançadas (como SemanticSearchTool e FindClassTool) para fornecer funcionalidades mais poderosas do que a simples correspondência de texto.

Principais Características Técnicas

1. Implementação de Busca Semântica

  • Embeddings Vetoriais: Usa embeddings de 1024 dimensões da Jina AI (recomendado) ou embeddings da OpenAI (descontinuado).
  • Construção Sob Demanda: O índice vetorial é construído somente quando necessário, por meio da ferramenta build_vector_index, evitando atrasos desnecessários na inicialização.
  • Segmentação de Código: Segmentação inteligente de blocos de código baseada na biblioteca Moatless.
  • Busca por Similaridade: Usa o banco de dados vetorial FAISS para busca eficiente.

2. Modelo de Segurança Flexível

  • Política de Lista de Permissões: Por padrão, permite acesso a vários tipos comuns de arquivos de código, configuração e documentação.
  • Filtragem Inteligente de Caminhos: Apenas proíbe diretórios de dependências principais e cache (node_modules, .venv, __pycache__, etc.).
  • Configurabilidade: As configurações de segurança podem ser facilmente ajustadas por meio da classe Config.

3. Sistema de Ferramentas Modular e Extensível

  • Classe Base de Ferramentas: MCPTool fornece uma interface clara para criar novas ferramentas personalizadas.
  • Registro Centralizado: ToolRegistry torna simples adicionar e gerenciar novas ferramentas.

Exemplos de Uso

Operações Básicas de Arquivo

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

Busca Semântica

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

Análise de Estrutura de Código

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

Implantação e Desenvolvimento

Para instruções detalhadas sobre como executar este servidor, fazer a implantação e como desenvolver e adicionar novas ferramentas, consulte README_deploy.md.

Documentação Relacionada