Servidor MCP del sistema de archivos

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

Arquitectura

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

Componentes

Capa de servidor : gestiona la comunicación del protocolo MCP y el envío de herramientas.
Registro de herramientas : administra 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

Clonar el repositorio:

git clone <repository-url>
cd filesystem-server

Instalar dependencias:

npm install

Construir el servidor:

npm run build

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

directorio_de_lista

Enumera 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;
    }[];
}

crear_directorio

Crea un nuevo directorio.

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

Operaciones con archivos

leer_archivo

Lee el contenido de archivos con soporte de codificación.

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

escribir_archivo

Escribe contenido en un archivo.

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

archivo adjunto

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

analizar_texto

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;
}

calcular_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;
}

encontrar_duplicados

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

crear_zip

Crea un archivo ZIP.

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

extraer_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 MCP estándar:

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

Ejecute el conjunto de pruebas:

npm test

Correr con cobertura:

npm run test:coverage

Modo de desarrollo

Ejecutar en modo reloj:

npm run watch

Calidad del código

Pelar el código base:

npm run lint

Comprobación de tipo:

npm run type-check

Dependencias

Dependencias principales:

@modelcontextprotocol/sdk: Implementación del servidor MCP
tipo de archivo: detección del tipo de archivo
mime-types: búsqueda de tipos MIME
crypto-js: Hashing de archivos
archivador: creación de ZIP
extract-zip: extracción ZIP
iconv-lite: Codificación de texto
chardet: Detección de codificación

Dependencias de desarrollo:

mecanografiado: sistema de tipos
broma: Prueba
eslint: Pelusa
Más bonita: Formato
ts-node: ejecución de TypeScript
nodemon: Servidor de desarrollo

Contribuyendo

Bifurcar el repositorio
Crea tu rama de funciones
Escribir pruebas para nuevas funciones
Asegúrese de que todas las pruebas pasen
Enviar una solicitud de extracción

Licencia

Instituto Tecnológico de Massachusetts (MIT)

Filesystem MCP Server

Integrations