cookie-mcp

cookie-mcp

一个 Model Context Protocol（MCP）服务，为任何 AI Agent 提供 Cookie Chain 区块链上的链上工具——读取市场信息、兑换代币、发行代币和 NFT 收藏、管理流动性、质押、交易 NFT，以及跨链桥接至 Solana。

它通过 stdio 在本地运行，并且使用你机器上的密钥签名，因此从设计上就是非托管的。对于托管应用（网页聊天、网站后面的机器人），它以 外部签名者模式运行：服务不持有密钥，每项操作都会在签名步骤停止并生成经过验证的交易，由用户自己的浏览器钱包签名——工具相同，安全防护也相同（详情）。这是一个面向整个 Cookie Chain 生态系统的社区项目。

目录

• 功能
• 安装 — Claude Code · Claude Desktop · Cursor
• 启用交易（添加密钥）
• 试用
• 配置
• 工具
• 托管／钱包签名模式 — 适用于 Web 应用及其他集成方
• 客户端身份 · 安全性
• 开发 — 发布

功能

• 了解市场动态——查询链状态、流动性池、代币信息、搜索代币、获取兑换报价和钱包余额。无需密钥。
• 兑换任意 Cookie Chain 代币对，可使用任一聚合器——Cookiebox Swap API 或 Candy Shop——两者都会聚合所有 Cookie Chain DEX 的流动性。Agent 可通过 aggregator 参数在每次调用时选择聚合器，也可以分别获取两者的报价进行比较。chain: "solana" 则通过 Jupiter 在 Solana 主网上买卖桥接的 COOK。
• 转账 COOK 或任意 SPL / Token-2022 代币。
• 在 Cookiebox 限价订单托管合约中设置限价单和止损单——按指定价格或更高价格止盈，或在汇率跌至触发价时按市价卖出的止损单；由 keeper 在所有可路由的 Cookie Chain 市场中成交。
• 在 MomoSwap 发射台发行代币——在 COOK 联合曲线上创建代币、买卖曲线代币、毕业后领取代币，以及提取创作者手续费。
• 在 MomoSwap NFT 发射台发行并铸造 NFT 系列——从图片文件夹发行固定供应量的 NFT、沿 COOK 联合曲线铸造项目、在项目开放期间卖回、毕业后赎回底价，以及领取创作者收益。
• 管理流动性——在 Cookiebox DAMM v2、Cookiebox CLMM 和 CookieSwap BAMM 中创建池、添加 / 移除流动性、领取手续费，并永久锁定头寸（自动检测交易场所）。
• 质押 COOK 以获取 bCOOK，并即时赎回。
• 在 Aera借贷——存入 COOK 赚取利息，或将 bCOOK 锁定为抵押品并借入 COOK；签署任何操作前都会检查健康因子。
• 在 Baked Bazaar交易 NFT——搜索、浏览、购买、上架以及发起 / 接受报价（Cookie Chain 的 Metaplex Auction House 市场）。
• 通过 Hyperlane跨链桥接 COOK、SOL，以及之后添加到桥上的任意代币，在 Cookie Chain 与 Solana 主网之间按 1:1 转移。
• 拥有一个名称——在 CookOven 名称服务中注册、转让和解析 .cook 名称，并在任何需要填写地址的地方使用它们（transfer to: "bot.cook"）。

默认安全：添加密钥前仅支持只读操作，所有涉及资金的操作都会在发送前进行模拟。

安装

需要 Node ≥ 22。无需安装或构建任何内容——首次运行时，npx 会获取已发布的软件包。请在下方选择你的客户端。三者使用相同的服务；区别仅在于配置文件的位置。

Claude Code

最快的方式——只需一条命令，即可在所有项目中使用：

claude mcp add --scope user --transport stdio cookie-mcp -- npx -y cookie-mcp

此命令会以只读模式（无密钥）注册服务。请参阅启用交易以添加钱包。

作用域——claude mcp add 会将配置写入以下三个位置之一；使用 --scope 选择：

--scope	可用范围	存储位置
user	你的所有项目	~/.claude.json
(省略) local	当前项目目录	~/.claude.json（按文件夹）
project	克隆仓库的任何人	仓库根目录中的 .mcp.json

仅当你希望将服务提交到特定仓库时，才使用 --scope project——它会写入 .mcp.json，队友首次使用时必须批准。对于这类通用工具，默认选择 --scope user 即可。

验证服务是否已注册：

claude mcp list          # all servers
claude mcp get cookie-mcp # this one's details
# or run /mcp inside a Claude Code session

Claude Desktop

编辑配置文件（若文件不存在则创建），然后重启 Claude Desktop：

• macOS — ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows — %APPDATA%\Claude\claude_desktop_config.json

在 mcpServers 下方添加下文的服务配置块。

Cursor

编辑 ~/.cursor/mcp.json（全局生效）或项目中的 .cursor/mcp.json（如果两者都存在，以项目配置为准），然后添加服务配置块。

服务配置块

Claude Desktop、Cursor 和 Claude Code 的 .mcp.json 使用完全相同的格式：

{
  "mcpServers": {
    "cookie-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "cookie-mcp"],
      "env": {
        "COOKIE_RPC_URL": "https://rpc.cookiescan.io",
        "COOKIE_PRIVATE_KEY": ""
      }
    }
  }
}

启用交易（添加密钥）

无需密钥即可读取数据。若要让 Agent 兑换、转账、发行、质押、提供流动性、购买 NFT 或跨链桥接， 请通过 COOKIE_PRIVATE_KEY 提供钱包——可以是 base58 密钥、solana-keygen JSON 字节数组，或密钥对文件的路径。

• **配置文件客户端（Desktop / Cursor / .mcp.json）：**将其放入上方的 env 块中。

