🔌 oclif-plugin-mcp-server

将任何 oclif CLI 转换为完全符合 MCP 2025-06-18 协议的服务器，以实现与 AI 助手的无缝集成

此插件会自动将您的 oclif CLI 命令转换为一个 完全符合 MCP 2025-06-18 协议的服务器，实现了最新的 模型上下文协议规范。它允许像 Claude、ChatGPT 和 Cursor 这样的 AI 助手通过对话自然地发现并执行您的 CLI 工具。

✨ MCP 2025-06-18 新特性

🎉 最新 MCP 规范：完全符合 MCP 2025-06-18 包括：

• 🔒 OAuth 2.1 授权：支持带有 PKCE 的 OAuth 2.1，用于安全的 HTTP 传输
• 🔄 采样能力：服务器端的 LLM 交互请求，用于高级 AI 工作流
• ❓ 引出支持：从客户端请求额外的用户输入和确认
• 📝 结构化日志：具有级别管理和通知的高级日志功能
• ⏳ 进度跟踪：增强的进度跟踪，支持取消操作
• 🌐 协议版本头：完整的 MCP-Protocol-Version: 2025-06-18 头支持
• 🛡️ 增强的安全性：资源指示符（RFC 8707）和改进的授权流程

什么是 MCP？

模型上下文协议 (MCP) 是一个开放标准，使 AI 助手能够安全地连接到外部数据源和工具。有了 MCP，您的 CLI 成为了 AI 工作流中的一等公民，助手可以：

• 🔍 发现您的命令和资源
• ✅ 验证输入，使用类型安全的模式
• 🚀 执行命令，并正确处理错误
• 📊 访问资源，支持惰性加载和适当的元数据
• 🔒 安全交互，通过标准化协议

🚀 特性

核心 MCP 2025-06-18 功能

• 🔍 自动发现：自动发现并公开 oclif 命令作为 MCP 工具
• 📝 模式生成：将 oclif 参数和标志转换为 Zod 模式，进行类型安全执行
• 📊 MCP 兼容资源：全面支持静态和动态资源，遵循 MCP 规范
• 🎯 提示模板：可重用的提示模板，带参数验证和处理器
• 🌳 工作区根目录：自动注册 CLI 工作目录为 MCP 根目录
• 🔄 惰性加载：通过适当的 MCP 端点按需获取资源
• 🛡️ 错误处理：优雅的错误处理，提供详细的反馈和适当的 JSON-RPC 错误码
• ⚙️ 零配置：开箱即用地适用于任何 oclif CLI
• 📋 标准兼容：实现官方 MCP 2025-06-18 规范
• ✅ 输入验证：对所有命令和提示进行类型安全的参数验证
• 🔔 智能通知：优化性能的资源更改通知

MCP 2025-06-18 新增内容

• 🔒 OAuth 2.1 安全：完整的 OAuth 2.1 授权服务器集成，支持 PKCE
• 🔄 采样支持：服务器端的 LLM 交互请求能力
• ❓ 引出框架：通过客户端请求用户输入和确认
• 📝 结构化日志：具有级别管理和客户端通知的高级日志
• ⏳ 进度跟踪：增强的进度标记，支持取消操作
• 🌐 协议头：正确的 MCP-Protocol-Version: 2025-06-18 头处理
• 🛡️ 增强授权：资源指示符（RFC 8707），用于安全令牌使用
• 🔐 会话管理：先进的 HTTP 会话处理，包括清理和监控

📦 安装

在您的 CLI 代码中嵌入插件（推荐）

在您的 CLI 的 package.json 中添加：

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

从 GitHub 安装

# 直接从 GitHub 安装（需要 oclif-plugin-plugins）
your-cli plugins install npjonath/oclif-plugin-mcp-server

# 验证安装
your-cli mcp --help

🎯 快速开始

1. 配置 AI 助手

将您的 CLI 添加到 AI 助手的 MCP 配置中：

Cursor (mcp.json)

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

Claude Desktop

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

使用此插件进行本地开发

1. 构建您的 CLI：yarn build
2. 生成清单：npx oclif manifest
3. 更新您的 MCP 配置：

Stdio 传输（默认）：

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

HTTP 传输：

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

2. 开始聊天

您的 AI 助手现在可以发现并使用您的 CLI 命令和资源：

👤 "将 my-app 部署到 staging 并显示部署日志"
🤖 "我将把您的应用程序部署到 staging 并获取部署日志。"

   执行：deploy my-app --environment staging
   ✅ 正在将 my-app 部署到 staging

   获取资源：logs://deployment/my-app
   📊 部署成功完成！
   🔍 日志：[部署详情...]

🌐 传输协议

此插件支持 官方规范 中定义的两种 MCP 传输协议：

📡 标准输入/输出（stdio）- 默认

本地集成和命令行工具的默认传输方式。

# 使用 stdio 传输启动 MCP 服务器（默认）
your-cli mcp
your-cli mcp --transport stdio

适合：

• 本地集成（Claude Desktop，Cursor）
• 命令行工具
• 简单进程通信
• Shell 脚本

🌐 可流式传输的 HTTP 传输

基于 HTTP 的传输，使用服务器发送事件（SSE）进行 Web 集成。

# 使用 HTTP 传输启动 MCP 服务器
your-cli mcp --transport http --port 3000 --host 127.0.0.1

适合：

• 基于 Web 的集成
• HTTP 上的客户端-服务器通信
• 有状态会话
• 多个并发客户端
• 可恢复连接
• Docker 容器

