# 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:
```bash
npm install
```

### 2. Configurar as Variáveis de Ambiente
Copie o arquivo `.env.example` para `.env` ou crie-o manualmente:
```bash
cp .env.example .env
```

Edite o arquivo `.env` e configure o caminho absoluto do diretório local que o servidor deve gerenciar:
```env
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:
```bash
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.
```bash
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:
```bash
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>`:
```bash
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:
    ```bash
    npx @modelcontextprotocol/inspector node dist/index.js
    ```
3.  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`:

```json
{
  "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).*