mahufong/coding-tools-mcp

•Updated 1 day ago

Image

1.0K

mahufong/coding-tools-mcp repository overview

⁠Coding Tools MCP Docker 镜像

xyTom/coding-tools-mcp⁠ 的多架构 Docker 镜像。它通过 MCP 提供 exec_command、apply_patch 等工具，支持本地编码和用户授权的 SSH 远程运维，并内置 Python、Node.js/npm、Java/Javac/Maven、Go、Rust/Cargo、GCC/G++、Clang、CMake/Ninja、Git、OpenSSH Client 和 Oracle Cloud Infrastructure CLI（oci）。

这些工具可以执行命令并修改 /workspace。挂载宿主机目录前，请确认 MCP 客户端和仓库内容可信。

⁠镜像信息

镜像：mahufong/coding-tools-mcp
架构：linux/amd64、linux/arm64
默认工作区：/workspace
HTTP 端口：8765
HTTP 协议：MCP Streamable HTTP

Tag	含义
`latest`	最新稳定 Release
`<version>`	上游语义版本，例如 `0.2.2`
`sha-<commit>`	上游 commit SHA 的前 12 位

⁠HTTP 模式

生成一个本地 bearer token：

export CODING_TOOLS_MCP_AUTH_TOKEN="$(uv run python -c 'import secrets; print(secrets.token_urlsafe(32))')"

启动服务，并把当前目录挂载为工作区：

docker run --rm --init \
  --name coding-tools-mcp \
  -p 127.0.0.1:8765:8765 \
  -e CODING_TOOLS_MCP_AUTH_MODE=bearer \
  -e CODING_TOOLS_MCP_AUTH_TOKEN="$CODING_TOOLS_MCP_AUTH_TOKEN" \
  -e CODING_TOOLS_MCP_PERMISSION_MODE=trusted \
  -v "$PWD:/workspace" \
  mahufong/coding-tools-mcp:latest

客户端连接地址：

http://127.0.0.1:8765/mcp

需要自定义 HTTP header 的客户端应发送：

Authorization: Bearer <token>

服务 metadata/liveness 地址：

curl --fail \
  -H "Authorization: Bearer $CODING_TOOLS_MCP_AUTH_TOKEN" \
  http://127.0.0.1:8765/.well-known/mcp.json

/mcp 是 Streamable HTTP 协议端点，不是旧式 /sse。直接 GET /mcp 返回 405 Method Not Allowed 是正常行为，不能将它用作 HTTP 健康检查。

⁠Docker Compose

export CODING_TOOLS_MCP_AUTH_TOKEN="$(uv run python -c 'import secrets; print(secrets.token_urlsafe(32))')"
export WORKSPACE_PATH="$PWD"
docker compose -f coding-tools-mcp/docker-compose.yml up -d

查看健康状态和日志：

docker compose -f coding-tools-mcp/docker-compose.yml ps
docker compose -f coding-tools-mcp/docker-compose.yml logs -f

停止并删除容器：

docker compose -f coding-tools-mcp/docker-compose.yml down

也可以复制默认环境变量样例，并将 token 和工作区路径替换为实际值：

cp coding-tools-mcp/.env.example coding-tools-mcp/.env

CODING_TOOLS_MCP_AUTH_TOKEN=replace-with-a-random-token
WORKSPACE_PATH=/absolute/path/to/project
CODING_TOOLS_MCP_PORT=8765
CODING_TOOLS_MCP_PERMISSION_MODE=trusted

使用该文件启动：

docker compose \
  --env-file coding-tools-mcp/.env \
  -f coding-tools-mcp/docker-compose.yml \
  up -d

真实 .env 已被 Git 忽略，不要提交 token。

⁠stdio 模式

stdio 适合由本机 MCP host 直接启动容器。必须保留 -i，不要使用 -t；MCP host 退出并关闭 stdin 后，服务会随 EOF 退出，--rm 会清理容器。

docker run --rm -i --init \
  -v "/absolute/path/to/project:/workspace" \
  mahufong/coding-tools-mcp:latest \
  --stdio

⁠Claude Code 和 Cursor

