oclif MCP Server Plugin

Um plugin CLI oclif que descobre e serve automaticamente comandos via o Model Context Protocol (MCP).

GitHub
13
Experimente este MCPPatrocinado

Documentação

🔌 oclif-plugin-mcp-server

Transforme qualquer CLI oclif em um servidor totalmente compatível com MCP 2025-06-18 para integração perfeita com assistentes de IA

oclif MCP 2025-06-18 Version Downloads/week License

Este plugin converte automaticamente os comandos da sua CLI oclif em um servidor totalmente compatível com o protocolo MCP 2025-06-18, implementando a mais recente especificação do Model Context Protocol. Ele permite que assistentes de IA como Claude, ChatGPT e Cursor descubram e executem suas ferramentas de CLI naturalmente por meio de conversas.

✨ Novidades no MCP 2025-06-18

🎉 Especificação MCP mais recente: Conformidade total com MCP 2025-06-18, incluindo:

  • 🔒 Autorização OAuth 2.1: Suporte completo a OAuth 2.1 com PKCE para transporte HTTP seguro
  • 🔄 Capacidade de Amostragem: Solicitações de interação com LLM no lado do servidor para fluxos de trabalho avançados de IA
  • ❓ Suporte a Elicitação: Solicite informações adicionais e confirmações do usuário aos clientes
  • 📝 Registro Estruturado: Capacidade avançada de registro com gerenciamento de níveis e notificações
  • ⏳ Rastreamento de Progresso: Rastreamento aprimorado de progresso com suporte a cancelamento
  • 🌐 Cabeçalhos de Versão do Protocolo: Suporte completo ao cabeçalho MCP-Protocol-Version: 2025-06-18
  • 🛡️ Segurança Aprimorada: Indicadores de Recurso (RFC 8707) e fluxos de autorização melhorados

O que é MCP?

O Model Context Protocol (MCP) é um padrão aberto que permite que assistentes de IA se conectem com segurança a fontes de dados e ferramentas externas. Com MCP, sua CLI se torna um cidadão de primeira classe nos fluxos de trabalho de IA, permitindo que os assistentes:

  • 🔍 Descubram seus comandos e recursos automaticamente
  • ✅ Validem entradas usando esquemas type-safe
  • 🚀 Executem comandos com tratamento adequado de erros
  • 📊 Acessem recursos com carregamento preguiçoso e metadados adequados
  • 🔒 Protejam interações por meio de protocolos padronizados

🚀 Recursos

Capacidades Principais do MCP 2025-06-18

  • 🔍 Descoberta Automática: Descobre e expõe automaticamente comandos oclif como ferramentas MCP
  • 📝 Geração de Esquemas: Converte argumentos e flags oclif em esquemas Zod para execução type-safe
  • 📊 Recursos Compatíveis com MCP: Suporte total a recursos estáticos e dinâmicos seguindo a especificação MCP
  • 🎯 Modelos de Prompt: Modelos de prompt reutilizáveis com validação de argumentos e manipuladores
  • 🌳 Raízes do Workspace: Registro automático do diretório de trabalho da CLI como raiz MCP
  • 🔄 Carregamento Preguiçoso: Recursos são buscados sob demanda por meio de endpoints MCP adequados
  • 🛡️ Tratamento de Erros: Tratamento gracioso de erros com feedback detalhado e códigos de erro JSON-RPC adequados
  • ⚙️ Zero Configuração: Funciona imediatamente com qualquer CLI oclif
  • 📋 Conformidade com Padrões: Implementa a especificação oficial MCP 2025-06-18
  • ✅ Validação de Entrada: Validação type-safe de argumentos para todos os comandos e prompts
  • 🔔 Notificações Inteligentes: Notificações de alteração de recursos com debounce para desempenho ideal

