从需求到发布：使用 OpenClaw + Ralph Loop 自动化开发 Nexus MCP Server

TL;DR

使用 OpenClaw + Ralph Loop + OpenCode 组合，完成了 Nexus MCP Server 的全自动化开发。

本文记录了从需求提出、Planning、Building，到遇到问题诊断、架构重构的完整过程，展示了 AI 辅助编码工具的实际效能。

源码以及实现的脚本、Planing、Building 等文档均提交到 GitHub 仓库 addozhang/nexus-mcp-server。

背景

今天在公司遇到一个问题：需要开发一个 Agent 来对比项目依赖细节，但远程仓库版本被删除导致用旧的 parent pom 构建失败。我想让 Agent 到 Nexus 仓库查找最接近的版本进行构建，以避免大跨度的版本升级引入新的问题。

向来不喜造轮子，内网外网找了一圈才找到一个基于 Node 的开源版 brianveltman/sonatype-mcp，马上着手验证，然后倒在了安装依赖包：内网仓库缺少一个间接依赖的包。

这就有了造轮子的借口了，装上 mcp-builder skill 马上 Vibe 一个。无奈模型有点弱鸡，稍微折腾一下，又没有太多时间草草收场。

下班时间想起我周末已经配置了常用的 Coding Agent 和 Skill 的 OpenClaw，这几天空余时间除了创建几个自己要用的 Agent 和 Skill 外，还没整过稍大的活。这不，正好拿 Nexus MCP server 练练手，而且月初还有配额使用 Claude Opus 4.5 模型。

技术栈介绍

OpenClaw：AI 自动化编码平台

OpenClaw 是一个开源的、本地优先（local-first）的个人 AI 助手与自主智能体平台，旨在为用户提供一个真正能“办实事”的私人 AI 代理。项目最初名为 Clawdbot，后曾用名 Moltbot，于 2025 年末发布，随后更名为 OpenClaw。

本文不涉及 OpenClaw 的安装和配置，后面有空再出一篇介绍我的云端 OpenClaw 环境。

Ralph Loop Skill：结构化开发流程

Ralph Loop 是本文使用的一个核心 Skill，提供了结构化的 自动化开发流程，包括两个主要阶段：

• Planning 阶段：分析需求、生成技术规格文档、制定实施计划
• Building 阶段：根据计划自动编写代码、运行测试、生成文档

Ralph Loop 支持三种工作模式：

1. Planning Only：仅生成规划文档
2. Building Only：基于现有规划实施开发
3. Both：完整的规划到实施流程（本文使用的模式）

OpenCode：命令行 AI 编码工具

OpenCode 是一个开源的 AI 编程智能体（AI coding agent），专为开发者在终端环境中高效编码而设计。它支持多种使用方式，包括：

• 终端命令行界面（TUI）
• 桌面应用程序
• IDE 插件扩展
• Web 界面

本次开发中使用的是 GitHub Copilot 提供的 Claude Opus 4.5 模型。

FastMCP：快速构建 MCP Server

FastMCP 是用于快速构建 MCP (Model Context Protocol) Server 的 Python 框架，极大简化了 MCP Server 的开发流程。通过 FastMCP，开发者可以专注于业务逻辑，而无需关心底层的协议细节。

工具链协同

用户需求 → OpenClaw (调度) → Ralph Loop (流程) → OpenCode (执行) → 代码输出

初始条件

开始前，环境中已具备：

• OpenCode：已安装并完成 GitHub Copilot 认证
• 模型：Claude Opus 4.5（月初配额充足）
• Ralph Loop Skill：提供自动化的 Planning → Building 流程
• Docker：提供隔离的开发环境
• Git：版本控制

完整工作流程

需求

这里我对制品的需求很明确：

为 Sonatype Nexus Pro 3 开发一个 MCP (Model Context Protocol，模型上下文协议) 服务器，使 AI 助手能够查询：

• Maven 仓库（搜索制品、获取版本）
• Python (PyPI) 仓库（搜索包、获取版本）
• Docker 仓库（列出镜像、获取标签）

认证方式: 通过 HTTP headers 传递 Nexus URL、用户名和密码

因此初始 prompt 格外简单：

使用 ralph-loop skill 配合 opencode，为 sonatype nexus pro 3 开发一个 mcp server，并通过 header 传递 nexus url、username 和 password 支持 maven、python、Docker image 的查询。

详细描述需求，包括 Nexus 版本、期望的功能、实现方式等等，这些非常重要。因为明确的描述可以实现“端到端生成”，无需交互、直接输出完整制品，类似视频制作中的“一镜到底”的效果。

