nanoodle

nanoodle-mcp

在 nanoodle.com 上以可视化方式构建多模型媒体工作流——然后将整个工作流作为一个类型化工具交给你的 Agent。

技能还是 MCP？ 只运行（或设计）一个工作流？nanoodle 技能只需一条命令，无需设置。这个服务适用于你已经构建了一组保存的图，并希望将每张图都作为独立工具提供给 Agent 的情况。

将此 MCP 服务指向一个存放 nanoodle 编辑器保存的 noodle-graph.json 文件的文件夹，每张图都会变成一个可调用工具，并派生出输入架构——可用于 Claude Code、Grok、Claude Desktop、Cursor、VS Code、Windsurf，或任何支持 Model Context Protocol 的工具。默认情况下，它通过 stdio 与你自己的 Agent 通信；也可以通过 HTTP 面向所有人提供服务，使用服务模式——还可以按调用收费，让陌生人的 Agent 也能付费运行你的工作流，无需在任何地方创建账户。

没有中间人服务，也没有遥测——使用钱包模式时，也无需账户。这里的 MCP 实现是手工编写的（stdio + 可流式传输的 HTTP、JSON-RPC 2.0——代码小巧易读）。运行时仅依赖两个项：nanoodle（MIT），零依赖的工作流执行器，负责所有繁重工作；以及 nanocurrency（GPL-3.0），用于签署 Nano 区块——仅在 x402 路径中加载，详见许可。你的 NanoGPT API 密钥会直接从你的机器发送到 nano-gpt.com；它绝不会被记录，也不会出现在 stdout 中。

示例：从描述生成一个可玩的格斗角色

游玩 Iron Verdict：一位熔炉骑士，拥有重力跳跃、拳击、地面重击和极具惩罚性的竞技场战斗。编码 Agent 使用 character-sprites 技能构建了这款游戏。

character-sprites 图会将一段对人形角色的描述转换为角色参考图和匹配的部件图。该技能的本地骨骼绑定脚本会把这些部件转换为带有图集和时序元数据的透明待机、行走、出拳和跳跃帧。随后，编码 Agent 会实现物理、战斗和游戏规则。最终游戏展示了这种组合的效果；一次 MCP 调用返回的是参考图和部件图，而不是完整游戏。

将 character-sprites 图放入服务的图文件夹，即可将其作为工具提供。使用 tools/list 检查指定服务是否已挂载该图，并在调用前读取其输入架构。对于已发布的图，生成步骤如下：

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"character-sprites","arguments":{"Character":"A compact furnace knight with an ivory helmet, amber visor, navy armor and brass gauntlets. Outlined 2D platformer art. No weapon or wings."}}}

安装该技能，以进行本地提取和动画制作（需要 Node 22.23.4+、24.22.1+ 或 26.12.1+，以及 ffmpeg/ffprobe）。一个实用的 Agent 请求示例：“使用 character-sprites 根据我的描述制作一个动画格斗角色，检查关节和 Alpha 边缘，然后构建一个小型可玩竞技场，采用强重力和有冲击感的战斗。”

安装

你需要：Node 22.23.4+、24.22.1+ 或 26.12.1+、一个保存的图表文件夹（例如 ~/noodles——参见 制作图表），以及一个 nano-gpt.com API 密钥，存放在 NANOGPT_API_KEY 中（或通过 --key / --env-file 传入）——也可以不使用密钥，改用 Nano 钱包，参见 钱包模式。

可选：将 ffmpeg 添加到 PATH。 图表包含本地媒体节点的工具 （调整大小、提取视频帧、合并、音频剪辑/提取）通常会使用纯 JS 方式处理，但对于无法处理的格式，则会回退到 ffmpeg/ffprobe——JPEG/WebP 调整大小、读取视频帧、压缩音频。未安装 ffmpeg 时，这些运行会失败（收费模式下会自动退款）；服务会在启动时打印警告，列出受影响的工具。纯图像/LLM/视觉工具不需要它。 使用 apt install ffmpeg（Debian/Ubuntu）/brew install ffmpeg 安装。

Claude Code

claude mcp add nanoodle --env NANOGPT_API_KEY=your-key-here -- npx -y nanoodle-mcp --graphs ~/noodles

也可以将其安装为插件——Claude Code 会提示你选择 noodles 文件夹并输入 API 密钥，还会了解 noodle 是什么（此仓库也兼作插件市场）：

/plugin marketplace add nanoodlecom/nanoodle-mcp
/plugin install nanoodle@nanoodle

Grok

grok mcp add nanoodle -e NANOGPT_API_KEY=your-key-here -- npx -y nanoodle-mcp --graphs ~/noodles

或者使用远程/服务端点（无需本地进程，机器上也无需 API 密钥）：

grok mcp add --transport http noodles https://mcp.nanoodle.com/mcp