• **Claude Code：**使用 --env 重新运行添加命令（注意：此配置会保存到 ~/.claude.json；请避免将原始密钥留在 shell 历史记录中）：

  claude mcp add --scope user --transport stdio cookie-mcp \
    --env COOKIE_RPC_URL=https://rpc.cookiescan.io \
    --env COOKIE_PRIVATE_KEY=<your-key-or-path> \
    -- npx -y cookie-mcp
  

你的密钥不会离开本机，仅用于本地签名，并且会从所有输出中隐去。每笔资金转移操作在发送前都会进行模拟。由场馆 API 构建的交易（兑换、任何 launchpad 操作）也会受到你请求内容的限制：如果模拟结果需要的金额超过请求金额加手续费、会触及你持有的其他代币、会将你的代币账户或委托人交给他人，或交付的金额低于报价中的最低金额，则交易会被拒绝签名。

试用

注册完成后，只需自然地向 Agent 提出请求：

• “Cookie Chain 现在的健康状况如何？” → chain_health
• “查找 cookhouse 代币，并告诉我它的价格和流动性。” → search_tokens → get_token_info
• “报价将 10 COOK 兑换为 bCOOK。” → get_quote
• “将 10 COOK 兑换为 bCOOK。” → get_quote → trade（需要密钥；先模拟）
• Token-2022 transfer-hook 代币（发行方代码会在每次转账时运行，并可能拒绝转账）：get_quote 始终会返回 warnings[]，而 trade 会返回 routeWarnings[]——每个挂钩 mint 对应一条记录，包含 reviewed、title、detail。交易前请阅读 detail。transfer 可处理挂钩 mint；在 Cookiebox CLMM 上，如果挂钩 mint 会导致交易超出限制，add_liquidity/create_pool 会将开启和存入交易拆分；如果 mint 仍需要 Cookiebox TokenBadge，create_pool 会提前拒绝。
• “有哪些 COOKHOUSE NFT 正在出售？帮我买下 50 COOK 以下最便宜的一件。” → search_nfts → buy_nft
• “你准备从哪个钱包交易？” → get_wallet

Agent 会通过 search_tokens / search_nfts 将名称解析为 mint 地址，然后对该 mint 执行操作—— 它绝不会直接根据名称进行交易。

配置

变量	默认值	用途
COOKIE_RPC_URL	https://rpc.cookiescan.io	Cookie Chain RPC。
COOKIE_PRIVATE_KEY	—	用于转移资金的工具的钱包密钥。未设置时为只读。
COOKIE_SIGNER	local	external = 进程中不保存密钥；工具返回 needs_signature，由用户的钱包签名。
COOKIE_WALLET_ADDRESS	—	外部模式：请求未携带 x-cookie-wallet 标头时使用的默认钱包。
COOKIE_MCP_HTTP_PORT / _HOST / _PATH	— / 127.0.0.1 / /mcp	使用 Streamable HTTP 而非 stdio 提供服务（等同于 --http [port]）。
COOKIE_MCP_CORS_ORIGIN	*，或使用本地密钥时不设置	允许调用 HTTP 服务的浏览器来源，以逗号分隔（* = 任意来源）。
COOKIE_MCP_HTTP_TOKEN	—	每个 HTTP MCP 请求都必须发送的 Bearer 令牌。使用本地密钥通过 HTTP 连接时为必填项。
COOKIE_MCP_ALLOWED_HOSTS	使用回环地址绑定时为回环名称	HTTP 服务响应的 Host 值，以逗号分隔（阻止 DNS 重绑定）。
COOKIE_IMAGE_DIR	主目录	deploy_token.imagePath 和 create_nft_drop 的美术素材可读取的唯一文件夹（仅限 stdio）。
COOKIE_SLIPPAGE_BPS	500	默认滑点（bps）。
COOKIE_REFERRER	mcp treasury	推荐钱包（仅限 MomoSwap）。
COOKIE_APP_ID	—	应用名称，会通过 User-Agent 发送给交易平台（参见客户端身份）。
SOLANA_RPC_URL	https://api.mainnet-beta.solana.com	Solana RPC。
JUPITER_API_KEY	—	可选；否则使用无密钥的 Jupiter，每秒 0.5 次请求。

工具

读取（无需密钥）：chain_health、get_pools、get_token_info、search_tokens（将代币名称或代码解析为其 mint）、 get_quote、get_wallet（此服务使用哪个密钥签名，以及使用的 RPC——不调用 RPC，因此即使链不可用也能正常工作）、get_balance、stake_info（bCOOK 流动质押汇率 / TVL / APY / 手续费）、启动平台读取工具 get_launchpad_pools / get_launchpad_token / get_launchpad_positions，以及 NFT 读取工具 get_nft_listings、search_nfts（将 NFT 或系列名称解析为已上架的 mint）、get_nft、 get_wallet_nfts、get_nft_offers、get_nft_market_stats，以及 .cook 名称读取工具 resolve_domain / get_owned_domains / get_domain_listings，还有 get_bridge_tokens（桥接可转移的代币）。 资金（需要 COOKIE_PRIVATE_KEY）：trade（通过 Cookiebox 或 Cookiescan 进行兑换）、transfer（COOK 或任意代币，可选通过 SPL Memo 程序写入 memo——可用于支付发票或付款请求，这类请求会按 memo 匹配转账）、unwrap_cook（将钱包中的包装版 COOK——Launchpad 推荐收益和 NFT 售回款会存入其中——转换回原生 COOK）、stake / unstake（COOK ⇄ bCOOK 流动性质押）。

限价订单（Cookiebox 限价订单托管，程序 L1M1tk…）： get_limit_orders 无需密钥即可列出钱包的挂单（可查询自己的订单，也可查询任意地址 / .cook 名称）；place_limit_order 和 cancel_limit_order 需要 COOKIE_PRIVATE_KEY。订单会将输入资产锁定在程序拥有的储备金中；keeper 通过 trade 使用的同一套路由器完成成交，因此任何有可用路由的交易对都可以挂单，并将输出支付到固定的账户（支持部分成交）。有两种订单：