这里给自己挖了个坑：需求中提到过通过 HTTP header 传递 Nexus URL、用户名和密码，我的本意默认使用 HTTP 传输模式，但是 OpenClaw 自作主张使用了 stdio 模式，并在最终的结果中教育我：MCP 使用 stdio 传输，不支持 HTTP 头。

这种不够详细的描述，也导致我后面又做了一次重构。意外多了一次重构的经验！

交互

初始 Prompt 之后是唯一的一次交互，涉及：

1. 工具选择：Ralph Loop 的模式（Planing、Building、Both），选择“谋而后动”的 Both 模式。
2. 语言：选择 Python（可以用 FastMCP 框架）
3. 迭代次数：15（Planing 5 轮 + Building 10 轮）
4. 模型：GitHub Copilot 的 Claude Opus 4.5
5. 沙箱：Docker

提供选择之后 OpenClaw 输出了：

• 5 个 spec 文件 (authentication、maven、python、docker、mcp-architecture)
• Ralph loop 脚本
• 基础框架：PROMPT.md、AGENTS.md
• Git 初始化

图 1: Planning 阶段自动生成的项目规格文件和配置

尝试启动

由于是第一次使用 OpenClaw + Ralph loop + OpenCode 的组合，出现问题是难免的。

问题 1: OpenCode 命令未找到

刚运行就报错了，提示找不到 OpenCode 命令。我强硬地表达已经安装并配置了模型。OpenClaw 马上找到了 OpenCode 的位置并修改了脚本。

- if ! command -v opencode &> /dev/null; then
+ OPENCODE_BIN="/home/addo/.opencode/bin/opencode"
+ if ! [ -f "$OPENCODE_BIN" ]; then

根本原因：OpenCode 是在 OpenClaw 启动之后，我在 SSH 会话中安装的。

问题 2: OpenCode 进程挂起

现象：

# 进程运行但无任何输出
PID 16249  运行时间: 21:08
日志: 只有启动信息，之后完全静默

这个问题早在我意料之中，一开始就担心 OpenCode 在纯后台 Bash 模式下无法正常运行，因为早前在另一个 skill coding-agent 见过解决方案，而在 Ralph Loop 并没有提到。果断 " 盲猜 “：

是不是 opencode 的运行方式不对，无法在后台运行？

图 2: OpenClaw 通过 tmux 解决 OpenCode 的 TTY 依赖问题

经过一番排查：

1. ✅ 检查认证: opencode auth list → GitHub Copilot 已登录
2. ✅ 检查日志: 无新日志产生
3. ✅ 简单测试: opencode run "2+2" → 同样挂起
4. ❌ strace: 权限不足

根本原因：OpenCode run 命令需要真实的 TTY (伪终端)，在纯后台 bash 中会永久等待

OpenClaw 提供了 tmux 的 TTY 解决方案，并做了验证：

# 测试: 在 tmux 中运行 OpenCode
SOCKET="/tmp/openclaw-tmux-sockets/opencode-test.sock"
tmux -S "$SOCKET" new -d -s test
tmux -S "$SOCKET" send-keys "opencode run 'What is 2+2?'" Enter

# 结果: ✅ 立即返回 "4"

术语解释：tmux 是一个终端复用器（terminal multiplexer），它运行在 TTY 之上，用于管理和组织多个虚拟终端会话。它基于客户端 - 服务器模型，会话由服务器维护，客户端可以随时 attach 或 detach

基于验证解决，提供了新的脚本 ralph-loop-tmux.sh，核心改进：

原方案 (纯后台):
- opencode run "$(cat PROMPT.md)" 2>&1 | tee -a "$LOG_FILE"

新方案 (tmux + TTY):
+ tmux -S "$SOCKET" send-keys "$OPENCODE_BIN run --model $MODEL \"$(cat PROMPT.md)\"" Enter
+ # 等待 shell 提示符返回
+ while [ $ELAPSED -lt $TIMEOUT ]; do
+   OUTPUT=$(tmux -S "$SOCKET" capture-pane -p -t "$SESSION" -S -5)
+   if echo "$OUTPUT" | grep -q "addo@.*\$"; then
+     break
+   fi
+ done

Planning 阶段

OpenClaw 直接用 tmux 运行 OpenCode (绕过脚本测试)

/home/addo/.opencode/bin/opencode run --model github-copilot/claude-opus-4.5 "$(cat PROMPT_PLANNING.md)"

输出了任务实现计划，关键内容：

• Phase 1: 项目基础 (pyproject.toml, 包结构)
• Phase 2: 核心基础设施 (NexusClient, Auth, MCP Server)
• Phase 3-5: Maven/Python/Docker 工具实现
• Phase 6: 测试和质量
• Phase 7: 文档

