marketplace-mcp

marketplace-mcp

LLM エージェント向けの NOSTR ストアフロント — 2 つの方言に対応します。 エージェントが代理でマーケットプレイスイベントを作成・更新できる MCP サーバーです。最初から 2 つの方言に対応しています。

• NIP-15（kind:30017 の店舗 + kind:30018 の商品）：NIP-15 ネイティブのクライアント（Plebeian Market など）向けです。
• Shopstr-modern（kind:30019 のショッププロフィール + kind:30402 の NIP-99 分類リスティング） — shopstr.store が実際に表示する形式です。イベントがリレーだけでなくストアフロントにも表示されるよう、自動でキャッシュへの POST を行います。

7 つのツール、多層防御の安全対策、MIT ライセンス。

v0.2 — 2 方言対応のパブリッシャーです。 v0.1.x は NIP-15 のみをサポートしていたため、リスティングは shopstr.store に表示されませんでした。Shopstr は Postgres を基盤とする CMS であり、独自の DB（POST /api/db/cache-event 経由で登録）にあるイベントだけを表示し、キャッシュ可能なイベントの許可リストから NIP-15 の kind を除外しているためです。v0.2 では Shopstr-modern のツールとキャッシュへの POST フックを追加し、ストアフロントに実際に表示されるようにしました。Shopstr 以外を対象とする場合に備え、NIP-15 のツールも残しています。

---

このサーバーが必要な理由

Shopstr（NOSTR における標準的な Bitcoin-Lightning マーケットプレイス UI）は、リレーを読み取る Nostr クライアントではありません。Postgres キャッシュを備えた Next.js アプリです。マーケットプレイスページには独自の DB から商品が表示されます。この DB は、クライアントが署名済みイベントを /api/db/cache-event に POST すると登録されます。キャッシュ可能なイベントの許可リスト（shopstr-eng/shopstr → utils/db/cache-event-policy.ts）では NIP-15 の店舗・商品 kind が除外されています。最新の Shopstr では kind:30019（merchants: [<pubkey>] を含むショッププロフィール）と kind:30402（NIP-99 分類リスティング。すべてのデータはタグ内に格納）を使用します。["t","shopstr"] タグがないとリスティングは表示されず、["image",<url>] タグが 1 つ以上ないと、カードは何も表示されないままになります。

marketplace-mcp v0.2 は適切なイベントを作成し、リレーへの公開後に Shopstr のキャッシュへ POST します。また、他のクライアントを対象とするユーザー向けに、従来の NIP-15 ツールも引き続き利用できます。

---

これを使って構築できるもの

• 自動運転型の Shopstr ストアフロント — エージェントが設定ファイルからショッププロフィールと商品リスティングを生成し、メタデータが変更されるたびに再公開します。商品ごとに新しい t タグのカテゴリを追加して、見つけやすくします。同じ呼び出しでリレーへの公開と Shopstr のキャッシュへの複製を行います。
• 販売チャネルのマルチプレクサー — 商品イベントは共有リレー上にあるため、NIP-15 または NIP-99 に対応するすべてのクライアント（Shopstr、Plebeian Market など）に伝播します。ツールごとに方言を選択できます。対象ユーザーが複数のクライアントにまたがる場合は、両方に公開できます。
• コードとして管理するリスティングのワークフロー — 商品の JSON を git でバージョン管理し、CI から shopstr_create_or_update_product を呼び出してデプロイします。同じ id で再公開すると、冪等な更新になります（パラメーター化された置換可能イベント）。
• サーバー間でのアイデンティティ共有 — nostr-ops-mcp と nwc-mcp を組み合わせて、アイデンティティとコマースを連携できます。同じ署名者、同じ npub、3 つの専門的なツール群です。

---

7 つのツール

Shopstr-modern（v0.2 で追加）— shopstr.store に表示するには必須

ツール	Kind	目的
shopstr_create_or_update_shop	30019	販売者のショッププロフィール（name、about、picture、banner）を公開します。d タグは販売者の pubkey の hex 形式で、1 つの pubkey につきショップは 1 つです。リレーへの公開後、Shopstr のキャッシュに POST し、ストアフロント UI にショップを表示します。
shopstr_create_or_update_product	30402	NIP-99 分類リスティングを公開します。すべての商品データはタグに格納されます（title、summary、price、location、shipping、image × N、t × N、quantity、condition、status、valid_until）。商品が Shopstr のマーケットプレイスフィードに表示されるよう、["t","shopstr"] を自動で追加します。キャッシュへの POST も含まれます。