这会将 [mcp_servers.noodles] 写入 ~/.grok/config.toml（如果使用 --scope project，则写入 .grok/config.toml）。手动配置时格式相同：

[mcp_servers.noodles]
url = "https://mcp.nanoodle.com/mcp"
enabled = true

Cursor

在 Cursor 中安装 （然后编辑图表路径和密钥），或者自行添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "nanoodle": {
      "command": "npx",
      "args": ["-y", "nanoodle-mcp", "--graphs", "/absolute/path/to/noodles"],
      "env": { "NANOGPT_API_KEY": "your-key-here" }
    }
  }
}

VS Code

.vscode/mcp.json——注意 VS Code 的根键是 servers，而不是 mcpServers：

{
  "servers": {
    "nanoodle": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "nanoodle-mcp", "--graphs", "/absolute/path/to/noodles"],
      "env": { "NANOGPT_API_KEY": "your-key-here" }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "nanoodle": {
      "command": "npx",
      "args": ["-y", "nanoodle-mcp", "--graphs", "/absolute/path/to/noodles"],
      "env": { "NANOGPT_API_KEY": "your-key-here" }
    }
  }
}

Claude Desktop

格式与 Cursor/Windsurf 相同，放在 claude_desktop_config.json 中的 mcpServers 下。

ChatGPT

ChatGPT 只能连接远程 HTTPS MCP 服务。托管端点已上线——添加 https://mcp.nanoodle.com/mcp（按调用次数以 Nano 付费，无需 API 密钥）。本地 stdio（npx nanoodle-mcp --graphs …）仍采用 BYOK 模式，ChatGPT 无法访问。

⚠️ 这会花费真金白银

该服务使用你的资金运行——可以使用 nano-gpt.com API 密钥（BYOK），也可以不使用密钥，改用你自己的 Nano 钱包，通过 x402 付款。每次 tools/call 都会针对 NanoGPT API 执行一个工作流，并从余额中扣款——而调用方通常是自行决定何时调用的 AI Agent。只将服务连接到你愿意运行的图表，并留意余额。 每个结果末尾都会附上一行 cost: $X.XXXX，让 Agent（以及你）了解每次调用的花费。

钱包模式——无需账户、无需 API 密钥（x402）

NanoGPT 支持 x402 免账户付款： 不带密钥的 API 调用会返回包含 Nano 发票的 HTTP 402，付款后调用即可完成。为服务端提供一个钱包，它就会自动完成这些操作——无需 NanoGPT 账户、无需 API 密钥，也无需在任何地方注册：

export NANO_SEED=<64-hex seed>        # account 0 pays; or NANO_PRIVATE_KEY=<64-hex key>
nanoodle-mcp --graphs ~/noodles --max-usd 0.50

每次调用时，服务端都会：收到 402 发票 → 在本地签署 Nano 发送区块 → 通过 Nano RPC 节点广播（--nano-rpc / NANO_RPC_URL，默认为 rpc.nano.to）→ NanoGPT 检测到存款并返回结果。种子/私钥绝不会离开进程：只有已签名的 区块会发送到 RPC 节点，而且绝不会记录任何机密信息。如果提供了 API 密钥，则始终优先使用 API 密钥——只有在不使用密钥时才会使用钱包。

工作量证明的可靠性。 每个发送区块都需要 Nano 工作量证明。服务端会先向 RPC 节点请求 work_generate，但公共节点通常会拒绝请求或限制频率（没有 GPU，需要密钥）；此时会回退到本地单线程 CPU 运算，可能需要一分钟。可通过 --work-rpc / NANO_WORK_URL 使用以下两种快速方案：

• 托管 GPU 工作量 API——亚秒级完成，无需硬件。例如 nano.to 的 PoW API（--work-rpc https://rpc.nano.to） 或 Nanswap Nodes （--work-rpc https://nodes.nanswap.com/XNO——快速工作服务器仅供其付费方案使用；免费方案需要排队数分钟）。将 API 密钥放入 NANO_WORK_KEY（环境变量或 --env-file，切勿作为标志传入）——密钥会同时作为 key 请求体字段（nano.to 风格）和 nodes-api-key 请求头（Nanswap 风格）发送。
• 在同一台机器上运行自己的 nano-work-server （nano-work-server --cpu-threads 8 -l 127.0.0.1:7076 → 几秒内完成工作，永久免费）。

执行顺序：--work-rpc（超时为 2 分钟，避免服务器无响应导致付款停滞） → --nano-rpc 节点 → 本地 CPU。钱包还会在区块发布后立即为下一个区块预先计算工作量，而服务模式会在启动时预热——只要有任何可用的工作量来源，调用者实际上就无需等待工作量证明。

本地 CPU 作为最后的备用方案时，会在 Node 主线程上运行：在 --serve 模式下，发送难度运算（需要数分钟）会在运行期间冻结整个 HTTP 服务。如果你的远程工作量来源可靠，请传入 --no-local-work——此时发送失败会妥善处理（无法支付的发票会被提前拒绝，而退款/付款发送失败时，余额会留在钱包中，供下次结算转出）。

