Servidor MCP - Gerenciador de Arquivos Local (TypeScript)

Este é um projeto de estudo desenvolvido para aprofundamento no Model Context Protocol (MCP). Ele implementa um servidor MCP que permite a clientes de IA (como o Claude Desktop ou outras ferramentas habilitadas com MCP) gerenciar e manipular arquivos de texto em um diretório local seguro configurado via variáveis de ambiente.

O projeto foi construído utilizando Node.js, TypeScript e o SDK oficial da Anthropic (@modelcontextprotocol/sdk).

🛠️ Tecnologias e Dependências

• Runtime: Node.js (v18+)
• Linguagem: TypeScript (transpilado para ES Modules)
• MCP SDK: @modelcontextprotocol/sdk (transporte via Stdio)
• Validação de Dados: zod
• Gerenciamento de Ambiente: dotenv
• Execução em Desenvolvimento: tsx

🚀 Como Iniciar o Projeto

1. Instalar as dependências

Execute o comando abaixo na pasta raiz do projeto:

npm install

2. Configurar as Variáveis de Ambiente

Copie o arquivo .env.example para .env ou crie-o manualmente:

cp .env.example .env

Edite o arquivo .env e configure o caminho absoluto do diretório local que o servidor deve gerenciar:

LOCAL_WORKSPACE_PATH=C:\caminho\completo\para\sua\pasta\workspace

(Nota: O servidor validará a existência deste diretório ao iniciar e lançará um erro se ele não for encontrado).

3. Compilar o Projeto

Para gerar o código JavaScript transpilado pronto para produção:

npm run build

O output será gerado na pasta /dist.

4. Executar

O servidor pode ser executado em dois modos de transporte: Stdio (padrão) ou SSE (Server-Sent Events).

#### Modo Stdio (Padrão) Ideal para integração local com clientes como o Claude Desktop.

npm start
# ou em desenvolvimento
npm run dev

#### Modo SSE (HTTP) Ideal para integração com plataformas como n8n, OpenClaw, ou outros clientes de rede.

Você pode ativar este modo definindo TRANSPORT=sse no arquivo .env, ou passando o argumento --sse na inicialização:

npm start -- --sse
# ou em desenvolvimento
npm run dev -- --sse

Você também pode configurar uma porta customizada usando a variável de ambiente PORT ou passando o argumento --port <numero>:

npm start -- --sse --port 4000

Quando executado em modo SSE, o servidor subirá uma aplicação Express com os seguintes endpoints:

• GET /sse (para iniciar o fluxo de stream de Server-Sent Events)
• POST /messages (para o envio de comandos JSON-RPC do cliente)

🔒 Segurança e Prevenção contra Directory Traversal

Para garantir a integridade dos dados e do sistema host, o servidor MCP implementa um validador de caminho estrito chamado safeResolvePath. Qualquer tentativa de um modelo de IA acessar arquivos fora do diretório especificado em LOCAL_WORKSPACE_PATH (utilizando caminhos relativos como ../../ ou absolutos como C:/Windows) será imediatamente negada pelo servidor com uma mensagem de erro controlada.

🛠️ Ferramentas Disponibilizadas (Tools)

O servidor disponibiliza 7 ferramentas para os clientes de IA realizarem o gerenciamento de arquivos:

1. `list_files`: Lista arquivos e subdiretórios a partir de um relativePath opcional (vazio para a raiz).
2. `download_file`: Lê e retorna o conteúdo em UTF-8 de um arquivo de texto simples especificado pelo relativePath.
3. `upload_file`: Grava ou sobrescreve o conteúdo UTF-8 de um arquivo de texto. Cria subpastas pai automaticamente se não existirem.
4. `get_file_info`: Retorna os metadados detalhados (tamanho, data de criação, data de modificação e status de tipo) de um arquivo ou diretório.
5. `delete_file`: Remove de forma segura um arquivo ou um diretório vazio especificado pelo relativePath.
6. `create_directory`: Cria um novo diretório de forma recursiva dentro da pasta de trabalho.
7. `move_file`: Renomeia ou move arquivos e diretórios dentro do workspace usando caminhos relativos de origem (sourcePath) e destino (destinationPath).

🔍 Como Testar Usando o MCP Inspector

O MCP Inspector é uma ferramenta oficial de testes interativos que simula o comportamento de um cliente MCP via Stdio:

1. Garanta que o projeto esteja compilado (npm run build).
2. Rode o Inspector no terminal do projeto:

    npx @modelcontextprotocol/inspector node dist/index.js

1. Acesse o link gerado no seu terminal (por padrão http://localhost:6274) no navegador para testar interativamente cada uma das ferramentas.

💻 Integração com Claude Desktop

Para utilizar este servidor MCP no aplicativo oficial do Claude Desktop, edite o arquivo de configuração claude_desktop_config.json:

• Caminho no Windows: %APPDATA%\Claude\claude_desktop_config.json
• Caminho no macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Adicione a seguinte entrada dentro de mcpServers:

{
  "mcpServers": {
    "local-file-manager": {
      "command": "node",
      "args": [
        "C:\\Users\\seu-usuario\\Documents\\Pessoal\\my-first-mpc-server\\dist\\index.js"
      ],
      "env": {
        "LOCAL_WORKSPACE_PATH": "C:\\Users\\seu-usuario\\Documents\\Pessoal\\my-first-mpc-server\\workspace"
      }
    }
  }
}

(Lembre-se de ajustar os caminhos absoluto do arquivo `index.js` e do diretório local para os caminhos corretos da sua máquina).