Novidades no MCP 2025-06-18

  • 🔒 Segurança OAuth 2.1: Integração completa de servidor de autorização OAuth 2.1 com suporte a PKCE
  • 🔄 Suporte a Amostragem: Capacidade no lado do servidor para solicitações de interação com LLM
  • ❓ Estrutura de Elicitação: Solicite entrada e confirmações do usuário por meio do cliente
  • 📝 Registro Estruturado: Registro avançado com gerenciamento de níveis e notificações ao cliente
  • ⏳ Rastreamento de Progresso: Tokens de progresso aprimorados com suporte a cancelamento
  • 🌐 Cabeçalhos de Protocolo: Tratamento adequado do cabeçalho MCP-Protocol-Version: 2025-06-18
  • 🛡️ Autorização Aprimorada: Indicadores de Recurso (RFC 8707) para uso seguro de tokens
  • 🔐 Gerenciamento de Sessão: Tratamento avançado de sessões HTTP com limpeza e monitoramento

📦 Instalação

Incorporar plugin no código da sua CLI (Recomendado)

Adicione ao package.json da sua CLI:

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

Do GitHub

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

# Verify installation
your-cli mcp --help

🎯 Início Rápido

1. Configurar o Assistente de IA

Adicione sua CLI à configuração MCP do seu assistente 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 desenvolvimento local com este plugin

  1. Compile sua CLI: yarn build
  2. Gere o manifesto: npx oclif manifest
  3. Atualize sua configuração MCP:

Transporte Stdio (padrão):

{
  "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. Comece a Conversar

Seu assistente de IA agora pode descobrir e usar seus comandos e recursos de 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 suporta ambos os protocolos de transporte MCP conforme definido na especificação oficial:

📡 Entrada/Saída Padrão (stdio) - Padrão

O transporte padrão para integrações locais e ferramentas de linha de comando.

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

Perfeito para:

  • Integrações locais (Claude Desktop, Cursor)
  • Ferramentas de linha de comando
  • Comunicação simples entre processos
  • Scripts de shell

🌐 Transporte HTTP Streamable

Transporte baseado em HTTP com Server-Sent Events (SSE) para integrações web.

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

Perfeito para:

  • Integrações baseadas na web
  • Comunicação cliente-servidor via HTTP
  • Sessões com estado
  • Múltiplos clientes simultâneos
  • Conexões retomáveis
  • Contêineres Docker

Recursos do Transporte HTTP

  • JSON-RPC sobre HTTP: Comunicação cliente-servidor via solicitações POST
  • Server-Sent Events (SSE): Comunicação servidor-cliente via solicitações GET
  • Gerenciamento de Sessão: Sessões com estado com cabeçalhos X-Session-Id
  • Cabeçalhos de Protocolo: MCP-Protocol-Version: 2025-06-18 em todas as respostas
  • Integração OAuth 2.1: Autorização segura com suporte a PKCE
  • Retomabilidade: IDs de evento e suporte ao cabeçalho Last-Event-ID
  • Suporte CORS: Compartilhamento de recursos entre origens configurável com controles de segurança
  • Verificação de Saúde: Endpoint /health para monitoramento com versão do protocolo

Endpoints HTTP

  • POST / - Solicitações JSON-RPC (cliente para servidor)
  • GET /events/:sessionId - Fluxos SSE (servidor para cliente)
  • DELETE /sessions/:sessionId - Encerramento de sessão
  • GET /health - Verificação de saúde com versão do protocolo
  • GET /oauth/authorize - Endpoint de autorização OAuth 2.1 (se configurado)
  • GET /oauth/callback - Endpoint de callback OAuth 2.1 (se configurado)

Exemplos 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

Integração com 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()

Guia de Seleção de Transporte

Caso de UsoTransporte RecomendadoMotivo
Integração CLI localstdioComunicação simples e direta entre processos
Extensões VS CodestdioPadrão para integrações de desktop
Claude DesktopstdioPadrão para integrações de desktop
IDE CursorstdioPadrão para integrações de desktop
Aplicações webhttpFunciona pela rede, suporta múltiplos clientes
Contêineres DockerhttpMelhor para implantações em contêineres
Desenvolvimento/depuraçãohttpFácil de testar com curl/navegador
Servidores de produçãohttpEscalável, suporta balanceamento de carga
Pipelines CI/CDhttpMelhor para ambientes automatizados

🔒 Considerações de Segurança

Este plugin expõe seus comandos de CLI a assistentes de IA por meio do protocolo MCP. A especificação mais recente de 2025-06-18 inclui recursos de segurança aprimorados:

Segurança Aprimorada no MCP 2025-06-18

  • 🔒 Autorização OAuth 2.1: Implementação completa de OAuth 2.1 com suporte a PKCE
  • 🛡️ Indicadores de Recurso: Conformidade com RFC 8707 para acesso seguro a recursos
  • 🔐 Gerenciamento de Sessão: Tratamento avançado de sessões HTTP com limpeza automática
  • 🌐 Proteção CORS: Controles aprimorados entre origens com validação de origem
  • 📋 Cabeçalhos de Protocolo: Negociação adequada de versão e cabeçalhos de segurança

Limites de Confiança

  • Desenvolvimento Local: Ao executar localmente, o plugin opera no contexto do seu usuário com suas permissões
  • Uso em Produção: Exponha apenas comandos que sejam seguros para assistentes de IA executarem
  • Transporte HTTP: Use OAuth 2.1 para acesso remoto seguro com fluxos de autorização adequados
  • Operações Sensíveis: Use a flag disableMCP para comandos que executam operações sensíveis

Segurança 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
  }
}

