oclif MCP Server Plugin

Un plugin de CLI oclif que descubre y sirve automáticamente comandos a través del Protocolo de Contexto de Modelo (MCP).

GitHub

Prueba este MCPPatrocinado

Documentación

🔌 oclif-plugin-mcp-server

Transforma cualquier CLI de oclif en un servidor totalmente compatible con MCP 2025-06-18 para una integración perfecta con asistentes de IA

Este plugin convierte automáticamente los comandos de tu CLI de oclif en un servidor totalmente compatible con el protocolo MCP 2025-06-18, implementando la última especificación del Model Context Protocol. Permite que asistentes de IA como Claude, ChatGPT y Cursor descubran y ejecuten tus herramientas CLI de forma natural a través de conversaciones.

✨ Novedades en MCP 2025-06-18

🎉 Última especificación MCP: Cumplimiento total con MCP 2025-06-18, incluyendo:

🔒 Autorización OAuth 2.1: Soporte completo de OAuth 2.1 con PKCE para transporte HTTP seguro
🔄 Capacidad de muestreo: Solicitudes de interacción LLM del lado del servidor para flujos de IA avanzados
❓ Soporte de elicitación: Solicita información adicional y confirmaciones del usuario a los clientes
📝 Registro estructurado: Capacidad de registro avanzada con gestión de niveles y notificaciones
⏳ Seguimiento de progreso: Seguimiento de progreso mejorado con soporte de cancelación
🌐 Encabezados de versión de protocolo: Soporte completo de encabezados MCP-Protocol-Version: 2025-06-18
🛡️ Seguridad mejorada: Indicadores de recursos (RFC 8707) y flujos de autorización mejorados

¿Qué es MCP?

El Protocolo de Contexto de Modelo (MCP) es un estándar abierto que permite a los asistentes de IA conectarse de forma segura a fuentes de datos y herramientas externas. Con MCP, tu CLI se convierte en un ciudadano de primera clase en los flujos de trabajo de IA, permitiendo a los asistentes:

🔍 Descubrir tus comandos y recursos automáticamente
✅ Validar entradas usando esquemas con seguridad de tipos
🚀 Ejecutar comandos con manejo de errores adecuado
📊 Acceder a recursos con carga diferida y metadatos apropiados
🔒 Asegurar interacciones mediante protocolos estandarizados

🚀 Características

Capacidades principales de MCP 2025-06-18

🔍 Auto-descubrimiento: Descubre y expone automáticamente los comandos de oclif como herramientas MCP
📝 Generación de esquemas: Convierte argumentos y banderas de oclif a esquemas Zod para ejecución con seguridad de tipos
📊 Recursos compatibles con MCP: Soporte completo para recursos estáticos y dinámicos según la especificación MCP
🎯 Plantillas de prompts: Plantillas de prompts reutilizables con validación de argumentos y manejadores
🌳 Raíces de espacio de trabajo: Registro automático del directorio de trabajo del CLI como raíz MCP
🔄 Carga diferida: Los recursos se obtienen bajo demanda a través de endpoints MCP adecuados
🛡️ Manejo de errores: Manejo de errores elegante con retroalimentación detallada y códigos de error JSON-RPC apropiados
⚙️ Configuración cero: Funciona de inmediato con cualquier CLI de oclif
📋 Cumplimiento de estándares: Implementa la especificación oficial MCP 2025-06-18
✅ Validación de entradas: Validación de argumentos con seguridad de tipos para todos los comandos y prompts
🔔 Notificaciones inteligentes: Notificaciones de cambios de recursos con debounce para rendimiento óptimo

Nuevo en MCP 2025-06-18

🔒 Seguridad OAuth 2.1: Integración completa del servidor de autorización OAuth 2.1 con soporte PKCE
🔄 Soporte de muestreo: Capacidad del lado del servidor para solicitudes de interacción LLM
❓ Marco de elicitación: Solicita entradas y confirmaciones del usuario a través del cliente
📝 Registro estructurado: Registro avanzado con gestión de niveles y notificaciones al cliente
⏳ Seguimiento de progreso: Tokens de progreso mejorados con soporte de cancelación
🌐 Encabezados de protocolo: Manejo adecuado de encabezados MCP-Protocol-Version: 2025-06-18
🛡️ Autorización mejorada: Indicadores de recursos (RFC 8707) para uso seguro de tokens
🔐 Gestión de sesiones: Manejo avanzado de sesiones HTTP con limpieza y monitoreo

📦 Instalación

Incrustar el plugin en el código de tu CLI (Recomendado)

Añade a package.json de tu CLI:

{
  "dependencies": {
    "oclif-plugin-mcp-server": "latest"
  },
  "oclif": {
    "plugins": ["oclif-plugin-mcp-server"]
  }
}

Desde GitHub

# Install directly from GitHub (requires oclif-plugin-plugins)
your-cli plugins install npjonath/oclif-plugin-mcp-server

# Verify installation
your-cli mcp --help

🎯 Inicio rápido

1. Configurar el asistente de IA

Añade tu CLI a la configuración MCP de tu asistente de IA:

Cursor (mcp.json)