这是一个热钱包。 请使用存放少量资金的专用钱包，而不要使用存款钱包：钱包余额自然构成支出上限，此外，--max-usd 还会为每次调用设置单独的上限。NanoGPT 会在其端自动退还多付款项，并退还生成失败的费用。

更倾向于预付？ 钱包模式会按次在链上结算。如果你希望一次付款并逐步扣减余额，这正是 NanoGPT 账户的用途： 将加密货币（包括 Nano）存入账户，获取 API 密钥，并以常规 BYOK 模式运行服务端——工具相同，只需付款一次。

服务模式 — 将你的 noodles 托管为服务（--serve）

以上所有内容都通过 stdio 使用 MCP 与你自己的 Agent 通信。--serve 则改为通过可流式传输的 HTTP使用 MCP，将一个 noodles 目录变成一项服务，供任何人的 Agent 连接：

nanoodle-mcp --graphs ~/noodles --serve 8402

调用者只需一条命令即可连接——无需密钥，无需注册：

claude mcp add --transport http noodles https://your-host/mcp
# or
grok mcp add --transport http noodles https://your-host/mcp

GET / 会提供一个落地页，其中列出工具和那条原样的命令（Claude 和 Grok 可通过一键切换——使用相同的端点和标志），因此分享服务的裸 URL 就是入门方式。页面上的每个工作流都链接到其来源：一个在编辑器中打开链接（从正在提供的确切图文件生成的分享链接——它会在 nanoodle 编辑器 中加载工作流，以便查看、改编或使用你自己的密钥运行），以及其原始图 JSON，位于 /graph/<tool>.json。页面还会说明费用构成（按计量成本加 20% 结算；对于指定了收款地址的图，加价部分归作者所有；对于其余图，则归运营者所有，页面会标明哪些是你的），以及如何自托管——此服务、编辑器和执行器均采用 MIT 许可（许可）。生成的媒体会通过无法猜测的 /out/… URL 提供（小图片也会随工具结果内联返回）。不会记录运行本身：免费服务模式不会保留任何人调用了什么的记录；收费模式只保留付款账本（仅记录资金事件，不记录运行遥测——见下文）。

生成的媒体会在 --out-ttl 指定的小时数后删除——这是隐私保障措施，防止托管服务永远将所有调用者生成的内容囤积在磁盘上。在 --serve 模式下，默认值为 24h；传入 --out-ttl <hours> 可更改（0.5 这样的分数也可以），传入 --out-ttl 0 则会保留所有内容。stdio 模式下默认关闭——你在本地生成的文件由你自行保留——但如果传入此标志，也会遵照执行。清理操作只会删除媒体文件（图片、视频、音频）；绝不会触及运营者自己的 costs.json、gate-state.json 和 usage.jsonl。请注意，24h 的默认值与收费门控的重放窗口一致：付费结果可在 24h 内重放，并会引用其 /out/ URL，因此在收费模式下将 --out-ttl 设为短于 24h，可能导致重放结果指向已被清理的文件。

隐私——你的服务会保留什么

使用默认设置运行时，托管服务作出的同一承诺在你的设备上也同样成立，且每一行代码都可以在此仓库中查证：

• 无需账户、无需 API 密钥、无需登录。 在收费模式下，付款是授权调用的唯一条件。
• 提示词和输入绝不会写入磁盘或日志。 输入媒体仅在内存中流转——绝不存储。在收费模式下，支付门控只保留一段短哈希，用于将付款与调用绑定（hashArgs），绝不保留参数。
• 生成的媒体会在 --out-ttl 小时后自动删除（--serve 默认 24 小时，本地 stdio 模式下关闭），在此之前可通过难以猜到的 /out/… URL 访问。设置 --out-ttl 0 可永久保留所有内容。
• 结果保留在内存中以供交付，不会存储——重启状态文件不包含结果文本或错误详情。
• 没有分析数据、跟踪器或 IP 日志——应用不会保留请求日志。在收费模式下，它唯一写入的内容是 usage.jsonl，这是记录资金生命周期事件的账本，与公开的 Nano 账本相对应——不包含运行遥测数据或错误文本。免费服务模式完全不写入账本。

gate-state.json 本身从不包含客户内容。它用于确保部署引发重启时，在途资金安全——报价和待发送款项都会保留——但付费工具的文本输出和任何上游错误详情绝不会写入磁盘。媒体结果只会持久保存其 /out/ 指针和收据；文本结果则什么也不会持久保存。因此，在运行工具后、调用方重试前发生重启时，只会重新运行工具（只收费一次，交付一次——运营方承担一次重复的模型调用），而不会从磁盘重放内容；运行失败时，则会重放固定的占位内容和退款状态，绝不会重放原始错误消息。