Configuração 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áticas Recomendadas

  • ✅ Revise os comandos expostos antes da implantação
  • ✅ Use OAuth 2.1 para implantações HTTP de produção
  • ✅ Implemente Indicadores de Recurso para escopo seguro de tokens
  • ✅ Use anotações de ferramentas para marcar claramente operações destrutivas
  • ✅ Implemente validação adequada nos manipuladores de seus comandos
  • ✅ Monitore o uso de MCP em ambientes de produção
  • ✅ Configure CORS adequadamente para integrações web
  • ⚠️ Evite expor comandos que modifiquem configurações de nível de sistema
  • ⚠️ Tenha cuidado com operações de arquivo que possam afetar dados sensíveis
  • ⚠️ Use HTTPS para todas as implantações de transporte HTTP em produção

⚖️ Limites de Ferramentas dos Provedores de IA

Diferentes provedores de IA têm limites variados no número de ferramentas que podem lidar efetivamente:

ProvedorLimite de FerramentasObservações
VS Code128 ferramentasLimite rígido imposto pela plataforma
Cursor40 ferramentasLimite rígido imposto pela plataforma
Claude DesktopdesconhecidoVaria por modelo e nível de assinatura
ChatGPTdesconhecidoVaria por modelo e nível de assinatura
GitHub CopilotdesconhecidoVaria por modelo e nível de assinatura

Configuração de Filtragem de Comandos

Para gerenciar CLIs grandes com muitos comandos, você pode configurar a filtragem para permanecer dentro desses limites:

Filtragem Básica por Tópico

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

Filtragem Avançada por Padrão

{
  "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"]
      }
    }
  }
}

Configuração Baseada em Ambiente

{
  "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"
    }
  }
}

Configuração em Tempo de Execução

Você também pode configurar a filtragem em tempo de execução:

# 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:*"

Estratégias de Filtragem

  • first - Inclui os primeiros N comandos até o limite
  • prioritize - Inclui comandos prioritários primeiro, depois outros até o limite
  • balanced - Tenta incluir comandos de todos os tópicos proporcionalmente
  • strict - Falha se os comandos filtrados excederem o limite

Sugestões Automáticas

Quando comandos são filtrados devido a limites, o plugin registrará sugestões:

⚠️  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 Avançado

IDs de Ferramenta Personalizados

Substitua a geração padrão de IDs de ferramenta:

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

Anotações de Ferramentas

Adicione anotações de ferramentas compatíveis com MCP para fornecer aos assistentes de IA metadados sobre o comportamento do seu 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
  }
}

Modelos de Prompt Aprimorados

Crie prompts com validação avançada 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 Compatíveis com MCP

