Junimo MCP server
Commit Nov 4, 2026An OCaml-based MCP server that enables AI agents to play Stardew Valley by performing farming, socializing, and exploring through 41 intent tools.
Also known as mlkgrnt/Junimo-MCP
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 4, 2026
- License
- MIT
What is Junimo MCP?
Junimo is an OCaml-based MCP server that enables AI agents to play Stardew Valley by performing farming, socializing, and exploring through 41 intent tools.
Summary generated from the project's README
About Junimo MCP server
Automating farming, socializing, and exploration in Stardew Valley is what Junimo-MCP enables for AI agents. This OCaml-based server provides 41 intent-driven tools that allow an agent to perform complex in-game tasks like harvesting crops, gifting NPCs, and managing inventory. It operates via JSON-RPC 2.0 over stdio, connecting your AI client to the game through a bridge mod like JunimoBridge or NagiBridge-Remix.
Developers can deploy the server on Windows, Linux, or macOS. On Windows, the integration is highly streamlined through the dsh-junimo plugin for DeepSeek Harness or manual registration in clients like Claude Code and Cursor. The server is designed for high reliability, using a verification system that reads game state to ensure an action like watering a tile actually succeeded before reporting success to the agent. It avoids common pitfalls by automatically handling long-distance pathfinding and batching farm tasks when tools are upgraded.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
STARDEW_API_URL
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablemlkgrnt/junimo-mcp is public and reachablegithub.com/mlkgrnt/junimo-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-04github.com/mlkgrnt/junimo-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubJunimo-MCP
简体中文 · 繁體中文 · English · Español
用 OCaml 手写的 MCP 服务器:给 AI Agent 一副在《星露谷物语》里干活的手——41 个意图工具(含剧情阅读与菜单关闭),从种地收割到取物聚餐、社交过节,全流程可靠执行。
- 协议层:JSON-RPC 2.0 over stdio,手写实现(
initialize/tools/list/tools/call),零 MCP 框架依赖 - 控制层:原生 HTTP + keep-alive(OCaml socket)→ JunimoBridge(默认
http://localhost:7850)→ 游戏内角色;也兼容 NagiBridge-Remix(7842,用STARDEW_API_URL指过去) - 不假成功:工具报成功 = 游戏里真的发生了(挥动/浇水后会回读地块直到效果真的落地才记账);失败大多无副作用(送礼失败自动退礼、吃失败不扣物),可放心重试
- 会挑快的路:
go_to一次请求走全程(出发前就否掉越界/大门/站不住的坐标);till/water在工具已升级时自动改用蓄力批量(一片地几挥搞定) - 依赖极简:唯一第三方 OCaml 库是 yojson;运行零外部依赖(HTTP 走原生 socket,不需要系统 curl;
STARDEW_HTTP=curl可回退到旧路径)
只想用、不想开发?让 Agent 一键部署
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) │ 41 个意图工具 │ (OCaml 5.5) │ 原生 HTTP(socket) │ (SMAPI mod) │
└────────────┘ └──────────────────┘ └──────────────────┘
工程亮点:
- 可靠性三纪律:游戏侧校验、逐格三态计分(成功 / 幂等跳过 / 失败带原因)、精确回读——"绝不假成功";
- 四层测试防线:单元测试 + 157 项 mock 冒烟(不用开游戏)+ 真机测试套件 + 压测;
- 全中文人话回执:工具返回的错误文案可直接展示给用户,Agent 无需二次翻译。
前置依赖
| 项 | 版本 / 说明 |
|---|---|
| 游戏 | Stardew Valley 1.6.15(Steam 版实测) |
| SMAPI | 4.5.2(或 4.x 兼容版本) |
| 执行器 mod | JunimoBridge v0.3.2(解压到 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不用改一行;换哪个只由STARDEW_API_URL决定。⚠️ 两个都是 NagiBridge 系的话别同装:原版 NagiBridge 与 Remix 的 UniqueID 不同(
Nagi.NagiBridgevspendel001.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:
{
"mcpServers": {
"junimo": {
"command": "D:/junimo-mcp/junimo-mcp.exe"
}
}
}
不用写
STARDEW_API_URL:默认就是http://localhost:7850。只有指到 NagiBridge 时才需要"env": { "STARDEW_API_URL": "http://localhost:7842" }。
写入后不会自动生效:到 WorkBuddy「连接器管理 → 右上角自定义连接器」给 junimo 点 Trust,并重启 WorkBuddy。
接入其它客户端?四家主流客户端都有现成配置(复制粘贴级,详见 AGENTS.md 的《步骤 5 · 注册到 MCP 客户端》):
| 客户端 | 配置位置 | 快速接入 |
|---|---|---|
| WorkBuddy | ~/.workbuddy/mcp.json |
图形界面点 Trust |
| Claude Code | ~/.claude.json / 项目 .mcp.json |
claude mcp add --transport stdio junimo -- "<EXE>" |
| Codex | ~/.codex/config.toml |
codex mcp add junimo -- "<EXE>" |
| DeepSeek Harness | dsh profile(dsh plugin add) |
使用 dsh-junimo 插件,一条命令,exe 已内置 |
DeepSeek Harness 用户:无需手工编写 cordis patch。dsh-junimo 已将本项目的 41 个工具封装为 dsh 组合包,内含
junimo-mcp.exe、部署自检(junimo_doctor)与游戏生命周期工具(聚焦 / 启动 / 读档),以及随包 skill 与操作纪律提示词。dsh plugin --profile web add github:mlkgrnt/dsh-junimo安装后重启 dsh,先执行
junimo_doctor完成链路检查。
冒烟验证
# 桥通了吗(必须带 --noproxy '*':绕开系统代理)
curl -sS --noproxy '*' http://localhost:7850/status
# {"ok":true,"server":"JunimoBridge","version":"0.1.0",...,"worldReady":true,...}
⚠️ 地址必须用
http://localhost:7850,不能用127.0.0.1——mod 的 HttpListener 只注册了 localhost 前缀,127.0.0.1 会被系统以 400 拒绝(实机实测)。同理,命令行调用一律带--noproxy '*'。
工具清单(41)
| 组 | 工具 | 说明 |
|---|---|---|
| 感知 | get_state |
全量状态(玩家 / 位置 / 时间 / 天气 / 背包 / 菜单)+ 状态速报 |
look |
环视半径内:作物(含阶段 / 浇水 / 可收)、物件、树石、NPC | |
get_inventory |
背包清单(水壶附余水量) | |
| 移动 | go_to |
寻路移动(长距自动分段接力;拒绝直线穿墙回退;距离 ≤1 即视为到达——部分目标格游戏侧不可站立,会停在邻格并如实回报坐标) |
warp |
跨地图传送(异步,自动回读确认落地位置) | |
face |
转向 0上 / 1右 / 2下 / 3左 | |
| 交互 | swing_tool |
挥动工具单次(走 /use:带游戏侧校验,报告实际作用格) |
use_held |
使用手持物(播种 / 放置) | |
interact |
与面前格交互(=确认键),返回面前格信息 | |
press_key |
模拟按键(confirm / cancel / 数字 / 方向…) | |
| 界面 | menu_read |
读当前菜单 / 对话 / 商店 / 按钮 |
story |
读/推进剧情:read 读当前一屏、next 下一屏、choose 选回答(会自动补一发「真实点击」让选择落地)、skip 跳过整段 | |
menu_close |
关掉当前菜单/文本框(睡完的 SaveGameMenu、夜里的 ShippingMenu 靠它) | |
menu_click |
点菜单(选项 index / 按钮名 / 坐标) | |
| 物品 | select_item |
选中背包物品拿在手上 |
| 农活 | till |
批量锄地(蛇形走位;幂等:"已锄"记软跳过;体力 <15% 中止) |
plant |
批量播种(目标格必须已锄;"已有作物"记软跳过) | |
water |
自动扫描"种了作物且未浇水"的格子逐格浇水(自动补水) | |
harvest |
批量收割成熟作物(游戏内瞬间完成,直接进包) | |
| 箱子 | chest_scan |
扫描当前地图所有箱子(位置 + 内容 + 格号) |
chest_take |
单箱取物(name 或 slot;count 缺省 = 全部;放不下留在箱里并如实回报) |
|
chest_take_list |
跨箱批量取物(只从"够得着"≤4 格的箱子凑清单;远箱列入 tooFar 附坐标) | |
| 吃 | eat |
吃东西回体力 / HP / 拿 buff(给名字自动选中;报前后数值;失败不扣物) |
| 社交 | find_npc |
全地图找 NPC(中英文模糊匹配;位置 / 朝向 / 是否睡觉 / 正在说的话) |
friendship |
查好感(点数 / 心数 / 本周与今日已送次数;中文名自动解析) | |
gift |
给 NPC 送礼(真实流程;返喜好档位与好感变化;送满 / 被拒自动退礼) | |
| 节日 | festival |
节日情报(今天 / 明天 / 下一个节日 + 正在进行中的活动现场状态) |
festival_interact |
节日现场与 NPC 互动(自动走位 + 触发;仅活动进行中) | |
festival_answer |
节日问答 / 分支提交(answer 序号) |
|
| 生计 | sleep |
睡觉翻日(唯一落盘方式——SDV 只在睡觉 / 翻日时存档);返回新一天状态 |
buy |
远程购买(售价×2,直接进包;id 472 = 防风草种子) | |
ship |
发货箱卖出(给 name 或 all=true;工具 / 种子 / 装备自动保留;需在农场) |
|
chest_read |
读取箱子内容(同地图任意距离,无需开箱) | |
chest_store |
把背包物品存进箱子(工具默认保留) | |
map_info |
建筑 / 传送点 / NPC / 动物情报(导航规划用) | |
pause_time |
冻结游戏时钟(长任务防晕倒;记得恢复) | |
resume_time |
恢复被冻结的游戏时钟 | |
| 钓鱼 | fishing |
钓鱼状态 + 找钓点(radius>0 时列出附近水域与「站哪格、往哪抛」) |
cast |
蓄力抛竿,ms 控制远近;失败自动重试一次 |
|
fish |
全自动一条:抛竿→等咬钩→提竿→控绿条→结算。回执分 won / delivered / directCatch,只认 delivered |
|
| 小游戏 | minigame |
read / key / quit;键名用字面物理键(小游戏不读键位绑定) |
农活组统一纪律:站 (tx, ty-1) 朝下 → 瞬移 + 精确回读校验 → /use(核对返回命中格 == 期望格)→ settle 0.55s;每格失败带原因列出,绝不盲挥。
从源码构建(开发者)
标准 opam 环境(Linux / macOS / 常规 Windows)直接使用 dune:
opam install yojson # 唯一的第三方依赖
dune build # → _build/default/bin/main.exe
dune runtest # 单元测试
Windows 受管 Cygwin 工具链(本项目的开发环境)则走 build.sh 统一入口——它负责:受管 Cygwin bash + pi-env.sh + OCAMLPATH + 无条件清 _build/.lock(陈旧锁会引发莫名报错):
bash build.sh build # dune build → _build/default/bin/main.exe
bash build.sh runtest # 单元测试
bash build.sh release # 构建并复制到 release/junimo-mcp.exe
bash build.sh exec -- ... # 透传任意 dune 子命令
工具链踩坑记录(装配方式、Cygwin 参数重写、lock 坑等)见配套 skill「ocaml-windows-toolchain」。
测试
| 套件 | 命令 | 说明 |
|---|---|---|
| 单元测试 | bash build.sh runtest |
JSON-RPC 编解码、状态解析 / 渲染、蛇形地块数学 |
| mock 冒烟 | python test/mock_smoke.py(自动起 mock) |
假 NagiBridge(完整状态机:地图 / 移动 / 菜单 / 校验 / 生计 / 取物 / 社交 / 节日),157 项全流程断言,不需要游戏 |
| 真机闭环 | python test/live_e2e.py |
需游戏在跑:锄地 → 播种 → 浇水 + 独立 HTTP 交叉核验 |
| 真机完整农活 | python test/live_m4.py |
需游戏在跑:自动进档 → 买种 → 3×3 锄 / 种 / 浇 → 催熟收割 → 长距分段导航 |
| 真机 v2 生计 | python test/live_v2.py |
需游戏在跑:map / 箱子读写 / 时钟控制 / 睡觉翻日(会推进一天并写盘) |
| 真机 v3 生活 | python test/live_v3.py |
需游戏在跑:天气 / 箱子扫描取物 / 吃 / 找人与送礼 / 节日(改动最小可逆) |
| 真机抽检 | python test/live_swing.py |
单次挥动工具的正 / 负用例 |
| 稳定性压测 | python test/live_soak.py [分钟] |
连续读写 + 走位,统计错误率与 curl 子进程回收 |
mock 与真机使用同一代码路径(只换 STARDEW_API_URL),mock 的 /use 校验语义与真 mod 逐字对齐。
CI(GitHub Actions):push / PR 跑 Linux + Windows(构建 + 单元测试 + mock 冒烟); macOS 每天定时跑一次,另外手动触发和打 tag 时也会带上 —— 免费档的 macOS runner 排队动辄十几分钟, 放进每次 push 的关键路径只会让"这次改动过没过"这个唯一有用的信号一直挂着。
这不只是多测一遍,而是跨平台可行性探针:mock_smoke.py 全程不需要游戏(它自己起一个假 mod),所以 157 项断言在三平台全绿,即证明内核层不含平台绑定。矩阵绿 ≠ 非 Windows 能玩——端到端还要执行器 mod 与窗口聚焦支持:JunimoBridge 的虚拟输入走进程内补丁(可移植),但 /focus / 前台判据仍依赖 Win32;NagiBridge 的 /press_key / /click_tile 更是直接用 user32。
环境变量
| 变量 | 默认 | 说明 |
|---|---|---|
STARDEW_API_URL |
http://localhost:7850 |
执行器 mod 地址(必须 localhost):默认指 JunimoBridge,指 NagiBridge 时写 http://localhost:7842 |
STARDEW_HTTP |
native |
HTTP 实现:native(原生 socket + keep-alive)/ curl(回退,排查用) |
STARDEW_HTTP_TIMEOUT |
30 |
单次 HTTP 调用超时(秒;批量端点可调大) |
STARDEW_SETTLE |
自适应 | 通用动作结算等待:不设=自适应(400ms 起,失败 +150 / 连续成功 −50);NNN 固定毫秒;fixed = 旧行为 550ms。农活(till/plant/water)现在按效果核验自定步,不受此项影响 |
STARDEW_AUTO_MENU |
1 |
动作前自动按掉"无选项对话"(NPC 招呼 / 提示框);=0 关闭(一律交回 Agent 处理) |
STARDEW_AUTO_EVENT |
未设 | =1 时剧本事件(过场)自动 skip;默认不跳(跳剧情是口味问题) |
STARDEW_WALK |
walk |
go_to 走位实现:walk(默认,一次请求走全程,出发前校验越界/门格/站不住)/ move(旧的分段接力,排查对照用) |
STARDEW_AREA |
auto |
till/water 是否走 mod 的批量蓄力端点:auto(工具升级后自动启用)/ force(达格数阈值就启用)/ off(一律逐格) |
STARDEW_AREA_MIN |
4 |
批量最少作用格数(低于此值逐格更可控) |
STARDEW_AREA_TIMEOUT |
90 |
批量端点单次等待上限(秒) |
STARDEW_TIMEOUT |
30 |
轮询总超时(秒) |
STARDEW_CURL |
自动探测 | curl.exe 路径覆盖(仅 STARDEW_HTTP=curl 时用) |
STARDEW_NO_STRIP |
未设 | =1 关闭返回文本末尾的状态速报 |
STARDEW_LOG |
warn |
stderr 日志级别(debug / info / warn) |
平台支持
| 平台 | 产物 | 状态 |
|---|---|---|
| Windows x86_64 | junimo-mcp.exe |
主开发平台,端到端完整可用 |
| Linux x86_64 | junimo-mcp-linux-x86_64 |
在 ubuntu-22.04(glibc 2.35)构建,发布前通过全部 157 项免游戏断言 |
| macOS arm64 | junimo-mcp-macos-arm64 |
在 Apple Silicon 构建,发布前通过全部 157 项免游戏断言。Intel Mac 暂无产物,可自行 dune build |
三个产物都附 .sha256(格式 <hash> + 两个空格 + 文件名):
https://github.com/mlkgrnt/Junimo-MCP/releases/latest/download/junimo-mcp-linux-x86_64
https://github.com/mlkgrnt/Junimo-MCP/releases/latest/download/junimo-mcp-macos-arm64
它们在 Release binaries 工作流里构建,关键一点:发布前先在该平台上跑一遍 mock 套件,而 mock 直接驱动待上传的那个文件——所以通过断言的正是发布出去的二进制,不是"另一个能编译的版本"。
范围要说清。 跨平台的是内核(这个 OCaml 服务器)。它通过 HTTP 与游戏内的执行器 mod 通信,而 mod 的 /press_key 与 /click_tile 使用 Windows 的 keybd_event / mouse_event,在 macOS / Linux 上没有实现,这两个端点会失败。其余工具不依赖平台——读状态、走位、农活、菜单读写都走进程内调用,/click 在有菜单或带 no_mouse 时同样如此。
也就是说:macOS / Linux 上可以构建并直接使用本服务器,少数端点需要自行适配 mod。 想要开箱即用的 Windows 集成,用 dsh-junimo。
已知限制
-
fish回执分三层:won只是打赢钓鱼小游戏,delivered才是物品真入包,directCatch是垃圾类直接发放(不进小游戏);别把progressPeak=1当成果。产出垃圾是游戏特性(农场池塘getFish本身如此),不是故障,不用排查;换钓点或加鱼饵可改善。 -
截图 / 录像不可用:本机 GDI 抓不到 OpenGL 画面——验证一律走游戏内 API 读数(比截图更精确)。
-
长距移动:mod 的 BFS 有 500 步上限,
go_to已内置分段接力(≤10 格/段)绕过;跨地图请用warp。 -
给宠物起名(NamingMenu)是 mod 盲区:
/menu不暴露它的文本框与按钮。工具输出里会直接给出办法——menu_click {"x":800,"y":352}接受默认名字(16:9 布局实测有效),press_key cancel则退回上一步。 -
长时段挂机:先
pause_time冻结游戏时钟(现实 ~12 分钟游戏内就从早到 2:00 晕倒,实测会扣 10% 金币),结束resume_time。 -
远程购买:mod 的
/buy端点按售价 ×2 计价(无商店界面的便利费 / 调试端点)。 -
无"明天天气预报":只有当天天气(
get_state的【天气】行);"今天 / 明天是不是节日"由工具内置日历计算。 -
节日到场需自行导航:
festival系列负责情报与现场交互;去节日场地走游戏原生入口,别用warp直接传非节日地图(不会触发节日场景)。 -
收割 / 取物前请用
get_inventory确认背包空间(背包满会掉地上)。 -
游戏进度靠
sleep落盘:不睡觉直接关游戏,当天操作会回滚——让 Agent 每天收尾时sleep。
文档导航
| 文档 | 给谁看 | 内容 |
|---|---|---|
AGENTS.md |
AI Agent | 部署安装 + 十条铁律 + 41 工具速查 + 开发纪律 |
README.md |
人类 | 本文件(简体中文 zh-Hans) |
README.zh-Hant.md / README.en-US.md / README.es-ES.md |
人类 | 繁中 / 英文 / 西语版本 |
| dsh-junimo | DeepSeek Harness 用户 | dsh 插件版:内置 exe、一条命令安装、含部署自检与游戏生命周期工具 |
test/ |
开发者 | 四层测试套件 |
许可与致谢
本项目自身代码以 MIT 许可开源,见 LICENSE。
- 执行器 mod(推荐):JunimoBridge(MIT,本项目的姊妹仓库)——只实现真正在用的那批端点,报文与 NagiBridge 对齐
- 执行器 mod(兼容):NagiBridge-Remix(PolyForm Noncommercial 1.0.0,作者 pendel001)——个人 / 非商业使用免费;本项目与两者都只通过 HTTP 交互,不打包任何 mod 代码
- 上游原作:NagiBridge(MIT)
- 控制层理念与端点语义:NagiBridge 原作者(
farm_row.py/water_crops.py的站姿 / 时序纪律) - 状态速报(state strip)设计参考 NagiBridge-Remix
- JunimoBridge 的行为与报文兼容性由同一套真机验收(
live_m4/live_e2e/live_v3/live_swing)守着
Junimo MCP questions
What can the AI agent do in Stardew Valley with this server?
The agent can perform a wide range of tasks including farming (tilling, planting, watering, harvesting), socializing (finding NPCs, giving gifts), fishing, managing chests, and navigating the game world.