{
  "mcpServers": {
    "your-cli": {
      "command": "your-cli",
      "args": ["mcp"],
      "env": {}
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "your-cli": {
      "command": "your-cli",
      "args": ["mcp"]
    }
  }
}

Para desarrollo local con este plugin

Compila tu CLI: yarn build
Genera el manifiesto: npx oclif manifest
Actualiza tu configuración MCP:

Transporte Stdio (predeterminado):

{
  "mcpServers": {
    "your-cli-dev": {
      "command": "node <path_to_project_folder>/bin/dev.js",
      "args": ["mcp"]
    }
  }
}

Transporte HTTP:

{
  "mcpServers": {
    "your-cli-dev-http": {
      "command": "node <path_to_project_folder>/bin/dev.js",
      "args": ["mcp", "--transport", "http", "--port", "3000"]
    }
  }
}

2. Comienza a chatear

Tu asistente de IA ahora puede descubrir y usar los comandos y recursos de tu CLI:

👤 "Deploy my-app to staging and show me the deployment logs"
🤖 "I'll deploy your application to staging and fetch the deployment logs."

   Executing: deploy my-app --environment staging
   ✅ Deploying my-app to staging

   Fetching resource: logs://deployment/my-app
   📊 Deployment completed successfully!
   🔍 Logs: [deployment details...]

🌐 Protocolos de transporte

Este plugin soporta ambos protocolos de transporte MCP según la especificación oficial:

📡 Entrada/Salida estándar (stdio) - Predeterminado

El transporte predeterminado para integraciones locales y herramientas de línea de comandos.

# Start MCP server with stdio transport (default)
your-cli mcp
your-cli mcp --transport stdio

Perfecto para:

Integraciones locales (Claude Desktop, Cursor)
Herramientas de línea de comandos
Comunicación simple entre procesos
Scripts de shell

🌐 Transporte HTTP Streamable

Transporte basado en HTTP con Eventos Enviados por el Servidor (SSE) para integraciones web.

# Start MCP server with HTTP transport
your-cli mcp --transport http --port 3000 --host 127.0.0.1

Perfecto para:

Integraciones basadas en web
Comunicación cliente-servidor sobre HTTP
Sesiones con estado
Múltiples clientes concurrentes
Conexiones reanudables
Contenedores Docker

Características del transporte HTTP

JSON-RPC sobre HTTP: Comunicación cliente-servidor mediante solicitudes POST
Eventos Enviados por el Servidor (SSE): Comunicación servidor-cliente mediante solicitudes GET
Gestión de sesiones: Sesiones con estado con encabezados X-Session-Id
Encabezados de protocolo: MCP-Protocol-Version: 2025-06-18 en todas las respuestas
Integración OAuth 2.1: Autorización segura con soporte PKCE
Reanudabilidad: IDs de eventos y soporte de encabezado Last-Event-ID
Soporte CORS: Intercambio de recursos entre orígenes configurable con controles de seguridad
Verificación de salud: Endpoint /health para monitoreo con versión de protocolo

Endpoints HTTP

POST / - Solicitudes JSON-RPC (cliente a servidor)
GET /events/:sessionId - Flujos SSE (servidor a cliente)
DELETE /sessions/:sessionId - Terminación de sesión
GET /health - Verificación de salud con versión de protocolo
GET /oauth/authorize - Endpoint de autorización OAuth 2.1 (si está configurado)
GET /oauth/callback - Endpoint de devolución de llamada OAuth 2.1 (si está configurado)

Ejemplos de transporte HTTP

# List available tools
curl -X POST http://localhost:3000/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Call a tool
curl -X POST http://localhost:3000/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"your-command","arguments":{"arg":"value"}},"id":2}'

# Subscribe to SSE stream for session updates
curl -N http://localhost:3000/events/your-session-id \
  -H "Accept: text/event-stream"

# Health check with protocol version
curl http://localhost:3000/health
# Response: {"status":"ok"} with MCP-Protocol-Version: 2025-06-18 header

# OAuth authorization flow (if configured)
curl http://localhost:3000/oauth/authorize?session_id=your-session

Integración con cliente web

// Initialize HTTP MCP client with 2025-06-18 support
const client = new MCPClient({
  transport: 'http',
  endpoint: 'http://localhost:3000/',
  protocolVersion: '2025-06-18',
  // Optional OAuth configuration
  oauth: {
    authorizationUrl: 'http://localhost:3000/oauth/authorize',
    callbackUrl: 'http://localhost:3000/oauth/callback',
  },
})

await client.connect()
const tools = await client.listTools()

Guía de selección de transporte

Caso de uso	Transporte recomendado	Razón
Integración CLI local	`stdio`	Comunicación simple y directa entre procesos
Extensiones de VS Code	`stdio`	Estándar para integraciones de escritorio
Claude Desktop	`stdio`	Estándar para integraciones de escritorio
IDE Cursor	`stdio`	Estándar para integraciones de escritorio
Aplicaciones web	`http`	Funciona sobre red, soporta múltiples clientes
Contenedores Docker	`http`	Mejor para despliegues contenedorizados
Desarrollo/depuración	`http`	Fácil de probar con curl/navegador
Servidores de producción	`http`	Escalable, soporta balanceo de carga
Pipelines CI/CD	`http`	Mejor para entornos automatizados

🔒 Consideraciones de seguridad

Este plugin expone los comandos de tu CLI a asistentes de IA a través del protocolo MCP. La última especificación 2025-06-18 incluye características de seguridad mejoradas:

Seguridad mejorada en MCP 2025-06-18

🔒 Autorización OAuth 2.1: Implementación completa de OAuth 2.1 con soporte PKCE
🛡️ Indicadores de recursos: Cumplimiento de RFC 8707 para acceso seguro a recursos
🔐 Gestión de sesiones: Manejo avanzado de sesiones HTTP con limpieza automática
🌐 Protección CORS: Controles mejorados entre orígenes con validación de origen
📋 Encabezados de protocolo: Negociación de versión adecuada y encabezados de seguridad

Límites de confianza

Desarrollo local: Cuando se ejecuta localmente, el plugin opera en el contexto de tu usuario con tus permisos
Uso en producción: Solo expone comandos que sean seguros para que los ejecuten los asistentes de IA
Transporte HTTP: Usa OAuth 2.1 para acceso remoto seguro con flujos de autorización adecuados
Operaciones sensibles: Usa la bandera disableMCP para comandos que realizan operaciones sensibles

Seguridad de comandos

export default class SensitiveCommand extends Command {
  static description = 'This command performs sensitive operations'
  static disableMCP = true // 🔒 Exclude from MCP exposure

  async run() {
    // Sensitive operations that shouldn't be exposed to AI
  }
}

Configuración de OAuth 2.1

// Configure OAuth for secure HTTP transport
const oauthConfig = {
  authorizationServer: 'https://your-auth-server.com',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret', // Optional for public clients
  tokenEndpoint: 'https://your-auth-server.com/token',
  scope: 'mcp:read mcp:write',
}

Prácticas recomendadas

✅ Revisa los comandos expuestos antes del despliegue
✅ Usa OAuth 2.1 para despliegues HTTP de producción
✅ Implementa indicadores de recursos para un alcance seguro de tokens
✅ Usa anotaciones de herramientas para marcar claramente operaciones destructivas
✅ Implementa validación adecuada en tus manejadores de comandos
✅ Monitorea el uso de MCP en entornos de producción
✅ Configura CORS adecuadamente para integraciones web
⚠️ Evita exponer comandos que modifiquen configuraciones a nivel de sistema
⚠️ Ten precaución con operaciones de archivos que puedan afectar datos sensibles
⚠️ Usa HTTPS para todos los despliegues de transporte HTTP en producción

⚖️ Límites de herramientas de proveedores de IA

Diferentes proveedores de IA tienen límites variables en la cantidad de herramientas que pueden manejar de manera efectiva:

Proveedor	Límite de herramientas	Notas
VS Code	128 herramientas	Límite estricto impuesto por la plataforma
Cursor	40 herramientas	Límite estricto impuesto por la plataforma
Claude Desktop	desconocido	Varía según el modelo y nivel de suscripción
ChatGPT	desconocido	Varía según el modelo y nivel de suscripción
GitHub Copilot	desconocido	Varía según el modelo y nivel de suscripción

Configuración de filtrado de comandos

Para gestionar CLIs grandes con muchos comandos, puedes configurar el filtrado para mantenerse dentro de estos límites:

Filtrado básico por tema

{
  "oclif": {
    "mcp": {
      "toolLimits": {
        "maxTools": 40,
        "warnThreshold": 35
      },
      "topics": {
        "include": ["auth", "deploy", "config"],
        "exclude": ["debug", "internal", "experimental"]
      }
    }
  }
}

Filtrado avanzado por patrones

{
  "oclif": {
    "mcp": {
      "toolLimits": {
        "maxTools": 80,
        "strategy": "prioritize"
      },
      "commands": {
        "include": ["auth:*", "deploy:*", "config:get", "config:set", "status", "logs:*"],
        "exclude": ["*:debug", "internal:*", "test:*", "*:experimental"],
        "priority": ["auth:login", "deploy:production", "status", "logs:tail"]
      }
    }
  }
}

Configuración basada en entorno

{
  "oclif": {
    "mcp": {
      "profiles": {
        "development": {
          "maxTools": 128,
          "topics": {
            "include": ["*"]
          }
        },
        "production": {
          "maxTools": 40,
          "topics": {
            "include": ["auth", "deploy", "config", "status", "logs"],
            "exclude": ["debug", "test", "internal"]
          }
        },
        "minimal": {
          "maxTools": 20,
          "commands": {
            "include": ["auth:login", "auth:logout", "deploy:production", "status", "logs:tail"]
          }
        }
      },
      "defaultProfile": "production"
    }
  }
}

Configuración en tiempo de ejecución

También puedes configurar el filtrado en tiempo de ejecución:

# Use a specific profile
your-cli mcp --profile minimal

# Override max tools
your-cli mcp --max-tools 50

# Include specific topics only
your-cli mcp --include-topics auth,deploy,config

# Exclude specific patterns
your-cli mcp --exclude-patterns "*:debug,test:*,internal:*"

Estrategias de filtrado

first - Incluye los primeros N comandos hasta el límite
prioritize - Incluye primero los comandos prioritarios, luego otros hasta el límite
balanced - Intenta incluir comandos de todos los temas proporcionalmente
strict - Falla si los comandos filtrados exceden el límite

Sugerencias automáticas

Cuando los comandos se filtran debido a límites, el plugin registrará sugerencias:

⚠️  Filtered out 45 commands due to tool limit (40)
💡 Consider using topic filtering: --include-topics auth,deploy
💡 Or increase limit for your AI provider: --max-tools 80
🔍 See filtered commands: your-cli mcp --show-filtered

📚 Uso avanzado

IDs de herramientas personalizados

Anula la generación predeterminada de IDs de herramientas:

export default class MyCommand extends Command {
  static toolId = 'custom-tool-name' // Custom MCP tool identifier
}

Anotaciones de herramientas

Añade anotaciones de herramientas compatibles con MCP para proporcionar a los asistentes de IA metadatos sobre el comportamiento de tu comando:

import {Command} from '@oclif/core'

export default class DeployCommand extends Command {
  static description = 'Deploy your application to production'

  // Specify tool behavior annotations following MCP specification
  static mcpAnnotations = {
    readOnlyHint: false, // This command modifies the environment
    destructiveHint: true, // This operation may be destructive
    idempotentHint: false, // Multiple calls may have different effects
    openWorldHint: true, // Interacts with external systems (deployment)
  }

  async run() {
    // ... deployment logic
  }
}

export default class StatusCommand extends Command {
  static description = 'Get application status'

  static mcpAnnotations = {
    readOnlyHint: true, // This command only reads data
    destructiveHint: false, // Safe operation
    idempotentHint: true, // Multiple calls return same result
    openWorldHint: true, // May check external systems
  }

  async run() {
    // ... status logic
  }
}

Plantillas de prompts mejoradas

Crea prompts con validación avanzada de argumentos:

import {Command} from '@oclif/core'
import {z} from 'zod'

export default class AnalyzeCommand extends Command {
  static description = 'Analyze code and provide insights'

  // Define prompts with custom validation schemas
  static mcpPrompts = [
    {
      name: 'code-review',
      description: 'Review code for best practices and potential issues',
      arguments: [
        {name: 'filePath', required: true, description: 'Path to the file to review'},
        {name: 'severity', required: false, description: 'Minimum severity level'},
      ],
      // Custom Zod schema for advanced validation
      argumentSchema: z.object({
        filePath: z.string().min(1, 'File path is required'),
        severity: z.enum(['low', 'medium', 'high']).default('medium'),
        includePerformance: z.boolean().default(false),
      }),
      handler: 'handleCodeReview', // Method name to call
    },
  ]

  async handleCodeReview(args: {filePath: string; severity: string; includePerformance: boolean}) {
    // Custom prompt handler with validated arguments
    return {
      description: `Code review for ${args.filePath}`,
      messages: [
        {
          role: 'assistant' as const,
          content: {
            type: 'text' as const,
            text: `I'll review the file "${args.filePath}" for ${args.severity} and above issues.${
              args.includePerformance ? ' Including performance analysis.' : ''
            }`,
          },
        },
      ],
    }
  }
}

  async run() {
    // ... status check logic
  }
}

