TrueNAS Middleware MCP Server

Servidor MCP de Middleware de TrueNAS

Este servidor MCP (Protocolo de Contexto de Modelo) proporciona recursos de documentación optimizados del repositorio de middleware de TrueNAS a Code Claude, ayudándole a comprender la estructura del código y las APIs sin sobrecargar el contexto.

Inicio Rápido

1. Para la Integración con Code Claude: Ver INTEGRATION_GUIDE.md
2. Para el Uso en Code Claude: Ver QUICK_REFERENCE.md
3. Para Añadir Documentación: Ver DOCUMENTATION_GUIDE.md
4. Para la Plantilla de Documentación de Plugins: Ver PLUGIN_DOCUMENTATION_TEMPLATE.md
5. Para los Planes de Desarrollo: Ver ACTION_PLAN.md

Características

• Descubre y procesa automáticamente todos los archivos CLAUDE.md en el repositorio de middleware
• Organiza la documentación en categorías lógicas (Visión General, Plugins, API, Pruebas, Subsistemas)
• Proporciona recursos concisos y enfocados para evitar la sobrecarga de contexto
• Implementa resumen inteligente de contenido

Opciones de Configuración

Opción 1: Python Nativo (Recomendado)

1. Crea y activa el entorno virtual:

python3.11 -m venv venv_tn_mcp
source venv_tn_mcp/bin/activate  # On Windows: venv_tn_mcp\Scripts\activate

2. Instala las dependencias:

pip install -r requirements.txt

3. Ejecuta el servidor:

./run_server.sh  # Or: python truenas_mcp_server.py

Opción 2: Contenedor Docker

1. Construye la imagen de Docker:

docker-compose build

2. Ejecuta el servidor:

docker-compose run --rm truenas-mcp

Recursos Disponibles

El servidor proporciona los siguientes tipos de recursos:

Recursos de Visión General

• truenas://overview - Arquitectura de middleware de alto nivel
• truenas://development/guidelines - Mejores prácticas de desarrollo

Recursos de Plugins

• truenas://plugins/service-types - Guía de clases base de servicios
• truenas://plugins/patterns - Patrones comunes de plugins
• truenas://plugins/categories - Lista de plugins categorizada
• truenas://plugins/{plugin_name} - Documentación específica de plugins

Recursos de API

• truenas://api/versioning - Guía de versionado de API
• truenas://api/models - Patrones de modelos Pydantic

Recursos de Pruebas

• truenas://testing/overview - Guía de pruebas
• truenas://testing/patterns - Patrones comunes de pruebas

Recursos de Subsistemas

• truenas://subsystems/{name} - Documentación para subsistemas específicos

Integración con Code Claude

Ver INTEGRATION_GUIDE.md para instrucciones detalladas de configuración.

Configuración Rápida (añadir a claude_desktop_config.json):

{
  "mcpServers": {
    "truenas-docs": {
      "command": "/path/to/venv_tn_mcp/bin/python",
      "args": ["/path/to/tn_mcp/truenas_mcp_server.py"]
    }
  }
}

Cómo Funciona

1. El servidor escanea el repositorio de middleware en busca de todos los archivos CLAUDE.md
2. Cada archivo se procesa y categoriza según su ubicación
3. El contenido se resume inteligentemente para reducir el tamaño del contexto
4. Los recursos se exponen a través del protocolo MCP para que Code Claude los consulte

Estrategia de Optimización

Para evitar la sobrecarga de contexto, el servidor:

• Extrae secciones clave de la documentación
• Limita los ejemplos de código a los esenciales
• Se centra en las firmas de API y patrones en lugar de implementaciones completas
• Agrupa información relacionada en recursos lógicos

Ejecución de Pruebas

Las pruebas se ejecutan usando Docker para garantizar un entorno consistente.

Ejecutar Todas las Pruebas

docker-compose run --rm truenas-mcp-test

Ejecutar un Archivo de Prueba Específico

docker-compose run --rm truenas-mcp-test pytest tests/test_truenas_mcp_tools_server.py -v

Ejecutar con Cobertura

docker-compose run --rm truenas-mcp-test pytest --cov=. --cov-report=html

Ejecución de Pruebas de Middleware

El servidor incluye una herramienta para ejecutar pruebas de middleware de TrueNAS. Usa el script run_middleware_tests.sh:

# Run all middleware tests
./run_middleware_tests.sh

# Run a specific test file
./run_middleware_tests.sh . test_construct_schema.py

# Clean up test container
./run_middleware_tests.sh /path/to/middleware --cleanup