有一点需要明确说明：生成任务运行在 NanoGPT 的 API 上，因此传输中的提示词内容受其隐私政策约束。

免费服务模式使用的是你的余额——在可信网络中没问题，但放到开放互联网中就会造成巨大损失。要在这种情况下使用，请为调用收费：

按调用收费（--charge-usd）

nanoodle-mcp --graphs ~/noodles --env-file wallet.env \
  --serve 0.0.0.0:8402 --public-url https://noodles.example.com --charge-usd 0.05

现在，每次工具调用都由调用方以 Nano（XNO）付款，双方都无需账户。Agent 会按以下流程操作（服务的 MCP instructions 会自动引导它）：

每次遇到需要付款的报价时，tools/call 都会挂起，并返回 payUrl、watchUrl 和一个 next 指令（blocking: false）：

1. 付款。 只向用户展示 payUrl（包含准确金额的二维码）；任何 Nano 钱包都可以扫描。绝不要向用户展示 watchUrl 或钱包地址。
2. 监控——立即在同一个付款链接上进行。 Agent 获得报价后，立即打开 watchUrl（GET /x402/watch/<id>，仅供 Agent 使用的 SSE）。每次状态变化都会发送一个 status 事件；付款到账后，流会以 done: true 和指向第 3 阶段的 next 字段关闭。（付款页面使用相同的流；可将 GET /x402/status/<id>?wait=1 作为轮询备用方案。）检测方式为 RPC 轮询，或通过 --nano-ws 推送——大约只需一秒。
3. 获取结果。 只有在监控流因付款到账而关闭后，才能使用相同参数和 _payment_id 重新调用工具。该 tools/call 就是结果流——它会运行工作流（在流式传输中发送进度心跳），并返回结果和收据。付款仍在监控中时，不要打开该流。使用相同 _payment_id 重新调用会免费重放缓存结果。

用户支付的是押金，而不是最终价格：调用最终按实际计量的大模型成本加 20% 结算；超出部分会作为找零退回付款钱包——与 NanoGPT 自身使用的押金→计量→退款模式相同，只是多了一层。任何人都不会按估算金额付款。 Nano 没有付款备注，因此每个报价的金额都会带有一些随机的原始 dust——金额就是备注。报价 15 分钟后过期；迟到的付款会立即退回，付款后运行失败时会自动退款。签发报价前会先验证参数（不会有人为拼写错误付款），而 run_noodle 已从收费模式中移除——任意分享链接的费用无法预先定价。

定价：--charge-usd 设置上限押金，以及某个工具从未运行过时的初始报价。工具运行过后，其押金会自动根据实际费用调整：报价为结算价格的两倍（来自 costs.json sidecar 的最高观测计量费用 + 20%），向上取整到整分，最低为 1¢——计量费用为 $0.004 的工具，报价押金为 $0.01，而不是固定上限。请将上限设得宽裕些；多收的费用会作为找零退回，因此不会让调用方多付；但押金不足时，运行费用可能超过已收金额，差额将由你承担（如果某个图的押金低于最近一次观测费用 + 20%，网关会在启动时发出警告）。XNO 汇率直接来自 NanoGPT：网关会发送一个无需密钥的 x-x402 探测请求，并保留发票中的精确 raw-XNO/USD 汇率对——这与下游付款结算使用的汇率相同，因此报价与费用不会因汇率而产生偏差，也不涉及任何市场数据服务（探测发票不会付款，只会过期）。缓存有效期为 60 秒，探测服务中断时会沿用过期缓存；如果需要，也可以通过 --xno-usd 强制使用静态汇率。每个图的覆盖设置是图 JSON 中手动添加的顶层区块：

"x402": { "usd": 0.10, "author": "nano_1abc…" }

humanize-comment 会为每个请求单独报价。报价根据实际发送的草稿、上下文、指导内容和 maxChars 生成。每次调用的 max_tokens 都会根据该请求调整大小：使用 maxChars；若未提供 maxChars，则使用草稿长度，再加少量余量。判定器还会为其排名 JSON 和 GLM 推理预留令牌，这些内容共用 max_tokens 配额。令牌数按每个令牌约 3.5 字节估算。最坏情况下的定价涵盖每位写作者各调用一次、额外重试一次、判定器调用一次，以及在可修复受保护片段或可要求判定器确认一个符合要求的改写（标题、长度上限或必需结尾）时，再进行第二轮判定器调用。当 Cydonia 失败并启用 Starry Ocean 备用方案时，两次调用都会计费。 对于托管付款，报价会限制客户的最高付款金额。若某个步骤的估算费用或发票会使总支出超过报价，则会跳过该步骤。跳过写作者步骤后，结果会标记为部分结果；若没有发送任何内容，则无需付款。跳过判定器步骤或判定器不可用时会报错，不会将原始草稿作为成功评论返回。押金是在该计价费用基础上增加 12%，最低为 $0.001，并向上取整，且绝不会低于该费用。托管付款结算时，向客户收取实际计量费用 + 20% 与报价押金两者中的较低金额，并退还差额。如果服务提供方计量的费用超过报价，超出部分由运营方承担。此退款和上限仅适用于托管付款。直接钱包支出没有上限，也不予退款。短评论不会按最长评论的额度预留押金。图中的 usd 仅作为最长请求的费用上限，在模型没有价格信息时使用。