Recursos fornecem dados contextuais aos assistentes de IA seguindo a especificação oficial MCP. Os recursos são automaticamente descobertos por meio do endpoint resources/list e buscados sob demanda via resources/read. Nossa implementação inclui 100% de conformidade com MCP com:

  • ✅ Recursos Diretos - Recursos estáticos com campos uri, name, description, mimeType e size
  • ✅ Modelos de Recursos - Recursos dinâmicos usando modelos de URI RFC 6570 com campo uriTemplate
  • ✅ Resolução de Modelos de URI - Extração e resolução automática de parâmetros (ex.: users://profile/{userId})
  • ✅ Recursos Binários - Suporte para ambos os tipos de conteúdo text e blob (base64)
  • ✅ Retorno de Múltiplos Recursos - Um único resources/read pode retornar múltiplos recursos
  • ✅ Assinaturas de Recursos - Rastreamento completo de assinaturas via resources/subscribe/resources/unsubscribe
  • ✅ Notificações em Tempo Real - notifications/resources/updated e notifications/resources/list_changed reais
  • ✅ Geração de URI - API pública para criação programática de URIs a partir de modelos
  • ✅ Capacidades do Servidor - Declaração adequada de capacidades com suporte a assinaturas

Recursos Estáticos

Perfeito para configuração, documentação ou dados fixos:

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
    },
  ]
}

Modelos de Recursos

Use modelos de URI seguindo RFC 6570 para padrões 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 com Manipuladores de Função

Use manipuladores de função para geração de conteúdo 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 via Métodos Estáticos

Gere recursos programaticamente:

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 de Método de Instância

Recursos que precisam de acesso à instância do 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`
  }
}

Padrões de Manipuladores 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 Binários e Modelos de URI

Padrões avançados de recursos com conformidade total com 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)

Notificações de Recursos e Geração de URI

Gerenciamento avançado de recursos MCP com atualizações em tempo 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)

Prompts fornecem modelos reutilizáveis que ajudam assistentes de IA a interagir com sua CLI de forma mais eficaz. Eles seguem a especificação oficial do MCP usando os endpoints prompts/list e prompts/get.

Como os Prompts Funcionam

O plugin implementa automaticamente o protocolo de prompts do MCP:

  1. Descoberta: Assistentes de IA chamam prompts/list para descobrir prompts disponíveis
  2. Execução: Assistentes de IA chamam prompts/get com nome do prompt e argumentos
  3. Resposta: Prompts retornam mensagens estruturadas para processamento por LLM

Prompts Estáticos

Defina modelos de prompt reutilizáveis em suas classes 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

Gere prompts programaticamente com base no estado atual:

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 com Manipuladores Personalizados

Crie prompts que geram respostas 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(),
    }
  }
}

Conformidade com o Protocolo MCP

A implementação de prompts segue a especificação oficial do MCP:

  • ✅ prompts/list - Lista todos os prompts disponíveis com nomes, descrições e argumentos
  • ✅ prompts/get - Executa prompts específicos com validação de argumentos
  • ✅ Validação de argumentos - Garante que os argumentos obrigatórios sejam fornecidos
  • ✅ Suporte a manipuladores - Manipuladores de função, referências de método e padrões
  • ✅ Respostas estruturadas - Retorna matrizes de mensagens formatadas corretamente para LLMs

🌳 Suporte a Raízes MCP

Raízes fornecem limites de workspace e contexto para assistentes de IA. Você pode definir raízes personalizadas ou usar a raiz automática do diretório de trabalho padrão.

Raízes Personalizadas

Defina raízes de workspace personalizadas em seus 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ízes Dinâmicas

Gere raízes programaticamente:

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ízes de Método de Instância

Raízes que precisam de acesso à instância do 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`,
      },
    ]
  }
}

Raiz de Fallback Automática

Quando nenhuma raiz personalizada é definida, o plugin registra automaticamente o diretório de trabalho atual da sua CLI:

  • URI: file://[current-working-directory]
  • Nome: "Diretório de Trabalho da CLI"
  • Propósito: Fornece contexto de workspace para assistentes de IA para operações de arquivo

Benefícios para Assistentes de IA

  • Compreensão do Workspace: Assistentes de IA conhecem os limites do projeto
  • Contexto de Arquivos: Melhor compreensão de caminhos relativos e estrutura do projeto
  • Segurança: Limites claros para acesso ao sistema de arquivos
  • Navegação: Ajuda assistentes de IA a entender o layout do projeto
  • Suporte a Múltiplos Workspaces: Suporte para projetos complexos com múltiplas raízes

