Cobra MCP库
一个可插拔的库，使任何基于Cobra的CLI应用程序能够将其命令结构作为模型上下文协议（MCP）工具公开，并提供AI聊天功能。
特性
- 零配置：自动发现并公开所有Cobra命令作为MCP工具
- 分层工具结构：按操作（创建、列出、描述等）对命令进行分组，以减少工具数量
- 智能系统消息：自动生成详细的系统消息，解释工具使用模式
- 丰富的工具模式：将标志描述和枚举值直接包含在工具模式中，以提高AI的准确性
- 危险指挥安全：配置在执行前需要明确确认的危险命令
- 调试模式：聊天客户端包括调试模式，用于显示工具调用和参数
- 可插拔架构：只需最小的代码更改，即可轻松集成到任何现有的Cobra CLI中
- 双模式：支持MCP服务器（用于MCP客户端）和聊天客户端（用于直接AI交互）
- 灵活执行：支持进程内执行（快速）和子进程执行（不受os.Exit（）的影响）
- 自动检测：使用自动检测命令
Run:并在子流程中执行它们以防止终止
安装
go get github.com/paulczar/cobra-mcp/pkg快速开始
基本集成
package main
import (
"github.com/spf13/cobra"
cobra_mcp "github.com/paulczar/cobra-mcp/pkg"
)
func main() {
rootCmd := &cobra.Command{
Use: "mycli",
Short: "My CLI tool",
}
// Register your commands...
rootCmd.AddCommand(createCmd)
rootCmd.AddCommand(listCmd)
// Add MCP commands (these are added directly to root, not under a subcommand)
rootCmd.AddCommand(cobra_mcp.NewMCPCommand(rootCmd, &cobra_mcp.ServerConfig{
Name: "mycli-mcp-server",
ToolPrefix: "mycli",
}))
rootCmd.AddCommand(cobra_mcp.NewChatCommand(rootCmd, &cobra_mcp.ChatConfig{
Model: "gpt-4",
}))
rootCmd.Execute()
}用法
MCP服务器
通过stdin启动MCP服务器：
mycli mcp start通过HTTP启动MCP服务器：
mycli mcp stream --port 8080将可用的MCP工具导出为JSON：
mycli mcp tools聊天客户端
启动交互式聊天会话：
mycli chat --api-key YOUR_API_KEY或者使用环境变量：
export OPENAI_API_KEY=your_key
mycli chat处理单个消息：
mycli chat --message "List all clusters"启用调试模式以查看工具调用和参数：
mycli chat --debug --message "Create a cluster"从stdin读取：
echo "List clusters" | mycli chat --stdin打印系统消息：
mycli chat system-message配置
服务器配置
config := &cobra_mcp.ServerConfig{
Name: "mycli-mcp-server",
Version: "1.0.0",
ToolPrefix: "mycli",
EnableResources: true,
CustomActions: []string{"create", "list", "describe", "delete"},
StandaloneCmds: []string{"version", "help"},
// Dangerous commands that require explicit confirmation
DangerousCommands: []string{"delete", "destroy"},
// Execution mode: "in-process" (default), "sub-process", or "auto"
ExecutionMode: "auto", // Auto-detect: use sub-process for commands with Run:, in-process for RunE:
}聊天配置
config := &cobra_mcp.ChatConfig{
APIKey: "your-api-key",
APIURL: "", // Optional custom API URL
Model: "gpt-4",
Debug: false, // Enable debug output showing tool calls and parameters
SystemMessage: "", // Optional custom system message (overrides generated message)
SystemMessageFile: "", // Optional file path for system message (overrides generated message)
SystemMessageAppend: "", // Optional content to append to generated system message
}示例：将自定义指令附加到系统消息中
rootCmd.AddCommand(cobra_mcp.NewChatCommand(rootCmd, &cobra_mcp.ChatConfig{
Model: "gpt-4",
SystemMessageAppend: `OUTPUT LIMITATION:
When listing clusters or other resources, always use the following flags to limit output:
- Use --parameter size=10 to limit results to 10 items
- Use --columns to specify only essential columns (e.g., --columns "id,name,state")
- Combine both flags to minimize token usage`,
}))这会将您的自定义说明附加到自动生成的系统消息中，允许您添加特定于CLI的指导，而无需覆盖整个消息。
api参考
新MCP命令
使用MCP子命令创建新的Cobra命令组(mcp start, mcp stream, mcp tools).
func NewMCPCommand(rootCmd *cobra.Command, config *ServerConfig) *cobra.Command该命令提供三个子命令：
mcp start-通过stdin/stdout启动MCP服务器mcp stream-通过HTTP启动MCP服务器（使用--port标志，默认值：8080）mcp tools-将可用的MCP工具导出为JSON
NewMCPServeCommand（已弃用）
创建一个新的Cobra命令，用于通过stdio或HTTP为MCP提供服务。 已弃用：使用 NewMCPCommand 相反。
func NewMCPServeCommand(rootCmd *cobra.Command, config *ServerConfig) *cobra.CommandNewChatCommand
通过工具调用为AI聊天创建新的Cobra命令。
func NewChatCommand(rootCmd *cobra.Command, config *ChatConfig) *cobra.Command生成系统消息
为聊天客户端生成系统消息。
func GenerateSystemMessage(config *SystemMessageConfig) string新建服务器
创建新的MCP服务器实例。
func NewServer(rootCmd *cobra.Command, config *ServerConfig) *Server新聊天客户端
创建新的聊天客户端实例。
func NewChatClient(server *Server, config *ChatConfig) (*ChatClient, error)最佳实践
执行模式
该库支持三种执行模式来处理可能调用的命令 os.Exit():
"in-process"（默认）：在进程中直接执行所有命令以获得最佳性能。快速但易受攻击os.Exit()电话。"sub-process"：执行子进程中的所有命令。更安全（不能杀死父进程），但由于进程生成开销，速度较慢。"auto"：使用自动检测命令Run:（没有RunE:)并在子进程中执行它们，同时使用进程内命令RunE:两全其美。
推荐：使用 "auto" 自动防护模式 os.Exit() 同时保持安全命令的性能：
config := &cobra_mcp.ServerConfig{
ExecutionMode: "auto", // Auto-detect and protect against os.Exit()
}错误处理-避免 os.Exit()
⚠️ 重要：默认情况下，通过MCP/聊天执行的命令会运行 过程中的。如果您的命令调用 os.Exit()，它会 终止整个MCP服务器或聊天客户端进程，阻止进一步的互动。
备注：使用时 ExecutionMode: "auto" 或 ExecutionMode: "sub-process"图书馆将 不 显示有关使用以下命令的警告 Run: 因为这些模式会自动防止 os.Exit() 电话。警告仅在默认情况下出现 "in-process" 模式。
解决：
- 使用
"auto"执行模式 （推荐）自动执行命令Run:在子流程中-无警告，无需更改代码 - 使用
"sub-process"执行模式 执行子进程中的所有命令-最安全的选项 - 使用
RunE:而不是Run:返回错误而不是调用os.Exit()-新代码的最佳实践
使用 RunE: 而不是 Run: 返回错误而不是调用 os.Exit():
// ❌ BAD - os.Exit() terminates the MCP/chat process
var listCmd = &cobra.Command{
Use: "list",
Run: func(cmd *cobra.Command, args []string) {
if err := doSomething(); err != nil {
fmt.Fprintf(os.Stderr, "Error: %v\n", err)
os.Exit(1) // ❌ This kills the MCP server!
}
},
}
// ✅ GOOD - Returns error instead
var listCmd = &cobra.Command{
Use: "list",
RunE: func(cmd *cobra.Command, args []string) error {
if err := doSomething(); err != nil {
return fmt.Errorf("error: %w", err) // ✅ Error is handled gracefully
}
return nil
},
}为什么这很重要：
- 命令的执行过程与MCP服务器/聊天客户端相同（默认情况下
"in-process"模式） os.Exit()立即终止整个进程（无清理，无返回）- 执行器无法捕获输出或在以下时间后继续会话
os.Exit()在进程模式下 - 使用
RunE:允许正确的错误处理，会话继续 - 使用
"auto"或"sub-process"执行模式隔离调用的命令os.Exit()并防止父进程终止
警告行为：
- 关于使用以下命令的警告
Run:是 仅显示 当ExecutionMode是"in-process"（默认） - 使用时
ExecutionMode: "auto"或"sub-process"，不显示警告，因为这些模式可以防止os.Exit() - 警告信息建议使用
ExecutionMode: "auto"或"sub-process"作为迁移命令的替代方案
备注：使用以下命令自动检测子进程执行的可执行路径 os.Executable() （当前运行的二进制文件）。无需配置。
指挥输出
在Cobra命令中写入命令输出时， 更喜欢使用 cmd.Println() 或 cmd.Printf() 而不是 fmt.Println() 或直接写信至 os.Stdout:
// ✅ Preferred - respects output redirection
cmd.Println(`{"id": "cluster-123"}`)
// ✅ Also works - captured automatically
fmt.Println(`{"id": "cluster-123"}`)库会自动捕获Cobra的两种输出方法(cmd.Println, cmd.Printf等）和直接写入(fmt.Println, os.Stdout.Write等等）以确保兼容性。然而，使用 cmd.Println 建议如下：
- 尊重输出重定向（对MCP协议很重要）
- 遵循Cobra最佳实践
- 与Cobra的所有功能一起正常工作
标志说明
库会自动提取标志描述并将其包含在工具模式中。为了提高AI的准确性：
- 提供详细的标志说明：在描述中包含枚举值（例如。，
"Cluster size: Small, Medium, or Large (required)") - 使用清晰的描述：AI使用标志描述来了解每个标志的作用
- 标记所需标志：使用
cmd.MarkFlagRequired()因此，人工智能知道哪些标志是强制性的
例子：
createCmd.Flags().String("size", "", "Cluster size: Small, Medium, or Large (required)")
createCmd.MarkFlagRequired("size")库将自动：
- 从描述中提取枚举值（“小”、“中”、“大”）
- 在工具架构中包含标志描述
- 在架构中标记所需的标志
示例
请参阅 examples/ 完整示例目录：
examples/basic/-基本集成示例examples/advanced/-高级定制示例
实施指南
有关将MCP和聊天功能集成到现有Cobra CLI的详细分步说明，请参阅 实施.md.
本指南专为AI编码代理和开发人员设计，提供：
- 分步集成说明
- 指挥结构分析
- 配置示例
- 常见模式和故障排除
- 完整的代码示例
更新日志
看 更改日志.md 查看更改和版本历史记录列表。
许可证
有关详细信息，请参阅LICENSE文件。