• limit（默认）是止盈单：达到指定价格或更优价格时成交。指定价格必须高于当前汇率。
• stop 是止损单，属于止损市价单：price 是触发价，必须低于当前汇率；当可执行汇率跌至该价位时，keeper 会按市价卖出并转交所得款项。链上还设有一个隐藏的价格下限（低于触发价 50%，可通过 floorPrice 覆盖），它只限制遭到入侵的 keeper 密钥可能支付的金额上限——并不代表你实际会收到的金额。

唯一的费用是程序收取的做市方手续费，启动时为 10 个基点，从每笔成交中扣除，并从链上实时读取（在 get_limit_orders 中显示为 fees）。订单默认一周后到期（expiresInSeconds，0 = 持续有效直至取消，最长一年）；过期订单仍会锁定输入资产，直至订单被取消。原生 COOK 会在下单时包装，取消时退还为 COOK。

在 cookiebox.app 上创建的 MomoSwap 曲线订单也会显示在 get_limit_orders 中：curve-buy 是普通托管订单，成交所得为曲线份额（可像其他订单一样在此取消）；curve-sell 是 Launchpad 出售授权，并非托管订单——escrowed: false，份额仍可用于支出，且 createdAt 为 null。cancel_limit_order 会撤销该授权：聚合器没有适用于它的 cancel-tx，因此此服务会先从链上读取授权信息（由 Launchpad 拥有、指令鉴别符正确、钱包为所有者），再自行构建 Launchpad 的 revoke_position_sale，随后在订单支付给仍然存在的曲线出售金库时调用限价订单程序的 settle_curve_sell(close)。结果会显示 revoked: true；由于没有资产被锁定，因此不会退还任何资产。 place_limit_order 也可为仍处于曲线阶段的代币下单（根据铸币地址检测），适用于代币与 COOK 的直接交易对（仅限 limit，不支持止损单）。COOK → 代币会变成 curve-buy：一笔普通托管订单，结算款是你的 launchpad 持仓，由 keeper 的 buy_for 执行；如果你的钱包尚未启用 enable_buy_for，系统会在首笔订单中加入这项免费的单次授权，并检查池的 minBuy / 每钱包上限，若订单无法成交则会提前拒绝。代币 → COOK 会变成 curve-sell：为 Cookiebox keeper 按你的底价创建一笔 approve_position_sale 授权，每个池一笔，并支付到你的曲线卖出金库——即限价订单程序为此池和钱包创建的 wCOOK 账户，同一笔交易中完成创建。每次成交款都会支付到该金库，程序的 settle_curve_sell 会将其转给你的钱包，扣除限价订单 maker 手续费（makerFeeBps，实时读取）；你在底价处实际收到的是 netAfterFee，且以原生 COOK支付（payoutNative: true，无需代币账户）。底价就是价格本身：若价格为 P，曲线支付到 P 时订单成交，你收到扣除手续费后的 P，与普通订单相同。keeper 会拒绝任何支付目标不是该金库的授权，因此无法创建免手续费的订单。cancel_limit_order 会撤销授权；只要金库仍存在，也会结算并关闭金库，退还两笔租金。订单有效期会被限制在销售本身的结束时间：launchpad 将授权有效期上限设为 30 天，且不会读取池信息；但 launch 结束后无法成交，而一次 launch 最长运行 7 天，因此 expiresAt 永远不会晚于 saleEndsAt。否则，一周的默认有效期会创建一笔显示为未来过期、实际上却永远无法成交的订单。此服务会自行组装这两种订单（聚合器自 2026-09-22 起已支持组装，但本地组装可确保签名字节根据我们读取的信息生成）；随后，买入订单会经过与聚合器组装结果相同的指令级验证器检查，且两种订单都会在签名前进行模拟。

⚠️ 交易由聚合器组装；此服务会在签名前进行验证。 每条指令都会根据程序 IDL 解码并检查，包括手续费支付方、maker、金额、类型、有效期、固定的退款 / 收款账户、订单 PDA，以及是否仅涉及预期的五个程序（托管、compute budget、system、token、associated-token）。若组装结果与请求不符，将拒绝签名。若订单会根据路由器当前汇率立即成交或触发（请改用 trade），或者交易对完全没有路由，place_limit_order 也会拒绝处理，除非设置了 skipMarketCheck: true。价格会以十进制字符串形式发送给 API；会以指数形式打印的数字将被拒绝，而不会进行舍入。

DCA 计划（Cookiebox DCA 托管，程序 DCAkvX8…——与限价订单程序分离，由同一 keeper 执行）：get_dca_schedules 可无密钥列出钱包正在运行的计划（你自己的钱包，或任何地址 / .cook 名称）；open_dca 和 close_dca 需要 COOKIE_PRIVATE_KEY。DCA 是一种按时钟而非价格触发、执行 N 次的市价止损单：全部预算在开仓时托管；每个周期 keeper 最多可释放一个 amountPerCycle 额度，通过与 trade 相同的路由器进行兑换，并将所得款项支付到开仓时固定的账户。计划由程序而非 keeper 控制，因此即使 keeper 密钥被盗，也无法加快执行。

• 使用 cycles 或 amountPerCycle 拆分预算。每份金额会向上取整，因此程序推导出的次数（ceil(amount / slice)，最多 1024）可能比你指定的次数少 1；每个结果报告的都是推导出的次数，而不是输入的次数。

• cycleSeconds 的范围是 60 … 31,536,000（从一分钟到一年）。startAt（Unix 秒）会延迟首次执行周期；如果时间戳已过，程序会拒绝，而不是将其钳制到当前时间，因为程序使用的 max(now) 会让它立即触发。

