Cobra MCP

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.Command

NewChatCommand

通过工具调用为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" 模式。

解决：

1. 使用 "auto" 执行模式 （推荐）自动执行命令 Run: 在子流程中-无警告，无需更改代码
2. 使用 "sub-process" 执行模式 执行子进程中的所有命令-最安全的选项
3. 使用 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文件。