File Explorer MCP

Um servidor para exploração programática de arquivos e pastas locais.

Documentação

File Explorer MCP Server & Client

Este projeto é uma implementação didática de um servidor e cliente que utilizam o protocolo MCP (Multi-Client Protocol) sobre JSON-RPC 2.0 para explorar arquivos e pastas de maneira programática.

O que é este projeto?

file_explorer_server.py: Um servidor que expõe ferramentas ("tools") para listar arquivos e diretórios usando o protocolo MCP. Responde a mensagens JSON-RPC pela entrada/saída padrão (stdio).
file_explorer_client.py: Um cliente simples que se comunica com o servidor, envia solicitações e mostra as respostas.

Como o servidor e o cliente usam MCP?

O servidor (`file_explorer_server.py`)

Implementa o protocolo MCP completo
Expõe ferramentas ("tools") que seguem a especificação MCP
Responde a mensagens JSON-RPC 2.0 com os métodos MCP padrão:
- initialize - Inicialização do servidor
- tools/list - Lista as ferramentas disponíveis
- tools/call - Executa uma ferramenta específica

O cliente (`file_explorer_client.py`)

É um cliente MCP simples e autônomo
Se comunica com o servidor usando o protocolo MCP
Inicia o servidor como subprocesso e se comunica com ele
Não precisa de mcp.json porque gerencia a conexão diretamente

A diferença chave

O cliente é um "cliente MCP completo" que gerencia tudo por si mesmo
Os clientes que precisam de mcp.json são clientes MCP mais avançados (como IDEs) que querem descobrir e conectar com múltiplos servidores MCP de forma automática

Ambos usam MCP, mas o cliente é autossuficiente e não precisa de configuração externa.

Para que serve?

Permite explorar o sistema de arquivos de maneira estruturada e automatizada, usando um protocolo padrão. É útil para aprender sobre:

Comunicação entre processos
Protocolos de mensagens (JSON-RPC)
Automação de tarefas de exploração de arquivos

Como se usa?

1. Requisitos

Python 3.x instalado

2. Execução rápida

Abra um terminal na pasta do projeto e execute:

python3 file_explorer_client.py [ruta/opcional]

Se você não passar nenhum argumento, listará o diretório atual.
Se você passar um caminho como argumento, listará os arquivos e pastas desse caminho.

Exemplos:

python3 file_explorer_client.py

python3 file_explorer_client.py /ruta/que/quieras

Isso fará o seguinte:

Iniciará o servidor como um subprocesso.
Enviará uma solicitação de inicialização (initialize).
Pedirá a lista de ferramentas disponíveis (tools/list).
Usará a ferramenta list_files para listar os arquivos e pastas do diretório indicado (ou o atual se nenhum argumento for passado).
Mostrará todas as respostas na tela em formato JSON.

3. Interpretar os resultados

initialize: Retorna informações sobre o servidor e o protocolo suportado.
tools/list: Mostra as ferramentas disponíveis e os argumentos que aceitam.
tools/call: Executa uma ferramenta (por exemplo, list_files) e retorna o resultado, que pode ser uma lista de arquivos e pastas.

Exemplo de resposta para list_files:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Contents of '.':\n\nDirectories:\n  DIR: .cursor\n\nFiles:\n  FILE: file_explorer_client.py\n  FILE: file_explorer_server.py\n"
      }
    ]
  }
}

Directories: Listagem de pastas (DIR:).
Files: Listagem de arquivos (FILE).

4. Personalização

Você pode modificar o cliente para explorar outros caminhos alterando o argumento de linha de comando ao executá-lo:

python3 file_explorer_client.py otra/carpeta

Como funciona internamente?

O cliente e o servidor se comunicam usando JSON-RPC 2.0 por stdio.
O servidor expõe ferramentas que o cliente pode descobrir e utilizar dinamicamente.
O fluxo é: inicializar → descobrir ferramentas → chamar ferramentas → mostrar resultados.

Configuração MCP com mcp.json

O que é mcp.json?

O arquivo mcp.json é um arquivo de configuração que define os servidores MCP disponíveis para um cliente. Ele está localizado tipicamente em:

macOS/Linux: ~/.cursor/mcp.json
Windows: %APPDATA%\mcp.json

Estrutura do arquivo

{
	"mcpServers": {
	  "file_explorer": {
		"command": "python3",
		"args": ["[ruta-completa]file_explorer/file_explorer_server.py"],
		"env": {}
	  }
	}
  }

Escopo e funcionalidade

Descoberta automática: Os clientes MCP buscam automaticamente este arquivo para encontrar servidores disponíveis.
Configuração centralizada: Permite configurar múltiplos servidores MCP a partir de um único lugar.
Integração com IDEs: Muitos editores de código (VS Code, Cursor, etc.) podem usar esta configuração para integrar ferramentas MCP.
Ferramentas dinâmicas: Uma vez configurado, as ferramentas do servidor estarão disponíveis no IDE sem necessidade de executar manualmente o cliente.

Configuração para este projeto

Para integrar este servidor de exploração de arquivos com um cliente MCP:

Crie ou edite o arquivo ~/.cursor/mcp.json
Adicione a configuração do servidor com o caminho completo para file_explorer_server.py
Reinicie seu IDE ou cliente MCP

Exemplo de configuração completa:

{
	"mcpServers": {
	  "file_explorer": {
		"command": "python3",
		"args": ["[ruta-completa]file_explorer/file_explorer_server.py"],
		"env": {}
	  }
	}
  }

Uma vez configurado, você poderá usar as ferramentas de exploração de arquivos diretamente do seu IDE ou cliente MCP preferido.

File Explorer MCP

Documentação