• minPrice / maxPrice 是可选的输出端每周期价格区间，按完整份额报价。minPrice 用于保护价格；maxPrice 用于防止在受操纵的池中以不合理的好价格成交。超出区间或没有路由的周期会跳过，不会补执行，因此在开仓前会根据路由器对单份的可执行汇率检查价格区间；如果无法满足，程序会拒绝，除非设置 skipMarketCheck: true。根据中间价报价的价格区间，Keeper 永远无法满足。

• 唯一的费用是 DCA 程序自身的做市商费用（10 bps，稳定币交易对为 3），从每个周期的收益中扣除，并实时读取自其 Fee 单例账户。原生 COOK 输入会在开仓时封装，并由 close_dca 以 COOK 退款。

• get_dca_schedules 会报告 averagePrice，即该计划目前实际买入的价格；这是单独列出每笔成交记录无法提供的关键数据。它还会标记 status: "overdue"，表示某个周期已错过：程序会直接丢弃该周期而不是补执行，因此这是真实损失，而非延迟。

• 不支持： Token-2022 铸币（Keeper 每个周期都使用经典代币程序签名），以及仍处于联合曲线阶段的 MomoSwap 代币（周期通过路由器成交，而路由器没有曲线 buy_for 这一步，与曲线 限价 订单不同）。这两种情况都会在托管任何资产之前被拒绝。

• close_dca 会退还未花费的余额；计划已经买入的资产仍留在钱包中。计划花完整笔预算后会自行关闭，不再显示在列表中。

开仓和关仓交易由聚合器构建，并在此处像限价订单一样进行验证，验证内容包括用户、金额、频率、价格区间、开始时间、针对签名 base 的计划 PDA、固定的退款/付款账户以及五个允许的程序；交易还会在签名前进行模拟。

Launchpad（需要 COOKIE_PRIVATE_KEY，MomoSwap）：deploy_token 会在 COOK 联合曲线上发行代币（必须提供 Logo——传入 imageBase64 并将其固定到 IPFS，或设置 noLogo: true 以在不带 Logo 的情况下发行；元数据不可变，因此之后无法再添加 Logo。费用包括发行平台创建费（调用时从其配置中读取）以及任何 devBuyCook；maxCostCook 用于限制总成本，并且在设置 devBuyPctOfTotalSupply 时必填），launchpad_buy / launchpad_sell 用于交易该曲线，claim_launchpad 用于结算持仓（毕业后领取实际 SPL 代币、Fair 模式退款，或 Jackpot/Survivor 赔付），而 claim_creator_fees 用于提取你所创建发行项目的交易手续费分成。

⚠️ 毕业前，持仓是由程序跟踪的曲线份额，而非 SPL 代币——它们不会显示在 get_balance 中，trade 也无法对其路由。请使用 launchpad_sell 退出，或在池毕业后使用 claim_launchpad 领取实际代币；此后它的交易方式与其他代币相同。

由于 get_balance 看不到这些份额，get_launchpad_positions 是查看资产组合的工具：它会显示钱包持有仓位的每个发行项目、仓位在实时曲线上的价值，以及尚未领取的资产（毕业后的代币、Fair 模式退款、结算赔付、创作者费用或归属资产）。它会分批直接从链上读取 UserPosition 账户，因此每 100 个发行项目大约需要一次 RPC 往返。传入任意钱包的 owner，也可以省略以查询你自己的仓位。 毕业前的代币也完全没有 DEX 池，因此 get_quote / trade 只会报告“没有路由”。现在它们能识别这种情况，并改为提示使用 launchpad 工具；如果某个 mint 因仍处于曲线阶段而没有价格或流动性，get_token_info 也会添加 launchpad 字段。

NFT launchpad（MomoSwap NFT drops，程序 momoDc2L…）：通过 COOK 联合曲线铸造的固定供应量系列。get_nft_drops 和 get_nft_drop 无需密钥；其余工具需要 COOKIE_PRIVATE_KEY。每次铸造的价格都会略高于上一次；这些项目从首次铸造起就是真正存在于钱包中的 NFT（不同于 launchpad 代币），其艺术作品会在销售结束前隐藏在已提交的揭晓机制之后。

• nft_drop_mint 一次铸造 1–10 个项目，每个项目各用一笔交易；每个项目的费用上限为 maxCookPerItem（含费用），或报价加上 slippageBps（默认 1%）。Drop 在达到目标后毕业时，铸造请求会由 keeper 结算，并随机分配一个剩余项目。
• 如果请求一直处于 pending 状态，可使用 nft_drop_settle：它会推进该 drop 的 FIFO 铸造队列，直到处理到你的请求；结算随机结果已就绪的队首请求，并为随机结果已过期（约 3 分钟）的请求退款。排在你前面的请求会向各自的买家付款；你只需支付费用。
• nft_drop_sell 会在 drop 仍处于开放状态时将项目卖回曲线（保证退出）。
• nft_drop_redeem 会在毕业后销毁项目，以兑换永久底价；如果 drop 未达目标便结束，则可兑换按比例退款，具体取决于适用情况。
• nft_drop_claim 会向 drop 的创建者支付收益（并向版税合作方支付其份额）。
• nft_drop_graduate 会使已售罄的 drop 毕业。任何人都可以发送该请求（通常由 keeper 发送）；这会开放底价和创建者的付款，并结束回售。
• create_nft_drop 会从一个图像文件夹发布系列（可在每张图片旁附上 Metaplex <name>.json 以添加特征）：艺术作品会固定到 IPFS，其顺序会通过公平性承诺封存，种子由 MomoSwap 持有，因此创建者无法挑选稀有铸造结果。请先使用 dryRun: true 运行：预览会显示首末价格、售罄时的募集金额和底价。发布后不可撤销。稍后可使用 reveal_nft_drop 在链上记录种子（可选；无论是否使用，艺术作品都会公开）。