将绝对工作区路径替换为实际项目目录：

{
  "mcpServers": {
    "coding-tools": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--init",
        "-v",
        "/absolute/path/to/project:/workspace",
        "mahufong/coding-tools-mcp:latest",
        "--stdio"
      ]
    }
  }
}

Claude Code 可将相同内容保存为项目 .mcp.json；Cursor 可放入其 MCP 配置文件。Windows 使用 Docker Desktop 时，请将挂载源改为 Docker 可访问的绝对路径，例如 C:/Users/name/project。

⁠Codex

[mcp_servers.coding_tools]
command = "docker"
args = [
  "run", "--rm", "-i", "--init",
  "-v", "/absolute/path/to/project:/workspace",
  "mahufong/coding-tools-mcp:latest", "--stdio"
]

⁠通用 HTTP MCP 客户端

在支持 MCP Streamable HTTP 的客户端中配置：

URL: http://127.0.0.1:8765/mcp
Header: Authorization: Bearer <token>

客户端应完成 MCP initialize 并在后续请求携带服务返回的 Mcp-Session-Id 和协商后的 MCP-Protocol-Version。不要将 URL 配置为 /sse。

⁠主要环境变量

变量	默认值/用途
`CODING_TOOLS_MCP_WORKSPACE`	`/workspace`
`CODING_TOOLS_MCP_HOST`	`0.0.0.0`
`CODING_TOOLS_MCP_PORT`	`8765`
`CODING_TOOLS_MCP_PERMISSION_MODE`	`trusted`
`CODING_TOOLS_MCP_AUTH_MODE`	`bearer`、`oauth` 或 `noauth`
`CODING_TOOLS_MCP_AUTH_TOKEN`	bearer token；建议显式设置
`CODING_TOOLS_MCP_GENERATE_AUTH_TOKEN`	未配置认证时生成 token；镜像默认启用
`CODING_TOOLS_MCP_EXEC_ALLOW_ROOTS`	增加 `exec_command` 可读取的系统路径
`OCI_CLI_CONFIG_FILE`	`exec_command` 默认注入 `/run/secrets/oci/config`，供 OCI CLI 读取 API Key 配置
`CODING_TOOLS_MCP_SERVER_URL`	OAuth 部署的稳定公网 origin，不包含 `/mcp`
`CODING_TOOLS_MCP_OAUTH_PASSWORD`	OAuth 授权页面密码
`CODING_TOOLS_MCP_OAUTH_TOKEN_SECRET`	OAuth token 签名密钥

命令行参数可在镜像名后传入，例如：

docker run --rm -i mahufong/coding-tools-mcp:latest --stdio --permission-mode safe

⁠控制 Oracle Cloud Infrastructure 资源

镜像包含固定版本的 Oracle Cloud Infrastructure CLI，可通过现有 exec_command 使用 oci；它不会新增 MCP 方法，也不会在镜像中预置租户信息或凭据。可以先检查版本：

oci --version

⁠API Key 认证

推荐为该容器创建权限受限的专用 OCI 用户和 API Key，并准备单独的配置文件。配置中的 key_file 必须使用容器内路径：

[DEFAULT]
user=ocid1.user.oc1..example
fingerprint=00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
key_file=/run/secrets/oci/oci_api_key.pem
tenancy=ocid1.tenancy.oc1..example
region=ap-singapore-1

只读挂载配置和私钥两个文件，不要挂载整个 ~/.oci 或宿主机 home：

docker run --rm --init \
  --name coding-tools-mcp \
  -p 127.0.0.1:8765:8765 \
  -e CODING_TOOLS_MCP_AUTH_MODE=bearer \
  -e CODING_TOOLS_MCP_AUTH_TOKEN="$CODING_TOOLS_MCP_AUTH_TOKEN" \
  -e CODING_TOOLS_MCP_PERMISSION_MODE=trusted \
  -e CODING_TOOLS_MCP_EXEC_ALLOW_ROOTS=/etc:/run/secrets \
  -v "$PWD:/workspace" \
  -v "$HOME/.oci/coding-tools-mcp-config:/run/secrets/oci/config:ro" \
  -v "$HOME/.oci/oci_api_key.pem:/run/secrets/oci/oci_api_key.pem:ro" \
  mahufong/coding-tools-mcp:latest