usd 会覆盖其他所有工具的押金。author 会将每次成功调用的 20% 加价转给该地址——按运行的实际费用计算，绝不按押金计算；且转账金额不得超过扣除费用后押金中的剩余金额（押金不足以覆盖费用 + 20% 时，作者只能收到剩余部分）。Nano 没有网络费用，且此服务不抽取加价，因此创作者可保留实际转出的全部金额。如果没有 author 字段，加价将留在运行服务器的钱包中——这是每个图的可选设置，而非默认行为。按每笔结算调用精确到 raw 计算：

cost   = metered model cost, converted at the deposit's own oracle pair, rounded up
markup = cost / 5                    (20%, integer floor)
take   = min(markup, deposit − cost) → author (or kept, if no author field)
change = deposit − cost − take       → back to the payer

一次运行的费用超过其押金时，押金将全部扣留，超出部分由运营方承担；如果模型报告的费用为零，则按 $0 结算，并退还全部押金（绝不会根据计费器未产生的数字向调用方收费）。整个计算过程端到端精确到整数：USD 小数按字符串解析为纳美元，汇率采用 oracle 发票中的原始 raw/USD 数值对，每次换算都使用明确向下或向上取整的 BigInt 比率运算，浮点数绝不会用于链上数值。

钱包（通过 --env-file 设置 NANO_SEED / NANO_PRIVATE_KEY）接收付款、发送退款和作者收益，并且——如果你未设置 API 密钥——还会通过 x402 按次向 NanoGPT 付款，让整个服务实现纳美元收入、纳美元支出。使用 API 密钥时，运行费用由密钥支付，钱包只处理客户付款。

付款检测

默认始终开启的方式，是轮询你的 Nano RPC 节点上的 receivable（有待处理报价时每 1 秒轮询一次）。添加 --nano-ws wss://… 即可订阅 Nano 节点 websocket，以推送方式检测付款——此时结算几乎即时，轮询则作为安全保障。也有公共 websocket（例如，撰写本文时 wss://nanoslo.0x.no/websocket 可用）；自有节点才是可靠之选。无论采用哪种方式，轮询器也会检查 account_history，因此由同时运行的钱包收取的付款也能被发现。

付款账本

在收费模式下，<out>/usage.jsonl 是一份付款账本：每笔资金事件单独占一行，仅包含 quote、paid、refund、change、author_payout——这是你的服务端自身的资金流动记录，不包含任何客户端信息。它刻意不是使用日志：没有 run 事件、运行时间、成功／失败遥测信息，也没有上游错误字符串（其中可能引用用户内容）。资金事件确实包含 .tool——工具名称是付款的对象，而不是运行记录——因此你能看到哪些工具带来收益，却无法知道谁在何时运行了什么工具，也无法知道运行是否失败。退款只记录固定类别（run_failed、late_payment），绝不记录底层错误文本——完整错误仍会返回给调用方，并输出到运营方的 stderr。免费服务模式不会写入任何账本。以下是一些起始示例：

jq -r 'select(.event=="paid") | .tool' usage.jsonl | sort | uniq -c | sort -rn  # paid calls per tool
jq 'select(.event=="paid") | .settleMs' usage.jsonl                             # quote→settle latency
jq 'select(.event=="paid") | .usd' usage.jsonl | jq -s add                      # gross deposits taken
jq -r 'select(.event=="refund") | .reason' usage.jsonl | sort | uniq -c         # refunds by category

托管检查清单

• 反向代理／隧道：绑定 localhost，在前面配置 Caddy/nginx/cloudflared 以启用 HTTPS，并将 --public-url 设为外部 URL（付款链接和媒体链接均由此生成）。

• systemd（按需调整路径）：

  [Unit]
  Description=nanoodle-mcp serve
  After=network-online.target
  
  [Service]
  ExecStart=/usr/bin/npx nanoodle-mcp --graphs /srv/noodles --out /srv/noodle-out \
    --env-file /srv/wallet.env --serve 8402 --public-url https://noodles.example.com \
    --charge-usd 0.05 --work-rpc http://127.0.0.1:7076
  Restart=on-failure
  
  [Install]
  WantedBy=multi-user.target
  

• 保持小额热钱包余额：该钱包是热钱包。定期将收入转入冷存储；如果使用 API 密钥，也要限制该账户的余额。