⚠️ MomoSwap API 会构建每笔 NFT 交易；此服务器会在签名前进行检查。 每笔构建的交易都会依据程序随附的 IDL（src/idl/momo_nft_launchpad.json）进行核验：只包含操作调用所需的指令，且顺序正确；账户数量、签名者标志、固定地址和每个 PDA 都会重新推导；该钱包位于授权槽位；系列和项目均为请求中指定的对象；max_cost 不超过批准的支出；除此之外只允许包含计算单元限制、幂等 ATA 创建和 COOK 包装交易。随后还会根据支出预算核验模拟结果：离开钱包的 COOK 不超过所述数量；离开钱包的只有指定项目；铸造时项目必须到账。

流动性（需要 COOKIE_PRIVATE_KEY）：create_pool、add_liquidity、remove_liquidity、claim_fees（Cookiebox DAMM v2、Cookiebox CLMM 和 CookieSwap BAMM，自动检测场所）、lock_liquidity（Cookiebox DAMM v2 和 Cookiebox CLMM，永久且不可逆——CLMM 会锁定整个头寸；无论哪种情况，费用仍可领取）。集中流动性场所（CLMM / BAMM）默认会开立全范围头寸。

NFT 市场（需要 COOKIE_PRIVATE_KEY，Baked Bazaar）：buy_nft、list_nft、cancel_listing、make_offer、accept_offer、cancel_offer。基于 Cookie Chain Metaplex Auction House 构建（1% 市场手续费 + 创建者版税）；每项操作都会在本地构建并签名。 借贷（Aera，超额抵押的 COOK 货币市场）：get_lending_markets （每个储备：已供应 / 已借出 / 可用数量、供应和借款 APR、上限、抵押条款、预言机健康状态）和 get_lending_position（钱包的份额代币、抵押品、债务和健康因子）无需密钥。写入操作需要 COOKIE_PRIVATE_KEY：lend / withdraw_lend（供应 COOK 或 bCOOK，持有会随利息增长的 aCOOK / abCOOK 份额）、deposit_collateral / withdraw_collateral（锁定 bCOOK——在一笔交易中供应并以 abCOOK 形式存入——或将其取出）、borrow / repay（COOK，收取 0.15% 的发放手续费）。该功能直接根据程序构建——Aera 没有 API，也没有 IDL——并且每个依赖健康状态的操作，都会在同一笔交易中携带其同槽 accrue / refresh_oracle / refresh_obligation 前置步骤，这是程序所要求的。

⚠️ 贷款可能会被清算。 如果贷款价值比将超出上限，或健康因子将低于 minHealthFactor（默认值为 1.1；1.0 是清算线，届时抵押品将以 8% 的奖励转给清算人），borrow 和 withdraw_collateral 会在签名前拒绝执行。可以显式传入较低的下限以承担更高风险。利息按槽累积，因此放置不管的贷款会逐渐接近清算线；get_lending_position 会将其预测至当前状态。即使协议暂停，repay 仍可使用；供应方提款则受储备可用流动性的限制。

跨链桥（需要 COOKIE_PRIVATE_KEY）：bridge 通过 Hyperlane warp 路由，在 Cookie Chain 和 Solana 主网之间按 1:1 转移代币（token = 符号或 mint，默认为 COOK；direction = cookie-to-solana | solana-to-cookie）。目前支持 COOK（Cookie 上的原生 COOK ⇄ Solana 上 6 位小数的 Token-2022 SPL COOK）和 SOL（Solana 上的原生 SOL ⇄ Cookie 上的合成 SOL 代币，mint 为 6tL24Fn75uCMrBSZAvohAq57LSv6KrY6ceEq1wonvucb）。两种方向的金额都以代币自身单位计量。只需源链签名一次即可发起转账；中继器会在几分钟内将其送达另一端——可通过 bridge_status 查询（按 Hyperlane 消息 ID 读取）。

无需更新即可支持新代币。 get_bridge_tokens 和 bridge 不会携带代币列表：它们会查找 Cookie Chain 上由桥接升级权限持有的每个 warp 程序，读取各程序的 Hyperlane 代币账户（路由类型、mint、小数位数、IGP、已登记的 Solana 路由器），并且只有当其指定的 Solana 程序位于 Solana mailbox 上且路由返回该程序时，才接受该路由。桥接团队添加的代币只要登记了路由即可跨链转移；其他任何人部署的程序都不会列出。发现结果会缓存 10 分钟。如果 Cookie RPC 拒绝提供程序列表，仍会检查内置的 COOK 和 SOL 路由，并由 get_bridge_tokens 在 warnings 中说明这一点。

会先进行模拟，并在签名前预检目标链，因为源链模拟无法查看另一端：

• 抵押资产。 一条会在另一端付款的路由（原生币或托管账户）只能支付该账户持有的资产；超额转账会导致资金被扣走，却无法通过无法送达的消息完成交付。bridge 会拒绝此类转账，并报告账户中的资产数量为 destinationCollateral（如果目标端会铸造代币，例如 Cookie 上的 SOL，则为 null）。
• 向空钱包支付原生币必须达到免租最低金额，否则在资金扣除后，每次重试都会被拒绝。bridge 会拒绝低于此金额的转账。
• 接收方的代币账户。 代币交付会将资金存入关联代币账户；如果接收方没有此账户，bridge 会先用你的钱包创建账户（在目标链上多发一笔交易，需支付少量该链的原生币作为租金；关闭账户后可收回），并在派发前确认账户已创建，因此此步骤失败不会造成损失。warp 路由可以自行创建账户，但会从部署时注资一次的 PDA 中支付；当 PDA 资金耗尽时，中继器的交付会在 模拟阶段 失败，永远不会上链，转账也会一直挂起，且不会在任何地方显示错误（此情况发生于 2026-08-26）。传入 createRecipientAccount: false，即可改用该 PDA——若可确认 PDA 资金不足，bridge 就会拒绝转账。结果会通过 recipientTokenAccount 报告该账户。