Filtragem de Comandos

O servidor MCP filtra comandos automaticamente:

  • ✅ hidden: false - O comando não deve estar oculto
  • ✅ disableMCP: true - O comando não deve desabilitar o MCP (padrão: falso)
  • ✅ cmdClass.pluginType === 'jit' - Comandos JIT (Just-In-Time) são automaticamente excluídos da exposição MCP por razões de segurança e estabilidade.
  • ✅ Não é o próprio comando MCP

🏗️ Arquitetura

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

🔄 Conformidade com o Protocolo MCP 2025-06-18

Este plugin implementa a especificação completa do MCP 2025-06-18 com recursos de conformidade aprimorados:

Recurso MCPStatusImplementação
Versão do Protocolo✅ CompletoCabeçalhos MCP-Protocol-Version: 2025-06-18
Ferramentas✅ CompletoTodos os comandos oclif descobertos automaticamente como ferramentas
Anotações de Ferramentas✅ CompletoSuporte para readOnlyHint, destructiveHint, etc.
Recursos✅ CompletoEndpoints resources/list e resources/read
Recursos Estáticos✅ CompletoRegistro de conteúdo direto e URI com tamanho
Recursos Dinâmicos✅ CompletoManipuladores de função e método
Modelos de Recursos✅ CompletoModelos de URI RFC 6570 com resolução automática
Recursos Binários✅ CompletoSuporte a Buffer com codificação base64
Resolução de URI✅ CompletoExtração de parâmetros de URIs modelados
Múltiplos Recursos✅ CompletoUma única solicitação de leitura pode retornar múltiplos recursos
Atualizações de Recursos✅ CompletoNotificações MCP em tempo real para mudanças de recursos
Geração de URI✅ CompletoAPI pública para criação programática de modelos de URI
Sistema de Notificação✅ CompletoImplementação completa do protocolo de notificação MCP
Prompts✅ CompletoModelos de prompt reutilizáveis com suporte a argumentos
Raízes✅ CompletoDiretório de trabalho da CLI como raiz MCP
Tipos de Conteúdo✅ CompletoTratamento adequado de tipos MIME
Tratamento de Erros✅ CompletoRespostas de erro graciosas
Validação de Esquema✅ CompletoGeração de esquema Zod a partir de definições oclif
Validação de Entrada✅ AprimoradoValidação Zod completa para todos os argumentos de ferramentas
Erros JSON-RPC✅ AprimoradoCódigos de erro MCP adequados (-32xxx) para todos os erros
Validação de Prompts✅ AprimoradoAnálise de argumentos de prompt com segurança de tipos
Notificações com Debounce✅ AprimoradoNotificações otimizadas de mudança de recursos
Prompts Aprimorados✅ AprimoradoRespostas de prompt interativas no estilo assistente
Capacidade de Amostragem✅ NovoSolicitações de interação LLM no lado do servidor
Suporte a Elicitação✅ NovoSolicitações de entrada e confirmação do usuário
Registro Estruturado✅ NovoRegistro avançado com gerenciamento de nível
Rastreamento de Progresso✅ NovoTokens de progresso aprimorados com cancelamento
Autorização OAuth 2.1✅ NovoOAuth 2.1 completo com suporte a PKCE
Indicadores de Recursos✅ NovoConformidade com RFC 8707 para uso seguro de tokens
Gerenciamento de Sessão✅ NovoTratamento e limpeza avançados de sessão HTTP

📋 Exemplos

Integração CLI do 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"

Fluxo de Descoberta 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

🤝 Contribuindo

Aceitamos contribuições! Consulte nosso Guia de Contribuição para detalhes.

Configuração de Desenvolvimento

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

Testes

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

Testando a Conformidade com 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

📄 Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

MIT © Jonathan Jot

🙏 Agradecimentos

🌟 Agora totalmente compatível com MCP 2025-06-18 com segurança aprimorada e capacidades avançadas - pronto para o futuro de CLI com IA!