Building 阶段

成功启动 Building 阶段：

SOCKET="/tmp/openclaw-tmux-sockets/opencode-building.sock"
SESSION="opencode-building"

tmux -S "$SOCKET" new -d -s "$SESSION" -n building
tmux -S "$SOCKET" send-keys '/home/addo/.opencode/bin/opencode run --model github-copilot/claude-opus-4.5 "$(cat PROMPT.md)"' Enter

简单梳理下 OpenCode 的工作流程：

11:50:30 - 读取 IMPLEMENTATION_PLAN.md, AGENTS.md, specs/*
11:51:15 - 创建 17 todos
11:51:20 - Task 1.1: 创建 pyproject.toml ✅
11:52:00 - Task 1.2: 创建包结构 ✅
11:53:30 - Task 2.1: 实现 NexusClient ✅
11:55:00 - Task 2.2: 实现认证上下文 ✅
... (省略中间任务)
12:15:00 - 所有测试通过 (26/26) ✅
12:15:30 - 更新文档 (README, AGENTS.md) ✅
12:16:00 - Git commit ✅

最终交付：

pyproject.toml
src/nexus_mcp/__init__.py
src/nexus_mcp/__main__.py
src/nexus_mcp/auth.py
src/nexus_mcp/nexus_client.py
src/nexus_mcp/server.py
src/nexus_mcp/tools/__init__.py
src/nexus_mcp/tools/implementations.py
tests/conftest.py
tests/test_nexus_client.py
tests/test_tools.py

文档与发布

基于英文 README 生成完整中文版 README.zh-CN.md:

• 完整功能说明
• 详细安装步骤
• 中文示例代码
• 故障排查指南
• 技术栈说明
• 开发历史记录

看了最终的文档，我发现了严重的问题：” 与基于 HTTP 的 API 不同，MCP 使用 stdio 传输，不支持 HTTP 头。凭证作为参数传递给每个工具调用。"

HTTP Streaming 重构

这次的需求更加明确：改用 HTTP streaming transport，支持使用 HTTP headers 传递凭证。

再次进入 Planning -> Building，回炉重造。

Planning 阶段:

• 创建 specs/http-streaming.md 重构规格
• OpenCode 分析 FastMCP HTTP transport 文档
• 生成 14 个重构任务，4 个 Phase
• 预估 10 小时工作量

Building 阶段 :

• Phase 8: HTTP Transport 重构 (5 tasks)
  • 更新服务器入口点
  • 实现 HTTP header 依赖注入
  • 重构所有工具签名（移除凭证参数）
• Phase 9: 测试更新 (4 tasks)
  • 新增 test_http_transport.py (10 个测试)
  • 更新所有工具测试
  • 测试从 26 → 36 个
• Phase 10: 文档更新 (3 tasks)
  • 更新 README 配置示例
  • 更新 specs 反映 HTTP 架构
• Phase 11: Docker 和部署 (2 tasks)
  • Dockerfile 暴露端口 8000
  • 添加 /health 健康检查端点

实际完成时间: 17 分钟（预估 10 小时，效率提升 35x）。这里预估的 10 小时，应该是人工实现的成本。看到这里的你，焦虑感是不是更重了？

总结

先别焦虑，我们选择的这个案例其实很特殊：将已有的 Nexus REST API 封装为 MCP Server。本质上是重复性的适配工作——读 API 文档、写调用代码、处理参数、写测试。技术含量不高，但繁琐且耗时。

这正是 AI 工具的最佳应用场景。它不是要取代你的技术判断和架构设计能力，而是把你从这些机械的 " 搬砖 " 工作中解放出来。当 AI 用 44 分钟完成实现时，你获得的不仅仅是时间节省，更重要的是：你可以把精力投入到更有建设性的思考中——比如系统架构设计、技术选型、业务逻辑优化。

回看整个过程，人的价值体现在哪里？

1. 需求梳理：明确要做什么、怎么做（虽然第一次没说清楚）
2. 工具选择：选择 OpenClaw + Ralph Loop + FastMCP 的技术栈
3. 问题诊断：发现 OpenCode 挂起问题，定位 TTY 依赖
4. 方向调整：意识到架构问题，决定重构为 HTTP transport
5. 质量把控：确保测试覆盖、代码规范

AI 负责的是执行层：生成代码、运行测试、更新文档。这些工作它做得又快又好，但它需要你给出明确的方向。

附上量化的指标：

注意： 这里 2 小时 13 分 的总时长，更多的是因为出错挂起，而我在处理其他的事情。