桥接网站会对其自身的转账收取固定费用（向中继器支付 0.01 SOL / 15,000 COOK）。此费用由网站强制收取，并非 warp 程序收取，bridge 也不会收取此费用。 使用 get_balance 并设置 chain: "solana"，可查看桥接前 Solana 端的余额：钱包中的 SPL COOK（solana-to-cookie 会花费此资产）、SOL（用于支付费用和跨链 gas，也会被 SOL 桥接所花费），以及 bridgeTokens：桥接可从 Solana 转出的所有其他代币，这些代币会像路由一样通过链上发现。它不会枚举与此无关的 Solana 代币。如果 RPC 拒绝 getTokenAccountsByOwner（Shyft 免费套餐会这样），则会改为读取每种代币的标准账户，并添加警告，说明未统计其他账户中的代币。 在 Solana 上兑换（使用 chain: "solana" 调用 get_quote / trade）：通过 Jupiter 路由 Solana 主网流动性，而非 Cookie Chain；你可以借此买入或卖出桥接后的 SPL COOK（36ZrtQoab5MhhySaP1YSTwUahSk6GRVUTtZ6cuVfm9e1）。此操作与其他兑换一样采用非托管模式：Jupiter 报价并构建交易，我们通过你的 Solana RPC 模拟交易，在本地签名、发送并确认。费用以 SOL 支付，且 两个链上都使用同一个 COOKIE_PRIVATE_KEY 签名——请先运行 get_wallet。请注意以下两点：

• 有意仅支持 COOK 相关兑换。 其中一项资产必须是 SPL COOK mint，因此 SOL → COOK 和 COOK → USDC 可用，但会拒绝 SOL → USDC 这类无关币对。Jupiter 可以为其路由；但此服务面向 Cookie Chain，支持每个额外币对都会扩大可转移资金的范围。
• 在 Cookie Chain 上，So1111…112 是 COOK；在 Solana 上则是 wSOL——mint 字符串相同，但代表的资产不同。代币元数据会按链解析；当 chain: "solana" 时，aggregator 参数（仅适用于 Cookie Chain）会被拒绝，而非忽略。
• trade 会拒绝使用 Solana 公共端点。 报价完全不需要 RPC，但兑换需要；api.mainnet-beta.solana.com 对 sendTransaction 的速率限制最严格——如果交易延迟上链并超过你的滑点上限，交易就会失败。请将 SOLANA_RPC_URL 指向专用 RPC（免费的 Helius/Triton/QuickNode 密钥即可）。

桥接在主网开箱即用。若要使用其他部署，请覆盖邮箱地址（COOKIE_MAILBOX / SOLANA_MAILBOX），设置受信任的升级权限发现配置（BRIDGE_COOKIE_UPGRADE_AUTHORITY；将其设为 "" 可关闭发现），并添加一个始终检查的 Cookie warp 程序 COOKIE_WARP_PROGRAM_ID。Solana 端和 IGP 均从路由本身读取。 .cook 名称（CookOven）：resolve_domain 可查询名称信息——所有者、注册日期、解析器／元数据指针——或报告该名称可注册并显示实时价格；get_owned_domains 会列出钱包持有的所有名称及其主名称。写入操作需要 COOKIE_PRIVATE_KEY：register_domain、set_primary_domain（或使用 clear: true 取消设置）、transfer_domain、update_domain。所有信息都直接从链上注册表读取并构建——不需要 API 或索引器。后缀在任何地方都是可选的：chef 和 chef.cook 是同一个名称。

拥有名称后，你可以用它代替地址：transfer、get_balance、 get_wallet_nfts、get_nft_offers、get_launchpad_positions 和 transfer_domain 在需要 Cookie Chain 钱包的任何地方都接受 .cook 名称。普通 base58 地址无需额外查询。

.cook 域名市场（CookOven Marketplace）：已注册名称的二级市场——通常比 15,000–35,000 COOK 的注册费更便宜，也是获得他人已持有名称的唯一途径。get_domain_listings 无需密钥即可浏览（按 name、seller、maxPriceCook 或 maxLength 筛选；按价格、长度或上架时间排序），并报告实时市场手续费，该费用由卖家从售价中支付。写入操作需要 COOKIE_PRIVATE_KEY：list_domain（以 COOK 标价）、buy_domain、cancel_domain_listing。所有信息都直接从程序读取并构建——不需要 API 或索引器。

⚠️ 上架会将名称托管起来。 list_domain 会在同一条指令中将域名交给市场的托管账户，因此上架期间，注册表会将托管账户报告为其所有者：卖家无法对其执行 transfer_domain、update_domain 或 set_primary_domain，该名称也不再解析为可收款地址。这些工具会明确说明这一点，而不会将陌生人报告为所有者；在需要地址的地方传入已上架的名称会被拒绝——托管账户是程序账户，向其付款会导致资金无法取回。cancel_domain_listing 可随时撤销上架并退还其租金。没有调价指令：先取消，再重新上架。

出于与 register_domain 相同的原因，buy_domain 需要 maxPriceCook——该指令不包含价格参数，因此价格上限是唯一的保护措施。不提供该参数时，系统只会返回报价，不会扣款。

使用 COOK／原生 mint So11111111111111111111111111111111111111112 代表 COOK。所有工具都返回 JSON；失败时返回 { error, hint }——绝不会返回堆栈跟踪，也绝不会暴露你的密钥。

托管／钱包签名模式

默认设置假设你既是运营者，也是用户。托管式产品——例如网页聊天、Telegram 机器人或共享 Agent——无法持有用户的密钥，也不应索要密钥。为此，cookie-mcp 可以不使用任何密钥运行，并让用户用自己的钱包签名：