• 工作服务器：退款和付款都通过 Nano 转账，需要工作量证明——使用托管 GPU 工作 API（nano.to、Nanswap；在环境文件中设置密钥 NANO_WORK_KEY），或者将 NANO_WORK_URL 指向你通过 tailnet 在任意自有设备上运行的 nano-work-server --gpu（工作请求仅包含区块哈希，不含任何秘密信息）。无论哪种方式，都要配合 --no-local-work，避免工作服务中断时服务器因在 CPU 上执行工作量计算而卡住。钱包材料和密钥环境变量都应放在 --env-file 中；该文件也可配置 NANO_WS_URL，用于设置包含密钥的 websocket URL（例如 Nanswap 的 wss://nodes.nanswap.com/ws/?ticker=XNO&api_key=…）。

• 此处有意不设置身份验证：在收费服务上，付款就是授权。不要提供你不希望陌生人运行的图表。

工作原理

~/noodles/
  generate-hero-image.json   →  tool "generate-hero-image"
  make-jingle.json           →  tool "make-jingle"

--graphs 中每个可读取的 *.json 图都会成为一个 MCP 工具：

工具字段	根据图推导
name	去掉 .json 的文件名，并清理为 [a-z0-9_-]（重复项会获得 -2、-3，……）
description	图中的首条注释（如果有）、按依赖顺序排列且包含节点名称的节点链（例如 text:Feature -> llm -> image:Mockup）、returns … 契约（输出类型、末端节点的模型／尺寸以及保存到磁盘的说明）、费用警告，以及工具运行后观测到的最近一次费用（last run $0.018）
inputSchema	每个未连接字段对应一个字符串属性，与 nanoodle CLI 的 inspect 完全一致；下拉字段会变为 enum；只有没有预设默认值的输入才是 required
媒体输入	图片／音频／视频输入接受文件路径或 https URL——本地文件会以 base64 内联传递
结果	文本输出作为文本块；媒体输出保存到 --out（默认为 ./nanoodle-out），并返回绝对路径；最后一个文本块报告本次运行的费用；如果本次运行更改了调用者要求的内容，结果开头会有一个 note: 块（见下文）

如果本次运行没有原样使用你的提示词，结果会说明。 许多图像和视频模型会直接拒绝过长的提示词；而在图中，提示词通常由上游 LLM 编写——没人手动输入，也就没人能缩短它。nanoodle（0.8.0+）会在句子边界处将提示词截短至模型的上限，而不是让本次运行因必然出现的 400 错误而失败。只有告知调用者这一情况，这样的做法才站得住脚，因此工具结果会以截短提示开头：

note: prompt trimmed for "Poster" (qwen-image-3) — the prompt was 1320 characters
and this model accepts at most 800, so nanoodle cut it to 791 characters at a
sentence boundary. The run used the shortened prompt.

这在计费模式下尤为重要，因为本次运行的费用已经产生。库也会发出 process 警告，但 stderr 属于启动服务的主体，而不是支付费用的 Agent。

⚖️ Decide gate 返回否是一个结果，而不是错误。 nanoodle 0.9.0 会运行 Decide 节点。返回否的 yes/no gate 会以状态 gated 结束，并停止其分支。工具结果正常返回（isError 不为真），会收取该决策产生的少量费用，门后所有节点均不会运行或产生费用。结果开头会显示：

gated: "Is it a cat?" answered no (yes 12%), so the run stopped there on purpose — skipped, not billed: "Cat poem". This is a result, not an error.
Cat poem: skipped — gate "Is it a cat?" answered no
cost: $0.000003

值得了解的协议行为：格式错误的调用（未知工具、未知／缺失／非字符串参数）会在花费任何费用之前作为 JSON-RPC -32602 被拒绝；运行失败（网络、模型错误、缺少密钥）则会作为普通工具结果返回，并设置 isError: true。

