Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
docs(mcp): give the KOL and Loom servers runnable examples and honest outage docs
nirholasadd791c58367
diff --git a/packages/kol-mcp/README.md b/packages/kol-mcp/README.mdindex 10cb5c568..9f54a058a 100644--- a/packages/kol-mcp/README.md+++ b/packages/kol-mcp/README.md@@ -113,6 +113,21 @@ Both tools read live data: holdings, P&L and trade feeds move between calls, so`has_activity: false` on a portfolio (no holdings and no trades) means the proxy has no recorded history for that address yet: an honest "no data", not a failure. A **null** P&L field with `pnl_source: null` is the same kind of honesty at field level: three.ws has no trade history for that wallet in the window, so it reports nothing rather than a zero that would read as a flat record.+An outage is never dressed up as either of those. When the holdings provider is down or rate-limited, three.ws omits the wallet's row rather than inventing one, and `get_wallet_portfolio` fails with **`upstream_unavailable`** instead of answering with an empty card. A quiet wallet and a dark provider are different answers, and an agent copying a trader needs to be able to tell them apart.++## Examples++Runnable examples live in [`examples/`](./examples):++```bash+node examples/list-tools.mjs # both tools with their full input schemas+node examples/wallet-card.mjs # a trader's portfolio card + trades, live+```++Both spawn this server over stdio and read the live public KOL API. Every tool+here is read-only, so nothing can be signed, spent, or published. See+[`examples/README.md`](./examples/README.md) for expected output.+## Requirements- **Node.js >= 20.**diff --git a/packages/kol-mcp/examples/README.md b/packages/kol-mcp/examples/README.mdnew file mode 100644index 000000000..1ced7a31d--- /dev/null+++ b/packages/kol-mcp/examples/README.md@@ -0,0 +1,96 @@+# Examples: @three-ws/kol-mcp++Two runnable examples. Both spawn this package's own MCP server over stdio (the+same `node src/index.js` entry point the README documents), speak real MCP+JSON-RPC to it, and read the live public KOL API.++| File | What it does | Run |+|---|---|---|+| [`list-tools.mjs`](list-tools.mjs) | Prints both tools with titles, annotation hints, and full input schemas. | `node examples/list-tools.mjs` |+| [`wallet-card.mjs`](wallet-card.mjs) | One trader's portfolio card, then that trader's trades on a mint. | `node examples/wallet-card.mjs` |++Run them from the package directory:++```bash+cd packages/kol-mcp+node examples/list-tools.mjs+node examples/wallet-card.mjs+```++Nothing to install and nothing to configure: both tools on this server are+read-only and keyless. The server prints a one-line banner to stderr on connect+(`[[email protected]] connected over stdio with 2 tools`), which is normal.++## list-tools.mjs++Runs the MCP `initialize` handshake, then `tools/list`, and formats every tool.+Expected output (abridged):++```+server: kol-mcp v0.1.1 (stdio)+capabilities: tools+tools: 2++1. get_wallet_portfolio+ title: KOL wallet portfolio + P&L+ hints: read-only, open-world+ params:+ - wallet (required; string, minLength 1)++2. get_wallet_trades+ title: A KOL wallet's trades on a mint+ hints: read-only, open-world+ params:+ - wallet (required; string, minLength 1)+ - mint (required; string, minLength 1)+ - limit (optional; integer, min 1, max 100)+```++Both tools report `read-only, open-world`. There is no write tool on this+server to accidentally reach for.++## wallet-card.mjs++The two calls chained the way an agent would chain them: pull the trader's card,+then look at how that trader is positioning in one token.++```bash+node examples/wallet-card.mjs # picks a tracked wallet for you+node examples/wallet-card.mjs <wallet> # a wallet you care about+node examples/wallet-card.mjs <wallet> <mint> # and a token to inspect+```++With no wallet argument it reads one off the public KOL leaderboard at runtime,+so the example stays runnable without pasting an address in. The mint defaults+to `$THREE`.++```+get_wallet_portfolio: 5xY…KoL+ holdings: 14 position(s) worth $38,120+ top token: THREE at $21,500+ realized: $124,300 over 30d+ win rate: 64.0%+ trades: 412 (source: onchain-fifo)++get_wallet_trades: FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump+ - buy 4.2 SOL $612.4 2026-06-24 09:12++Both calls were read-only. Nothing was signed, spent, or modified.+```++Live data moves between runs. Two states are printed rather than hidden, and+both are worth reading:++- **`unknown (no data to measure)`** where a P&L field is null. three.ws has no+ trade history for that wallet in the window. It is not a flat record, and the+ example refuses to render it as `$0`.+- **`provider outage: …`** when the holdings or trade provider is down or+ rate-limited. The server reports that as an error rather than an empty card,+ so an outage can never be misread as a quiet wallet. The example prints it and+ keeps going.++### Environment++Optional, forwarded to the server if set: `THREE_WS_BASE` (default+`https://three.ws`) and `THREE_WS_TIMEOUT_MS`. Point `THREE_WS_BASE` at your own+deployment to read its KOL data instead.diff --git a/packages/kol-mcp/examples/list-tools.mjs b/packages/kol-mcp/examples/list-tools.mjsnew file mode 100644index 000000000..cc71e72de--- /dev/null+++ b/packages/kol-mcp/examples/list-tools.mjs@@ -0,0 +1,102 @@+// list-tools.mjs: print every tool @three-ws/kol-mcp advertises, with its input+// schema.+//+// Spawns this package's own MCP server over stdio the way the README runs it+// (`node src/index.js`), performs the MCP initialize handshake, calls+// tools/list, and prints each tool's title, annotation hints, and parameters.+//+// node examples/list-tools.mjs+//+// Read-only: no key, no signer, no payment.++import { fileURLToPath } from 'node:url';++import { Client } from '@modelcontextprotocol/sdk/client/index.js';+import {+ StdioClientTransport,+ getDefaultEnvironment,+} from '@modelcontextprotocol/sdk/client/stdio.js';++// The README's "Run standalone" entry point. Swap for+// { command: 'npx', args: ['-y', '@three-ws/kol-mcp'] } to exercise the+// published package instead of this checkout.+const SERVER_PATH = fileURLToPath(new URL('../src/index.js', import.meta.url));++// Env this server reads (see src/config.js). getDefaultEnvironment() drops+// everything else, so an example never leaks unrelated secrets to the child.+const FORWARDED_ENV = ['THREE_WS_BASE', 'THREE_WS_TIMEOUT_MS'];++function childEnv() {+ const env = getDefaultEnvironment();+ for (const key of FORWARDED_ENV) {+ const value = process.env[key];+ if (value) env[key] = value;+ }+ return env;+}++/** One-line summary of a tool's MCP annotation hints. */+function hints(annotations) {+ if (!annotations) return 'no hints';+ const flags = [];+ if (annotations.readOnlyHint) flags.push('read-only');+ if (annotations.destructiveHint) flags.push('destructive');+ if (annotations.idempotentHint) flags.push('idempotent');+ if (annotations.openWorldHint) flags.push('open-world');+ return flags.length ? flags.join(', ') : 'no hints';+}++/** Render a JSON Schema property as one readable constraint string. */+function constraints(prop) {+ const parts = [prop.type ?? 'any'];+ if (Array.isArray(prop.enum)) parts.push(`one of ${prop.enum.join(' | ')}`);+ if (prop.default !== undefined) parts.push(`default ${JSON.stringify(prop.default)}`);+ if (prop.minimum !== undefined) parts.push(`min ${prop.minimum}`);+ if (prop.maximum !== undefined) parts.push(`max ${prop.maximum}`);+ if (prop.minLength !== undefined) parts.push(`minLength ${prop.minLength}`);+ return parts.join(', ');+}++function printTool(tool, index) {+ const schema = tool.inputSchema ?? {};+ const properties = schema.properties ?? {};+ const required = new Set(schema.required ?? []);+ const names = Object.keys(properties);++ console.log(`\n${index}. ${tool.name}`);+ if (tool.title) console.log(` title: ${tool.title}`);+ console.log(` hints: ${hints(tool.annotations)}`);+ if (tool.description) console.log(` ${tool.description}`);+ if (names.length === 0) {+ console.log(' params: none');+ return;+ }+ console.log(' params:');+ for (const name of names) {+ const prop = properties[name];+ const flag = required.has(name) ? 'required' : 'optional';+ console.log(` - ${name} (${flag}; ${constraints(prop)})`);+ if (prop.description) console.log(` ${prop.description}`);+ }+}++const transport = new StdioClientTransport({+ command: process.execPath,+ args: [SERVER_PATH],+ env: childEnv(),+ stderr: 'inherit',+});+const client = new Client({ name: 'kol-mcp-list-tools-example', version: '1.0.0' });++await client.connect(transport);++const server = client.getServerVersion();+console.log(`server: ${server?.name} v${server?.version} (stdio)`);+console.log(`capabilities: ${Object.keys(client.getServerCapabilities() ?? {}).join(', ') || 'none'}`);++const { tools } = await client.listTools();+console.log(`tools: ${tools.length}`);++tools.forEach((tool, i) => printTool(tool, i + 1));++await client.close();diff --git a/packages/kol-mcp/examples/wallet-card.mjs b/packages/kol-mcp/examples/wallet-card.mjsnew file mode 100644index 000000000..7e4db8801--- /dev/null+++ b/packages/kol-mcp/examples/wallet-card.mjs@@ -0,0 +1,138 @@+// wallet-card.mjs: size up one smart trader with both tools on this server.+//+// 1. get_wallet_portfolio the wallet's live holdings card + real 30d P&L+// 2. get_wallet_trades that same wallet's buys/sells of one mint+//+// Every call hits the live public three.ws KOL API. Nothing here needs a key, a+// signer, or a payment, and both tools are read-only.+//+// node examples/wallet-card.mjs # picks a tracked wallet for you+// node examples/wallet-card.mjs <wallet> # a wallet you care about+// node examples/wallet-card.mjs <wallet> <mint> # and a token to inspect+//+// With no wallet argument the example reads one off the public KOL leaderboard+// at runtime, so it stays runnable without pasting an address in. The mint+// defaults to $THREE, the only coin this platform promotes.++import { fileURLToPath } from 'node:url';++import { Client } from '@modelcontextprotocol/sdk/client/index.js';+import {+ StdioClientTransport,+ getDefaultEnvironment,+} from '@modelcontextprotocol/sdk/client/stdio.js';++const SERVER_PATH = fileURLToPath(new URL('../src/index.js', import.meta.url));+const FORWARDED_ENV = ['THREE_WS_BASE', 'THREE_WS_TIMEOUT_MS'];+const BASE = (process.env.THREE_WS_BASE || 'https://three.ws').replace(/\/+$/, '');+const THREE = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';++// Both tools read live third-party market data through three.ws. A throttled or+// unconfigured provider is a real state of this system, not a bug in the+// example: render it plainly and keep going, so an outage is never mistaken for+// a wallet with nothing to show.+const OUTAGE_CODES = new Set(['upstream_unavailable', 'upstream_error', 'timeout', 'network_error']);++const [walletArg, mintArg] = process.argv.slice(2);+const mint = mintArg || THREE;++function childEnv() {+ const env = getDefaultEnvironment();+ for (const key of FORWARDED_ENV) {+ const value = process.env[key];+ if (value) env[key] = value;+ }+ return env;+}++/** Unwrap an MCP tool result's JSON payload from its text content block. */+function payload(result) {+ const text = result?.content?.find((c) => c.type === 'text')?.text ?? '';+ try {+ return JSON.parse(text);+ } catch {+ return { ok: false, raw: text };+ }+}++/**+ * Call a tool. A provider outage comes back as `{ ok: false }` for the caller to+ * render; anything else (a bad argument, an unknown tool) fails loudly.+ */+async function call(client, name, args) {+ const data = payload(await client.callTool({ name, arguments: args }));+ if (!data.ok && !OUTAGE_CODES.has(data.error)) {+ throw new Error(`${name} failed: ${data.message || data.error || data.raw || 'unknown error'}`);+ }+ return data;+}++/**+ * A tracked wallet to demo with, read live off the public leaderboard. Ranking+ * the KOL set is intel-mcp's job (kol_leaderboard), not this server's, so the+ * example reads it directly rather than pretending this server exposes it.+ */+async function pickWallet() {+ const res = await fetch(`${BASE}/api/kol/leaderboard?limit=1`, { headers: { accept: 'application/json' } });+ if (!res.ok) throw new Error(`leaderboard lookup failed (HTTP ${res.status}). Pass a wallet address instead.`);+ const { items } = await res.json();+ const wallet = items?.[0]?.wallet;+ if (!wallet) throw new Error('the leaderboard is empty right now. Pass a wallet address instead.');+ return wallet;+}++/** USD with thousands separators, or a clearly-marked unknown. */+function usd(value) {+ if (value == null) return 'unknown (no data to measure)';+ return `$${Number(value).toLocaleString('en-US', { maximumFractionDigits: 2 })}`;+}++const wallet = walletArg || (await pickWallet());+if (!walletArg) console.log(`no wallet given, using the top tracked wallet: ${wallet}`);++const transport = new StdioClientTransport({+ command: process.execPath,+ args: [SERVER_PATH],+ env: childEnv(),+ stderr: 'inherit',+});+const client = new Client({ name: 'kol-mcp-wallet-card-example', version: '1.0.0' });+await client.connect(transport);++try {+ // -- 1. get_wallet_portfolio ------------------------------------------+ const card = await call(client, 'get_wallet_portfolio', { wallet });+ console.log(`\nget_wallet_portfolio: ${wallet}`);+ if (!card.ok) {+ console.log(` provider outage: ${card.message}`);+ } else {+ if (!card.has_activity) console.log(' no holdings and no trades on record for this wallet yet');+ console.log(` holdings: ${card.holdings} position(s) worth ${usd(card.portfolio_value_usd)}`);+ const top = card.top_token;+ console.log(` top token: ${top ? `${top.symbol} at ${usd(top.valueUsd)}` : 'none'}`);+ console.log(` realized: ${usd(card.realized_pnl_usd)} over ${card.pnl_window ?? 'an unreported window'}`);+ // A null P&L field is an honest "unknown", never a flat record: printing it+ // as $0 would report an unmeasured wallet as a break-even trader.+ const win = card.win_rate == null ? 'unknown (no closed trades)' : `${(card.win_rate * 100).toFixed(1)}%`;+ console.log(` win rate: ${win}`);+ console.log(` trades: ${card.total_trades ?? 'unknown'} (source: ${card.pnl_source ?? 'none'})`);+ }++ // -- 2. get_wallet_trades ---------------------------------------------+ const feed = await call(client, 'get_wallet_trades', { wallet, mint, limit: 5 });+ console.log(`\nget_wallet_trades: ${mint}`);+ if (!feed.ok) {+ console.log(` provider outage: ${feed.message}`);+ } else if (feed.count === 0) {+ console.log(' this wallet has not traded that mint in the feed window');+ } else {+ for (const trade of feed.trades) {+ const when = trade.time ? new Date(trade.time).toISOString().replace('T', ' ').slice(0, 16) : 'unknown time';+ console.log(` - ${String(trade.side ?? '?').padEnd(4)} ${trade.amountSol ?? '?'} SOL ${usd(trade.usd)} ${when}`);+ }+ }++ console.log('\nBoth calls were read-only. Nothing was signed, spent, or modified.');+} finally {+ await client.close();+}diff --git a/packages/loom-mcp/README.md b/packages/loom-mcp/README.mdindex 23ed86756..f87cd6a51 100644--- a/packages/loom-mcp/README.md+++ b/packages/loom-mcp/README.md@@ -85,7 +85,9 @@ The `glbUrl` must be an **https** URL hosted on one of these domains (enforced b`three.ws` · `r2.dev` · `cloudflarestorage.com` · `replicate.delivery` · `githubusercontent.com`-Re-submitting the exact same `glbUrl` returns the existing creation instead of duplicating it.+Re-submitting the exact same `glbUrl` returns the existing creation instead of duplicating it. The dedupe is best-effort by design: it scans only the newest few entries, which is where an accidental re-POST lands. Re-submitting a GLB that has since scrolled down the feed creates a second record.++`get_creation` answers an id that no longer exists with a typed **`not_found`** error rather than an empty creation, so a stale id in a saved reference is unambiguous.## Example@@ -121,6 +123,20 @@ Re-submitting the exact same `glbUrl` returns the existing creation instead of dDrop a creation's `iframe_snippet` onto any web page, or open its `viewer_url` to orbit the model (with AR on supported devices).+## Examples++Runnable examples live in [`examples/`](./examples):++```bash+node examples/list-tools.mjs # all 3 tools with their full input schemas+node examples/browse-loom.mjs # a page of the gallery + one creation's embed, live+```++Both spawn this server over stdio and read the live public gallery. They are+deliberately read-only: `submit_creation` posts to a world-readable feed, so no+example writes on your behalf. See [`examples/README.md`](./examples/README.md)+for expected output.+## Requirements- **Node.js >= 20.**diff --git a/packages/loom-mcp/examples/README.md b/packages/loom-mcp/examples/README.mdnew file mode 100644index 000000000..655d46f01--- /dev/null+++ b/packages/loom-mcp/examples/README.md@@ -0,0 +1,93 @@+# Examples: @three-ws/loom-mcp++Two runnable examples. Both spawn this package's own MCP server over stdio (the+same `node src/index.js` entry point the README documents), speak real MCP+JSON-RPC to it, and read the live public Loom gallery.++| File | What it does | Run |+|---|---|---|+| [`list-tools.mjs`](list-tools.mjs) | Prints all 3 tools with titles, annotation hints, and full input schemas. | `node examples/list-tools.mjs` |+| [`browse-loom.mjs`](browse-loom.mjs) | A page of the gallery, the next page via its cursor, then one creation with a paste-ready embed. | `node examples/browse-loom.mjs` |++Run them from the package directory:++```bash+cd packages/loom-mcp+node examples/list-tools.mjs+node examples/browse-loom.mjs+```++Nothing to install and nothing to configure: every tool here is keyless. The+server prints a one-line banner to stderr on connect+(`[[email protected]] connected over stdio with 3 tools`), which is normal.++**Both examples are deliberately read-only.** `submit_creation` posts to a+world-readable public gallery, so no example here writes on your behalf.++## list-tools.mjs++Runs the MCP `initialize` handshake, then `tools/list`, and formats every tool.+Expected output (abridged):++```+server: loom-mcp v0.1.2 (stdio)+capabilities: tools+tools: 3++1. get_loom_feed+ hints: read-only, open-world+ params:+ - limit (optional; integer, min 1, max 120)+ - before (optional; integer)++2. get_creation+ hints: read-only, open-world+ params:+ - id (required; string, minLength 1)++3. submit_creation+ hints: open-world+ params:+ - prompt (required), glbUrl (required), author, previewImageUrl, tier, backend+```++`submit_creation` is the one tool without `read-only`: it appends to the public+feed, and it is not idempotent (only an identical `glbUrl` re-posted while it is+still among the newest few dedupes).++## browse-loom.mjs++```bash+node examples/browse-loom.mjs # 3 creations+node examples/browse-loom.mjs 5 # page size, 1-120+```++```+get_loom_feed: 3 creation(s), nextBefore=1786772590629+ - a low-poly wooden treasure chest with brass hinges+ by nova on 2026-08-15 via hunyuan++next page (before=1786772590629): 0 older creation(s)++get_creation: d67a1e0c-3e87-4200-b834-114b10b2ce9f+ prompt: a low-poly wooden treasure chest with brass hinges+ glb: https://…/chest.glb+ viewer: https://three.ws/forge/embed?src=…+ card: https://three.ws/api/avatar-og?src=…++ paste this anywhere:+ <iframe src="https://three.ws/forge/embed?src=…" width="640" height="360" …></iframe>++Every call was read-only. Nothing was submitted to the public gallery.+```++The gallery is live, so ids, prompts, and counts move between runs. What stays+stable is the shape: a full page hands back a `nextBefore` cursor, feeding it+back as `before` walks older items, and a null cursor means you reached the end.+An empty gallery is a normal outcome and the example says so instead of failing.++### Environment++Optional, forwarded to the server if set: `THREE_WS_BASE` (default+`https://three.ws`) and `THREE_WS_TIMEOUT_MS`. Point `THREE_WS_BASE` at your own+deployment to browse its gallery instead.diff --git a/packages/loom-mcp/examples/browse-loom.mjs b/packages/loom-mcp/examples/browse-loom.mjsnew file mode 100644index 000000000..d840050ae--- /dev/null+++ b/packages/loom-mcp/examples/browse-loom.mjs@@ -0,0 +1,106 @@+// browse-loom.mjs: walk the public Loom gallery with this server's two read+// tools, and print an embed you can paste straight into a page.+//+// 1. get_loom_feed the newest community-forged creations, with a cursor+// 2. get_creation one creation expanded, with its viewer URL + iframe+//+// Every call hits the live public /api/loom endpoint. No key, no account, no+// payment. Deliberately read-only: submit_creation writes to a world-readable+// gallery, so an example never posts on your behalf.+//+// node examples/browse-loom.mjs+// node examples/browse-loom.mjs 5 # page size (1-120, default 3)++import { fileURLToPath } from 'node:url';++import { Client } from '@modelcontextprotocol/sdk/client/index.js';+import {+ StdioClientTransport,+ getDefaultEnvironment,+} from '@modelcontextprotocol/sdk/client/stdio.js';++const SERVER_PATH = fileURLToPath(new URL('../src/index.js', import.meta.url));+const FORWARDED_ENV = ['THREE_WS_BASE', 'THREE_WS_TIMEOUT_MS'];++const limit = Math.min(120, Math.max(1, Number(process.argv[2]) || 3));++function childEnv() {+ const env = getDefaultEnvironment();+ for (const key of FORWARDED_ENV) {+ const value = process.env[key];+ if (value) env[key] = value;+ }+ return env;+}++/** Unwrap an MCP tool result's JSON payload from its text content block. */+function payload(result) {+ const text = result?.content?.find((c) => c.type === 'text')?.text ?? '';+ try {+ return JSON.parse(text);+ } catch {+ return { ok: false, raw: text };+ }+}++/** Call a tool and fail loudly rather than continuing on half-data. */+async function call(client, name, args) {+ const data = payload(await client.callTool({ name, arguments: args }));+ if (!data.ok) {+ throw new Error(`${name} failed: ${data.message || data.error || data.raw || 'unknown error'}`);+ }+ return data;+}++function truncate(text, max) {+ const one = String(text ?? '').replace(/\s+/g, ' ').trim();+ return one.length > max ? `${one.slice(0, max - 3)}...` : one;+}++const transport = new StdioClientTransport({+ command: process.execPath,+ args: [SERVER_PATH],+ env: childEnv(),+ stderr: 'inherit',+});+const client = new Client({ name: 'loom-mcp-browse-example', version: '1.0.0' });+await client.connect(transport);++try {+ // -- 1. get_loom_feed --------------------------------------------------+ const page = await call(client, 'get_loom_feed', { limit });+ console.log(`\nget_loom_feed: ${page.count} creation(s), nextBefore=${page.nextBefore ?? 'null'}`);+ if (page.count === 0) {+ console.log(' the gallery is empty right now: forge something and submit it with submit_creation');+ }+ for (const creation of page.creations) {+ const when = new Date(Number(creation.createdAt)).toISOString().slice(0, 10);+ console.log(` - ${truncate(creation.prompt, 70)}`);+ console.log(` by ${creation.author ?? 'anon'} on ${when}${creation.backend ? ` via ${creation.backend}` : ''}`);+ }++ // A full page hands back a cursor; feed it straight back as `before` to walk+ // older items. A null cursor means you reached the end of the gallery.+ if (page.has_more) {+ const older = await call(client, 'get_loom_feed', { limit, before: page.nextBefore });+ console.log(`\nnext page (before=${page.nextBefore}): ${older.count} older creation(s)`);+ }++ // -- 2. get_creation ---------------------------------------------------+ const first = page.creations[0];+ if (!first) {+ console.log('\nget_creation: skipped, the feed returned nothing to expand');+ } else {+ const { creation } = await call(client, 'get_creation', { id: first.id });+ console.log(`\nget_creation: ${creation.id}`);+ console.log(` prompt: ${truncate(creation.prompt, 70)}`);+ console.log(` glb: ${creation.glbUrl}`);+ console.log(` viewer: ${creation.viewer_url}`);+ console.log(` card: ${creation.og_image_url}`);+ console.log(`\n paste this anywhere:\n ${creation.iframe_snippet}`);+ }++ console.log('\nEvery call was read-only. Nothing was submitted to the public gallery.');+} finally {+ await client.close();+}diff --git a/packages/loom-mcp/examples/list-tools.mjs b/packages/loom-mcp/examples/list-tools.mjsnew file mode 100644index 000000000..eae44a798--- /dev/null+++ b/packages/loom-mcp/examples/list-tools.mjs@@ -0,0 +1,103 @@+// list-tools.mjs: print every tool @three-ws/loom-mcp advertises, with its input+// schema.+//+// Spawns this package's own MCP server over stdio the way the README runs it+// (`node src/index.js`), performs the MCP initialize handshake, calls+// tools/list, and prints each tool's title, annotation hints, and parameters.+//+// node examples/list-tools.mjs+//+// Read-only: no key, no signer, no payment.++import { fileURLToPath } from 'node:url';++import { Client } from '@modelcontextprotocol/sdk/client/index.js';+import {+ StdioClientTransport,+ getDefaultEnvironment,+} from '@modelcontextprotocol/sdk/client/stdio.js';++// The README's "Run standalone" entry point. Swap for+// { command: 'npx', args: ['-y', '@three-ws/loom-mcp'] } to exercise the+// published package instead of this checkout.+const SERVER_PATH = fileURLToPath(new URL('../src/index.js', import.meta.url));++// Env this server reads (see src/config.js). getDefaultEnvironment() drops+// everything else, so an example never leaks unrelated secrets to the child.+const FORWARDED_ENV = ['THREE_WS_BASE', 'THREE_WS_TIMEOUT_MS'];++function childEnv() {+ const env = getDefaultEnvironment();+ for (const key of FORWARDED_ENV) {+ const value = process.env[key];+ if (value) env[key] = value;+ }+ return env;+}++/** One-line summary of a tool's MCP annotation hints. */+function hints(annotations) {+ if (!annotations) return 'no hints';+ const flags = [];+ if (annotations.readOnlyHint) flags.push('read-only');+ if (annotations.destructiveHint) flags.push('destructive');+ if (annotations.idempotentHint) flags.push('idempotent');+ if (annotations.openWorldHint) flags.push('open-world');+ return flags.length ? flags.join(', ') : 'no hints';+}++/** Render a JSON Schema property as one readable constraint string. */+function constraints(prop) {+ const parts = [prop.type ?? 'any'];+ if (Array.isArray(prop.enum)) parts.push(`one of ${prop.enum.join(' | ')}`);+ if (prop.default !== undefined) parts.push(`default ${JSON.stringify(prop.default)}`);+ if (prop.minimum !== undefined) parts.push(`min ${prop.minimum}`);+ if (prop.maximum !== undefined) parts.push(`max ${prop.maximum}`);+ if (prop.minLength !== undefined) parts.push(`minLength ${prop.minLength}`);+ if (prop.maxLength !== undefined) parts.push(`maxLength ${prop.maxLength}`);+ return parts.join(', ');+}++function printTool(tool, index) {+ const schema = tool.inputSchema ?? {};+ const properties = schema.properties ?? {};+ const required = new Set(schema.required ?? []);+ const names = Object.keys(properties);++ console.log(`\n${index}. ${tool.name}`);+ if (tool.title) console.log(` title: ${tool.title}`);+ console.log(` hints: ${hints(tool.annotations)}`);+ if (tool.description) console.log(` ${tool.description}`);+ if (names.length === 0) {+ console.log(' params: none');+ return;+ }+ console.log(' params:');+ for (const name of names) {+ const prop = properties[name];+ const flag = required.has(name) ? 'required' : 'optional';+ console.log(` - ${name} (${flag}; ${constraints(prop)})`);+ if (prop.description) console.log(` ${prop.description}`);+ }+}++const transport = new StdioClientTransport({+ command: process.execPath,+ args: [SERVER_PATH],+ env: childEnv(),+ stderr: 'inherit',+});+const client = new Client({ name: 'loom-mcp-list-tools-example', version: '1.0.0' });++await client.connect(transport);++const server = client.getServerVersion();+console.log(`server: ${server?.name} v${server?.version} (stdio)`);+console.log(`capabilities: ${Object.keys(client.getServerCapabilities() ?? {}).join(', ') || 'none'}`);++const { tools } = await client.listTools();+console.log(`tools: ${tools.length}`);++tools.forEach((tool, i) => printTool(tool, i + 1));++await client.close();