@three-ws/mcp-server 1.1.0

package/LICENSE

@@ -0,0 +1,180 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other transformations
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as "Not a
+      Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or any
+      Contribution embodied within the Work constitutes direct or contributory
+      patent infringement, then any patent licenses granted to You under
+      this License for that Work shall terminate as of the date such
+      litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or in addition to the
+          NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, copy, modify, merge,
+      publish, distribute, sublicense, and/or sell copies of the
+      Derivative Works, and to permit persons to whom the Derivative Works
+      are furnished to do so.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may offer only
+      conditions consistent with this License.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 nirholas
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,304 @@
+<p align="center">
+  <a href="https://three.ws"><img src="https://three.ws/three-ws-mcp-icon.svg" alt="three.ws" width="88" height="88"></a>
+</p>
+
+<h1 align="center">@three-ws/mcp-server</h1>
+
+<p align="center"><strong>Paid x402 MCP tools from three.ws — text/image→3D, avatars, rigging, agent reputation, and more. Settled per call in USDC.</strong></p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@three-ws/mcp-server"><img alt="npm" src="https://img.shields.io/npm/v/@three-ws/mcp-server?logo=npm&color=cb3837"></a>
+  <a href="https://www.npmjs.com/package/@three-ws/mcp-server"><img alt="downloads" src="https://img.shields.io/npm/dm/@three-ws/mcp-server?color=cb3837"></a>
+  <img alt="license" src="https://img.shields.io/npm/l/@three-ws/mcp-server?color=3b82f6">
+  <a href="https://registry.modelcontextprotocol.io/?q=io.github.nirholas"><img alt="MCP Registry" src="https://img.shields.io/badge/MCP%20Registry-io.github.nirholas-7c3aed"></a>
+  <img alt="node" src="https://img.shields.io/node/v/@three-ws/mcp-server?color=339933&logo=node.js">
+  <a href="https://three.ws"><img alt="three.ws" src="https://img.shields.io/badge/built%20by-three.ws-000"></a>
+</p>
+
+<p align="center">
+  <a href="#quickstart-30-seconds">Quickstart</a> ·
+  <a href="#tools">Tools</a> ·
+  <a href="#environment-variables">Config</a> ·
+  <a href="#programmatic-client">Programmatic</a> ·
+  <a href="#payment-flow">Payments</a> ·
+  <a href="https://three.ws">three.ws</a>
+</p>
+
+---
+
+> Fifteen paid MCP tools from [three.ws](https://three.ws) — text/image→3D mesh generation, 3D avatars, GLB auto-rigging, pose seeds, pump.fun snapshots, ERC-8004 agent reputation, ENS/SNS resolution, agent-to-agent delegation, token sentiment, AgenC coordination reads, aixbt market intel, and a Solana vanity grinder. Each call is settled in USDC via the [x402](https://x402.org) payment protocol on Solana mainnet (`exact` scheme). No subscription, no API key — pay per call, and failed calls never bill the caller.
+
+---
+
+## Quickstart (30 seconds)
+
+### Claude Code
+
+```bash
+claude mcp add 3d-agent -- npx -y @three-ws/mcp-server
+```
+
+To also receive payments (server operators), pass the payout address as env: `claude mcp add 3d-agent -e MCP_SVM_PAYMENT_ADDRESS=YourSolanaWallet -- npx -y @three-ws/mcp-server`. Alternatively, run `/setup-mcp` in any project that includes this repo and Claude will detect your OS, collect your wallet addresses, and write the config for you.
+
+### Claude Desktop
+
+Paste this into your **Claude Desktop** config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):
+
+```json
+{
+	"mcpServers": {
+		"3d-agent": {
+			"command": "npx",
+			"args": ["-y", "@three-ws/mcp-server"],
+			"env": {
+				"MCP_SVM_PAYMENT_ADDRESS": "YourSolanaWallet"
+			}
+		}
+	}
+}
+```
+
+Restart Claude Desktop. All tools appear immediately — no install step required.
+
+---
+
+## Tools
+
+Every tool quotes a fixed USDC price and settles `exact` on Solana mainnet. Prices below come straight from each tool's source. Every tool also declares MCP tool annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) so clients can scope confirmation prompts correctly — none of these tools are destructive.
+
+### 3D generation
+
+| Tool             | Price  | What it returns                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `mesh_forge`     | $0.25  | Textured 3D GLB from a **text prompt or a reference image**. Text mode runs a chain of specialist models — an IBM Granite "prompt director" rewrites the prompt into an optimized single-subject 3D spec, FLUX renders a reference image, and Microsoft TRELLIS / Tencent Hunyuan3D reconstruct the mesh. Image mode (`image_url`) reconstructs directly. Returns the durable `glbUrl`, a three.ws viewer `preview`, the `directedPrompt`, and timing. |
+| `rig_mesh`       | $0.20  | Auto-rig a static GLB into an animation-ready model — humanoid skeleton + per-vertex skin weights via VAST-AI UniRig. Takes a `glb_url` (e.g. `mesh_forge`'s output), returns the `riggedGlbUrl` and a three.ws pose-studio link.                                                                                                                                                                                                                      |
+| `text_to_avatar` | $0.15  | Textured 3D GLB avatar from a text prompt or reference image URLs, driving Replicate (Hunyuan-3D 3.1 by default). Returns the GLB URL, model version, prediction id, and timing.                                                                                                                                                                                                                                                                       |
+| `get_pose_seed`  | $0.001 | Deterministic seed + full Euler-rotation pose map (radians) for the three.ws pose-studio mannequin, matched from the in-repo preset library. Includes a `previewUrl` at `https://three.ws/pose?seed=…&preset=…`.                                                                                                                                                                                                                                       |
+
+### Solana & markets
+
+| Tool              | Price  | What it returns                                                                                                                                                                                                                                                                         |
+| ----------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pump_snapshot`   | $0.005 | Live token snapshot — USD price (Jupiter), 24h volume + pair (Dexscreener), mint metadata + image (pump.fun frontend-api-v3), and on-chain top-holder distribution (Solana RPC). Adds Helius DAS data when `HELIUS_API_KEY` is set.                                                     |
+| `sentiment_pulse` | $0.003 | Sentiment for a Solana token: scores recent pump.fun comments (plus optional caller-supplied snippets) with the three.ws deterministic lexicon. Returns overall + per-source breakdown with examples. Pairs with `pump_snapshot`.                                                       |
+| `vanity_grinder`  | $0.05  | Solana keypair whose base58 address starts with `prefix` (and optionally ends with `suffix`). Returns the full base58 secret key — treat as a secret. Flat price (override with `MCP_VANITY_PRICE_USD`); a difficulty guard rejects prefixes too long to mine within the iteration cap. |
+| `aixbt_intel`     | $0.01  | aixbt narrative intelligence feed — recent intel items across crypto with category, description, observation count, official-source flag, and the project/ticker concerned. Optional category/chain filter. Live aixbt REST API.                                                        |
+| `aixbt_projects`  | $0.01  | aixbt momentum scan — projects ranked by spiking/climbing/active scores, with ticker, chain, market metrics (price, mcap, 24h volume + change), and recent intel. Filter by names or chain. Live aixbt REST API.                                                                        |
+
+### Agents & identity
+
+| Tool                    | Price   | What it returns                                                                                                                                                                                                                                              |
+| ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `agent_reputation`      | $0.01   | ERC-8004 reputation: `getReputation`, `getTotalStake`, and the latest `ReputationSubmitted` / `ReputationStaked` events from the canonical ReputationRegistry on the requested chain (default Base). Resolves `agentId` from a wallet address automatically. |
+| `agent_delegate_action` | $0.01   | Send a message to a three.ws-registered agent and receive its response (it uses its configured Claude model + system prompt). Agents opted out of MCP delegation are refused. For agent-to-agent collaboration and tool composition.                         |
+| `ens_sns_resolve`       | $0.0005 | Resolve a human-readable name across **ENS** (`.eth` → Ethereum address via ethers) and **SNS** (`.sol` → Solana owner wallet via Bonfida, plus the wallet's other owned `.sol` domains). Suffix-less names are tried against both.                          |
+| `agenc_list_tasks`      | $0.001  | List every public AgenC task created by a Solana wallet — task PDA, state, reward, deadline, worker counts, reward mint. AgenC (agenc.tech, Tetsuo Corp) is a Solana task-coordination protocol. `cluster` defaults to mainnet.                              |
+| `agenc_get_task`        | $0.001  | On-chain state + lifecycle timeline of a single AgenC task. Pass `taskPda` or `{creator, taskId}` (hex or any UTF-8 label). Returns state, reward, deadline, worker counts, lifecycle events, reward mint.                                                   |
+| `agenc_get_agent`       | $0.001  | An AgenC agent's on-chain registration. Pass `agentPda` or `agentId` (hex or UTF-8 label). Returns authority wallet, capability bitmask, endpoint URL, status, reputation, stake, and active task count.                                                     |
+
+---
+
+## Installation
+
+The server runs locally on your machine and speaks stdio JSON-RPC — your MCP client spawns it automatically via the `npx` command above. You do not need to `npm install` globally.
+
+If you prefer a global install:
+
+```bash
+npm install -g @three-ws/mcp-server
+```
+
+Then replace `"command": "npx", "args": ["-y", "@three-ws/mcp-server"]` with `"command": "3d-agent-mcp"` in your config.
+
+---
+
+## Environment variables
+
+### Required
+
+| Var                       | Description                                                                                                          |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `MCP_SVM_PAYMENT_ADDRESS` | Solana USDC payout address (base58) where tools receive payment. Falls back to `X402_PAY_TO_SOLANA` / `X402_PAY_TO`. |
+
+### Optional
+
+| Var                             | Default                               | Description                                                                                                        |
+| ------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `HELIUS_API_KEY`                | unset                                 | Adds Helius DAS enrichment to `pump_snapshot`                                                                      |
+| `SOLANA_RPC_URL`                | `https://api.mainnet-beta.solana.com` | Primary Solana RPC for `pump_snapshot` / AgenC reads                                                               |
+| `SOLANA_RPC_URLS`               | built-in public set                   | **Failover** — comma-separated Solana RPCs tried in order; first healthy one answers                               |
+| `MCP_EVM_RPC_<chainId>`         | built-in public set                   | **Failover** — comma-separated EVM RPCs for that chain (`agent_reputation`, ENS uses chain 1)                      |
+| `X402_FACILITATOR_URL_SOLANA`   | `https://facilitator.payai.network`   | Primary PayAI Solana facilitator that verifies + settles payments                                                  |
+| `X402_FACILITATOR_URLS_SOLANA`  | unset                                 | **Failover** — comma-separated facilitators; earlier entries take precedence at init, a later one covers an outage |
+| `X402_FACILITATOR_TOKEN_SOLANA` | unset                                 | Bearer token for the Solana facilitator, if required                                                               |
+| `X402_FEE_PAYER_SOLANA`         | three.ws default                      | Fee payer for the settlement transaction                                                                           |
+| `MCP_VANITY_PRICE_USD`          | `$0.05`                               | Flat price for `vanity_grinder`                                                                                    |
+| `MCP_POSE_PREVIEW_BASE`         | `https://three.ws/pose`               | Base URL for `get_pose_seed` preview links                                                                         |
+| `MCP_AGENT_REP_RPC_<chainId>`   | public RPC                            | Per-chain RPC override for `agent_reputation` (tried before the failover set)                                      |
+| `MCP_AGENT_REP_LOG_WINDOW`      | `200000`                              | Block window for `agent_reputation` event scan                                                                     |
+
+---
+
+## Claude Code slash commands
+
+This repo ships three slash commands in `.claude/commands/` that work in any project that references this repo:
+
+| Command                  | What it does                                                                            |
+| ------------------------ | --------------------------------------------------------------------------------------- |
+| `/setup-mcp`             | Detects your OS, collects wallet addresses, and writes the MCP config to the right file |
+| `/scaffold-agent`        | Scaffolds a new three.ws agent in the current project with MCP client wiring            |
+| `/use-tools [tool_name]` | Produces a complete, runnable code example for a specific paid tool                     |
+
+---
+
+## Programmatic client
+
+Use `@x402/mcp`'s `wrapMCPClientWithPayment` to call these tools from another Node service. The wrapper auto-handles 402 retries:
+
+```js
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { wrapMCPClientWithPayment } from '@x402/mcp';
+import { x402Client } from '@x402/core/client';
+import { registerExactSvmScheme } from '@x402/svm/exact/client';
+import { Keypair } from '@solana/web3.js';
+import bs58 from 'bs58';
+
+const transport = new StdioClientTransport({
+	command: 'npx',
+	args: ['-y', '@three-ws/mcp-server'],
+	env: {
+		// Where the server receives USDC. Your client funds payments from the
+		// Solana keypair below.
+		MCP_SVM_PAYMENT_ADDRESS: process.env.MCP_SVM_PAYMENT_ADDRESS,
+	},
+});
+
+const mcp = new Client({ name: 'agent', version: '1.0.0' });
+await mcp.connect(transport);
+
+// Solana mainnet, `exact` scheme — the only network/scheme these tools accept.
+const payer = Keypair.fromSecretKey(bs58.decode(process.env.AGENT_SOLANA_SECRET_KEY));
+const x402 = new x402Client();
+registerExactSvmScheme(x402, { signer: payer });
+const paid = wrapMCPClientWithPayment(mcp, x402, { autoPayment: true });
+
+const result = await paid.callTool('get_pose_seed', { prompt: 'warrior stance' });
+// Prefer MCP structured output; fall back to the text mirror for older servers.
+console.log(result.structuredContent ?? JSON.parse(result.content[0].text));
+```
+
+---
+
+## Cursor
+
+In Cursor's MCP settings (`Cursor > Settings > Features > MCP`):
+
+```json
+{
+	"mcpServers": {
+		"3d-agent": {
+			"command": "npx",
+			"args": ["-y", "@three-ws/mcp-server"],
+			"env": {
+				"MCP_SVM_PAYMENT_ADDRESS": "YourSolanaWallet"
+			}
+		}
+	}
+}
+```
+
+---
+
+## Run from source
+
+From the monorepo root:
+
+```bash
+npm install
+node mcp-server/src/index.js
+```
+
+Inspect tools interactively:
+
+```bash
+npm run inspect --prefix mcp-server
+```
+
+---
+
+## Payment flow
+
+The server is the x402 **resource server**. On each tool call:
+
+1. Client sends a `tools/call` request (no payment yet).
+2. Server returns `PaymentRequired` (v2 MCP transport spec) with the USDC amount and payment address.
+3. A payment-aware client (or `wrapMCPClientWithPayment`) signs and submits the on-chain payment.
+4. Client retries the `tools/call` with `_meta["x402/payment"]` attached.
+5. Server verifies + settles via the configured facilitator, runs the tool, and returns the result with `_meta["x402/payment-response"]`.
+
+Every tool settles in USDC on **Solana mainnet** with the `exact` scheme (`@x402/svm` ships no `upto`/metered scheme). Each tool quotes a fixed price; there is no post-hoc metering.
+
+A successful result carries the tool's JSON in two forms: `content[0].text` (for text-only clients) and `structuredContent` (MCP 2025-06-18 structured output — a ready-to-use object). A tool-level error sets `isError: true`, and the x402 wrapper **cancels rather than settles** the payment, so failed calls do not bill the caller.
+
+---
+
+## Reliability & failover
+
+Every external dependency has a backup path, so a single provider blip doesn't take a tool down — and no call can hang a paid request indefinitely.
+
+- **Every outbound HTTP call** runs through a shared resilient layer (`src/lib/resilient-fetch.js`): a hard per-attempt timeout plus jittered exponential-backoff retries on transient `429`/`5xx`/network errors, honoring `Retry-After`. Retries are restricted to idempotent reads by default — a non-idempotent action like `agent_delegate_action` gets the timeout but is **never** silently replayed.
+- **Solana RPC** (`src/lib/solana-rpc.js`) fails over across an ordered endpoint list (`SOLANA_RPC_URLS`, else the primary, else a built-in public set). A throttling or down endpoint rotates to the back and the next one answers.
+- **EVM RPC** (`src/lib/evm-rpc.js`) uses an ethers `FallbackProvider` (quorum 1) over multiple endpoints per chain (`MCP_EVM_RPC_<chainId>` or built-in redundancy), each request timeout-bounded.
+- **The x402 facilitator** accepts a comma-separated `X402_FACILITATOR_URLS_SOLANA`: earlier entries take precedence at init, and a later facilitator covers the Solana `exact` kind if the primary's `/supported` is unreachable.
+- **Data fallback:** `pump_snapshot` cross-fills its USD price from Dexscreener when Jupiter is unavailable, and each upstream fails soft to a `null`/`{ error }` field rather than failing the whole snapshot.
+
+For maximum redundancy, set dedicated endpoints rather than relying on the public defaults:
+
+```bash
+SOLANA_RPC_URLS="https://your-primary-rpc,https://your-secondary-rpc"
+MCP_EVM_RPC_8453="https://your-base-rpc,https://base-rpc.publicnode.com"
+X402_FACILITATOR_URLS_SOLANA="https://facilitator.payai.network,https://your-backup-facilitator"
+```
+
+---
+
+## Architecture
+
+```
+┌─────────────────┐     ┌─────────────────────┐     ┌──────────────────────┐
+│ Claude Desktop  │────▶│  @three-ws/mcp      │────▶│  x402 facilitator    │
+│  / Cursor /     │     │   (stdio transport) │     │  (PayAI — Solana     │
+│  your agent     │     │                     │     │   USDC, exact)       │
+└─────────────────┘     └─────────────────────┘     └──────────────────────┘
+```
+
+Source: [`mcp-server/`](https://github.com/nirholas/three.ws/tree/main/mcp-server)
+
+---
+
+## Requirements
+
+- Node.js **>= 20** (from `engines`).
+- A Solana USDC payout address in `MCP_SVM_PAYMENT_ADDRESS` (or `X402_PAY_TO_SOLANA` / `X402_PAY_TO`) to settle paid calls — see [Environment variables](#environment-variables). Tool registration (names/schemas) needs no env; only an actual paid invocation does.
+- A payment-aware MCP client (or `@x402/mcp`'s `wrapMCPClientWithPayment`) funding payments from a Solana keypair.
+
+## Related
+
+- [`@three-ws/pumpfun-mcp`](https://www.npmjs.com/package/@three-ws/pumpfun-mcp) — the free, read-only pump.fun + Solana MCP (token discovery, on-chain analysis, live 3D snapshots; no keys).
+
+## Links
+
+- Homepage: https://three.ws
+- Changelog: https://three.ws/changelog
+- Issues: https://github.com/nirholas/three.ws/issues
+- License: Apache-2.0 — see [LICENSE](./LICENSE)
+
+---
+
+<p align="center">
+  <sub>
+    Part of the <a href="https://three.ws">three.ws</a> SDK suite — 3D AI agents, on-chain identity, and agent payments.<br/>
+    <a href="https://three.ws">Website</a> · <a href="https://three.ws/changelog">Changelog</a> · <a href="https://github.com/nirholas/three.ws">GitHub</a>
+  </sub>
+</p>

package/package.json

@@ -0,0 +1,79 @@
+{
+	"name": "@three-ws/mcp-server",
+	"version": "1.1.0",
+	"mcpName": "io.github.nirholas/3d-agent-mcp",
+	"description": "Paid MCP tools for the 3d-agent stack — pose generation, pump.fun snapshots, ERC-8004 agent reputation, Solana vanity grinder. Settled in USDC via x402.",
+	"type": "module",
+	"author": "nirholas",
+	"license": "Apache-2.0",
+	"homepage": "https://three.ws",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/nirholas/three.ws.git",
+		"directory": "mcp-server"
+	},
+	"keywords": [
+		"mcp",
+		"model-context-protocol",
+		"3d-agent",
+		"three.ws",
+		"x402",
+		"usdc",
+		"solana",
+		"pump.fun",
+		"erc-8004",
+		"ai-agent",
+		"pose-generation",
+		"vanity-address"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"src",
+		"server.json",
+		"README.md",
+		"LICENSE"
+	],
+	"bin": {
+		"3d-agent-mcp": "src/index.js"
+	},
+	"main": "./src/index.js",
+	"exports": {
+		".": "./src/index.js"
+	},
+	"engines": {
+		"node": ">=20"
+	},
+	"scripts": {
+		"start": "node src/index.js",
+		"inspect": "npx -y @modelcontextprotocol/inspector node src/index.js",
+		"prepublishOnly": "node -e \"import('./src/index.js').catch(e => { if (!e.message.includes('facilitator')) throw e })\" 2>/dev/null; echo 'package check ok'"
+	},
+	"dependencies": {
+		"@bonfida/spl-name-service": "0.1.67",
+		"@coinbase/x402": "^2.1.0",
+		"@coral-xyz/anchor": "^0.32.1",
+		"@ethereum-attestation-service/eas-sdk": "0.29.1",
+		"@metaplex-foundation/js": "^0.20.1",
+		"@modelcontextprotocol/sdk": "^1.29.0",
+		"@solana/web3.js": "^1.98.4",
+		"@tetsuo-ai/protocol": "^0.2.0",
+		"@tetsuo-ai/sdk": "^1.4.0",
+		"@x402/core": "^2.13.0",
+		"@x402/evm": "^2.13.0",
+		"@x402/extensions": "^2.12.0",
+		"@x402/mcp": "^2.13.0",
+		"@x402/svm": "^2.13.0",
+		"agent0-sdk": "^1.7.1",
+		"bs58": "^6.0.0",
+		"colyseus": "0.17.10",
+		"ethers": "^6.16.0",
+		"short-uuid": "6.0.3",
+		"zod": "^3.23.8",
+		"zod-to-json-schema": "3.25.2"
+	},
+	"bugs": {
+		"url": "https://github.com/nirholas/three.ws/issues"
+	}
+}

package/server.json

@@ -0,0 +1,54 @@
+{
+	"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+	"name": "io.github.nirholas/3d-agent-mcp",
+	"title": "three.ws 3D Agent Tools",
+	"description": "Paid x402 MCP tools from three.ws: text-to-3D generation, rigging, agent reputation, market intel.",
+	"websiteUrl": "https://three.ws",
+	"icons": [
+		{
+			"src": "https://three.ws/three-ws-mcp-icon.svg",
+			"mimeType": "image/svg+xml",
+			"sizes": [
+				"any"
+			]
+		}
+	],
+	"repository": {
+		"url": "https://github.com/nirholas/three.ws",
+		"source": "github",
+		"subfolder": "mcp-server"
+	},
+	"version": "1.1.0",
+	"packages": [
+		{
+			"registryType": "npm",
+			"identifier": "@three-ws/mcp-server",
+			"version": "1.1.0",
+			"runtimeHint": "npx",
+			"transport": {
+				"type": "stdio"
+			},
+			"environmentVariables": [
+				{
+					"name": "MCP_SVM_PAYMENT_ADDRESS",
+					"description": "Solana address that receives USDC when a client pays for a tool call (falls back to X402_PAY_TO_SOLANA / X402_PAY_TO). Required to settle paid tools.",
+					"format": "string",
+					"isRequired": false
+				},
+				{
+					"name": "SOLANA_RPC_URL",
+					"description": "Solana mainnet RPC endpoint. Defaults to the public cluster — bring your own (Helius / QuickNode / Triton) for production traffic.",
+					"format": "string",
+					"isRequired": false
+				},
+				{
+					"name": "HELIUS_API_KEY",
+					"description": "Optional Helius API key — enables exact supply and richer DAS data in pump.fun snapshots.",
+					"format": "string",
+					"isRequired": false,
+					"isSecret": true
+				}
+			]
+		}
+	]
+}