Procesador de contexto de modelo (MCP) de contexto de archivo

insignia de herrería

Descripción general

File Context MCP es una aplicación basada en TypeScript que proporciona una API para consultar Modelos de Lenguaje Grandes (LLM) con contexto de archivos locales. Es compatible con múltiples proveedores de LLM (Ollama y Together.ai) y puede procesar diversos tipos de archivos para generar respuestas contextuales.

Related MCP server: MemGPT MCP Server

Características principales

1. Navegación por el sistema de archivos

Recorrido dinámico de archivos y directorios
Soporte para múltiples tipos de archivos ( .txt , .md , .ts , .json , etc.)
Manejo seguro de caminos con sanitización

import path from 'path';

export const fileUtils = {
  isTextFile(filePath: string): boolean {
    const textExtensions = [
      '.txt', '.md', '.js', '.ts', '.json', '.yaml', '.yml', 
      '.html', '.css', '.csv', '.xml', '.log', '.env',
      '.jsx', '.tsx', '.py', '.java', '.cpp', '.c', '.h'
    ];
    return textExtensions.includes(path.extname(filePath).toLowerCase());
  },

2. Procesamiento del contexto

Formato de contexto inteligente para consultas LLM
Truncamiento de contexto para manejar archivos grandes
Agregación de contenido de archivos para consultas de directorio

export const promptUtils = {
    formatContextPrompt(context: string, query: string): string {
      return `
  You are an AI assistant analyzing the following content:
  
  ---BEGIN CONTEXT---
  ${context}
  ---END CONTEXT---
  
  Please respond to the following query:
  ${query}
  
  Base your response only on the information provided in the context above.
  `;
    },
  
    truncateContext(context: string, maxLength: number = 4000): string {
      if (context.length <= maxLength) return context;
      
      // Try to truncate at a natural break point
      const truncated = context.slice(0, maxLength);
      const lastNewline = truncated.lastIndexOf('\n');
      
      if (lastNewline > maxLength * 0.8) {
        return truncated.slice(0, lastNewline) + '\n... (truncated)';
      }
      
      return truncated + '... (truncated)';
    }
  };

3. Soporte multimodelo

Integración de Ollama (local)
Integración de Together.ai (nube)
Diseño de interfaz de modelo extensible

export interface LLMResponse {
  text: string;
  model: string;
  error?: string;
}

export class ModelInterface {
  async queryOllama(prompt: string, context: string): Promise<LLMResponse> {
    try {
      const response = await axios.post(`${config.ollamaBaseUrl}/api/generate`, {
        model: config.modelName,
        prompt: this.formatPrompt(prompt, context),
        stream: false
      });
      return {
      if (!response.data || !response.data.response) {
        throw new Error('Invalid response from Ollama');
      }
    } catch (error) {
      return {
        text: response.data.response,
        model: 'ollama'
      };
    } catch (error) {
      console.error('Ollama error:', error);
      return {
        text: '',
        model: 'ollama',
        error: error instanceof Error ? error.message : 'Unknown error'
      };
    }
  }
          model: config.modelName,
  async queryTogether(prompt: string, context: string): Promise<LLMResponse> {
    try {
      const response = await axios.post(
        'https://api.together.xyz/inference',
        {
          model: config.modelName,
          prompt: this.formatPrompt(prompt, context),
          max_tokens: 512,
        },
        {
          headers: {
            Authorization: `Bearer ${config.togetherApiKey}`
          }
        }
      );
      return {
      return {
        text: response.data.output.text,
        model: 'together'
      };
    } catch (error) {
      return {
        text: '',
        model: 'together',
        error: error instanceof Error ? error.message : 'Unknown error'
      };
    }
  }
  private formatPrompt(prompt: string, context: string): string {
    return `Context: ${context}\n\nQuestion: ${prompt}`;
  }
}

Arquitectura

Componentes principales

Servidor (server.ts)
- Implementación de la API REST de Express.js
- Manejo de carga/eliminación de archivos con multer
- Validación y enrutamiento de solicitudes
- Integración de OpenAPI/Swagger
Herramientas del sistema de archivos (core/fileSystem.ts)
- Operaciones con archivos y directorios
- Lectura y análisis de contenido
- Recorrido de directorios
- Eliminación segura de archivos
- Manejo de errores en operaciones con archivos
Interfaz del modelo (core/modelInterface.ts)
- Compatibilidad con varios proveedores de LLM (Ollama, Together.ai)
- Formato de respuesta y manejo de errores
- Parámetros del modelo configurables
- Interfaz de consulta unificada
Módulos de utilidad
- fileUtils : detección de tipo de archivo, saneamiento de ruta, formato de tamaño
- promptUtils : Formato de contexto, truncamiento inteligente
- validators : validación de rutas, consultas y modelos
- logger : Registro estructurado con niveles
Configuración (config/config.ts)
- Gestión de variables ambientales
- Claves API y puntos finales
- Configuración del modelo
- Configuración del servidor
Especificación de API (recursos/file-context-api.yml)
- Documentación de OpenAPI 3.0
- Esquemas de solicitud/respuesta
- Documentación de puntos finales
- Definiciones de respuesta de error

Puntos finales de API

1. Lista de archivos

GET /api/files
Query params:
  - path: string (optional, defaults to './')
Response:
  - Array of FileInfo objects with file/directory details

2. Subir archivo

POST /api/files/upload
Content-Type: multipart/form-data
Body:
  - file: File (must be a text file, max 5MB)
Response:
{
  "message": "File uploaded successfully",
  "file": {
    "name": string,
    "size": string,
    "path": string
  }
}

3. Eliminar archivo

DELETE /api/files/{filename}
Params:
  - filename: string (name of file to delete)
Response:
{
  "message": "File deleted successfully"
}

4. Consulta con contexto

POST /api/query
Body:
{
  "path": string,
  "query": string,
  "model": "ollama" | "together"
}
Response:
{
  "text": string,
  "model": string,
  "error?: string
}

Configuración y configuración

Variables de entorno

TOGETHER_API_KEY=your_api_key_here
OLLAMA_BASE_URL=http://localhost:11434
MODEL_NAME=llama2
PORT=3001

Instalación

npm install

Instalación mediante herrería

Para instalar File Context MCP para Claude Desktop automáticamente a través de Smithery :

npx @smithery/cli@latest install @compiledwithproblems/file-context-mcp --client claude

Ejecutar la aplicación

# Development
npm run dev

# Production
npm run build
npm start

Cómo funciona

Flujo de procesamiento de archivos
- Solicitud recibida → Validación de ruta → Lectura de archivo → Extracción de contenido
- El manejo de directorios incluye la lectura recursiva de archivos
- Filtrado de contenido según el tipo de archivo
- Las cargas de archivos se validan por tipo y tamaño.
- Eliminación segura de archivos con validación de ruta
Procesamiento de contexto
- El contenido del archivo se agrega
- El contexto está formateado con límites claros
- Los contextos grandes se truncan de forma inteligente
- El formato de las indicaciones añade estructura para la comprensión del LLM
Integración de modelos
- Interfaz unificada para diferentes proveedores de LLM
- Manejo de errores y normalización de respuestas
- Parámetros del modelo configurables

Características de seguridad

Saneamiento de caminos
- Prevención de ataques de cruce de directorios
- Validación y normalización de rutas
- Comprobación segura del tipo de archivo
Seguridad de carga de archivos
- Validación del tipo de archivo
- Límites de tamaño de archivo (5 MB máximo)
- Almacenamiento seguro de archivos
- Eliminación segura de archivos
Validación de entrada
- Validación del contenido de la consulta
- Verificación del tipo de modelo
- Verificación de la estructura de la ruta
- Validación del contenido del archivo

Tipos de archivos admitidos

La aplicación admite los siguientes tipos de archivos basados en texto:

Documentación: .txt , .md
Archivos de código: .js , .ts , .jsx , .tsx , .py , .java , .cpp , .c , .h
Configuración: .json , .yaml , .yml , .env
Archivos web: .html , .css
Archivos de datos: .csv , .xml , .log

La validación del tipo de archivo se aplica durante:

Subidas de archivos
Procesamiento del contexto
Operaciones de lectura de archivos

Tamaño máximo de archivo: 5 MB por archivo

Manejo de errores

La aplicación implementa un manejo integral de errores:

Errores del sistema de archivos
Errores de respuesta de la API
Errores de entrada no válida
Errores específicos del modelo
Errores de carga/eliminación de archivos

Desarrollo

Estructura del proyecto

file-context-mcp/
├── src/
│   ├── server.ts              # Main application server
│   ├── core/                  # Core functionality
│   │   ├── fileSystem.ts      # File operations handling
│   │   └── modelInterface.ts  # LLM provider integrations
│   ├── utils/                 # Utility functions
│   │   ├── fileUtils.ts       # File type & path utilities
│   │   ├── promptUtils.ts     # Prompt formatting
│   │   ├── validators.ts      # Input validation
│   │   └── logger.ts         # Application logging
│   ├── config/               # Configuration
│   │   └── config.ts        # Environment & app config
│   └── resources/           # API specifications
│       └── file-context-api.yml  # OpenAPI spec
├── storage/                 # File storage directory
│   ├── code-samples/       # Example code files
│   └── notes/             # Documentation & notes
├── postman/               # API testing
│   └── File-Context-MCP.postman_collection.json  # Postman collection
├── dist/                  # Compiled output
└── node_modules/         # Dependencies

Añadiendo nuevas funciones

Nuevos tipos de archivos
- Agregar extensiones a fileUtils.isTextFile()
- Implementar controladores específicos si es necesario
Nuevos proveedores de modelos
- Extender la clase ModelInterface
- Agregar proveedor a validators.isValidModel()
- Implementar el manejo de errores específico del proveedor

Pruebas

Colección del Cartero

El proyecto incluye una colección de Postman ( postman/File-Context-MCP.postman_collection.json ) para probar todos los endpoints de la API. Para usarla:

Importar la colección
- Cartero abierto
- Haga clic en el botón "Importar"
- Seleccione o arrastre el File-Context-MCP.postman_collection.json

Solicitudes disponibles

File-Context-MCP
├── List files
│   └── GET http://localhost:3001/api/files?path=./storage
├── Query
│   └── POST http://localhost:3001/api/query (single file analysis)
├── Analyze multiple files
│   └── POST http://localhost:3001/api/query (directory analysis)
└── File Upload
    └── POST http://localhost:3001/api/files/upload

Prueba de operaciones de archivos
- Lista de archivos : ver el contenido del directorio de almacenamiento
- Subir archivo : utilice form-data con la clave "archivo" y seleccione un archivo de texto
- Consulta de archivos : Analice el contenido de un solo archivo con LLM
- Analizar directorio : procesar múltiples archivos con LLM

Consultas de ejemplo

// Single file analysis
{
    "path": "./storage/code-samples/example.ts",
    "query": "Explain what this TypeScript code does",
    "model": "ollama"
}

// Directory analysis
{
    "path": "./storage",
    "query": "What types of files are in this directory and summarize their contents?",
    "model": "ollama"
}

Guía de carga de archivos
- Utilice la solicitud "Carga de archivos"
- Seleccione "form-data" en la pestaña Cuerpo
- Agregar clave "archivo" con tipo "Archivo"
- Elija un archivo de texto compatible (consulte Tipos de archivos compatibles)
- Tamaño máximo de archivo: 5 MB

Pruebas manuales

Utilice los archivos de prueba proporcionados en /storage
Pruebe diferentes tipos de archivos y consultas
Verificar las respuestas del modelo y el manejo de errores
Límites de tamaño de archivo de prueba y restricciones de tipo

Configuración del entorno

Asegúrese de:

Tener el servidor en ejecución ( npm run dev )
Configurar variables de entorno
Tener Ollama ejecutándose localmente (para el modelo Ollama)
Establecer la clave API de Together.ai (para el modelo Together)

Consideraciones futuras

Cómo gestionar archivos grandes de forma eficiente
Ampliación de los tipos de archivos admitidos
Optimización del procesamiento del contexto
Agregar soporte de transmisión para las respuestas
Implementación de limitación de velocidad y almacenamiento en caché

Este proyecto demuestra prácticas modernas de TypeScript/Node.js con un enfoque en la modularidad, la seguridad de tipos y el manejo de errores, al tiempo que proporciona una interfaz flexible para las interacciones LLM con el contexto basado en archivos.

File Context MCP