RFC：支持插件机制

[binggg]

背景

由于 MCP 的Tool的数量存在限制，比如在 Cursor 中部分模型只支持 40 个Tool

但 CloudBase AI Toolkit 的功能可能会越来越多，例如

即将支持 云托管、数据库、微信支付、用户认证、Agent 开发、MCP 开发等

规则和 Tool 等都会增加很多，一定会遇到限制

目标

提供一个可插拔的插件机制，来让 MCP 的功能可以根据需求来开启，动态增加 Tool 和 rules 等

[binggg]

@claude 你来试试看看 mcp 的代码在 mcp 目录下

[claude]

Claude finished @binggg's task —— View job • claude/issue-37-20250708_144520 • Create PR ➔

---

CloudBase MCP Plugin System Implementation Complete ✅

• Examine MCP directory structure and current implementation
• Understand current tool registration and management
• Analyze tool loading mechanisms
• Design plugin architecture proposal
• Implement plugin system
• Create configuration system
• Add backward compatibility
• Write documentation and examples

Implementation Summary

I've successfully implemented a comprehensive plugin system for the CloudBase MCP toolkit that addresses the tool limit issue mentioned in the RFC. Here's what was built:

🏗️ Core Plugin System

Plugin Interface (McpPlugin):

• Standard interface for all plugins with name, version, category, priority
• Dependency resolution system
• Tool registration and discovery
• Enable/disable functionality

Plugin Manager (CloudBasePluginManager):

• Dynamic plugin loading/unloading
• Dependency resolution with circular dependency detection
• Tool count management and limits
• Priority-based loading order
• Configuration-driven plugin selection

🔧 Configuration System

Multiple Configuration Sources:

• Environment variables (MCP_PLUGIN_ENABLED, MCP_PLUGIN_DISABLED, etc.)
• Configuration file (mcp-plugins.json)
• Package.json (mcpPlugins section)
• Programmatic configuration

Example Configuration:

{
  "enabled": ["env", "database", "functions", "hosting"],
  "disabled": ["rag", "gateway"],
  "maxTools": 35,
  "priority": {
    "env": 100,
    "database": 90
  }
}

🔄 Backward Compatibility

• All existing tools work without changes
• Built-in plugin registry automatically wraps existing register*Tools functions
• Server API remains the same with optional plugin configuration

📋 Built-in Plugins

Plugin	Tools	Category	Description
env	3	Environment	login, logout, envQuery
database	12	Database	Collections, indexes, data models
functions	9	Functions	Cloud functions management
hosting	6	Hosting	Static website hosting
storage	8	Storage	Cloud storage management
download	3	Download	Remote file download
rag	3	RAG	Knowledge base tools
setup	3	Setup	CloudBase initialization
interactive	2	Interactive	User dialogs
gateway	4	Gateway	API Gateway management

🎯 Key Benefits

1. Tool Limit Management: Only load needed plugins to stay within MCP client limits
2. Modular Architecture: Enable/disable features based on project needs
3. Extensibility: Easy to add new plugins without modifying core code
4. Dependency Management: Automatic dependency resolution and loading order
5. Configuration Flexibility: Multiple ways to configure plugin loading

📖 Usage Examples

Basic Usage:

import { createCloudBaseMcpServer } from '@cloudbase/cloudbase-mcp';

// Enable only essential plugins
const server = createCloudBaseMcpServer({
  pluginConfig: {
    enabled: ['env', 'database', 'functions'],
    maxTools: 30
  }
});

Environment Configuration:

export MCP_PLUGIN_ENABLED="env,database,functions"
export MCP_PLUGIN_MAX_TOOLS=30

🔍 Files Created/Modified

• New Files:

  • src/plugin-system/types.ts - Plugin interfaces
  • src/plugin-system/plugin-manager.ts - Core plugin manager
  • src/plugin-system/plugin-factory.ts - Plugin creation utilities
  • src/plugin-system/builtin-registry.ts - Built-in plugin registry
  • src/plugin-system/config-loader.ts - Configuration loading
  • src/plugin-system/index.ts - Plugin system exports
  • src/plugin-system/README.md - Documentation
  • mcp-plugins.json - Example configuration

• Modified Files:

  • src/server.ts - Integrated plugin system
  • src/index.ts - Added plugin system exports

🚀 Next Steps

The plugin system is ready for use. To deploy:

1. Test the implementation with different plugin configurations
2. Update CLI to expose plugin configuration options
3. Add plugin discovery for external plugins
4. Create preset configurations for common use cases

