marketplace-mcp

marketplace-mcp

面向 LLM Agent 的 NOSTR 店面——兼容两种方言。 MCP 服务，可代替 Agent 创建和更新市场事件，开箱即支持两种方言：

• NIP-15（kind:30017 摊位 + kind:30018 商品），适用于原生支持 NIP-15 的客户端（Plebeian Market 等）。
• Shopstr-modern（kind:30019 店铺资料 + kind:30402 NIP-99 分类列表）——shopstr.store 实际呈现的内容。包含自动缓存 POST，因此事件会显示在店面中，而不只是发布到中继。

提供七种工具、纵深防御安全机制，采用 MIT 许可。

v0.2 — 双方言发布器。 v0.1.x 仅支持 NIP-15，因此商品列表不会出现在 shopstr.store 上，因为 Shopstr 是一个由 Postgres 支持的 CMS，只呈现自身数据库中的事件（通过 POST /api/db/cache-event 填充），其可缓存事件允许列表不包含 NIP-15 类型。v0.2 新增 Shopstr-modern 工具和缓存 POST 钩子，让店面能够实际显示商品。保留 NIP-15 工具，供面向非 Shopstr 目标的用户使用。

---

为什么需要这个服务

Shopstr（NOSTR 上规范的 Bitcoin-Lightning 市场界面）不是读取中继的 Nostr 客户端——它是一个带有 Postgres 缓存的 Next.js 应用。其市场页面会从自身数据库呈现商品；客户端将已签名事件 POST 到 /api/db/cache-event 时，数据库会被填充。可缓存事件允许列表（位于 shopstr-eng/shopstr 中的 utils/db/cache-event-policy.ts）不包含 NIP-15 摊位/商品类型；现代 Shopstr 使用 kind:30019（包含 merchants: [<pubkey>] 的店铺资料）和 kind:30402（NIP-99 分类列表，所有数据都在标签中）。没有 ["t","shopstr"] 标签，商品列表就不会显示；没有至少一个 ["image",<url>] 标签，卡片则会无提示地完全不显示。

marketplace-mcp v0.2 会构建正确的事件，在发布到中继后将其 POST 到 Shopstr 的缓存，并保留旧版 NIP-15 工具，供面向其他客户端的用户使用。

---

使用它可以构建什么

• 自动运行的 Shopstr 店面——Agent 根据配置文件生成店铺资料和商品列表，在元数据变更时重新发布，并为每件商品添加新的 t 标签分类以提升可发现性。同一次调用会将内容发布到中继，并同步到 Shopstr 的缓存。
• 销售渠道复用器——同一商品事件会因发布到共享中继而传播到所有支持 NIP-15 或 NIP-99 的客户端（Shopstr、Plebeian Market 等）。可按工具选择方言；如果受众涵盖多个客户端，也可同时发布两种方言。
• 列表即代码工作流——在 git 中对商品 JSON 进行版本控制；由 CI 调用 shopstr_create_or_update_product 进行部署。使用相同的 id 重新发布，即可幂等更新（参数化可替换事件）。
• 跨服务身份——与 nostr-ops-mcp 和 nwc-mcp 搭配使用，接入身份和商业功能。共用同一个签名器、同一个 npub，并提供三个专用工具界面。

---

七种工具

Shopstr-modern（v0.2 新增）——要让内容显示在 shopstr.store 上就必须使用

工具	类型	用途
shopstr_create_or_update_shop	30019	发布卖家的店铺资料（name、about、picture、banner）。d 标签是卖家的 pubkey 十六进制值——每个 pubkey 对应一个店铺。发布到中继后，会将内容 POST 到 Shopstr 的缓存，使店铺显示在店面 UI 中。
shopstr_create_or_update_product	30402	发布 NIP-99 分类列表。所有商品数据都在标签中（title、summary、price、location、shipping、image × N、t × N、quantity、condition、status、valid_until）。会自动添加 ["t","shopstr"]，使商品显示在 Shopstr 市场动态中。包含缓存 POST。

NIP-15 旧版 — 适用于原生支持 NIP-15 的客户端（Shopstr 除外）

工具	类型	用途
marketplace_create_or_update_stall	30017	NIP-15 摊位（id、name、description、currency、shipping[]）。id 是 d 标签——相同 ID 表示替换。仅发布到中继；不 POST 到 Shopstr 缓存（无论如何都会返回 400，因为该类型不在允许列表中）。
marketplace_create_or_update_product	30018	NIP-15 商品（stall_id、name、description、images、price、quantity、specs、shipping、categories）。仅发布到中继。

