🔌 oclif-plugin-mcp-server

> Transform any oclif CLI into a fully MCP 2025-06-18 compliant server for seamless AI assistant integration


This plugin automatically converts your oclif CLI commands into a fully MCP 2025-06-18 protocol compliant server, implementing the latest Model Context Protocol specification. It allows AI assistants like Claude, ChatGPT, and Cursor to discover and execute your CLI tools naturally through conversation.

✨ What's New in MCP 2025-06-18

🎉 Latest MCP Specification: Full compliance with MCP 2025-06-18 including:

- 🔒 OAuth 2.1 Authorization: Complete OAuth 2.1 support with PKCE for secure HTTP transport
- 🔄 Sampling Capability: Server-side LLM interaction requests for advanced AI workflows
- ❓ Elicitation Support: Request additional user input and confirmations from clients
- 📝 Structured Logging: Advanced logging capability with level management and notifications
- ⏳ Progress Tracking: Enhanced progress tracking with cancellation support
- 🌐 Protocol Version Headers: Full MCP-Protocol-Version: 2025-06-18 header support
- 🛡️ Enhanced Security: Resource Indicators (RFC 8707) and improved authorization flows

What is MCP?

The Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect to external data sources and tools. With MCP, your CLI becomes a first-class citizen in AI workflows, allowing assistants to:

- 🔍 Discover your commands and resources automatically
- ✅ Validate inputs using type-safe schemas
- 🚀 Execute commands with proper error handling
- 📊 Access resources with lazy loading and proper metadata
- 🔒 Secure interactions through standardized protocols

🚀 Features

$3

- 🔍 Auto-discovery: Automatically discovers and exposes oclif commands as MCP tools
- 📝 Schema Generation: Converts oclif arguments and flags to Zod schemas for type-safe execution
- 📊 MCP-Compliant Resources: Full support for static and dynamic resources following MCP specification
- 🎯 Prompt Templates: Reusable prompt templates with argument validation and handlers
- 🌳 Workspace Roots: Automatic CLI working directory registration as MCP root
- 🔄 Lazy Loading: Resources are fetched on-demand through proper MCP endpoints
- 🛡️ Error Handling: Graceful error handling with detailed feedback and proper JSON-RPC error codes
- ⚙️ Zero Configuration: Works out-of-the-box with any oclif CLI
- 📋 Standards Compliant: Implements the official MCP 2025-06-18 specification
- ✅ Input Validation: Type-safe argument validation for all commands and prompts
- 🔔 Smart Notifications: Debounced resource change notifications for optimal performance

$3

- 🔒 OAuth 2.1 Security: Full OAuth 2.1 authorization server integration with PKCE support
- 🔄 Sampling Support: Server-side capability for LLM interaction requests
- ❓ Elicitation Framework: Request user input and confirmations through the client
- 📝 Structured Logging: Advanced logging with level management and client notifications
- ⏳ Progress Tracking: Enhanced progress tokens with cancellation support
- 🌐 Protocol Headers: Proper MCP-Protocol-Version: 2025-06-18 header handling
- 🛡️ Enhanced Authorization: Resource Indicators (RFC 8707) for secure token usage
- 🔐 Session Management: Advanced HTTP session handling with cleanup and monitoring

📦 Installation

$3

Add to your CLI's package.json:

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

$3

`bash


Install directly from GitHub (requires oclif-plugin-plugins)

your-cli plugins install npjonath/oclif-plugin-mcp-server

Verify installation

your-cli mcp --help
`

🎯 Quick Start

$3

Add your CLI to your AI assistant's MCP configuration:

#### Cursor (mcp.json)

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

#### Claude Desktop

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

#### For local development with this plugin

1. Build your CLI: yarn build
2. Generate manifest: npx oclif manifest
3. Update your MCP configuration:

Stdio Transport (default):

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

HTTP Transport:

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

$3

Your AI assistant can now discover and use your CLI commands and resources:

`
👤 "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...]
`

🌐 Transport Protocols

This plugin supports both MCP transport protocols as defined in the official specification:

$3

The default transport for local integrations and command-line tools.

`bash


Start MCP server with stdio transport (default)


your-cli mcp
your-cli mcp --transport stdio
`