usage: nanoodle-mcp --graphs <dir> [--graphs <dir> …] [--out dir] [--key K] [--env-file path] [--nano-rpc url] [--work-rpc url] [--max-usd n]

  --graphs dir   directory of noodle-graph.json saves (required; repeat to serve
                 several dirs — scanned in order, so an earlier dir wins name clashes)
  --out dir      where media outputs are saved (default ./nanoodle-out)
  --key K        NanoGPT API key (defaults to NANOGPT_API_KEY)
  --env-file p   read NANOGPT_API_KEY / NANO_SEED / NANO_PRIVATE_KEY / NANO_WORK_URL /
                 NANO_WORK_KEY / NANO_WS_URL from a .env-style file
  --nano-rpc u   Nano RPC node for wallet mode (default https://rpc.nano.to; NANO_RPC_URL)
  --work-rpc u   dedicated work_generate endpoint — a local nano-work-server or a hosted
                 GPU work API (NANO_WORK_URL; NANO_WORK_KEY carries its API key;
                 falls back to --nano-rpc, then local CPU work)
  --max-usd n    wallet mode: refuse any single x402 invoice above $n

密钥优先级与 nanoodle CLI 一致：--key > --env-file > NANOGPT_API_KEY；钱包密钥只能来自环境或 --env-file，绝不会来自 argv。如果没有目录包含可运行的图，服务将拒绝启动，并在 stderr 中说明每个文件的问题；stdout 仅用于协议通信。

每个项目的图 + 共享库

--graphs 可以重复指定，因此一个服务可以合并多个文件夹。做法是：将 noodles/ 目录提交到仓库，作为该项目自己的工具，然后将全局库列在它之后作为后备：

nanoodle-mcp --graphs ./noodles --graphs ~/noodles

目录会按给定顺序扫描，较早的目录在名称冲突时优先：如果两个文件夹都有 changelog.json，项目中的文件会成为 changelog，共享库中的文件则会成为 changelog-2。因此，只需在 ./noodles 中放入同名图，项目就可以覆盖共享工具，同时 ~/noodles 中的其他所有内容仍然可用。无法读取的目录（例如拼写错误或目录不存在）会导致启动错误，并指出出错目录——不会静默地只加载一部分。

将其接入编辑器

大多数客户端的 MCP 配置都是按项目设置的，因此这两个目录的模式会放在仓库中，就在它所服务的图表旁边。对于 Claude Code，这是项目根目录中的 .mcp.json——将它与 noodles/ 一起提交，所有克隆仓库的人都会获得相同的工具：

{
  "mcpServers": {
    "nanoodle": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "nanoodle-mcp", "--graphs", "./noodles", "--graphs", "/home/you/noodles"]
    }
  }
}

相对路径以项目根目录为基准解析。项目级服务器 nanoodle 会覆盖同名的用户级服务器，因此带有 .mcp.json 的仓库会使用自己的图表，其他所有目录则会原样使用你的全局安装。

提交配置时有两项内容需要排除：你的 API 密钥（不要填写 env，让 NANOGPT_API_KEY 从环境变量中读取，或将 --env-file 指向仓库外的文件——绝不要提交密钥）；以及团队仓库中的 个人库路径（上方第二个 --graphs 是你自己的机器上的绝对路径；从共享仓库的配置中删掉它，只保留 ./noodles，因为 MCP 参数不会展开 ~）。Cursor（.cursor/mcp.json）和 VS Code（.vscode/mcp.json）的配置格式与安装中所示相同，使用相同的 args。

运行任意分享链接

每个 nanoodle 分享链接都是一个可执行工具。除了已保存的图表，服务器始终还会公开一个名为 run_noodle 的工具，它接受任意分享链接并运行，无需文件：

run_noodle("https://nanoodle.com/#g=…", { "Text": "a lighthouse at dawn" })

将链接作为 url 传入，将工作流输入作为 inputs 传入（使用图表自身工具所接受的相同易用键名；媒体输入可以是文件路径或 https URL）。它接受 #g=/#j= 工作流链接、#a= 应用链接，以及指向上述链接的短链接。直接链接会在本地解码；只有不含片段的短链接会触发网络读取，且不会携带凭据。与其他所有工具一样，运行会产生实际费用，并以 cost: $X.XXXX 行结束。

创建图表

在 nanoodle 编辑器中构建并测试工作流，点击 💾，然后将下载的 noodle-graph.json 放入你的 --graphs 文件夹（重命名它——文件名会成为工具名称）。重启服务器（或 MCP 客户端）以载入新文件。

描述你的工具

图表中的第一个注释节点会同时用作 MCP 工具的描述：其文本会排在自动生成的节点链之前，因此调用该工具的 Agent 会先读到你的文字。将描述控制在一句话，说明工具会根据哪些输入生成什么内容——例如，“根据一行功能描述渲染产品模型图像。” 长文本会截断至 200 个字符，空白也会合并，因此请按单行内容撰写。没有注释的图表仍只会显示节点链，与之前一样。

每次成功运行后，工具的实际费用都会记录在 <out>/costs.json 中（一个小型 {tool: {usd, at}} 旁置文件，位于媒体输出旁边），并合并到描述中的 last run $X——这是实际观察到的费用，而非估算值。服务器会通过 notifications/tools/list_changed 通知宣布更改，因此支持该通知的 MCP 客户端会在会话期间显示更新后的价格；其他客户端则会在重启时获取更新。

局限

如实列出——其中大多数是执行器本身的限制：