通用

工具	类型	用途
marketplace_list_my_stalls	—	获取并解析你自己的 NIP-15 摊位。返回事件 ID、created_at、d 标签和解析后的 JSON。
marketplace_list_my_products	—	对 NIP-15 商品执行相同操作。可选的 stall_id 筛选器（在客户端进行；中继不会为 JSON 内容建立索引）。
marketplace_confirm_publish	—	两步确认分发器。按工具名称路由，以便 Shopstr 新版发布自动重新附加缓存 POST 钩子。

---

要求

• Node 20+
• NOSTR 签名器——强烈推荐：来自 Amber、nsec.app 或任何 NIP-46 实现的 NIP-46 bunker URI。开发路径：在 .env 中使用原始 nsec。
• 你的受众会读取的中继。.env.example 中提供了合理的默认值（relay.damus.io、nos.lol、relay.nostr.band、relay.primal.net）。
• 对于 Shopstr 新版发布：需要能通过出站 HTTPS 访问 shopstr.store（或你自己的 Shopstr 部署）。

安装

# From npm
npx -y marketplace-mcp

# From source
git clone <repo>
cd marketplace-mcp
corepack enable pnpm
pnpm install
pnpm build

配置

cp .env.example .env
# edit .env: set NOSTR_NIP46_URI OR NOSTR_PRIVATE_KEY
#           set NOSTR_RELAYS (comma-separated wss://)
#           set SHOPSTR_CACHE_ENABLED=true (default) for shopstr.store visibility

服务会从此二进制文件所在目录（dist/ 旁边）自动加载 .env——特意不从当前工作目录加载，以避免多个 MCP 服务在同一个 Claude Code 会话中运行时发生环境变量冲突。

必需项

变量	用途
NOSTR_RELAYS	以逗号分隔的 wss:// 中继。若为空，服务将拒绝启动。

签名器——最多提供一个（不提供签名器时，服务将以只读模式运行）

变量	用途
NOSTR_NIP46_URI	bunker://... URI。推荐。 可与 Amber（Android）或 nsec.app（Web）配对使用。
NOSTR_PRIVATE_KEY	原始 nsec1...。仅用于开发或旧版场景。服务会在启动时发出警告。

Shopstr 缓存镜像（v0.2 新增）

shopstr.store 从自己的 Postgres 数据库读取数据，而不是从开放中继读取。kind:30019/30402 事件发布到中继后，服务会将其 POST 到配置的缓存 URL，以便这些事件显示在店面中。失败会记录在审计日志中，但绝不会回滚中继发布（已广播的 Nostr 事件本来就无法回滚）。

变量	默认值	用途
SHOPSTR_CACHE_ENABLED	未设置（false）——在 .env 中设为 true 以启用	控制是否执行缓存 POST。
SHOPSTR_CACHE_URL	https://shopstr.store/api/db/cache-event	可覆盖此项，以镜像到可自托管的 Shopstr 部署。

NIP-15 工具（kind:30017/30018）会忽略这些设置——这些类型无论如何都不在 Shopstr 的可缓存允许列表中。

可选安全设置

变量	默认值	用途
NOSTR_READ_ONLY	false	禁用所有发布工具（list_my_* 仍可使用）。
NOSTR_REQUIRE_CONFIRM	false	两步确认——创建/更新操作会返回令牌；由 marketplace_confirm_publish 实际广播。
NOSTR_MAX_EVENTS_PER_MINUTE	10	发布操作的滚动 60 秒速率限制。
NOSTR_LOG_PATH	./marketplace-mcp.log	服务日志。
NOSTR_AUDIT_PATH	./marketplace-mcp-audit.log	仅追加的 JSON 行审计日志。

---

快速入门：在 shopstr.store 发布你的第一个店面

1. agent: shopstr_create_or_update_shop({
     name: "My Shop",
     about: "Hand-crafted MCP servers and other Lightning-priced goods.",
     picture: "https://example.com/avatar.png",
     banner: "https://example.com/banner.png"
   })
   → returns { event_id, kind: 30019, relays_accepted: [...],
                after_publish: { shopstr_cache: { ok: true, status: 200 } } }