Perfect for:

- Local integrations (Claude Desktop, Cursor)
- Command-line tools
- Simple process communication
- Shell scripts

$3

HTTP-based transport with Server-Sent Events (SSE) for web integrations.

`bash


Start MCP server with HTTP transport


your-cli mcp --transport http --port 3000 --host 127.0.0.1
`

Perfect for:

- Web-based integrations
- Client-server communication over HTTP
- Stateful sessions
- Multiple concurrent clients
- Resumable connections
- Docker containers

#### HTTP Transport Features

- JSON-RPC over HTTP: Client-to-server communication via POST requests
- Server-Sent Events (SSE): Server-to-client communication via GET requests
- Session Management: Stateful sessions with X-Session-Id headers
- Protocol Headers: MCP-Protocol-Version: 2025-06-18 on all responses
- OAuth 2.1 Integration: Secure authorization with PKCE support
- Resumability: Event IDs and Last-Event-ID header support
- CORS Support: Configurable cross-origin resource sharing with security controls
- Health Check: /health endpoint for monitoring with protocol version

#### HTTP Endpoints

- POST / - JSON-RPC requests (client-to-server)
- GET /events/:sessionId - SSE streams (server-to-client)
- DELETE /sessions/:sessionId - Session termination
- GET /health - Health check with protocol version
- GET /oauth/authorize - OAuth 2.1 authorization endpoint (if configured)
- GET /oauth/callback - OAuth 2.1 callback endpoint (if configured)

#### HTTP Transport Examples

`bash


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
`

#### Web Client Integration

`javascript
// 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()
`

$3

| Use Case | Recommended Transport | Reason |
| --------------------- | --------------------- | --------------------------------------------- |
| Local CLI integration | stdio | Simple, direct process communication |
| VS Code extensions | stdio | Standard for desktop integrations |
| Claude Desktop | stdio | Standard for desktop integrations |
| Cursor IDE | stdio | Standard for desktop integrations |
| Web applications | http | Works over network, supports multiple clients |
| Docker containers | http | Better for containerized deployments |
| Development/debugging | http | Easy to test with curl/browser |
| Production servers | http | Scalable, supports load balancing |
| CI/CD pipelines | http | Better for automated environments |

🔒 Security Considerations

This plugin exposes your CLI commands to AI assistants through the MCP protocol. The latest 2025-06-18 specification includes enhanced security features:

$3

- 🔒 OAuth 2.1 Authorization: Complete OAuth 2.1 implementation with PKCE support
- 🛡️ Resource Indicators: RFC 8707 compliance for secure resource access
- 🔐 Session Management: Advanced HTTP session handling with automatic cleanup
- 🌐 CORS Protection: Enhanced cross-origin controls with origin validation
- 📋 Protocol Headers: Proper version negotiation and security headers

$3

- Local Development: When running locally, the plugin operates in your user context with your permissions
- Production Use: Only expose commands that are safe for AI assistants to execute
- HTTP Transport: Use OAuth 2.1 for secure remote access with proper authorization flows
- Sensitive Operations: Use the disableMCP flag for commands that perform sensitive operations

$3

`typescript
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
}
}
`

$3

`typescript
// 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',
}
`

$3

- ✅ Review exposed commands before deployment
- ✅ Use OAuth 2.1 for production HTTP deployments
- ✅ Implement Resource Indicators for secure token scoping
- ✅ Use tool annotations to clearly mark destructive operations
- ✅ Implement proper validation in your command handlers
- ✅ Monitor MCP usage in production environments
- ✅ Configure CORS properly for web integrations
- ⚠️ Avoid exposing commands that modify system-level configurations
- ⚠️ Be cautious with file operations that could affect sensitive data
- ⚠️ Use HTTPS for all production HTTP transport deployments

⚖️ AI Provider Tool Limits

Different AI providers have varying limits on the number of tools they can handle effectively:

| Provider | Tool Limit | Notes |
| ------------------ | ---------- | ------------------------------------- |
| VS Code | 128 tools | Hard limit enforced by the platform |
| Cursor | 40 tools | Hard limit enforced by the platform |
| Claude Desktop | unknown | Varies by model and subscription tier |
| ChatGPT | unknown | Varies by model and subscription tier |
| GitHub Copilot | unknown | Varies by model and subscription tier |

