关键词

CLI集成AI工具Cobra框架LLM上下文外部功能调用

项目简介

Ophis是一个Go语言框架，旨在帮助开发者快速将现有的Cobra命令行界面（CLI）应用程序转换为MCP服务器。通过Ophis，您的CLI命令可以被大型语言模型（LLM）客户端（如Claude Desktop或VSCode Copilot）识别为可调用的工具，从而实现AI助手与您的CLI应用程序的无缝交互。它处理了MCP协议的复杂性、命令执行和工具注册，极大地简化了MCP服务器的搭建过程。

主要功能点

  • 自动化工具转换： 自动将Cobra CLI中的命令解析并转换为符合MCP规范的工具，包括命令名称、描述、参数和标志。
  • 灵活的工具过滤： 支持通过白名单、黑名单、隐藏命令过滤或自定义逻辑来控制哪些CLI命令暴露为MCP工具。
  • 自定义输出处理： 允许开发者定义自定义处理器来格式化CLI命令的输出，例如将文本输出转换为图像、JSON或其他MCP客户端支持的富媒体格式。
  • 多平台集成支持： 提供简便的CLI命令，用于配置Claude Desktop和VSCode，使其能够发现并连接到由Ophis驱动的MCP服务器。
  • JSON-RPC通信： 服务器通过JSON-RPC协议与客户端通信，实现上下文信息的提供和工具调用。
  • Stdio传输协议： 默认支持Stdio传输协议，方便与各种LLM客户端集成。

安装步骤

在您的Go项目中，通过以下命令引入Ophis：

go get github.com/njayp/ophis

然后，在您的Cobra CLI应用程序的'main()'函数中，添加Ophis提供的MCP服务器命令：

package main

import (
    "os"
    "github.com/njayp/ophis"
    "github.com/spf13/cobra"
)

func createMyRootCommand() *cobra.Command {
    // 您的Cobra根命令定义
    rootCmd := &cobra.Command{
        Use:   "my-cli",
        Short: "我的自定义CLI工具",
        Long:  "一个用于演示的CLI应用程序。",
    }
    // 添加一些示例命令
    rootCmd.AddCommand(&cobra.Command{
        Use:   "hello",
        Short: "打招呼",
        Run: func(cmd *cobra.Command, args []string) {
            cmd.Println("Hello from my-cli!")
        },
    })
    return rootCmd
}

func main() {
    rootCmd := createMyRootCommand()
    
    // 添加MCP服务器命令，可以传入nil使用默认配置
    rootCmd.AddCommand(ophis.Command(nil))
    
    if err := rootCmd.Execute(); err != nil {
        os.Exit(1)
    }
}

编译您的应用程序：

go build -o my-cli .

服务器配置

MCP服务器的配置是用于告知MCP客户端如何启动和连接到Ophis生成的MCP服务器。这些配置通常以JSON格式存储在MCP客户端（如Claude或VSCode）的配置文件中。以下是两个MCP客户端所需的典型配置信息：

1. Claude Desktop 配置示例 Claude Desktop通常会在其配置文件（例如 'claude_desktop_config.json'）中添加如下JSON对象，用于启动MCP服务器：

{
  "mcpServers": {
    "your-cli-name": {
      "command": "/path/to/your/my-cli",
      "args": [
        "mcp",
        "start",
        "--log-level",
        "info"
      ],
      "env": {}
    }
  }
}
  • 'your-cli-name': 您自定义的MCP服务器名称，通常会从可执行文件名称派生。
  • 'command': 指向您的CLI可执行文件的绝对路径。
  • 'args': 启动MCP服务器所需的参数列表。'mcp start' 是启动Ophis MCP服务器的核心命令，'--log-level info' 是可选的日志级别参数。
  • 'env': 可选的环境变量。

2. VSCode Copilot 配置示例 VSCode Copilot（在Agent模式下）会在其配置文件（例如 '.vscode/mcp.json' 或用户设置）中添加如下JSON对象：

{
  "servers": {
    "your-cli-name": {
      "type": "stdio",
      "command": "/path/to/your/my-cli",
      "args": [
        "mcp",
        "start",
        "--log-level",
        "info"
      ],
      "env": {},
      "url": "",
      "headers": {}
    }
  }
}
  • 'your-cli-name': 您自定义的MCP服务器名称，通常会从可执行文件名称派生。
  • 'type': 服务器的传输协议类型，Ophis默认为 'stdio'。
  • 'command': 指向您的CLI可执行文件的绝对路径。
  • 'args': 启动MCP服务器所需的参数列表。'mcp start' 是启动Ophis MCP服务器的核心命令，'--log-level info' 是可选的日志级别参数。
  • 'env': 可选的环境变量。
  • 'url', 'headers': 对于Stdio类型服务器通常为空，用于其他传输协议。

请注意： 上述JSON配置是示例，实际配置会根据您的应用程序名称和安装路径自动生成。Ophis提供了内置的命令 ('mcp claude enable' 和 'mcp vscode enable') 来自动生成和更新这些配置。

基本使用方法

  1. 构建您的CLI应用程序： 首先，确保您的Cobra CLI应用程序已经集成了'ophis.Command(nil)'并且已成功编译成可执行文件（例如 './my-cli'）。

  2. 启用MCP服务器集成：

    • 对于Claude Desktop： 运行以下命令，Ophis将自动配置Claude Desktop以识别您的CLI作为MCP服务器。 
      ./my-cli mcp claude enable
# 之后，重启Claude Desktop以加载新的配置。
    • 对于VSCode Copilot： 运行以下命令，Ophis将自动配置VSCode以识别您的CLI作为MCP服务器。 
      ./my-cli mcp vscode enable
# 确保Copilot处于Agent模式，并重启VSCode或重新加载窗口以应用配置。

  3. 使用AI助手调用CLI命令： 配置完成后，您就可以在Claude Desktop或VSCode Copilot中与AI助手交互。AI助手会识别您的CLI命令为可用工具，并可以在对话中根据需要调用它们。例如，如果您的CLI有一个 'my-cli hello' 命令，您可以在AI助手中说 "请调用 hello 命令"，AI助手就能执行它。

  4. 自定义工具暴露和输出： 您可以在 'ophis.Command()' 中传入 'ophis.Config' 对象来自定义工具的生成和输出处理。例如，您可以指定只暴露某些命令，或者将命令的输出格式化为JSON或图像。

    import (
    "log/slog"
    "github.com/njayp/ophis"
    "github.com/njayp/ophis/tools"
    "github.com/mark3labs/mcp-go/mcp"
    "context"
)

// 自定义输出处理器示例
myCustomHandler := func(ctx context.Context, request mcp.CallToolRequest, data []byte, err error) (*mcp.CallToolResult, error) {
    if err != nil {
        return mcp.NewToolResultError(err.Error()), nil
    }
    // 例如，将所有输出视为JSON
    return mcp.NewToolResultJSON(data), nil
}

config := &ophis.Config{
    GeneratorOptions: []tools.GeneratorOption{
        tools.Allow([]string{"get", "list"}), // 只暴露 'get' 和 'list' 命令
        tools.WithHandler(myCustomHandler),   // 使用自定义输出处理器
    },
    SloggerOptions: &slog.HandlerOptions{
        Level: slog.LevelDebug, // 设置日志级别为Debug
    },
}
rootCmd.AddCommand(ophis.Command(config))

信息

分类

开发者工具

访问项目