• 仅支持前馈 DAG。 nanoodle 图是无状态流水线；没有循环、对话，也不会在调用之间保留记忆。
• 每次调用运行一次，不支持流式传输。 tools/call 会一直阻塞，直到整个工作流完成——视频图可能需要几分钟。目前还不支持 MCP 进度通知。
• 图仅在启动时加载一次。 添加或编辑 --graphs 中的文件需要重启；工具列表不会在会话中途变化（没有 listChanged 通知）。
• 无头模式的支持范围以 nanoodle 0.9.0（此软件包的依赖项）为准。 本地媒体图（resize、combine、trim、extract-audio、video-frames、soundtrack）在你的机器上运行——尽可能使用纯 JS，其余部分则需要 PATH 中有 ffmpeg。Decide、Clean voice（cleanvoice）、3D model（model3d）、3D input（mupload）和自定义端点节点也会加载并运行；它们不会在启动时跳过。Decide 门关闭时会正常返回 gated 结果。请参阅支持的节点表。如果图中包含库不认识的节点类型，仍会在启动时跳过，并在 stderr 中显示提示。
• 媒体以内嵌方式传输。 NanoGPT 没有上传端点，因此媒体输入会以 base64 格式放在请求正文中发送（上限约为 4 MB，花费发生前会检查）。
• 密钥模式没有费用上限。 服务不会阻止客户端反复调用高成本的图。NanoGPT 余额是唯一的限制。（钱包模式在这方面更好：--max-usd 会限制每次调用的费用，钱包余额则会限制总费用。）

不进行遥测或分析；API 密钥和钱包密钥绝不会被记录，也不会出现在 stdout 中。

测试

完全离线——测试套件会启动真实服务，通过本地预置的 NanoGPT 模拟服务运行，并通过 stdio 完成 MCP 握手：

npm test

测试套件还包含发布检查：三个发布清单的版本必须一致，落地页的芯片表只能列出 nanoodle 库仍支持的节点类型，且任何启动路径都不得静态导入 GPL-3.0 依赖项。

这些检查可离线运行，因此只会相互比较仓库文件，无法访问 npm。另有一项检查需要联网，因此会在发布工作流中运行，而不是包含在 npm test 中：scripts/assert-npm-version.mjs 会在发布到注册表时检查 server.json 中的版本是否确实已发布到 npm。请参阅 PUBLISHING.md。

注册表

server.json 是官方 MCP 注册表清单（io.github.nanoodlecom/nanoodle-mcp）；发布检查清单请参阅 PUBLISHING.md。

我该选择哪个仓库？

此服务会将已保存的工作流作为类型化 MCP 工具提供。如果你的 Agent 支持 Agent Skills，而不是 MCP 服务，那么 nanoodle-skill（教你的 Agent 构建任意图）和 noodle-skills（预先构建的单任务工作流）可以提供类似功能，无需运行服务。在 GitHub CI 中运行图？→ run-noodle-action。

许可

MIT： 此服务（见 LICENSE）、nanoodle 编辑器，以及此服务用于运行图的执行器 nanoodle。相关项目 — nanoodle-py、 nanoodle-skill、 noodle-skills — 也采用 MIT 许可。

图不受上述许可约束。 noodle-graph.json 是其作者的作品。将其作为工具提供，或从 /graph/<tool>.json 下载，都不会使其受本仓库许可约束。本项目维护的公共库 awesome-noodles 采用 MIT 许可，因为该仓库如此声明；其他任何服务上的图则遵循其作者指定的许可。

GPL-3.0： 一个运行时依赖项 nanocurrency。它用于派生 Nano 密钥、构建并签名区块，以及计算工作量证明。它仅用于可选的 x402 Nano 钱包：钱包模式（NANO_SEED / NANO_PRIVATE_KEY）和收费模式（--charge-usd）。

请明确这对你意味着什么。每位安装者都会收到它。 npm install nanoodle-mcp 和 npx -y nanoodle-mcp 都会将 nanocurrency 下载并解压到你的磁盘上，无论你是否使用 x402。自安装起，你的依赖树中就包含 GPL-3.0 代码，而且它会随你基于此软件包构建的任何 bundle 或镜像一起再分发。

按需加载改变的范围更窄，而且仅涉及这一点：哪些运行会执行它。 src/wallet.mjs 和 src/gate.mjs 是唯一会使用 nanocurrency 的模块，而 bin/nanoodle-mcp.mjs 通过 await import() 在已启用 x402 的分支中调用它们。因此，BYOK（API 密钥）运行不会加载或执行 GPL-3.0 代码 — 但它仍会安装该代码。tests/gpl-boundary.test.mjs 用于确保这一边界。

我们有意将其保留为普通依赖项。npm 默认会安装 optionalDependencies，因此这样做不会带来任何改变；唯一能跳过它的方式是将其设为可选的 peerDependency，但这样一来，npx -y nanoodle-mcp — 文档中介绍的一条命令安装方式 — 就完全无法运行钱包或收费模式。正确标注许可，比让免账户安装方式无法使用更重要。

与 NanoGPT 或 Anthropic 无关联。在 nanoodle.com 构建工作流；使用 nanoodle-js / nanoodle-py 通过代码运行。