HTTP 传输特性

• JSON-RPC over HTTP：通过 POST 请求进行客户端到服务器的通信
• 服务器发送事件（SSE）：通过 GET 请求进行服务器到客户端的通信
• 会话管理：带有 X-Session-Id 头的状态会话
• 协议头：所有响应中的 MCP-Protocol-Version: 2025-06-18
• OAuth 2.1 集成：带有 PKCE 支持的安全授权
• 可恢复性：事件 ID 和 Last-Event-ID 头支持
• CORS 支持：可配置的跨域资源共享，带有安全控制
• 健康检查：带有协议版本的 /health 端点用于监控

HTTP 端点

• POST / - JSON-RPC 请求（客户端到服务器）
• GET /events/:sessionId - SSE 流（服务器到客户端）
• DELETE /sessions/:sessionId - 会话终止
• GET /health - 带有协议版本的健康检查
• GET /oauth/authorize - OAuth 2.1 授权端点（如果已配置）
• GET /oauth/callback - OAuth 2.1 回调端点（如果已配置）

HTTP 传输示例

# 列出可用工具
curl -X POST http://localhost:3000/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# 调用工具
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}'

# 订阅 SSE 流以接收会话更新
curl -N http://localhost:3000/events/your-session-id \
  -H "Accept: text/event-stream"

# 带有协议版本的健康检查
curl http://localhost:3000/health
# 响应：{"status":"ok"}，带有 MCP-Protocol-Version: 2025-06-18 头

# OAuth 授权流程（如果已配置）
curl http://localhost:3000/oauth/authorize?session_id=your-session

Web 客户端集成

// 初始化支持 2025-06-18 的 HTTP MCP 客户端
const client = new MCPClient({
  transport: 'http',
  endpoint: 'http://localhost:3000/',
  protocolVersion: '2025-06-18',
  // 可选的 OAuth 配置
  oauth: {
    authorizationUrl: 'http://localhost:3000/oauth/authorize',
    callbackUrl: 'http://localhost:3000/oauth/callback',
  },
})

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

传输选择指南

使用场景	推荐传输	原因
本地 CLI 集成	stdio	简单、直接的进程通信
VS Code 扩展	stdio	桌面集成的标准
Claude Desktop	stdio	桌面集成的标准
Cursor IDE	stdio	桌面集成的标准
Web 应用程序	http	通过网络工作，支持多个客户端
Docker 容器	http	对容器化部署更好
开发/调试	http	使用 curl/浏览器容易测试
生产服务器	http	可扩展，支持负载均衡
CI/CD 管道	http	对自动化环境更好

🔒 安全注意事项

此插件通过 MCP 协议将您的 CLI 命令暴露给 AI 助手。最新的 2025-06-18 规范包括增强的安全功能：

MCP 2025-06-18 增强安全性

• 🔒 OAuth 2.1 授权：带有 PKCE 支持的完整 OAuth 2.1 实现
• 🛡️ 资源指示符：RFC 8707 合规，用于安全资源访问
• 🔐 会话管理：带有自动清理的先进 HTTP 会话处理
• 🌐 CORS 保护：增强的跨域控制，带有来源验证
• 📋 协议头：适当的版本协商和安全头

信任边界

• 本地开发：当本地运行时，插件在您的用户上下文中运行，具有您的权限
• 生产使用：仅暴露 AI 助手可以安全执行的命令
• HTTP 传输：使用 OAuth 2.1 进行安全远程访问，带有适当的授权流程
• 敏感操作：对于执行敏感操作的命令，使用 disableMCP 标志

命令安全性

export default class SensitiveCommand extends Command {
  static description = '此命令执行敏感操作'
  static disableMCP = true // 🔒 不暴露给 MCP

  async run() {
    // 不应暴露给 AI 的敏感操作
  }
}

OAuth 2.1 配置

// 为安全的 HTTP 传输配置 OAuth
const oauthConfig = {
  authorizationServer: 'https://your-auth-server.com',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret', // 公共客户端可选
  tokenEndpoint: 'https://your-auth-server.com/token',
  scope: 'mcp:read mcp:write',
}

推荐实践

• ✅ 审查暴露的命令在部署前
• ✅ 使用 OAuth 2.1进行生产 HTTP 部署
• ✅ 实现资源指示符进行安全令牌范围
• ✅ 使用工具注释明确标记破坏性操作
• ✅ 在命令处理器中实现适当的验证
• ✅ 监控生产环境中的 MCP 使用
• ✅ 为 Web 集成正确配置 CORS
• ⚠️ 避免暴露修改系统级配置的命令
• ⚠️ 谨慎处理可能影响敏感数据的文件操作
• ⚠️ 使用 HTTPS进行所有生产 HTTP 传输部署

⚖️ AI 提供商工具限制

不同的 AI 提供商对有效处理的工具数量有不同的限制：

提供商	工具限制	备注
VS Code	128 个工具	平台强制执行的硬限制
Cursor	40 个工具	平台强制执行的硬限制
Claude Desktop	未知	根据模型和订阅层级变化
ChatGPT	未知	根据模型和订阅层级变化
GitHub Copilot	未知	根据模型和订阅层级变化

命令过滤配置

为了管理具有许多命令的大 CLI，您可以配置过滤以保持在这些限制内：

基本主题过滤

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

高级模式过滤

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

基于环境的配置

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