镜像会把 OCI_CLI_CONFIG_FILE=/run/secrets/oci/config 注入 exec_command 的子进程，因此 OCI CLI 能读取上述配置；仅向容器设置同名环境变量不会绕过 MCP 的 shell 环境白名单。

连接后可先通过 MCP 执行只读查询，确认身份和区域配置正确：

oci iam region list --output table

CODING_TOOLS_MCP_EXEC_ALLOW_ROOTS 是覆盖值而非追加值。加入 /run/secrets 时必须保留 /etc，以便命令执行沙箱读取系统证书、DNS、NSS 等配置。OCI CLI 还需要访问所选区域的 OCI HTTPS API。

⁠Instance Principal 认证

容器运行在 OCI Compute 实例上时，可以避免挂载 API Key，改用实例身份执行命令：

oci iam region list --auth instance_principal --output table

使用前必须为实例配置正确的动态组和最小权限 IAM 策略，并确保容器能够访问 OCI Instance Metadata Service、DNS 和出站 HTTPS。任何能够连接到此 MCP 服务并执行命令的客户端都会获得该实例身份允许的 OCI 权限，因此不应授予超出任务所需的策略。

无论使用哪种认证方式，都应使用专用、可撤销且权限最小化的身份。不要把 OCI 私钥、security token 或配置文件复制进镜像、/workspace、普通环境变量或 Git 仓库；不要在 CI 中使用生产 OCI 凭据或执行资源变更。

默认 docker-compose.yml 不强制配置 OCI 凭据，以免影响只使用编码工具链的用户。需要 OCI 时，可按上述方式扩展启动参数或创建本地 Compose override。

⁠连接 SSH 远程主机

镜像包含 OpenSSH Client，可通过 exec_command 使用 ssh、scp、sftp，也可以通过 SSH URL 操作 Git 仓库。镜像不包含或启动 SSH Server，不会开放入站 SSH 端口。

本镜像在构建上游 wheel 前更新 MCP server instructions，明确允许用户授权的 SSH 远程运维，包括远程文件读写、部署、服务管理和软件更新。apply_patch（以及上游提供时的 apply_changes）用于直接修改本地文件；远程文件可以通过 exec_command 调用 SSH、SCP 或 SFTP 修改。此调整不会改变本地工作区边界、运行时权限检查或认证配置，SSH 运维使用默认的 trusted 模式即可，不需要切换到 dangerous。

该修改属于本镜像的下游定制。构建脚本会校验上游 instructions 的结构和原文；上游改变这些内容时，构建会失败并要求检查，避免发布仍带有旧限制的镜像。镜像更新后需要重建容器，并让 MCP 客户端重新连接或刷新工具元数据；现有会话缓存的 instructions 不会自动更新，客户端自身的更高优先级限制也不受此修改影响。

推荐为容器准备权限受限的专用密钥和已校验的 known_hosts，只读挂载单个文件，不要挂载整个 ~/.ssh：

docker run --rm --init \
  -p 127.0.0.1:8765:8765 \
  -e CODING_TOOLS_MCP_AUTH_MODE=bearer \
  -e CODING_TOOLS_MCP_AUTH_TOKEN="$CODING_TOOLS_MCP_AUTH_TOKEN" \
  -e CODING_TOOLS_MCP_EXEC_ALLOW_ROOTS=/etc:/run/secrets \
  -v "$PWD:/workspace" \
  -v "$HOME/.ssh/coding-tools-mcp:/run/secrets/ssh_key:ro" \
  -v "$HOME/.ssh/known_hosts:/run/secrets/known_hosts:ro" \
  mahufong/coding-tools-mcp:latest

通过 MCP 执行的连接命令示例：

ssh \
  -F /dev/null \
  -i /run/secrets/ssh_key \
  -o IdentitiesOnly=yes \
  -o BatchMode=yes \
  -o StrictHostKeyChecking=yes \
  -o UserKnownHostsFile=/run/secrets/known_hosts \
  [email protected] 'uname -a'