COOKIE_SIGNER=external COOKIE_MCP_HTTP_TOKEN=<long random secret> \
COOKIE_MCP_ALLOWED_HOSTS=mcp.example.com COOKIE_MCP_CORS_ORIGIN=https://app.example.com \
  npx cookie-mcp --http 3000 --host 0.0.0.0

• 每个请求都通过 x-cookie-wallet: <base58> 标头指定其操作所针对的钱包（也可以为单钱包部署设置 COOKIE_WALLET_ADDRESS）。读取操作照常工作。

• 请求还可以通过 x-cookie-app: <id> 指明来源应用；此设置会覆盖该请求的 COOKIE_APP_ID（参见客户端身份）。

• 每个会转移资金的工具都会执行所有检查——指令解码、支出拒绝、模拟及余额检查——然后不进行签名，而是返回普通的（非错误）结果：

  {
    "status": "needs_signature",
    "tool": "transfer",
    "kind": "transaction",
    "what": "transfer",
    "signer": "FFWf…4wq2",
    "transactionBase64": "AQAAAA…",
    "version": "legacy",
    "blockhash": "6FdF…TSvT",
    "lastValidBlockHeight": 24638662,
    "submit": { "via": "cookie-rpc" },
    "step": "final",
    "summary": { "to": "…", "symbol": "COOK", "amount": "0.001" },
    "next": "sign transactionBase64 with wallet … then call submit_signed_tx …"
  }
  

  你的应用将 transactionBase64 原样交给浏览器钱包（它已经由任何临时签名者或 API 端签名者共同签名），然后使用已签名的字节以及相同的 submit／blockhash／lastValidBlockHeight／what 字段调用 submit_signed_tx。该工具会通过指定的路由（Cookie RPC、Solana RPC 或 Candy Shop）发送并确认交易。它会拒绝仍缺少签名的字节，而且绝不会自行构建交易。

• step: "intermediate" 表示前置步骤（为开发者购买包装 COOK、桥接前创建 Solana 代币账户、初始化 CLMM tick-array）。确认后，使用相同参数再次调用同一工具以继续。

• kind: "message"（仅 deploy_token 和 reveal_nft_drop，用于 launchpad 登录）要求钱包对确切文本调用 signMessage；使用 loginSignature: { message, signature } 再次调用该工具。在外部模式下，会话不会缓存在服务器端（钱包标头无法证明任何信息），因此每次发布都需要单独的登录签名。

• NFT 工具会添加 bazaarLog。将它传回 submit_signed_tx，交易确认后，它会将交易告知 Baked Bazaar 的索引器（本地签名者会自行完成此操作），因此无需等待索引器自行扫描，挂牌或报价就会显示出来。

• 区块哈希大约一分钟后过期。如果钱包提示响应较慢，submit_signed_tx 会报告超时，并提供签名和“切勿盲目重试”的提示；重新运行工具以获取新的字节。

• HTTP 服务器是无状态的（每个 POST 都会启动一个全新的服务器），并响应 /healthz。绑定到回环地址并不代表私有：在同一台机器的浏览器中打开的任何网页都能访问 127.0.0.1。因此，每个请求都会先经过检查。Host 必须是服务器响应的地址之一（绑定到回环地址时为回环名称，否则为 COOKIE_MCP_ALLOWED_HOSTS），以此防止 DNS 重绑定。来自浏览器的请求（带有 Origin 标头）必须与 COOKIE_MCP_CORS_ORIGIN 匹配。未设置时，如果使用外部签名者，则允许任何来源；网页只能获取未经签名的交易，仍需用户的钱包批准。如果服务器持有本地密钥，则不允许任何来源。设置 COOKIE_MCP_HTTP_TOKEN 后，必须提供 Authorization: Bearer <token>。如果设置了本地 COOKIE_PRIVATE_KEY，但未同时设置 COOKIE_HTTP_ALLOW_LOCAL_KEY=1 和 COOKIE_MCP_HTTP_TOKEN，服务器将拒绝启动，因为任何能访问该端口的人都可能使用该密钥进行支出。

作为库使用。 无需 MCP 也能导入并使用相同的工作流：

import {
  ExternalSigner,
  transfer,
  submitSignedTransaction,
  runWithRequestContext,
} from "cookie-mcp";
import { createServer } from "cookie-mcp/server"; // embed the MCP server in your own process

资金操作会根据 COOKIE_SIGNER 和请求上下文解析签名者（runWithRequestContext({ wallet }, () => transfer({...}))），并抛出 SignatureRequired，其中包含与工具返回内容相同的载荷。本地 Agent（COOKIE_PRIVATE_KEY、stdio）不受这些限制影响。

每个领域也有各自的入口，因此只需一个工作流的应用无需打包总入口引入的所有交易场所 SDK：cookie-mcp/trade、/transfer、/stake、/bridge、/bridge-routes、/nft、/domains、/launchpad、/lending、/limit-orders、/dca、/liquidity、/quote、/balances，以及 /signer、/context、/submit 和 /errors。它们与总入口共享状态（一个请求上下文、一个钱包缓存），因此可以安全混用。

import { trade } from "cookie-mcp/trade"; // ~100 KB gzipped, against ~450 KB for the barrel
import { runWithRequestContext } from "cookie-mcp/context";
import { SignatureRequired } from "cookie-mcp/signer";

该库也支持为边缘运行时（Cloudflare Workers、Vercel Edge）打包。在 Workers 上启用 nodejs_compat（用于 AsyncLocalStorage、node:net、node:dns），并确保变量能够传入 process.env——配置会在导入时从中读取。从兼容性日期 2025-04-01 起，这是默认行为；在此之前则需启用 nodejs_compat_populate_process_env 标志。deploy_token 的 imageUrl 获取请求通过 node:https 发送，Workers 从兼容性日期 2025-08-15 起提供该模块（或启用 enable_nodejs_http_modules）；如果使用更早的日期，请改为传入 imageBase64。