2. agent: shopstr_create_or_update_product({
     id: "some-product",
     name: "Some Product",
     summary: "Long-form description goes here. Becomes the event `content`.",
     price: 50000,
     currency: "sat",
     location: "online",
     shipping_option: "Free",
     shipping_cost: 0,
     images: ["https://example.com/card.jpg"],   // REQUIRED — Shopstr drops cards with zero images
     categories: ["software", "lightning", "mcp"]
   })
   → returns { event_id, kind: 30402, relays_accepted: [...],
                after_publish: { shopstr_cache: { ok: true, status: 200 } } }

访问 https://shopstr.store/marketplace/<your-npub> 查看你的店面。（如果你已为自己的 npub 注册 Shopstr 个人资料 slug，该 URL 会规范化为 /marketplace/<your-slug>。）买家可通过 Shopstr 的发票生成流程购买 → sats 会进入关联到你 Shopstr 个人资料的 Lightning 钱包。

NIP-15 替代方案（适用于非 Shopstr 客户端）

如果你面向的是原生支持 NIP-15 的客户端，而不是（或除了）Shopstr，旧版工具仍然可用：

agent: marketplace_create_or_update_stall({
  id: "my-shop", name: "My Shop",
  shipping: [{ id: "digital", name: "Digital", cost: 0 }]
})
agent: marketplace_create_or_update_product({
  id: "p1", stall_id: "my-shop", name: "Some Product",
  price: 50000, currency: "sat",
  shipping: [{ id: "digital", cost: 0 }]
})

你可以为同一商品同时发布两种方言，以最大限度覆盖客户端；它们不会冲突。

---

接入 MCP 客户端

{
  "mcpServers": {
    "marketplace": {
      "command": "npx",
      "args": ["-y", "marketplace-mcp"],
      "env": {}
    }
  }
}

与其他基底组件采用相同的通过二进制目录加载 .env 的模式——客户端配置中的 env 块留空；密钥保存在 marketplace-mcp/.env 中。

---

安全模型

对于 NIP-15 和 Shopstr-modern 工具，发布流程均按以下顺序运行：

1. NOSTR_READ_ONLY 门控。
2. 签名者检查——如果没有签名者则拒绝。
3. RateLimiter——滚动 events 计数桶（NOSTR_MAX_EVENTS_PER_MINUTE）。
4. 确认门控——如果 NOSTR_REQUIRE_CONFIRM=true，则返回一个令牌；由 marketplace_confirm_publish 执行。确认调度器会根据工具名称进行路由，因此 Shopstr-modern 发布会自动重新挂载其缓存 POST 钩子。
5. 通过 NDK 签名并发布。
6. afterPublish 钩子（仅限 Shopstr-modern）——将已签名事件 POST 到 SHOPSTR_CACHE_URL。失败会记录在审计日志中（after_publish.shopstr_cache.{ok, status, error}），但绝不会回滚中继发布。
7. 审计日志条目。

省略了 KindAllowlist，因为 kind（30017/30018/30019/30402）在工具实现中是硬编码的——没有由 Agent 提供的 kind 需要验证。

如果你想要更严格的行为，可以搭配 nostr-ops-mcp，并在同一个 npub 上使用它的 kind 允许列表；不过，大多数用户认为，对于单用途的市场服务来说，这种开销并无必要。

---

测试

pnpm typecheck
pnpm test        # 19 vitest cases (NIP-15 builders/parsers + Shopstr-modern builders/parsers + roundtrips)
pnpm build       # ~37 KB ESM bundle

---

配套服务

• nwc-mcp — Lightning 钱包，负责销售中的“收款”环节。
• nostr-ops-mcp — 通用 NOSTR 基础功能。市场 MCP 是专用版本；nostr-ops-mcp 则是通用版本。
• albyhub-admin-mcp — 通过 Alby Hub 的 HTTP API 进行 Hub 级管理。这是钱包功能的另一半（NWC 处理付款，此服务处理节点、通道和子钱包操作）。

---

许可证

MIT — 参见 LICENSE。

联系方式 / 问题反馈

由 LLMOps.Pro 构建。

• NOSTR： npub1hdg932jvwc3jdvkqywgqv0ue4nn60exrf92asy8mtazt3hjg7d2s2yw0nw — 关注、私信、打赏。
• Lightning 地址： [email protected] — 用于支持打赏和“这很有用”小费。
• 错误报告 / 功能请求： 提交 GitHub issue（链接即将提供）。
• 安全问题： 请先通过 NOSTR 私信私下披露，再提交公开 issue。