Go MCP Commander

go mcp指挥官

用于执行系统命令的安全、跨平台模型上下文协议（MCP）服务器。它用Go编写，提供命令执行功能和可配置的安全控制，包括命令分配列表、块列表和超时管理。

特性

• 交叉平台的：支持Windows、macOS和Linux
• 安全控制：可配置的命令列表和块列表
• 默认阻止列表：内置防止危险指令的保护
• 超时管理：可配置的命令超时
• 工作目录：在特定目录中执行命令
• 环境变量：将自定义环境变量传递给命令
• 网络抓取：使用可自定义的标头和方法从HTTP/HTTPS URL检索内容
• 谷歌搜索：执行网络搜索并检索结果
• 综合录井：具有可配置级别的详细日志记录
• 符合MCP协议：完全支持JSON-RPC 2.0和MCP协议

安装

来自二进制版本

从以下网址下载适用于您平台的最新二进制文件 发布 页面：

来源

git clone https://github.com/user/go-mcp-commander.git
cd go-mcp-commander
go build -o go-mcp-commander .

用法

命令行选项

go-mcp-commander [options]

配置优先

配置值按以下优先级顺序解析：

1. 命令行标志（最高优先级）
2. 环境变量
3. 默认值（最低优先级）

MCP工具

execute_命令

执行系统命令并返回其输出。

参数：

例子：

{
  "name": "execute_command",
  "arguments": {
    "command": "ls -la",
    "working_directory": "/tmp",
    "timeout": "10s",
    "env": {
      "MY_VAR": "value"
    }
  }
}

答复：

{
  "stdout": "...",
  "stderr": "...",
  "exit_code": 0,
  "duration": "50ms"
}

list_allowed_命令

列出所有允许的命令模式。

答复：

{
  "allowed_commands": ["git", "npm", "docker"],
  "allow_all": false
}

list_blocked_命令

列出所有被阻止的命令模式。

答复：

{
  "blocked_commands": ["rm -rf /", "mkfs", ...],
  "using_default_blocklist": true
}

get_shell_info

获取有关用于执行命令的shell的信息。

答复：

{
  "shell": "/bin/sh",
  "shell_arg": "-c",
  "default_timeout": "30s"
}

web_fetch

从URL获取内容并返回响应正文。支持HTTP/HTTPS，具有可自定义的标头、方法和超时。

参数：

例子：

{
  "name": "web_fetch",
  "arguments": {
    "url": "https://api.github.com/users/octocat",
    "headers": {
      "Accept": "application/json"
    },
    "timeout": "10s"
  }
}

答复：

{
  "status_code": 200,
  "status": "200 OK",
  "content_length": 1234,
  "content_type": "application/json",
  "duration": "150ms",
  "headers": {"Content-Type": "application/json", ...},
  "body": "{\"login\": \"octocat\", ...}"
}

谷歌搜索

执行谷歌搜索并返回搜索结果页面。结果包含可以解析链接、代码段和标题的原始HTML。

参数：

例子：

{
  "name": "google_search",
  "arguments": {
    "query": "golang mcp server",
    "num_results": 20,
    "language": "en"
  }
}

答复：

{
  "query": "golang mcp server",
  "status_code": 200,
  "content_length": 45678,
  "duration": "250ms",
  "search_url": "https://www.google.com/search?q=golang+mcp+server&num=20&hl=en&safe=moderate",
  "body": "..."
}

整合

克劳德桌面版

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "commander": {
      "command": "/path/to/go-mcp-commander",
      "args": ["-log-level", "info"]
    }
  }
}

克劳德代码

创建一个 .mcp.json 项目根目录中的文件：

{
  "mcpServers": {
    "commander": {
      "command": "/path/to/go-mcp-commander",
      "args": ["-log-level", "info"]
    }
  }
}

或创建 .claude/mcp.json 对于特定于工作区的配置：

{
  "mcpServers": {
    "commander": {
      "command": "${workspaceFolder}/go-mcp-commander",
      "args": [
        "-log-dir", "${workspaceFolder}/logs",
        "-log-level", "info"
      ]
    }
  }
}

Continue.dev

创建一个 .continue/config.json 文件：

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "name": "go-mcp-commander",
        "transport": {
          "type": "stdio",
          "command": "/path/to/go-mcp-commander",
          "args": ["-log-level", "info"]
        }
      }
    ]
  }
}

安全

默认阻止列表

以下命令在Unix系统上默认被阻止：

