Filesystem MCP Server

Servidor MCP de Sistema de Archivos

Una implementación de servidor de Protocolo de Contexto de Modelo (MCP) que proporciona operaciones de sistema de archivos, análisis y manipulación a través de una interfaz de herramientas estandarizada.

Arquitectura

El servidor está construido sobre el SDK de MCP y organizado en capas distintas:

graph TD
    A[MCP Server Layer] --> B[Tool Registry]
    B --> C[Operations Layer]
    C --> D[File System Operations]
    C --> E[Analysis Operations]
    C --> F[Stream Operations]

Componentes

• Capa de Servidor: Maneja la comunicación del protocolo MCP y el despacho de herramientas
• Registro de Herramientas: Gestiona el registro y la ejecución de herramientas
• Capa de Operaciones: Implementa la funcionalidad principal
• Interfaz del Sistema de Archivos: Proporciona acceso seguro al sistema de archivos

Instalación

1. Clonar el repositorio:

git clone <repository-url>
cd filesystem-server

2. Instalar dependencias:

npm install

3. Compilar el servidor:

npm run build

4. Configurar los ajustes de MCP (cline_mcp_settings.json):

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": ["path/to/filesystem-server/build/index.js"]
    }
  }
}

Referencia de Herramientas

Operaciones de Directorio

list_directory

Lista el contenido del directorio con metadatos.

interface ListDirectoryParams {
    path: string;       // Directory path
    recursive?: boolean; // List recursively (default: false)
}

interface ListDirectoryResult {
    entries: {
        name: string;
        path: string;
        isDirectory: boolean;
        size: number;
        created: string;
        modified: string;
        accessed: string;
        mode: string;
    }[];
}

create_directory

Crea un nuevo directorio.

interface CreateDirectoryParams {
    path: string;       // Directory path
    recursive?: boolean; // Create parent directories (default: true)
}

Operaciones de Archivo

read_file

Lee el contenido del archivo con soporte de codificación.

interface ReadFileParams {
    path: string;     // File path
    encoding?: string; // File encoding (default: 'utf8')
}

write_file

Escribe contenido en un archivo.

interface WriteFileParams {
    path: string;     // File path
    content: string;  // Content to write
    encoding?: string; // File encoding (default: 'utf8')
}

append_file

Añade contenido a un archivo.

interface AppendFileParams {
    path: string;     // File path
    content: string;  // Content to append
    encoding?: string; // File encoding (default: 'utf8')
}

Operaciones de Análisis

analyze_text

Analiza las propiedades de archivos de texto.

interface AnalyzeTextParams {
    path: string; // File path
}

interface AnalyzeTextResult {
    lineCount: number;
    wordCount: number;
    charCount: number;
    encoding: string;
    mimeType: string;
}

calculate_hash

Calcula el hash del archivo utilizando el algoritmo especificado.

interface CalculateHashParams {
    path: string;           // File path
    algorithm?: 'md5' | 'sha1' | 'sha256' | 'sha512'; // Hash algorithm
}

interface CalculateHashResult {
    hash: string;
    algorithm: string;
}

find_duplicates

Identifica archivos duplicados en un directorio.

interface FindDuplicatesParams {
    path: string; // Directory path
}

interface FindDuplicatesResult {
    duplicates: {
        hash: string;
        size: number;
        files: string[];
    }[];
}

Operaciones de Compresión

create_zip

Crea un archivo ZIP.

interface CreateZipParams {
    files: string[];  // Files to include
    output: string;   // Output ZIP path
}

extract_zip

Extrae un archivo ZIP.

interface ExtractZipParams {
    path: string;    // ZIP file path
    output: string;  // Output directory
}

Manejo de Errores

El servidor utiliza códigos de error estándar de MCP:

enum ErrorCode {
    ParseError = -32700,
    InvalidRequest = -32600,
    MethodNotFound = -32601,
    InvalidParams = -32602,
    InternalError = -32603
}

Las respuestas de error incluyen:

• Código de error
• Mensaje legible para humanos
• Contexto adicional cuando esté disponible

Ejemplo de error:

{
    "code": -32602,
    "message": "File not found: /path/to/file.txt"
}

Desarrollo

Estructura del Proyecto

src/
├── operations/     # Core operations implementation
├── tools/         # MCP tool definitions and handlers
├── __tests__/     # Test suites
├── index.ts       # Entry point
├── server.ts      # MCP server setup
├── types.ts       # Type definitions
└── utils.ts       # Utility functions

Ejecución de Pruebas

Ejecutar el conjunto de pruebas:

npm test

Ejecutar con cobertura:

npm run test:coverage

Modo de Desarrollo

Ejecutar en modo de observación:

npm run watch

Calidad del Código

Ejecutar lint en el código:

npm run lint

Verificación de tipos:

npm run type-check

Dependencias

Dependencias principales:

• @modelcontextprotocol/sdk: Implementación del servidor MCP
• file-type: Detección de tipo de archivo
• mime-types: Búsqueda de tipos MIME
• crypto-js: Hash de archivos
• archiver: Creación de ZIP
• extract-zip: Extracción de ZIP
• iconv-lite: Codificación de texto
• chardet: Detección de codificación

Dependencias de desarrollo:

• typescript: Sistema de tipos
• jest: Pruebas
• eslint: Linting
• prettier: Formateo
• ts-node: Ejecución de TypeScript
• nodemon: Servidor de desarrollo

Contribuciones

1. Hacer un fork del repositorio
2. Crear tu rama de características
3. Escribir pruebas para nuevas características
4. Asegurar que todas las pruebas pasen
5. Enviar una solicitud de extracción

Licencia

MIT