客户端身份

cookie-mcp 向场馆 API 或 RPC 发出的每个请求都会携带类似 cookie-mcp/0.7.0 (stdio; local; app=cookie-chat/2.1) 的 User-Agent，其中包含版本、传输方式（嵌入时为 stdio、http 或 library）、签名者模式，以及设置后会包含的应用 ID；同时还会在 X-Cookie-Client 中发送相同字符串（浏览器环境除外，因为自定义标头会触发 CORS 预检）。设置 COOKIE_APP_ID（或通过 HTTP 为每个请求发送 x-cookie-app）即可为你的应用命名：最多 64 个字符，仅允许使用 A-Z a-z 0-9 . _ : / @ + -，其他字符会被移除。这样，场馆运营方就能将流量归因于 cookie-mcp、特定版本以及你的集成。get_wallet 会显示此进程发送的确切字符串。这不是遥测：不会额外发出请求，也不会添加任何钱包数据——只是现在原本就会发出的请求会标明来源。

安全性

非托管：不远程存储密钥。使用本地密钥时，密钥会保存在 COOKIE_PRIVATE_KEY 中，在本地签名，并从所有输出中脱敏。托管模式下，进程完全不持有密钥，由用户的钱包签名。配置签名者之前仅支持只读；每项资金转移操作都会先进行模拟，然后才会发送（或交由签名）。

开发

yarn install
yarn test    # lint + format + typecheck + unit tests + boot smoke
yarn mcp     # run the server on stdio from source (tsx)
yarn build   # bundle to dist/ (CLI, `cookie-mcp/server` factory, `cookie-mcp` library + subpaths)

若要让 Agent 使用本地检出版本而非已发布的软件包，请将命令设置为 npx tsx /ABS/PATH/cookie-mcp/src/mcp/server.ts。使用 --http [port] 可改为提供 Streamable HTTP 服务。

发布

发布包括一次 npm 发布，以及将同一版本重新发布到 MCP 注册表；第三方目录（mcpservers.org 等）会镜像注册表条目，因此真正更新这些目录的是注册表发布步骤。确保 npm 的 latest 与 main 保持同步——这些目录会抓取 GitHub，而 npm 版本落后会导致用户看到的 README 承诺了已安装服务并不具备的工具。

yarn release <X.Y.Z | patch | minor | major> 会端到端运行以下所有步骤：在本地更新版本、执行门禁检查、提交并打标签，显示发布说明并询问一次，然后将提交和标签推送到 main、创建 GitHub 发布，并发布到 npm 和注册表。已完成的步骤会被检测并跳过，因此运行失败后，用同一条命令即可继续。--dry-run 会运行预检、门禁检查和 tarball 检查，但不会更改任何内容；--yes 会跳过推送和发布前的确认。若未设置 MCP_GITHUB_TOKEN，命令会拒绝启动；该令牌必须是具有 read:org 权限的经典 PAT（见第 7 步）。使用 read -s MCP_GITHUB_TOKEN && export MCP_GITHUB_TOKEN 可避免令牌进入 shell 历史记录。

1. 在四处更新版本号，并确保全部为同一个字符串：package.json 中的 version、src/version.ts（MCP 握手报告的版本），以及 server.json 中顶层的 version 和 packages[0].version。注册表会拒绝版本号不一致的情况；package.json 中的 mcpName 必须保持为 io.github.cookiechain/cookie-mcp（注册表会检查已发布的 tarball）。
2. 更新 CHANGELOG： 将 [Unreleased] 标题改为 # [X.Y.Z](https://github.com/cookiechain/cookie-mcp/releases/tag/vX.Y.Z)，并在下方添加带日期的行，然后在它上方新建一个 # [Unreleased]，用于下一个周期。
3. **门禁检查：**运行 yarn test——这与 CI 中的 lint / 格式 / 类型检查 / 单元测试 / 冒烟测试流程相同。每个新工具都必须列在 scripts/smoke.ts 的 EXPECTED_TOOLS 中（冒烟测试只报告 缺少 的名称，因此忘记在其中添加工具会悄无声息地通过），并列在上方的 工具 列表中。
4. **检查 tarball：**运行 npm pack --dry-run。其中必须仅包含 dist/**、README.md、LICENSE 和 package.json——不得包含 src/、.env、密钥材料或绝对路径。prepublishOnly 会运行 yarn build（tsup），确保始终根据已打标签的源代码重新构建 dist/。
5. **提交、打标签并发布：**以 Release X.Y.Z 为提交说明，创建标签 vX.Y.Z，运行 git push --tags，并根据该标签创建 GitHub 发布，将 CHANGELOG 中对应部分作为发布说明正文（CHANGELOG 链接指向该发布页面）。
6. **发布到 npm：**运行 npm publish，然后使用 npm view cookie-mcp version 验证，并从干净目录固定版本启动：npx -y [email protected] 必须能够启动并注册所有工具。

   如果 npm publish 报错 E404 … PUT …/cookie-mcp … could not be found or you do not have permission，几乎从来不是因为包不存在——npm 会将未经身份验证的发布报告为 404。运行 npm whoami；如果失败，请运行 npm login，然后重新发布。

7. 发布到 MCP Registry：运行 brew install mcp-publisher，然后在仓库根目录运行 mcp-publisher login github && mcp-publisher publish。io.github.cookiechain/* 命名空间要求你是 GitHub 组织的所有者。如果设备授权登录仍然因为 403 回退到个人命名空间，说明该组织限制了 OAuth 应用——请改用具有 read:org 权限的经典 PAT 登录：MCP_GITHUB_TOKEN=<pat> mcp-publisher login github。

许可证

本项目根据 MIT 许可证条款授权。请参阅 LICENSE 文件。