Skip to main content
Glama

CraftGraph MCP

把运行中的 Minecraft 配方数据接到 AI 客户端上的 MCP 服务器。

这是 Craft-Graph 的消费端:模组负责读游戏、出快照, 这里负责配方树、产线计算、缓存和 MCP 工具。两半通过本地 HTTP 协议通信(protocolVersion 是兼容判据)。

它是什么

  • 输入:MCP(stdio),给 Claude Code / Cursor / DSH 这类客户端用

  • 数据来源:本机运行中的 Minecraft(由 CraftGraph 模组暴露),游戏关着时退回磁盘快照

  • 输出:配方树、产线规划、搜索结果,支持 markdown / tsv / json / html

Related MCP server: kontexta

安装

npm ci
npm run build

然后把客户端指向 dist/index.js(需要 Node ≥ 20):

{
  "mcpServers": {
    "craftgraph": {
      "command": "node",
      "args": ["/绝对路径/Craft-Graph-MCP/dist/index.js"]
    }
  }
}

模组那一半(jar)在 Craft-Graph releases。

工具

用途

工具

状态 / 覆盖度

get_bridge_status、refresh_recipes

查找

search_items、get_registry、list_recipe_types、expand_tag

配方

get_recipes_for_output、get_recipes_for_input、get_recipe_details、find_alternative_recipes

规划

build_recipe_tree、calculate_production_plan

不给 AI 客户端也行:npm run plan -- --item create:brass_ingot --rate 100 直接在终端出规划, --html 生成自包含网页。

Skill

skill/craftgraph/SKILL.md 是给 AI 客户端的工作流说明(先确认产量、怎么读 opaque/截断、不要手工重算)。 复制到客户端的 skills 目录即可。

开发

npm run typecheck   # 类型检查
npm run smoke       # 算法层,不需要游戏
npm run e2e         # MCP 协议层
npm run contract    # 跨语言契约,需要 fixtures/bridge-dump/
npm run live        # 对运行中的游戏体检
npm run measure     # 改了输出/渲染就跑,看 token 涨没涨