$3

To manage large CLIs with many commands, you can configure filtering to stay within these limits:

#### Basic Topic Filtering

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

#### Advanced Pattern Filtering

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

#### Environment-Based Configuration

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

#### Runtime Configuration

You can also configure filtering at runtime:

`bash


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

#### Filtering Strategies

- first - Include first N commands up to the limit
- prioritize - Include priority commands first, then others up to limit
- balanced - Try to include commands from all topics proportionally
- strict - Fail if filtered commands exceed limit

#### Auto-suggestions

When commands are filtered out due to limits, the plugin will log suggestions:

`
⚠️ 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
`

📚 Advanced Usage

$3

Override the default tool ID generation:

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

$3

Add MCP-compliant tool annotations to provide AI assistants with metadata about your command's behavior:

`typescript
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
}
}
`

$3

Create prompts with advanced argument validation:

`typescript
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
}
}
`

$3

Resources provide contextual data to AI assistants following the official MCP specification. Resources are automatically discoverable through the resources/list endpoint and fetched on-demand via resources/read. Our implementation includes 100% MCP compliance with:

- ✅ Direct Resources - Static resources with uri, name, description, mimeType, and size fields
- ✅ Resource Templates - Dynamic resources using RFC 6570 URI templates with uriTemplate field
- ✅ URI Template Resolution - Automatic parameter extraction and resolution (e.g., users://profile/{userId})
- ✅ Binary Resources - Support for both text and blob (base64) content types
- ✅ Multiple Resource Returns - Single resources/read can return multiple resources
- ✅ Resource Subscriptions - Full subscription tracking via resources/subscribe/resources/unsubscribe
- ✅ Real-time Notifications - Actual notifications/resources/updated and notifications/resources/list_changed
- ✅ URI Generation - Public API for programmatic URI creation from templates
- ✅ Server Capabilities - Proper capabilities declaration with subscription support

#### Static Resources

Perfect for configuration, documentation, or fixed data:

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

#### Resource Templates

Use URI templates following RFC 6570 for dynamic resource patterns:

`typescript
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',
},
]
}
}
`

#### Dynamic Resources with Function Handlers

Use function handlers for dynamic content generation:

`typescript
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',
}
}
}
`

#### Dynamic Resources via Static Methods

Generate resources programmatically:

`typescript
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(),
}
}
}
`

#### Instance Method Resources

Resources that need access to command instance:

`typescript
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
}
}
`

$3

`typescript
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'
}
}
`

#### Binary Resources and URI Templates

Advanced resource patterns with full MCP compliance:

`typescript
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)
`

#### Resource Notifications and URI Generation

Advanced MCP resource management with real-time updates:

`typescript
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 provide reusable templates that help AI assistants interact with your CLI more effectively. They follow the official MCP specification using prompts/list and prompts/get endpoints.

#### How Prompts Work

The plugin automatically implements the MCP prompts protocol:

1. Discovery: AI assistants call prompts/list to discover available prompts
2. Execution: AI assistants call prompts/get with prompt name and arguments
3. Response: Prompts return structured messages for LLM processing

#### Static Prompts

Define reusable prompt templates on your command classes:

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

#### Dynamic Prompts

Generate prompts programmatically based on current state:

`typescript
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 with Custom Handlers

Create prompts that generate dynamic responses:

`typescript
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(),
}
}
}
`

#### MCP Protocol Compliance

The prompts implementation follows the official MCP specification:

- ✅ prompts/list - Lists all available prompts with names, descriptions, and arguments
- ✅ prompts/get - Executes specific prompts with argument validation
- ✅ Argument validation - Ensures required arguments are provided
- ✅ Handler support - Function handlers, method references, and defaults
- ✅ Structured responses - Returns properly formatted message arrays for LLMs

$3

Roots provide workspace boundaries and context for AI assistants. You can define custom roots or use the automatic default working directory root.

#### Custom Roots

Define custom workspace roots in your commands:

`typescript
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',
},
]
}
`

#### Dynamic Roots

Generate roots programmatically:

`typescript
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'},
]
}
}
`

#### Instance Method Roots

Roots that need access to command instance:

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

#### Automatic Fallback Root

When no custom roots are defined, the plugin automatically registers your CLI's current working directory:

- URI: file://[current-working-directory]
- Name: "CLI Working Directory"
- Purpose: Provides AI assistants with workspace context for file operations

#### Benefits for AI Assistants

- Workspace Understanding: AI assistants know the project boundaries
- File Context: Better understanding of relative paths and project structure
- Security: Clear boundaries for file system access
- Navigation: Helps AI assistants understand the project layout
- Multi-workspace Support: Support for complex projects with multiple roots

$3

The MCP server automatically filters commands:

- ✅ hidden: false - Command must not be hidden
- ✅ disableMCP: true - Command must not disable MCP (default: false)
- ✅ cmdClass.pluginType === 'jit' - JIT (Just-In-Time) commands are automatically excluded from MCP exposure for security and stability reasons.
- ✅ Not the MCP command itself

🏗️ Architecture

`mermaid
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
`

🔄 MCP 2025-06-18 Protocol Compliance

This plugin implements the full MCP 2025-06-18 specification with enhanced compliance features:

| MCP Feature | Status | Implementation |
| --------------------------- | ----------- | ------------------------------------------------- |
| Protocol Version | ✅ Complete | MCP-Protocol-Version: 2025-06-18 headers |
| Tools | ✅ Complete | All oclif commands auto-discovered as tools |
| Tool Annotations | ✅ Complete | Support for readOnlyHint, destructiveHint, etc. |
| Resources | ✅ Complete | resources/list and resources/read endpoints |
| Static Resources | ✅ Complete | Direct content and URI registration with size |
| Dynamic Resources | ✅ Complete | Function and method handlers |
| Resource Templates | ✅ Complete | RFC 6570 URI templates with automatic resolution |
| Binary Resources | ✅ Complete | Buffer support with base64 encoding |
| URI Resolution | ✅ Complete | Parameter extraction from templated URIs |
| Multiple Resources | ✅ Complete | Single read request can return multiple resources |
| Resource Updates | ✅ Complete | Real-time MCP notifications for resource changes |
| URI Generation | ✅ Complete | Public API for programmatic URI template creation |
| Notification System | ✅ Complete | Full MCP notification protocol implementation |
| Prompts | ✅ Complete | Reusable prompt templates with argument support |
| Roots | ✅ Complete | CLI workspace directory as MCP root |
| Content Types | ✅ Complete | Proper MIME type handling |
| Error Handling | ✅ Complete | Graceful error responses |
| Schema Validation | ✅ Complete | Zod schema generation from oclif definitions |
| Input Validation | ✅ Enhanced | Full Zod validation for all tool arguments |
| JSON-RPC Errors | ✅ Enhanced | Proper MCP error codes (-32xxx) for all errors |
| Prompt Validation | ✅ Enhanced | Type-safe prompt argument parsing |
| Debounced Notifications | ✅ Enhanced | Optimized resource change notifications |
| Enhanced Prompts | ✅ Enhanced | Interactive assistant-style prompt responses |
| Sampling Capability | ✅ New | Server-side LLM interaction requests |
| Elicitation Support | ✅ New | User input and confirmation requests |
| Structured Logging | ✅ New | Advanced logging with level management |
| Progress Tracking | ✅ New | Enhanced progress tokens with cancellation |
| OAuth 2.1 Authorization | ✅ New | Complete OAuth 2.1 with PKCE support |
| Resource Indicators | ✅ New | RFC 8707 compliance for secure token usage |
| Session Management | ✅ New | Advanced HTTP session handling and cleanup |

📋 Examples

$3

`bash


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"

`

$3

`mermaid
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
`

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

$3

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

$3

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

$3

`bash


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

``

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT © Jonathan Jot

🙏 Acknowledgments

- oclif - The Open CLI Framework
- Model Context Protocol - Official MCP specification
- Anthropic - For developing and promoting MCP
- MCP TypeScript SDK - Official MCP implementation

---

🌟 Now fully MCP 2025-06-18 compliant with enhanced security and advanced capabilities - ready for the AI-powered CLI future!