NIP-15 レガシー — NIP-15 ネイティブクライアント向け（Shopstr を除く）

ツール	種別	用途
marketplace_create_or_update_stall	30017	NIP-15 の出店情報（id、name、description、currency、shipping[]）。id は d タグです。同じ ID を指定すると置き換えられます。リレーへの公開のみです。Shopstr のキャッシュへの POST は行いません（いずれにせよ、許可リストにない kind のため 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	—	2 段階確認ディスパッチャーです。ツール名に基づいて振り分けるため、Shopstr-modern の公開時にはキャッシュへの POST フックが自動的に再設定されます。

---

要件

• Node 20+
• NOSTR 署名者 — NIP-46 の bunker URI を強く推奨します。Amber、nsec.app、または任意の NIP-46 実装を使用してください。開発用の方法：.env に生の nsec を指定します。
• 対象ユーザーが読み取るリレー。.env.example に妥当なデフォルト値があります（relay.damus.io、nos.lol、relay.nostr.band、relay.primal.net）。
• Shopstr-modern への公開には、shopstr.store（または独自の Shopstr デプロイ）へのアウトバウンド HTTPS 接続が必要です。

インストール

# 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:// リレー。空の場合、サーバーは起動を拒否します。

署名者 — 最大 1 つだけ指定してください（署名者がない場合、サーバーは読み取り専用で動作します）

変数	用途
NOSTR_NIP46_URI	bunker://... URI。推奨。 Amber（Android）または nsec.app（Web）とペアリングします。
NOSTR_PRIVATE_KEY	生の nsec1...。開発用／レガシー用のみです。サーバー起動時に警告が表示されます。

Shopstr キャッシュミラー（v0.2 で追加）

shopstr.store は、オープンリレーではなく独自の Postgres DB からデータを読み込みます。kind:30019/30402 のイベントをリレーに公開した後、サーバーは設定されたキャッシュ URL に POST し、ストアフロントにイベントを表示できるようにします。失敗は監査ログに記録されますが、リレーへの公開がロールバックされることはありません（Nostr イベントはブロードキャスト済みであれば、いずれにせよロールバックできません）。

変数	デフォルト	用途
SHOPSTR_CACHE_ENABLED	未設定（false） — 有効にするには .env で true に設定	キャッシュへの POST を実行するかどうかを制御します。
SHOPSTR_CACHE_URL	https://shopstr.store/api/db/cache-event	セルフホスト可能な Shopstr デプロイにミラーする場合に上書きします。

NIP-15 ツール（kind:30017/30018）はこれらの設定を無視します。これらの kind は、Shopstr のキャッシュ可能な許可リストに含まれていません。

任意の安全設定

変数	デフォルト	用途
NOSTR_READ_ONLY	false	すべての公開ツールを無効にします（list_my_* は引き続き利用できます）。
NOSTR_REQUIRE_CONFIRM	false	2 段階確認です。作成／更新時にトークンが返され、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 プロフィールスラッグを登録している場合、URL は正規の /marketplace/<your-slug> に変換されます。）購入者は Shopstr のインボイス生成フローを通じて購入し、sats は Shopstr プロフィールにリンクされた Lightning ウォレットに入金されます。

NIP-15 の代替手段（Shopstr クライアント以外の場合）

Shopstr ではなく（または Shopstr に加えて）NIP-15 ネイティブのクライアントを対象にする場合、従来のツールも引き続き使用できます：

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 のみ）— 署名済みイベントを SHOPSTR_CACHE_URL に POST します。失敗は監査ログ（after_publish.shopstr_cache.{ok, status, error}）に記録されますが、リレーへの公開が取り消されることはありません。
7. 監査ログへの記録。

KindAllowlist は省略されています。使用する kind（30017/30018/30019/30402）はツールの実装にハードコードされており、検証対象となるエージェント提供の kind がないためです。

より厳格な動作が必要な場合は、nostr-ops-mcp と組み合わせ、同じ npub に対してその kind allowlist を使用してください。ただし、単一目的のマーケットプレイスサーバーでは、その手間は不要だと考えるユーザーがほとんどです。

---

テスト

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 — フォロー、DM、zap をお送りください。
• Lightning アドレス： [email protected] — サポートへの zap や「役に立った」という感謝のチップにご利用ください。
• バグ報告／機能リクエスト： GitHub の issue を作成してください（リンクは後日掲載）。
• セキュリティ上の問題： 公開 issue を作成する前に、NOSTR DM で非公開にてご報告ください。