fixtures/bridge-dump/ 不入库(陈旧样本会让契约测试假通过)。它有两个来源:

  • CI:从 bridge 的同版本 Release 下载 protocol-<ver>.zip(见 .github/workflows/ci.yml);

  • 本地:跑一次 bridge 的 ./gradlew test,把 protocol/fixtures/* 复制到 fixtures/。

两边的版本号约定对齐(MCP 的 package.json version ↔ bridge 的 tag)。

许可

MIT

Available Tools

12 tools
build_recipe_tree构建配方树A

递归展开一个物品的完整制作链,列出每一层需要什么、需要做几次,并汇总基础原料。用户问「X 怎么做出来的」「做 X 需要哪些原料」时首选这个工具。结果已经处理了循环配方、标签选择、概率产出,并说明所有不确定的地方。

默认只展示前 3 层结构(更深的分支用「⋯」标出节点数和原料),但基础原料是完整的 —— 未展开的分支也已计算在内。要看某个分支的细节,把 detailDepth 调大,或者直接拿那个物品再调用一次本工具。

Inputs: item (required), kind, count, format, +5 more.

calculate_production_plan计算产线A

给定目标产量(每分钟多少个),算出需要哪些机器各多少台、每分钟消耗多少原料、产出多少副产、总耗能。用户问「我要每分钟 X 个 Y,怎么建产线」时用。注意这是贪心近似:每种物品固定选一条配方(报告里会说明选路判据和落选候选),副产只统计不回代。

顶部那几张汇总表(机器/原料/副产/能耗)才是重点,逐环节明细默认只展示前 3 层。

Inputs: item (required), ratePerMinute (required), kind, format, +5 more.

expand_tag展开标签A

列出某个标签包含的所有物品。配方的输入里出现 #xxx 时,用这个看它到底可以是哪些东西。想知道某物品属于哪些标签,用 search_items 或 get_recipes_for_output 的结果。

Inputs: tag (required).

find_alternative_recipes查找替代配方B

找出同一物品的所有其他做法,并比较它们的原料和耗时,帮助用户选一条。用户问「还有别的做法吗」「哪条更省」时用。

Inputs: item (required), kind.

get_bridge_status检查与游戏的连接状态A

检查 CraftGraph 是否连上了 Minecraft、缓存了多少条配方、数据版本是多少。任何其他工具报错说连不上游戏时,先用这个确认状态。用户问「为什么查不到配方」时也先调这个。

Inputs: no named parameters.

get_recipe_details查看配方的完整信息A

按 id 获取配方的完整输入输出、耗时、耗能。需要先通过其他查询拿到具体配方 id。要看多条时用 recipeIds 一次传(最多 20 条)—— 逐条调用会让往返次数随配方数线性增长。

Inputs: recipeId, recipeIds.

get_recipes_for_input查某物品能用来做什么A

查询所有把指定物品当作输入的配方。用户问「X 有什么用」「X 能做什么」时用。已正确处理标签:用 #forge:ingots/iron 这类标签作输入的配方也会被算进来。

Inputs: item (required), kind, limit.

get_recipes_for_output查某物品是怎么做出来的A

查询所有能产出指定物品的配方。用户问「X 怎么做」「X 怎么来的」时用这个。会同时返回读不懂的配方(标记 opaque),因为「有配方但读不懂」和「没有配方」是两回事。

Inputs: item (required), kind, limit.

get_registry查询注册表A

列出 blocks / items / fluids / entities / recipe_types 注册表的内容。需要游戏在运行 —— 如果只是想找物品 id,优先用 search_items(它读本地缓存,离线也能用)。

Inputs: kind (required), limit, query.

list_recipe_types列出所有配方类型A

列出这个整合包里存在的全部配方类型及各自的配方数量。用户问「这包里有哪些机器/配方类型」时用,也用来判断某个模组的配方有没有被读出来。

Inputs: no named parameters.

refresh_recipes重新拉取配方数据A

强制重新从游戏拉取配方并重建缓存。正常情况下不需要调用 —— 配方重载会被 dataVersion 自动检测到。只在用户明确说「我刚改了配方」或怀疑数据不对时用。

Inputs: no named parameters.

search_items搜索物品A

按名称或 id 搜索物品,返回匹配的 id 列表。用户说「铁锭」「iron」这类模糊说法时,用它确定准确的物品 id,再拿去调配方查询工具。不需要游戏在运行。

Inputs: query (required), limit.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 12 tools

    Disambiguation4/5

    Most tools have clearly distinct roles: status check, cache refresh, item search, registry listing, and recipe-type listing are all unambiguous. The recipe query group has mild overlap — get_recipes_for_output, find_alternative_recipes, and build_recipe_tree all answer 'how to make X' — but the descriptions carefully differentiate them by scope (raw recipe list vs. comparison vs. recursive tree).

    Naming Consistency5/5

    Every tool uses consistent snake_case verb-first naming (get_, list_, search_, find_, build_, calculate_, expand_, refresh_). The pattern is predictable and readable throughout, with no camelCase or mixed conventions.

    Tool Count5/5

    Twelve tools sit squarely in the well-scoped range and each earns its place, covering status, search, querying, and planning without redundancy.

    Completeness5/5

    Covers the full recipe-querying lifecycle: connection status, cache refresh, item search, registry and recipe-type listing, input/output recipe lookup, detailed recipe data, alternative comparison, recursive crafting trees, production planning, and tag expansion. Minor gap would be a direct item-detail tool, but search_items and expand_tag effectively bridge that.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to interact with and manage Minecraft servers through a standardized interface, supporting server monitoring, player management, log analysis, and command execution.
      11
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      A local-first MCP server that gives AI coding agents persistent memory and controlled commands. Features a git-backed markdown knowledge vault with FTS5 search, surgical section edits, token-aware context budgeting, and a sandboxed command engine with human approval gates. Works with Claude Code, Cursor, Copilot, Gemini, and more.
      58
      196 npm
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      A local MCP server that lets coding agents turn conversational prompts into deterministic, re-runnable recipes for 3D objects, walkable worlds, and playable games, all stored on your own disk without API keys or cloud rendering. Those recipes can be edited in place and exported to the browser, Godot, Unity, Unreal, Blender, glTF/OpenUSD, or print-ready STL and 3MF at true scale.
      3
      Apache 2.0