Skip to content

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.

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.md
index 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.md
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.md
index 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 d
Drop 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.md
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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();