• rm -rf / 和 rm -rf /*
• mkfs
• dd if=
• 叉式炸弹(:(){:|:&};:)
• chmod -R 777 /
• chown -R
• > /dev/sda
• shutdown, reboot, halt, poweroff
• init 0, init 6

在Windows上：

• format
• del /s, rd /s, rmdir /s
• reg delete
• net user, net localgroup
• shutdown, restart

自定义允许列表

要将命令限制到特定集合，请使用 -allowed-commands 标志：

go-mcp-commander -allowed-commands "git,npm,docker,kubectl"

只允许使用以这些前缀开头的命令。

自定义阻止列表

要添加其他被阻止的命令，请执行以下操作：

go-mcp-commander -blocked-commands "curl,wget,ssh"

禁用默认阻止列表

要禁用默认阻止列表（不推荐）：

go-mcp-commander -use-default-blocklist=false

全局环境文件

所有go-mcp服务器都支持从以下位置加载环境变量 ~/.mcp_env。这提供了一个配置凭据和设置的中心位置，在GUI应用程序不从继承shell环境变量的macOS上特别有用 .zshrc 或 .bashrc.

文件格式

创建 ~/.mcp_env 对于KEY=VALUE对：

# ~/.mcp_env - MCP Server Environment Variables

# Commander Configuration
MCP_ALLOWED_COMMANDS=git,npm,docker,kubectl
MCP_BLOCKED_COMMANDS=curl,wget
MCP_DEFAULT_TIMEOUT=60s

# Logging
MCP_LOG_DIR=~/mcp-logs
MCP_LOG_LEVEL=info

特性

• 以开头的行 # 被视为评论
• 空行被忽略
• 值可以用单引号或双引号括起来
• 现有环境变量不会被覆盖 （环境变量优先）
• 路径与 ~ 会自动扩展到您的主目录

路径扩展

支持所有与路径相关的设置 ~ 扩展：

MCP_LOG_DIR=~/logs/commander

这在 ~/.mcp_env 文件、环境变量和命令行标志。

日志记录

日志被写入日志目录中带有日期戳的文件：

~/go-mcp-commander/logs/go-mcp-commander-2025-01-15.log

当 MCP_LOG_DIR 已设置或 -log-dir 如果使用标志，日志会自动放置在以二进制文件命名的子文件夹中。这允许多个MCP服务器共享同一日志目录：

MCP_LOG_DIR=/var/log/mcp
  └── go-mcp-commander/
      └── go-mcp-commander-2025-01-15.log

日志级别

日志格式

[2025-01-15T10:30:45.123Z] [INFO] TOOL_CALL tool="execute_command" args=[command, working_directory]
[2025-01-15T10:30:45.150Z] [ACCESS] CMD_EXEC command="ls -la" workdir="/tmp" exit_code=0 duration=27ms

安全说明：从不记录命令输出，以防止敏感数据泄露。

发展

先决条件

• 转到1.21或更高版本

建筑

# Build for current platform
go build -o go-mcp-commander .

# Build for all platforms
make build

测试

# Run unit tests
go test -v ./pkg/...

# Run integration tests
go test -v -tags=integration ./test/...

# Run all tests with coverage
go test -v -race -coverprofile=coverage.out ./...

项目结构

go-mcp-commander/
├── main.go                    # Entry point, tool registration
├── go.mod                     # Go module definition
├── pkg/
│   ├── mcp/
│   │   ├── server.go          # MCP server implementation
│   │   ├── server_test.go     # Server tests
│   │   └── types.go           # MCP protocol types
│   ├── logging/
│   │   ├── logging.go         # Logging implementation
│   │   └── logging_test.go    # Logging tests
│   └── commander/
│       ├── commander.go       # Command execution
│       └── commander_test.go  # Commander tests
├── test/
│   └── mcp_test.go            # MCP integration tests
├── .github/workflows/
│   ├── ci.yml                 # CI workflow
│   └── release.yml            # Release workflow
├── .mcp.json                  # MCP configuration
├── .claude/mcp.json           # Claude workspace config
├── .continue/config.json      # Continue.dev config
├── README.md                  # This file
└── TESTING.md                 # Testing documentation

工具参考

本节提供了有关LLM使用的每个MCP工具的详细信息。

execute_命令

目的：在主机系统上执行shell命令并检索输出。

何时使用:

• 运行构建命令（npm、go、make）
• 文件系统操作（ls、cat、mkdir）
• Git操作（Git状态、Git提交）
• 系统信息查询（whoami、pwd、uname）
• 运行脚本和自动化任务

参数:

返回字段:

示例请求:

{
  "name": "execute_command",
  "arguments": {
    "command": "git status --porcelain",
    "working_directory": "/home/user/project",
    "timeout": "5s"
  }
}

示例响应:

{
  "stdout": "M README.md\n?? newfile.txt\n",
  "stderr": "",
  "exit_code": 0,
  "duration": "23ms"
}

list_allowed_命令

目的：查询服务器的命令列表配置。

何时使用:

• 在执行命令以验证其是否被接受之前
• 调试命令拒绝问题
• 了解服务器安全配置

参数：无

返回字段:

示例响应 （受限）：

{
  "allowed_commands": ["git", "npm", "go", "docker"],
  "allow_all": false
}

示例响应 （无限制）：

{
  "allowed_commands": [],
  "allow_all": true
}

list_blocked_命令

目的：查询服务器的命令块列表配置。

何时使用:

• 了解哪些命令被阻止
• 调试意外的命令拒绝
• 验证安全配置

参数：无

返回字段:

示例响应:

{
  "blocked_commands": ["rm -rf /", "mkfs", "dd if=", "shutdown"],
  "using_default_blocklist": true
}

get_shell_info

目的：查询用于执行命令的shell配置。

何时使用:

• 确定要使用的shell语法（bash vs cmd vs powershell）
• 了解超时默认值
• 跨平台兼容性检查

参数：无

返回字段:

示例响应 （Unix）：

{
  "shell": "/bin/sh",
  "shell_arg": "-c",
  "default_timeout": "30s"
}

示例响应 （Windows）：

{
  "shell": "cmd",
  "shell_arg": "/c",
  "default_timeout": "30s"
}

web_fetch

目的：从HTTP/HTTPS URL获取内容，并完全控制请求参数。

何时使用:

• 检索API响应（REST、GraphQL）
• 正在下载网页内容
• 进行webhook调用
• 测试HTTP端点
• 获取JSON/XML数据

参数:

返回字段:

示例请求 （API调用）：

{
  "name": "web_fetch",
  "arguments": {
    "url": "https://api.github.com/repos/user/repo",
    "headers": {
      "Accept": "application/vnd.github.v3+json",
      "Authorization": "Bearer ghp_xxx"
    }
  }
}

示例请求 （带正文的POST）：

{
  "name": "web_fetch",
  "arguments": {
    "url": "https://api.example.com/webhook",
    "method": "POST",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": "{\"event\": \"deploy\", \"status\": \"success\"}"
  }
}

谷歌搜索

目的：执行谷歌网络搜索并检索结果页面HTML。

何时使用:

• 查找文档或教程
• 研究技术主题
• 发现相关网站
• 查找代码示例
• 一般网络研究

参数:

返回字段:

谷歌搜索运营商:

• site:github.com -在特定网站内搜索
• "exact phrase" -搜索精确短语
• filetype:pdf -搜索特定文件类型
• intitle:keyword -在页面标题中搜索
• -excluded -从结果中排除术语

示例请求:

{
  "name": "google_search",
  "arguments": {
    "query": "site:stackoverflow.com golang http client",
    "num_results": 20
  }
}

常见工作流

工作流程1：项目构建和测试

执行Go项目的典型构建工作流：

Step 1: Check current directory
  Tool: execute_command
  Args: {"command": "pwd"}

Step 2: Run tests
  Tool: execute_command
  Args: {"command": "go test -v ./...", "timeout": "5m"}

Step 3: Build binary
  Tool: execute_command
  Args: {"command": "go build -o app .", "working_directory": "/project"}

工作流程2:Git操作

执行git提交工作流：

Step 1: Check status
  Tool: execute_command
  Args: {"command": "git status --porcelain"}

Step 2: Stage changes
  Tool: execute_command
  Args: {"command": "git add -A"}

Step 3: Commit
  Tool: execute_command
  Args: {"command": "git commit -m \"feat: add new feature\""}

Step 4: Verify
  Tool: execute_command
  Args: {"command": "git log -1 --oneline"}

工作流程3：执行前的安全检查

运行前验证命令是否被接受：

Step 1: Check allowlist
  Tool: list_allowed_commands
  Result: Check if your command prefix is in allowed_commands or allow_all is true

Step 2: Check blocklist
  Tool: list_blocked_commands
  Result: Verify your command doesn't match any blocked patterns

Step 3: Execute if safe
  Tool: execute_command
  Args: {"command": "your-command-here"}

工作流程4：跨平台命令执行

基于shell适配命令：

Step 1: Get shell info
  Tool: get_shell_info
  Result: Check shell type (sh, cmd, powershell)

Step 2: Execute platform-appropriate command
  If shell contains "cmd":
    Tool: execute_command
    Args: {"command": "dir /b"}
  Else:
    Tool: execute_command
    Args: {"command": "ls -la"}

工作流5：具有自定义超时的长时间运行流程

执行一个可能比默认超时时间更长的命令：

Step 1: Execute with extended timeout
  Tool: execute_command
  Args: {
    "command": "npm install",
    "working_directory": "/project",
    "timeout": "10m"
  }

Step 2: Verify installation
  Tool: execute_command
  Args: {"command": "npm list --depth=0", "working_directory": "/project"}

工作流程6：研究和文档查找

查找技术主题的文档和示例：

Step 1: Search for documentation
  Tool: google_search
  Args: {"query": "site:pkg.go.dev net/http client example", "num_results": 10}

Step 2: Fetch a specific documentation page
  Tool: web_fetch
  Args: {"url": "https://pkg.go.dev/net/http"}

Step 3: Search for code examples
  Tool: google_search
  Args: {"query": "site:github.com golang http client example"}

工作流程7：API测试和集成

测试REST API并与之交互：

Step 1: Test API health endpoint
  Tool: web_fetch
  Args: {"url": "https://api.example.com/health", "timeout": "5s"}

Step 2: Authenticate and get token
  Tool: web_fetch
  Args: {
    "url": "https://api.example.com/auth/login",
    "method": "POST",
    "headers": {"Content-Type": "application/json"},
    "body": "{\"username\": \"user\", \"password\": \"pass\"}"
  }

Step 3: Make authenticated request
  Tool: web_fetch
  Args: {
    "url": "https://api.example.com/data",
    "headers": {"Authorization": "Bearer "}
  }

工作流程8：网页抓取和内容分析

获取和处理web内容：

Step 1: Fetch a web page
  Tool: web_fetch
  Args: {"url": "https://example.com/page", "max_size": 5242880}

Step 2: Parse content using command-line tools
  Tool: execute_command
  Args: {"command": "echo '' | grep -o '.*'"}

错误处理

错误：命令被Allowlist阻止

错误信息: command not allowed: 'wget' - not in allowed commands list

原因：服务器配置了允许列表，但命令前缀不匹配。

解决方案:

1. 使用 list_allowed_commands 查看允许的命令
2. 使用允许的命令选项
3. 请求服务器管理员向allowlist添加命令

示例:

{
  "isError": true,
  "content": [{
    "type": "text",
    "text": "command not allowed: 'wget' - not in allowed commands list"
  }]
}

错误：命令被阻止列表阻止

错误信息: command blocked: 'rm -rf /' matches blocked pattern

原因：命令匹配被阻止的模式（默认或自定义阻止列表）。

解决方案:

1. 使用 list_blocked_commands 查看被遮挡的图案
2. 使用更安全的替代命令
3. 将操作分解为更小、更安全的步骤

示例:

{
  "isError": true,
  "content": [{
    "type": "text",
    "text": "command blocked: 'rm -rf /' matches blocked pattern"
  }]
}

错误：命令超时

错误信息: command timed out after 30s

原因：命令执行超过了超时时间。

解决方案:

1. 增加超时时间： {"timeout": "5m"}
2. 将长期操作分解为更小的步骤
3. 检查命令是否挂起（无限循环，等待输入）

示例:

{
  "isError": true,
  "content": [{
    "type": "text",
    "text": "command timed out after 30s"
  }]
}

错误：工作目录无效

错误信息: working directory does not exist: '/nonexistent/path'

原因：指定的 working_directory 路径不存在。

解决方案:

1. 验证目录是否存在： {"command": "ls -la /path/to/dir"}
2. 首先创建目录： {"command": "mkdir -p /path/to/dir"}
3. 使用绝对路径而不是相对路径

示例:

{
  "isError": true,
  "content": [{
    "type": "text",
    "text": "working directory does not exist: '/nonexistent/path'"
  }]
}

错误：找不到命令

错误信息: exit_code: 127 随着 stderr: "command not found"

原因：PATH中不存在命令可执行文件。

解决方案:

1. 使用可执行文件的完整路径
2. 验证命令是否已安装： {"command": "which commandname"}
3. 检查路径： {"command": "echo $PATH"}

示例:

{
  "stdout": "",
  "stderr": "/bin/sh: mycommand: command not found",
  "exit_code": 127,
  "duration": "5ms"
}

错误：权限被拒绝

错误信息: exit_code: 1 随着 stderr: "Permission denied"

原因：权限不足，无法执行命令或访问文件。

解决方案:

1. 检查文件权限： {"command": "ls -la /path/to/file"}
2. 使用适当的用户上下文
3. 避免需要提升权限的操作

错误：HTTP身份验证失败（HTTP模式）

错误信息：HTTP 401未经授权

原因：缺失或无效 X-MCP-Auth-Token 头球

解决方案:

1. 确保 X-MCP-Auth-Token 请求中包含标头
2. 验证令牌是否与服务器的令牌匹配 MCP_AUTH_TOKEN 配置
3. 检查令牌值中的拼写错误

错误：无效的URL（web_fetch）

错误信息: Invalid URL: ... 或 URL must use http:// or https:// protocol

原因：URL格式不正确或缺少协议方案。

解决方案:

1. 确保URL包含 http:// 或 https://
2. 验证URL的格式是否正确
3. 检查可能需要编码的特殊字符

示例:

{
  "isError": true,
  "content": [{
    "type": "text",
    "text": "URL must use http:// or https:// protocol"
  }]
}

错误：请求失败（web_fetch）

错误信息: Request failed: ...

原因：网络错误、DNS解析失败或连接被拒绝。

解决方案:

1. 验证URL是否可访问
2. 检查网络连接问题
3. 验证防火墙设置
4. 尝试增加慢速服务器的超时时间

错误：响应太大（web_fetch）

原因：响应正文超过 max_size 限制。

解决方案:

1. 增加 max_size 参数（最大10MB）
2. 截断的响应体仍将返回
3. 考虑是否需要完整的响应

错误：请求超时（web_fetch/google_search）

错误信息: Request failed: context deadline exceeded

原因：请求所用时间超过配置的超时时间。

解决方案:

1. 增加 timeout 参数
2. 检查目标服务器是否缓慢或无响应
3. 考虑使用HEAD请求先检查可用性

错误：HTTP 429请求太多（google_search）

原因：由于搜索请求太多，谷歌限制了费率。

解决方案:

1. 在发出其他请求之前等待
2. 降低请求频率
3. 考虑使用Google自定义搜索API以获得更高的限制

参数格式

超时格式

这 timeout 参数接受Go持续时间字符串。

格式: ``

有效单位:

组合：单位可以组合： 1h30m, 2m30s

例子:

• "10s" -10秒
• "2m" -2分钟
• "1h" -1小时
• "1m30s" -1分30秒

默认: 30s 如果未指定

环境变量格式

这 env 参数接受具有字符串键值对的JSON对象。

格式: {"VAR_NAME": "value", "ANOTHER_VAR": "value2"}

规则:

• 密钥必须是有效的环境变量名（建议大写）
• 值必须是字符串
• 现有环境变量不会被覆盖
• 变量仅为当前命令执行设置

例子:

{
  "env": {
    "NODE_ENV": "production",
    "DEBUG": "true",
    "API_URL": "https://api.example.com"
  }
}

工作目录格式

这 working_directory 参数接受绝对路径字符串。

格式：现有目录的绝对路径

平台特定的:

• Unix： /home/user/project
• 窗户： C:\\Users\\user\\project 或 C:/Users/user/project

规则:

• 路径必须是绝对的（不是相对的）
• 执行命令前目录必须存在
• 在Windows上使用正斜杠以兼容JSON

例子:

• Unix： "/home/user/myproject"
• 窗户： "C:/dev/myproject"

命令格式

这 command 参数接受shell命令字符串。

格式：配置的shell的任何有效shell命令

支持的功能:

• 管： ls -la | grep .txt
• 重定向： echo hello > file.txt
• 命令链： cd /tmp && ls
• 环境变量扩展： echo $HOME
• 球状图案： ls *.txt

平台注意事项:

• Unix（sh/bash）：标准Unix命令语法
• Windows（cmd）：Windows命令语法(dir, type等等）
• Windows（powershell）：powershell cmdlet语法

例子:

{"command": "ls -la"}
{"command": "git status && git diff"}
{"command": "cat file.txt | grep pattern | head -10"}
{"command": "NODE_ENV=test npm run test"}

允许/阻止的命令格式

服务器配置使用逗号分隔的命令前缀。

格式: "cmd1,cmd2,cmd3"

匹配规则:

• 命令按前缀匹配
• 匹配不区分大小写
• 逗号周围的空格被修剪

例子:

• -allowed-commands "git,npm,go" -允许 git, npm, go 以及任何以这些开头的命令
• -blocked-commands "curl,wget" -积木 curl, wget 命令

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

致谢

• 灵感源自 mcp本地命令服务器
• 根据以下模式构建 go-mcp文件上下文服务器
• 实施 模型上下文协议