MCP Server Govbox

MCP Server Govbox

一个 MCP（Model Context Protocol）服务器，旨在帮助将大语言模型（LLM）与 Govbox 项目的 Rakefile 任务集成。

📋 关于项目

此服务器充当 LLM 与 Rake 命令之间的桥梁，使语言模型能够以安全、可控的方式执行自动化任务。该项目旨在简化 Rake 命令的执行，让用户无需预先了解具体命令即可使用。

🎯 目标

主要目标是让 LLM 能够：

• 以编程方式执行 Rakefile 任务
• 自动化常见流程
• 减少对 Rake 命令专业知识的需求
• 提供用于执行任务的标准化接口

🚀 功能

• 安全、可控地执行任务
• 支持多个项目
• 以标准格式返回结果
• 强大的错误处理机制

🛠️ 使用的技术

• 使用 Go (Golang) 构建 MCP 服务器
• 使用 Ruby/Rake 执行任务
• 使用 Docker 进行容器化

⚙️ 安装与配置

📦 第 1 步：获取代码

• 克隆代码仓库

git clone https://github.com/giovanoh/mcp-server-govbox.git
cd mcp-server-govbox

🔨 第 2 步：构建

• 使用 Docker

docker build -t mcp-server-govbox .

• 在本地运行

go build cmd/app/main.go

🔧 第 3 步：配置服务器

服务器使用环境变量进行配置。必须配置所有环境变量，服务器才能正常运行。首先：

cp .env.example .env
# Edite o arquivo .env com suas configurações

需要设置以下环境变量：

• MCP_GOVBOX_PROJECT_PATH：Govbox 项目目录的路径
• MCP_SHELL_PATH：用于执行命令的 shell（例如：/bin/zsh）
• MCP_SHELL_OPTIONS：shell 的附加参数（例如：-c）

重要说明：.env 文件必须位于调用该服务器的客户端项目根目录下。例如：

• 如果在 Windows 上通过 Claude Desktop 使用，文件应放在：C:\Users\<Usuário>\AppData\Local\AnthropicClaude\app-<Versão>\.env
• 如果使用自定义客户端，请将 .env 放在客户端根目录下

启动服务器前，请确保 .env 文件中的所有变量都已正确配置。

🔧 第 4 步：配置客户端

要将此服务器与 Claude Desktop 应用搭配使用，请根据以下示例调整 claude_desktop_config.json 文件：

使用 Docker

{
    "mcpServers": {
        "mcp-server-govbox": {
            "command": "docker",
            "args": [
                "run",
                "--rm",
                "-i",
                "mcp-server-govbox:latest"
            ]
        }
    }
}

直接使用可执行文件

{
    "mcpServers": {
        "mcp-server-govbox": {
            "command": "/path/to/executable"
        }
    }
}

对于其他客户端，请复制所需配置，并根据 LLM 客户端使用的配置格式进行设置。

# Usando Docker
cp config_docker_example.json config.json
# OU para executável
cp config_executable_example.json config.json

❌ 可能出现的错误

服务器运行期间可能会发生一些错误，并将返回给客户端。以下列出了可能出现的错误及其原因：

初始化错误

• "Error loading .env file"：

  • 找不到 .env 文件时发生
  • 或者读取文件时遇到权限问题
  • 或者文件格式不正确

• "Invalid shell configuration"：

  • shell 环境变量不正确或缺失时发生
  • 可能的原因：
    • 未设置 MCP_GOVBOX_PROJECT_PATH 或其值为空
    • 未设置 MCP_SHELL_PATH 或其值为空
    • 指定的 shell 在系统中不存在

验证错误

• "Param 'projects' must be a string"：
  • 请求中未提供参数 'projects' 时发生
  • 或者提供的值不是有效字符串

运行错误

• "Error during command execution (start)"：

  • 启动命令时出现问题
  • 可能原因：权限不足、找不到 shell、环境变量配置不当

• "Error during command execution (wait)"：

  • 命令执行期间出现问题
  • 可能原因：命令意外中断、系统资源问题

• "Error creating stdout/stderr pipe"：

  • 服务无法创建用于捕获命令输出的管道
  • 可能原因：权限问题、达到操作系统限制

解决方法

1. 检查 .env 文件中的所有环境变量是否配置正确
2. 确保 .env 文件位于正确的位置
3. 检查用户是否具有以下权限：
   • 读取 .env 文件
   • 执行已配置的 shell
   • 访问 Govbox 项目目录
4. 确认已配置的 shell 存在且可访问
5. 检查 Govbox 项目的路径是否正确
6. 查看服务日志，了解有关错误的更多详情

📝 许可证

本项目采用 MIT 许可证 授权。