# MCP Filesystem Server

Servidor MCP (Model Context Protocol) para operaciones de sistema de archivos. Este servidor implementa el protocolo MCP JSON-RPC y proporciona herramientas para navegar, leer, escribir y gestionar archivos y directorios.

## Características

- Implementación del protocolo MCP JSON-RPC
- 5 herramientas de filesystem:
  - `filesystem_list_directory` - Listar contenido de directorio
  - `filesystem_read_file` - Leer contenido de archivo
  - `filesystem_write_file` - Escribir contenido en archivo
  - `filesystem_create_directory` - Crear directorio
  - `filesystem_delete` - Eliminar archivo o directorio
- Validación de rutas permitidas
- Límite de tamaño de archivo
- Logging de operaciones

## Instalación

```bash
cd mcp-server
npm install
```

## Configuración

Variables de entorno (opcionales):

- `PORT` - Puerto del servidor (default: 3000)
- `ALLOWED_PATHS` - Rutas permitidas separadas por comas (default: /)
- `MAX_FILE_SIZE` - Tamaño máximo de archivo en bytes (default: 10485760 = 10MB)

Ejemplo:
```bash
export PORT=3000
export ALLOWED_PATHS=/,/home/user,/tmp
export MAX_FILE_SIZE=10485760
```

## Desarrollo

```bash
# Compilar TypeScript
npm run build

# Ejecutar en modo desarrollo
npm run dev

# Ejecutar en producción
npm start

# Modo watch para desarrollo
npm run watch
```

## API

### Endpoint Principal

**POST /** - Recibe requests JSON-RPC MCP

Formato de request:
```json
{
  "jsonrpc": "2.0",
  "method": "filesystem_list_directory",
  "params": {
    "path": "/"
  },
  "id": 1
}
```

Formato de response:
```json
{
  "jsonrpc": "2.0",
  "result": {
    "path": "/",
    "items": [
      {
        "name": "file.txt",
        "path": "/file.txt",
        "type": "file",
        "size": 1024,
        "modifiedDate": "2024-01-01T00:00:00.000Z"
      }
    ]
  },
  "id": 1
}
```

### Health Check

**GET /health** - Verifica estado del servidor

Response:
```json
{
  "status": "ok",
  "timestamp": "2024-01-01T00:00:00.000Z"
}
```

## Herramientas MCP

### filesystem_list_directory

Lista el contenido de un directorio.

**Parámetros:**
- `path` (string) - Ruta del directorio

**Response:**
- `path` (string) - Ruta del directorio
- `items` (array) - Lista de archivos y directorios
  - `name` (string) - Nombre del archivo/directorio
  - `path` (string) - Ruta completa
  - `type` (string) - "file" o "directory"
  - `size` (number) - Tamaño en bytes
  - `modifiedDate` (string) - Fecha de modificación ISO 8601

### filesystem_read_file

Lee el contenido de un archivo.

**Parámetros:**
- `path` (string) - Ruta del archivo

**Response:**
- `path` (string) - Ruta del archivo
- `content` (string) - Contenido del archivo

### filesystem_write_file

Escribe contenido en un archivo.

**Parámetros:**
- `path` (string) - Ruta del archivo
- `content` (string) - Contenido a escribir

**Response:**
- `path` (string) - Ruta del archivo
- `success` (boolean) - Indica si la operación fue exitosa

### filesystem_create_directory

Crea un directorio.

**Parámetros:**
- `path` (string) - Ruta del directorio

**Response:**
- `path` (string) - Ruta del directorio
- `success` (boolean) - Indica si la operación fue exitosa

### filesystem_delete

Elimina un archivo o directorio.

**Parámetros:**
- `path` (string) - Ruta del archivo/directorio

**Response:**
- `path` (string) - Ruta del archivo/directorio
- `success` (boolean) - Indica si la operación fue exitosa

## Seguridad

- Validación de rutas permitidas
- Límite de tamaño de archivo
- Solo se permiten rutas dentro de los directorios configurados en `ALLOWED_PATHS`

## Estructura del Proyecto

```
mcp-server/
├── src/
│   ├── handlers/
│   │   └── filesystem.handler.ts  # Implementación de operaciones de filesystem
│   ├── types/
│   │   ├── mcp.types.ts           # Tipos MCP generales
│   │   └── filesystem.types.ts    # Tipos específicos de filesystem
│   ├── config.ts                  # Configuración del servidor
│   ├── server.ts                  # Servidor MCP principal
│   └── index.ts                   # Punto de entrada
├── package.json
├── tsconfig.json
└── README.md
```

## Licencia

MIT