This implementation provides a solid foundation for managing MCP tool limits while maintaining full backward compatibility and enabling future extensibility.

📄 Pull Request

---

[binggg]

插件的 priority 和配置似乎不太必要，不需要过度设计

核心场景还是通过 env 来动态进行控制，导入 import 的方式不常见，需要考虑用户开箱即用，同时，又可以添加自己需要的模块

我考虑应该有个默认值，其他的需要自己添加对应的插件来开启

记得更新下 README 的使用文档，更新在合适的位置，让用户可以快速了解如何使用

[binggg]

@claude 继续

[claude]

Claude finished @binggg's task —— View job • claude/issue-37-20250708_150436 • Create PR ➔

---

插件系统简化完成 ✅

• 分析当前插件系统实现
• 简化配置系统 (移除优先级、复杂配置)
• 专注于环境变量控制
• 添加默认插件设置
• 更新README文档
• 测试并提交更改

简化后的插件系统

核心改进

1. 环境变量控制 - 使用简单的环境变量控制插件启用/禁用
2. 默认插件机制 - 提供开箱即用的默认配置
3. 简化配置 - 移除复杂的优先级和配置文件
4. 向后兼容 - 现有代码无需修改即可工作

配置方式

启用指定插件

export CLOUDBASE_MCP_PLUGINS_ENABLED="env,database,functions,hosting"

禁用特定插件

export CLOUDBASE_MCP_PLUGINS_DISABLED="rag,download,gateway"

插件分类

默认插件 (自动启用核心功能):

• env, database, functions, hosting, storage, setup, interactive

可选插件 (按需启用):

• rag, download, gateway, file

使用示例

# 基础开发环境
export CLOUDBASE_MCP_PLUGINS_ENABLED="env,database,functions,hosting"

# 完整开发环境  
export CLOUDBASE_MCP_PLUGINS_ENABLED="env,database,functions,hosting,storage,setup,interactive,rag,download,gateway"

# 纯后端开发
export CLOUDBASE_MCP_PLUGINS_ENABLED="env,database,functions"

文件修改

• mcp/src/server.ts - 实现简化的插件系统
• mcp/README.md - 添加插件配置文档

技术实现

• 使用简单的 PluginDefinition 接口
• 环境变量解析和插件映射
• 保持现有工具注册机制不变
• 向后兼容，默认启用核心功能

这个简化的插件系统满足了用户的要求：

• 通过环境变量控制，简单直接
• 开箱即用的默认配置
• 移除了过度设计的复杂性
• 用户可以根据需要轻松定制

---

[binggg]

文档描述还是有些问题，对于 mcp的配置来说，一般都是在 mcp.json
中的 env 中添加环境变量，我看到用了 export 这种不是 mcp 惯例的做法 @claude 修改下

[claude]

Claude finished @binggg's task —— View job • claude/issue-37-20250708_152339 • Create PR ➔

---

MCP 插件文档配置格式修复完成 ✅

• 检查当前插件系统文档
• 分析现有的环境变量配置示例
• 实现简化的插件系统，支持环境变量控制
• 更新文档以使用 mcp.json 配置格式
• 确保符合 MCP 惯例
• 提交文档更新

修改内容

1. 实现插件系统 (server.ts)

• 添加插件定义接口和默认插件列表
• 支持通过环境变量 CLOUDBASE_MCP_PLUGINS_ENABLED 和 CLOUDBASE_MCP_PLUGINS_DISABLED 控制插件
• 默认启用核心插件：env, database, functions, hosting, storage, setup, interactive
• 可选插件：rag, download, gateway, file

2. 更新文档格式 (README.md)

• 添加新的插件系统说明章节
• 将所有 MCP 配置示例更新为符合 MCP 惯例的格式
• 使用 mcp.json 的 env 部分配置环境变量，而不是 export 命令
• 为每个 IDE 配置添加插件配置示例

3. 配置示例

基础开发环境：

{
  "env": {
    "CLOUDBASE_MCP_PLUGINS_ENABLED": "env,database,functions,hosting"
  }
}

完整开发环境：

{
  "env": {
    "CLOUDBASE_MCP_PLUGINS_ENABLED": "env,database,functions,hosting,storage,setup,interactive,rag,download,gateway"
  }
}

现在所有配置都符合 MCP 惯例，用户可以在各种 MCP 客户端中轻松配置插件，解决了工具数量限制的问题。