远程文件读写示例（写入专用的临时检查文件）：

ssh -F /dev/null -i /run/secrets/ssh_key \
  -o IdentitiesOnly=yes -o BatchMode=yes -o StrictHostKeyChecking=yes \
  -o UserKnownHostsFile=/run/secrets/known_hosts \
  [email protected] 'cat /etc/os-release'

ssh -F /dev/null -i /run/secrets/ssh_key \
  -o IdentitiesOnly=yes -o BatchMode=yes -o StrictHostKeyChecking=yes \
  -o UserKnownHostsFile=/run/secrets/known_hosts \
  [email protected] 'printf "%s\n" "mcp-ops-check" > /tmp/mcp-ops-check && cat /tmp/mcp-ops-check'

引号中的命令和重定向在远程主机上执行；远程读写、更新软件和管理服务的权限由 SSH 登录用户及远程主机配置决定。SCP/SFTP 的本地文件仍须位于工作区内。容器网络也必须允许访问目标主机的 SSH 端口。

Git-over-SSH 示例：

GIT_SSH_COMMAND="ssh -F /dev/null -i /run/secrets/ssh_key -o IdentitiesOnly=yes -o UserKnownHostsFile=/run/secrets/known_hosts" \
  git clone [email protected]:owner/repository.git

上游执行白名单只接受目录；为让 OpenSSH 读取用户、NSS、DNS 和系统客户端配置，镜像默认将 /etc 加入只读执行白名单。自定义 CODING_TOOLS_MCP_EXEC_ALLOW_ROOTS 时必须保留 /etc，并加入密钥所在目录，否则 MCP 的命令执行沙箱无法正常运行 SSH 或读取 /run/secrets。示例通过 -F /dev/null 禁止读取用户级 SSH 配置，只使用显式提供的密钥和 known_hosts。请使用专用、可撤销且权限最小化的密钥；不要关闭 host key 校验，也不要把私钥复制进镜像或工作区。

⁠权限与安全

safe：更保守的操作策略。
trusted：容器默认值，适合可信客户端和可信工作区。
dangerous：关闭 MCP 安全门，仅可在额外隔离的容器或虚拟机内显式使用。

HTTP 服务只应绑定到宿主机 loopback。远程使用时，应保持服务监听本地地址，再通过带 HTTPS 和身份认证的 tunnel 或反向代理暴露；不要在公网使用 noauth。

认证只控制谁能连接，不等同于代码执行隔离。不要挂载整个宿主机 home、Docker socket、整个 SSH/OCI 配置目录或其他包含敏感信息的目录，也不要将 bearer token、OAuth 密码、签名密钥或 OCI 私钥写入镜像、Compose 文件或 Git 仓库。

⁠自动更新

GitHub Actions 每 3 天检查一次上游最新稳定 Release，不跟踪上游 main。发现新版本后会：

固定上游 release tag 和完整 commit SHA。
构建 amd64 smoke 镜像。
验证 HTTP 认证、MCP 初始化、远程运维 instructions、工具列表、命令执行和全部工具链。
发布 amd64/arm64 的 latest、版本和 SHA tag。
验证多架构 manifest 并同步本说明到 Docker Hub。

定时检查发现版本 tag 已存在时会跳过；手动触发或本目录变更仍会强制重建。OCI CLI 使用 Dockerfile 和工作流中显式固定的版本，通过本仓库提交更新，不随该上游 Release 检查自动升级。

⁠已知限制

完整多语言工具链使镜像体积较大，这是预期行为。
镜像提供工具链，但不会自动识别项目类型或安装项目依赖。
/workspace 中的写操作会直接影响挂载的宿主机目录。
上游应用代码固定到 release commit，OCI CLI 固定直接版本，但两者未锁定的 Python 间接依赖不保证 bit-for-bit 可复现。
latest 最多会比上游稳定 Release 晚一个自动检查周期。

⁠相关链接

Tag summary

Recent tags

Content type

Image

Digest

sha256:7a7b64312…

Size

809.4 MB

Last updated

1 day ago

docker pull mahufong/coding-tools-mcp