📊 Recursos compatibles con MCP

Los recursos proporcionan datos contextuales a los asistentes de IA siguiendo la especificación oficial de MCP. Los recursos son automáticamente descubribles a través del endpoint resources/list y se obtienen bajo demanda mediante resources/read. Nuestra implementación incluye 100% de cumplimiento MCP con:

✅ Recursos Directos - Recursos estáticos con campos uri, name, description, mimeType y size
✅ Plantillas de Recursos - Recursos dinámicos que utilizan plantillas URI RFC 6570 con campo uriTemplate
✅ Resolución de Plantillas URI - Extracción y resolución automática de parámetros (por ejemplo, users://profile/{userId})
✅ Recursos Binarios - Soporte para tipos de contenido text y blob (base64)
✅ Devolución de Múltiples Recursos - Un solo resources/read puede devolver múltiples recursos
✅ Suscripciones a Recursos - Seguimiento completo de suscripciones mediante resources/subscribe/resources/unsubscribe
✅ Notificaciones en Tiempo Real - notifications/resources/updated y notifications/resources/list_changed reales
✅ Generación de URI - API pública para la creación programática de URI a partir de plantillas
✅ Capacidades del Servidor - Declaración adecuada de capacidades con soporte de suscripción

Recursos Estáticos

Perfectos para configuración, documentación o datos fijos:

export default class ConfigCommand extends Command {
  static mcpResources = [
    {
      uri: 'config://app-settings',
      name: 'Application Settings',
      description: 'Current application configuration',
      content: JSON.stringify(
        {
          version: '1.0.0',
          environment: 'production',
          features: ['auth', 'logging'],
        },
        null,
        2,
      ),
      mimeType: 'application/json',
      size: 98, // Optional: size in bytes for better resource management
    },
  ]
}

Plantillas de Recursos

Utilice plantillas URI siguiendo RFC 6570 para patrones de recursos dinámicos:

export default class UserCommand extends Command {
  static mcpResourceTemplates = [
    {
      uriTemplate: 'users://profile/{userId}',
      name: 'User Profile Template',
      description: 'Access user profiles by ID using users://profile/123',
      mimeType: 'application/json',
    },
    {
      uriTemplate: 'files://document/{docId}/content',
      name: 'Document Content Template',
      description: 'Access document content by ID using files://document/abc/content',
      mimeType: 'text/plain',
    },
  ]

  // Dynamic templates via methods
  static async getMcpResourceTemplates() {
    return [
      {
        uriTemplate: 'logs://{service}/recent',
        name: 'Service Logs Template',
        description: 'Access recent logs for any service using logs://api/recent',
        mimeType: 'text/plain',
      },
    ]
  }
}

Recursos Dinámicos con Manejadores de Funciones

Utilice manejadores de funciones para la generación de contenido dinámico:

export default class UserCommand extends Command {
  static mcpResources = [
    {
      uri: 'users://profile-info',
      name: 'User Profile',
      description: 'User profile information',
      handler: 'getUserProfile', // Method name on class
      mimeType: 'application/json',
    },
  ]

  // Handler method generates dynamic content
  async getUserProfile() {
    const user = await this.fetchUserData()
    return JSON.stringify(user, null, 2)
  }

  private async fetchUserData() {
    // Your logic to fetch user data
    return {
      id: '123',
      name: 'John Doe',
      email: 'john@example.com',
    }
  }
}

Recursos Dinámicos mediante Métodos Estáticos

Genere recursos programáticamente:

export default class StatusCommand extends Command {
  // Static method for dynamic resource generation
  static async getMcpResources() {
    return [
      {
        uri: 'status://runtime',
        name: 'Runtime Status',
        description: 'Current system status',
        handler: async () => {
          const status = await this.getSystemStatus()
          return JSON.stringify(status, null, 2)
        },
        mimeType: 'application/json',
      },
    ]
  }

  private static async getSystemStatus() {
    return {
      uptime: process.uptime(),
      memory: process.memoryUsage(),
      timestamp: new Date().toISOString(),
    }
  }
}

Recursos con Métodos de Instancia

Recursos que necesitan acceso a la instancia del comando:

export default class LogsCommand extends Command {
  // Instance method for dynamic resources
  async getMcpResources() {
    return [
      {
        uri: 'logs://recent-entries',
        name: 'Recent Logs',
        description: 'Recent log entries',
        handler: () => this.getRecentLogs(),
        mimeType: 'text/plain',
      },
    ]
  }

  private async getRecentLogs() {
    // Access to command instance and configuration
    return await this.fetchLogs(this.config.logLevel)
  }

  private async fetchLogs(logLevel: string) {
    // Your logic to fetch logs
    return `Recent logs at ${logLevel} level:\n2024-01-01 10:00:00 INFO: Application started\n2024-01-01 10:01:00 DEBUG: Processing request`
  }
}

Patrones de Manejadores de Recursos

export default class ExampleCommand extends Command {
  static mcpResources = [
    // String content
    {
      uri: 'example://static',
      name: 'Static Content',
      content: 'Direct string content',
    },

    // Function handler
    {
      uri: 'example://dynamic',
      name: 'Dynamic Content',
      handler: async () => {
        return `Generated at: ${new Date().toISOString()}`
      },
    },

    // Method name reference
    {
      uri: 'example://method',
      name: 'Method Handler',
      handler: 'getMethodContent', // Calls this.getMethodContent()
    },
  ]

  async getMethodContent() {
    return 'Content from method'
  }
}

Recursos Binarios y Plantillas URI

Patrones avanzados de recursos con cumplimiento total de MCP:

export default class AdvancedCommand extends Command {
  // Resource templates for dynamic URI resolution
  static mcpResourceTemplates = [
    {
      uriTemplate: 'users://profile/{userId}',
      name: 'User Profile Template',
      description: 'Access user profiles by ID (e.g., users://profile/123)',
      mimeType: 'application/json',
    },
    {
      uriTemplate: 'files://{category}/{filename}',
      name: 'File Template',
      description: 'Access files by category (e.g., files://docs/readme.txt)',
      mimeType: 'text/plain',
    },
  ]

  // Binary resource example
  static mcpResources = [
    {
      uri: 'images://screenshot',
      name: 'Screenshot',
      handler: 'captureScreen',
      mimeType: 'image/png',
      size: 1024000, // Estimated size in bytes
    },
  ]

  async captureScreen() {
    // Return Buffer for binary content (automatically base64 encoded)
    return Buffer.from('fake-image-data', 'utf8')
  }
}

// AI assistants can now access:
// - users://profile/123 (resolves {userId} to "123")
// - files://docs/readme.txt (resolves {category} to "docs", {filename} to "readme.txt")
// - images://screenshot (returns base64 binary data)

Notificaciones de Recursos y Generación de URI

Gestión avanzada de recursos MCP con actualizaciones en tiempo real:

export default class NotificationCommand extends Command {
  static mcpResources = [
    {
      uri: 'data://live-metrics',
      name: 'Live System Metrics',
      handler: 'getLiveMetrics',
      mimeType: 'application/json',
    },
  ]

  static mcpResourceTemplates = [
    {
      uriTemplate: 'notifications://alert/{alertId}',
      name: 'Alert Notification Template',
      description: 'Real-time alerts by ID',
      mimeType: 'application/json',
    },
  ]

  async getLiveMetrics() {
    // When this content changes, subscribers get notified
    return JSON.stringify({
      timestamp: new Date().toISOString(),
      cpu: Math.random() * 100,
      memory: Math.random() * 100,
    })
  }
}

// Subscribers automatically receive notifications when resources change
// The server sends proper MCP notifications:
// - notifications/resources/updated (for specific resource changes)
// - notifications/resources/list_changed (when resource list changes)

Los prompts proporcionan plantillas reutilizables que ayudan a los asistentes de IA a interactuar con su CLI de manera más efectiva. Siguen la especificación oficial de MCP utilizando los endpoints prompts/list y prompts/get.

Cómo Funcionan los Prompts

El plugin implementa automáticamente el protocolo de prompts de MCP:

Descubrimiento: Los asistentes de IA llaman a prompts/list para descubrir los prompts disponibles
Ejecución: Los asistentes de IA llaman a prompts/get con el nombre del prompt y los argumentos
Respuesta: Los prompts devuelven mensajes estructurados para el procesamiento del LLM

Prompts Estáticos

Defina plantillas de prompts reutilizables en sus clases de comando:

export default class AnalyzeCommand extends Command {
  static mcpPrompts = [
    {
      name: 'analyze-logs',
      description: 'Analyze application logs for issues',
      arguments: [
        {
          name: 'logLevel',
          description: 'Log level to focus on (error, warn, info)',
          required: false,
        },
        {
          name: 'timeRange',
          description: 'Time range to analyze (e.g., "last 1 hour")',
          required: true,
        },
      ],
    },
  ]
}

Prompts Dinámicos

Genere prompts programáticamente basados en el estado actual:

export default class DeployCommand extends Command {
  // Static method for dynamic prompt generation
  static async getMcpPrompts() {
    const environments = await this.getAvailableEnvironments()

    return [
      {
        name: 'deploy-with-confirmation',
        description: 'Deploy with safety confirmation prompts',
        arguments: [
          {
            name: 'environment',
            description: `Target environment: ${environments.join(', ')}`,
            required: true,
          },
          {
            name: 'skipChecks',
            description: 'Skip pre-deployment safety checks',
            required: false,
          },
        ],
      },
    ]
  }

  private static async getAvailableEnvironments() {
    return ['development', 'staging', 'production']
  }
}

Prompts con Manejadores Personalizados

Cree prompts que generen respuestas dinámicas:

export default class StatusCommand extends Command {
  // Instance method for dynamic prompts
  async getMcpPrompts() {
    return [
      {
        name: 'troubleshoot-status',
        description: `Troubleshoot ${this.config.name} status issues`,
        arguments: [
          {
            name: 'component',
            description: 'Specific component to troubleshoot',
            required: false,
          },
        ],
        handler: 'generateTroubleshootingPrompt',
      },
    ]
  }

  async generateTroubleshootingPrompt(args: any) {
    const status = await this.getSystemStatus()

    return {
      description: 'Troubleshooting guidance based on current system status',
      messages: [
        {
          role: 'user',
          content: {
            type: 'text',
            text: `Please help troubleshoot ${args.component || 'the system'}. Current status: ${JSON.stringify(status, null, 2)}`,
          },
        },
      ],
    }
  }

  private async getSystemStatus() {
    return {
      status: 'running',
      uptime: process.uptime(),
      memory: process.memoryUsage(),
    }
  }
}

Cumplimiento del Protocolo MCP

La implementación de prompts sigue la especificación oficial de MCP:

✅ prompts/list - Lista todos los prompts disponibles con nombres, descripciones y argumentos
✅ prompts/get - Ejecuta prompts específicos con validación de argumentos
✅ Validación de argumentos - Garantiza que se proporcionen los argumentos requeridos
✅ Soporte de manejadores - Manejadores de funciones, referencias a métodos y valores predeterminados
✅ Respuestas estructuradas - Devuelve matrices de mensajes correctamente formateadas para LLMs

🌳 Soporte de Raíces MCP

Las raíces proporcionan límites de espacio de trabajo y contexto para los asistentes de IA. Puede definir raíces personalizadas o utilizar la raíz automática del directorio de trabajo predeterminado.

Raíces Personalizadas

Defina raíces de espacio de trabajo personalizadas en sus comandos:

export default class WorkspaceCommand extends Command {
  static mcpRoots = [
    {
      name: 'project-root',
      uri: 'file:///path/to/project',
      description: 'Main project directory',
    },
    {
      name: 'config-root',
      uri: 'file:///path/to/config',
      description: 'Configuration files directory',
    },
  ]
}

Raíces Dinámicas

Genere raíces programáticamente:

export default class ProjectCommand extends Command {
  // Static method for dynamic root generation
  static async getMcpRoots() {
    const projectPaths = await this.getProjectPaths()

    return projectPaths.map((path) => ({
      name: path.name,
      uri: `file://${path.fullPath}`,
      description: `${path.name} workspace directory`,
    }))
  }

  private static async getProjectPaths() {
    // Your logic to discover project paths
    return [
      {name: 'frontend', fullPath: '/workspace/frontend'},
      {name: 'backend', fullPath: '/workspace/backend'},
    ]
  }
}

Raíces con Métodos de Instancia

Raíces que necesitan acceso a la instancia del comando:

export default class EnvironmentCommand extends Command {
  // Instance method for dynamic roots
  async getMcpRoots() {
    const envConfig = this.config.get('environment')

    return [
      {
        name: 'env-root',
        uri: `file://${envConfig.rootPath}`,
        description: `${envConfig.name} environment root directory`,
      },
    ]
  }
}

Raíz de Respaldo Automática

Cuando no se definen raíces personalizadas, el plugin registra automáticamente el directorio de trabajo actual de su CLI:

URI: file://[current-working-directory]
Nombre: "Directorio de Trabajo de la CLI"
Propósito: Proporciona a los asistentes de IA contexto del espacio de trabajo para operaciones de archivos

Beneficios para los Asistentes de IA

Comprensión del Espacio de Trabajo: Los asistentes de IA conocen los límites del proyecto
Contexto de Archivos: Mejor comprensión de las rutas relativas y la estructura del proyecto
Seguridad: Límites claros para el acceso al sistema de archivos
Navegación: Ayuda a los asistentes de IA a comprender la disposición del proyecto
Soporte Multi-espacio de Trabajo: Soporte para proyectos complejos con múltiples raíces

Filtrado de Comandos

El servidor MCP filtra automáticamente los comandos:

✅ hidden: false - El comando no debe estar oculto
✅ disableMCP: true - El comando no debe deshabilitar MCP (predeterminado: falso)
✅ cmdClass.pluginType === 'jit' - Los comandos JIT (Just-In-Time) se excluyen automáticamente de la exposición MCP por razones de seguridad y estabilidad.
✅ No es el propio comando MCP

🏗️ Arquitectura

graph TB
    A[AI Assistant] -->|MCP JSON-RPC| B[oclif-plugin-mcp-server]

    subgraph "MCP Protocol Handlers"
        B -->|tools/list| C[Tool Discovery]
        B -->|tools/call| D[Command Execution]
        B -->|resources/list| E[Resource Discovery]
        B -->|resources/read| F[Content Fetching]
        B -->|prompts/list| G[Prompt Discovery]
        B -->|prompts/get| H[Prompt Execution]
        B -->|resources/subscribe| I[Subscription Management]
    end

    subgraph "Auto-Discovery Engine"
        C -->|Scan Commands| J[oclif Command Registry]
        J -->|Generate Schemas| K[Zod Schema Builder]
        J -->|Extract Metadata| L[Tool Annotations]
    end

    subgraph "Validation & Execution"
        D -->|Input Validation| K
        K -->|Validated Args| M[Command Runner]
        M -->|Capture Output| N[stdout/stderr Handler]
        N -->|Format Response| O[MCP Response Builder]
    end

    subgraph "Resource Management"
        E -->|Static Resources| P[Direct Content]
        E -->|Dynamic Resources| Q[Handler Functions]
        E -->|Resource Templates| R[URI Template Engine]
        F -->|URI Matching| R
        R -->|Parameter Extraction| S[Template Resolver]
        Q -->|Method Calls| T[Resource Handlers]
        P -->|Direct Content| U[Content Formatter]
        T -->|Generated Content| U
        S -->|Resolved Content| U
    end

    subgraph "Prompt System"
        G -->|Template Discovery| V[Prompt Registry]
        H -->|Argument Validation| W[Prompt Validator]
        W -->|Execute Handler| X[Prompt Response Builder]
    end

    subgraph "Notification System"
        Y[Resource Change Detector] -->|Debounced Events| Z[Notification Queue]
        Z -->|Batch Notifications| AA[MCP Notifier]
        AA -->|notifications/resources/updated| A
        AA -->|notifications/resources/list_changed| A
    end

    subgraph "Error Handling"
        BB[Error Interceptor] -->|JSON-RPC Codes| CC[MCP Error Builder]
        CC -->|Structured Errors| DD[Error Response]
    end

    O -->|Tool Response| A
    U -->|Resource Content| A
    X -->|Prompt Messages| A
    DD -->|Error Details| A

    M -.->|Triggers| Y
    T -.->|Triggers| Y
    D -.->|On Error| BB
    F -.->|On Error| BB
    H -.->|On Error| BB

    style B fill:#e1f5fe
    style J fill:#f3e5f5
    style K fill:#e8f5e8
    style R fill:#fff3e0
    style Y fill:#f1f8e9
    style BB fill:#ffebee

🔄 Cumplimiento del Protocolo MCP 2025-06-18

Este plugin implementa la especificación completa MCP 2025-06-18 con características de cumplimiento mejoradas:

Característica MCP	Estado	Implementación
Versión del Protocolo	✅ Completo	Cabeceras MCP-Protocol-Version: 2025-06-18
Herramientas	✅ Completo	Todos los comandos oclif auto-descubiertos como herramientas
Anotaciones de Herramientas	✅ Completo	Soporte para readOnlyHint, destructiveHint, etc.
Recursos	✅ Completo	Endpoints `resources/list` y `resources/read`
Recursos Estáticos	✅ Completo	Contenido directo y registro de URI con tamaño
Recursos Dinámicos	✅ Completo	Manejadores de funciones y métodos
Plantillas de Recursos	✅ Completo	Plantillas URI RFC 6570 con resolución automática
Recursos Binarios	✅ Completo	Soporte de Buffer con codificación base64
Resolución de URI	✅ Completo	Extracción de parámetros de URI con plantillas
Múltiples Recursos	✅ Completo	Una sola solicitud de lectura puede devolver múltiples recursos
Actualizaciones de Recursos	✅ Completo	Notificaciones MCP en tiempo real para cambios de recursos
Generación de URI	✅ Completo	API pública para creación programática de plantillas URI
Sistema de Notificaciones	✅ Completo	Implementación completa del protocolo de notificaciones MCP
Prompts	✅ Completo	Plantillas de prompts reutilizables con soporte de argumentos
Raíces	✅ Completo	Directorio de trabajo de la CLI como raíz MCP
Tipos de Contenido	✅ Completo	Manejo adecuado de tipos MIME
Manejo de Errores	✅ Completo	Respuestas de error elegantes
Validación de Esquemas	✅ Completo	Generación de esquemas Zod a partir de definiciones oclif
Validación de Entrada	✅ Mejorado	Validación Zod completa para todos los argumentos de herramientas
Errores JSON-RPC	✅ Mejorado	Códigos de error MCP adecuados (-32xxx) para todos los errores
Validación de Prompts	✅ Mejorado	Análisis de argumentos de prompts con seguridad de tipos
Notificaciones con Debounce	✅ Mejorado	Notificaciones optimizadas de cambios de recursos
Prompts Mejorados	✅ Mejorado	Respuestas de prompts interactivas estilo asistente
Capacidad de Muestreo	✅ Nuevo	Solicitudes de interacción LLM del lado del servidor
Soporte de Elicitación	✅ Nuevo	Solicitudes de entrada de usuario y confirmación
Registro Estructurado	✅ Nuevo	Registro avanzado con gestión de niveles
Seguimiento de Progreso	✅ Nuevo	Tokens de progreso mejorados con cancelación
Autorización OAuth 2.1	✅ Nuevo	OAuth 2.1 completo con soporte PKCE
Indicadores de Recursos	✅ Nuevo	Cumplimiento RFC 8707 para uso seguro de tokens
Gestión de Sesiones	✅ Nuevo	Manejo avanzado de sesiones HTTP y limpieza

📋 Ejemplos

Integración CLI del Mundo Real

# Your existing CLI
my-cli deploy my-app --environment production --force
my-cli status --format json
my-cli logs --tail 100

# After MCP integration, AI can discover and use:
# - Commands: "Deploy my-app to production with force flag"
# - Resources: "Show me the current deployment status"
# - Logs: "Get the last 100 log entries for my-app"

Flujo de Descubrimiento de Recursos

sequenceDiagram
    participant AI as AI Assistant
    participant MCP as MCP Server
    participant CLI as Your CLI

    AI->>MCP: resources/list
    MCP->>CLI: Discover resources
    CLI->>MCP: Return resource list
    MCP->>AI: Available resources

    AI->>MCP: resources/read(status://runtime)
    MCP->>CLI: Call resource handler
    CLI->>MCP: Generate content
    MCP->>AI: Resource content

🤝 Contribuciones

¡Damos la bienvenida a las contribuciones! Consulte nuestra Guía de Contribuciones para más detalles.

Configuración de Desarrollo

git clone https://github.com/npjonath/oclif-plugin-mcp-server.git
cd plugin-mcp-server
yarn install
yarn build

Pruebas

yarn test        # Run tests
yarn lint        # Check code style
yarn build       # Build the plugin

Pruebas de Cumplimiento MCP

# Test with MCP Inspector
npx @modelcontextprotocol/inspector your-cli mcp

# Test resource discovery with protocol version
curl -X POST http://localhost:3000/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"resources/list"}'
# Response includes MCP-Protocol-Version: 2025-06-18 header

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulte el archivo LICENCIA para más detalles.

🙏 Agradecimientos

oclif - El Marco CLI Abierto
Model Context Protocol - Especificación oficial de MCP
Anthropic - Por desarrollar y promover MCP
MCP TypeScript SDK - Implementación oficial de MCP

🌟 Ahora totalmente compatible con MCP 2025-06-18 con seguridad mejorada y capacidades avanzadas: ¡listo para el futuro de CLI impulsado por IA!