mlkgrnt/Junimo-MCP

简体中文 · 繁體中文 · English · Español
用 OCaml 手写的 MCP 服务器：给 AI Agent 一副在《星露谷物语》里干活的手——37 个意图工具（含剧情阅读与菜单关闭），从种地收割到取物聚餐、社交过节，全流程可靠执行。
协议层：JSON-RPC 2.0 over stdio，手写实现（initialize / tools/list / tools/call），零 MCP 框架依赖
控制层：原生 HTTP + keep-alive（OCaml socket）→ JunimoBridge（默认 http://localhost:7850）→ 游戏内角色；也兼容 NagiBridge-Remix（7842，用 STARDEWAPIURL 指过去）
不假成功：工具报成功 = 游戏里真的发生了（挥动/浇水后会回读地块直到效果真的落地才记账）；失败大多无副作用（送礼失败自动退礼、吃失败不扣物），可放心重试
会挑快的路：goto 一次请求走全程（出发前就否掉越界/大门/站不住的坐标）；till/water 在工具已升级时自动改用蓄力批量（一片地几挥搞定）
依赖极简：唯一第三方 OCaml 库是 yojson；运行零外部依赖（HTTP 走原生 socket，不需要系统 curl；STARDEWHTTP=curl 可回退到旧路径）
## 只想用、不想开发？让 Agent 一键部署
bash
git clone https://github.com/mlkgrnt/Junimo-MCP.git
把仓库交给你的 AI 客户端（WorkBuddy / Claude Code / Cursor / 任意能读文件、能跑命令的 Agent），对它说：
> "读 AGENTS.md，把 Junimo-MCP 部署到能用。"
Agent 会照 AGENTS.md 的《部署安装》章节自动完成全部步骤：
装 SMAPI → 装执行器 mod → 部署服务器 → 注册 MCP 连接器 → 调通验收。
你只需要两件事：① 一台 Windows + 已安装《星露谷物语》本体；② 在注册那一步按提示点一次 Trust 并重启客户端。（这条路径的插件目前仅 Windows；macOS / Linux 的现状见「平台支持」。）
> 成品二进制在 Releases：从最新发布下载 junimo-mcp.exe（附 SHA-256 校验文件）——不需要装任何开发环境。
> 喜欢自己动手，见下方《手动安装》。
## 它长什么样
┌────────────┐ stdio (JSON-RPC) ┌──────────────────┐ HTTP localhost:7850 ┌──────────────────┐
│ MCP 客户端 │ ◄──────────────────► │ junimo-mcp.exe │ ◄─────────────────────► │ JunimoBridge │ ──► 星露谷
│ (你的 AI) │ 37 个意图工具 │ (OCaml 5.5) │ 原生 HTTP(socket) │ (SMAPI mod) │
└────────────┘ └──────────────────┘ └──────────────────┘
工程亮点：
可靠性三纪律：游戏侧校验、逐格三态计分（成功 / 幂等跳过 / 失败带原因）、精确回读——"绝不假成功"；
四层测试防线：单元测试 + 114 项 mock 冒烟（不用开游戏）+ 真机测试套件 + 压测；
全中文人话回执：工具返回的错误文案可直接展示给用户，Agent 无需二次翻译。
## 前置依赖
| 项 | 版本 / 说明 |
| 游戏 | Stardew Valley 1.6.15（Steam 版实测） |
| SMAPI | 4.5.2（或 4.x 兼容版本） |
| 执行器 mod | JunimoBridge v0.1.0（解压到 Mods/JunimoBridge/，端口 7850）—— 或 NagiBridge-Remix v0.9（Mods/NagiBridge/，端口 7842） |
| OCaml（仅开发 / 构建需要） | 5.5.0 + dune 3.24 + yojson 3.0（Windows：opam + 受管 Cygwin，见下） |
> 推荐用 JunimoBridge：它是本项目的姊妹仓库（同样 MIT、只实现真正在用的那批端点、报文与 NagiBridge 对齐），
> 从 Releases 下 JunimoBridge.zip 解压到 Mods/ 即可。
> 两个 mod 的报文形状一致，junimo-mcp.exe 不用改一行；换哪个只由 STARDEWAPIURL 决定。
> ⚠️ 两个都是 NagiBridge 系的话别同装：原版 NagiBridge 与 Remix 的 UniqueID 不同（Nagi.NagiBridge vs pendel001.NagiBridge），
> 同装会抢 7842 端口。换装时把旧的 Mods/NagiBridge/ 整个移出 Mods 目录。
> JunimoBridge 走 7850，可以和 NagiBridge（7842）并存 —— 本机实测两个端口同时在听、4 个 mod 同跑无冲突。
> 许可说明：Remix 为原作授权二改（PolyForm Noncommercial 1.0.0，个人 / 非商业使用免费）；本项目与两个 mod 都只通过 HTTP 交互，不打包任何 mod 代码。
启动游戏：运行游戏目录里的 StardewModdingAPI.exe（不要走 Steam 启动，否则加载不到 mod；代价是 Steam 成就不可用）。进入存档后，执行器 mod 会在自己的端口起服（JunimoBridge = 7850）。
## 手动安装（4 步）
> 与 AGENTS.md 的《部署安装》章节一致，这里是人类版速览；每一步的校验方法与常见问题见那边的详细版。
| 步骤 | 做什么 | 要点 |
| 1 · SMAPI | 装 mod 加载器 | 若游戏目录已有 StardewModdingAPI.exe 则跳过 |
| 2 · 执行器 mod | 装 JunimoBridge（或 NagiBridge-Remix） | 解压到 \Mods\；JunimoBridge 走 7850、Remix 走 7842 |
| 3 · 服务器 | 从 Releases 下载并放好 junimo-mcp.exe | 免编译；建议放非 C 盘、路径不含空格 |
| 4 · 注册 | 写 ~/.workbuddy/mcp.json → Trust → 重启 | 格式见下 |
~/.workbuddy/mcp.json：
json
"mcpServers": {
"junimo": {
"command": "D:/junimo-mcp/junimo-mcp.exe"
> 不用写 STARDEWAPIURL：默认就是 http://localhost:7850。只有指到 NagiBridge 时才需要
> "env": { "STARDEWAPIURL": "http://localhost:7842" }。
写入后不会自动生效：到 WorkBuddy「连接器管理 → 右上角自定义连接器」给 junimo 点 Trust，并重启 WorkBuddy。
接入其它客户端？四家主流客户端都有现成配置（复制粘贴级，详见 AGENTS.md 的《步骤 5 · 注册到 MCP 客户端》）：