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.

feat(knock-mcp): declare the server manifest and wire its entry point

nirholasa7566e388235
diff --git a/packages/knock-mcp/package.json b/packages/knock-mcp/package.json
new file mode 100644
index 000000000..119a21ef1
--- /dev/null
+++ b/packages/knock-mcp/package.json
@@ -0,0 +1,56 @@
+{
+ "name": "@three-ws/knock-mcp",
+ "version": "0.1.0",
+ "mcpName": "io.github.nirholas/knock-mcp",
+ "description": "Let an agent reach a real person. Read what someone charges for one message, browse every open door, knock, and read the reply. Paid doors are quoted, never auto-paid: this server holds no wallet.",
+ "type": "module",
+ "author": "nirholas <[email protected]>",
+ "license": "Apache-2.0",
+ "homepage": "https://three.ws/knock",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/nirholas/three.ws.git",
+ "directory": "packages/knock-mcp"
+ },
+ "bugs": {
+ "url": "https://github.com/nirholas/three.ws/issues"
+ },
+ "keywords": [
+ "mcp",
+ "three.ws",
+ "knock",
+ "x402",
+ "agent-to-human",
+ "attention",
+ "usdc",
+ "solana"
+ ],
+ "publishConfig": {
+ "access": "public"
+ },
+ "files": [
+ "src",
+ "server.json",
+ "README.md",
+ "LICENSE"
+ ],
+ "bin": {
+ "knock-mcp": "src/index.js"
+ },
+ "main": "./src/index.js",
+ "exports": {
+ ".": "./src/index.js"
+ },
+ "engines": {
+ "node": ">=20"
+ },
+ "scripts": {
+ "start": "node src/index.js",
+ "test": "node --test \"test/**/*.test.mjs\"",
+ "inspect": "npx -y @modelcontextprotocol/inspector node src/index.js"
+ },
+ "dependencies": {
+ "@modelcontextprotocol/sdk": "^1.29.0",
+ "zod": "^3.23.8"
+ }
+}
diff --git a/packages/knock-mcp/server.json b/packages/knock-mcp/server.json
new file mode 100644
index 000000000..e71b53604
--- /dev/null
+++ b/packages/knock-mcp/server.json
@@ -0,0 +1,56 @@
+{
+ "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+ "name": "io.github.nirholas/knock-mcp",
+ "title": "three.ws Knock",
+ "description": "Reach a real person: quote their door, browse who is reachable, knock, and read the reply.",
+ "websiteUrl": "https://three.ws/knock",
+ "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": "packages/knock-mcp"
+ },
+ "version": "0.1.0",
+ "packages": [
+ {
+ "registryType": "npm",
+ "identifier": "@three-ws/knock-mcp",
+ "version": "0.1.0",
+ "runtimeHint": "npx",
+ "transport": {
+ "type": "stdio"
+ },
+ "environmentVariables": [
+ {
+ "name": "THREE_WS_API_KEY",
+ "description": "A three.ws API key (sk_live_… / sk_test_…) or OAuth access token. Optional: needed only for knock_inbox and knock_act, which manage your own door. Quoting, browsing, knocking and reading a receipt all work without it. Treat like a password.",
+ "format": "string",
+ "isRequired": false,
+ "isSecret": true
+ },
+ {
+ "name": "THREE_WS_BASE",
+ "description": "Base URL of the three.ws API. Override only when self-hosting or targeting a preview deployment.",
+ "format": "string",
+ "isRequired": false,
+ "default": "https://three.ws"
+ },
+ {
+ "name": "THREE_WS_TIMEOUT_MS",
+ "description": "Per-request timeout in milliseconds.",
+ "format": "number",
+ "isRequired": false,
+ "default": "20000"
+ }
+ ]
+ }
+ ]
+}
diff --git a/packages/knock-mcp/src/index.js b/packages/knock-mcp/src/index.js
new file mode 100755
index 000000000..42b452008
--- /dev/null
+++ b/packages/knock-mcp/src/index.js
@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+// @three-ws/knock-mcp: let an agent reach a real person.
+//
+// Knock is a priced door to a human. Every three.ws account can publish one at
+// three.ws/knock/<handle>; paying its price buys exactly one message through,
+// and that message is delivered in person: the recipient's 3D companion walks
+// on screen wherever they are on the site and says who is at the door and what
+// they paid. The USDC settles directly to the recipient.
+//
+// Tools:
+// knock_quote what it costs to reach one person (public)
+// knock_directory everyone reachable right now, cheapest first (public)
+// knock_send get one message through (free doors send, priced doors quote)
+// knock_receipt what became of a knock you sent (public, receipt-scoped)
+// knock_inbox the knocks YOUR door has taken (needs THREE_WS_API_KEY)
+// knock_act reply to, dismiss, or block one of them (needs THREE_WS_API_KEY)
+//
+// THIS SERVER HOLDS NO WALLET AND CANNOT SPEND. On a priced door, knock_send
+// returns the recipient, the amount, the token and the chain and stops, so the
+// decision to pay stays with the human and the payment happens in the wallet
+// they already control. That is deliberate, not a missing feature.
+//
+// Run standalone:
+// node packages/knock-mcp/src/index.js
+//
+// Or wire into Claude Code / Cursor. See README.md.
+
+import { realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+import { def as quote } from './tools/quote.js';
+import { def as directory } from './tools/directory.js';
+import { def as send } from './tools/send.js';
+import { def as receipt } from './tools/receipt.js';
+import { def as inbox } from './tools/inbox.js';
+import { def as act } from './tools/act.js';
+
+const require = createRequire(import.meta.url);
+const { version: PKG_VERSION } = require('../package.json');
+
+export const TOOLS = [quote, directory, send, receipt, inbox, act];
+
+/**
+ * Build the fully-registered server without connecting a transport.
+ * Registration is env-free, so tests can import this without a credential.
+ * @returns {McpServer}
+ */
+export function buildServer() {
+ const server = new McpServer(
+ { name: 'knock-mcp', title: 'three.ws Knock', version: PKG_VERSION },
+ {
+ capabilities: { tools: {} },
+ instructions:
+ 'three.ws Knock MCP: a priced door to a real person. knock_quote reads what one person charges ' +
+ 'for a single message and which chains they take it on; knock_directory lists everyone ' +
+ 'reachable, cheapest first. knock_send gets one message through, which lands in their inbox ' +
+ 'AND is delivered out loud by their 3D companion, naming the sender and the amount. This ' +
+ 'server holds no wallet: a free door sends immediately, and a priced door returns the ' +
+ 'recipient, amount, token and chain so a HUMAN can approve the spend and pay from their own ' +
+ 'x402 client (npx @three-ws/knock). Never present a paid knock as sent until a payment ' +
+ 'settled. knock_receipt reads what became of a knock using the receipt URL it returned, with ' +
+ 'no account. knock_inbox and knock_act manage your OWN door and need THREE_WS_API_KEY; they ' +
+ 'are account-scoped server-side and can never touch another account. $THREE is the only coin.',
+ },
+ );
+
+ for (const tool of TOOLS) {
+ server.registerTool(
+ tool.name,
+ {
+ title: tool.title,
+ description: tool.description,
+ inputSchema: tool.inputSchema,
+ annotations: tool.annotations,
+ },
+ async (args, extra) => {
+ try {
+ const result = await tool.handler(args, extra);
+ const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+ return { content: [{ type: 'text', text }], isError: result?.ok === false };
+ } catch (err) {
+ const payload = {
+ ok: false,
+ error: err?.code || 'unhandled',
+ message: err?.message || String(err),
+ ...(err?.status ? { status: err.status } : {}),
+ ...(err?.body ? { detail: err.body } : {}),
+ };
+ return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
+ }
+ },
+ );
+ }
+
+ return server;
+}
+
+async function main() {
+ const server = buildServer();
+ await server.connect(new StdioServerTransport());
+ console.error(`[knock-mcp@${PKG_VERSION}] connected over stdio with ${TOOLS.length} tools`);
+}
+
+// Connect stdio ONLY when this file is the process entry point, so importing
+// the module (tests, embedding) never grabs the transport. realpath both sides:
+// npm bin shims are symlinks, so argv[1] may differ from import.meta.url.
+function isProcessEntryPoint() {
+ if (!process.argv[1]) return false;
+ try {
+ return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+ } catch {
+ return false;
+ }
+}
+
+if (isProcessEntryPoint()) {
+ main().catch((err) => {
+ console.error('[knock-mcp] fatal:', err);
+ process.exit(1);
+ });
+}
diff --git a/packages/knock-mcp/test/server.test.mjs b/packages/knock-mcp/test/server.test.mjs
new file mode 100644
index 000000000..a0860dd72
--- /dev/null
+++ b/packages/knock-mcp/test/server.test.mjs
@@ -0,0 +1,92 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { TOOLS, buildServer } from '../src/index.js';
+
+test('every advertised tool is complete', () => {
+ assert.equal(TOOLS.length, 6);
+ for (const tool of TOOLS) {
+ assert.match(tool.name, /^knock_[a-z_]+$/, `${tool.name} follows the knock_ prefix`);
+ assert.ok(tool.title, `${tool.name} has a title`);
+ assert.ok(tool.description.length > 120, `${tool.name} explains itself`);
+ assert.ok(tool.annotations, `${tool.name} carries MCP annotations`);
+ assert.equal(typeof tool.handler, 'function');
+ }
+});
+
+test('the public tools are marked read-only so clients do not gate them', () => {
+ for (const name of ['knock_quote', 'knock_directory', 'knock_receipt', 'knock_inbox']) {
+ const tool = TOOLS.find((t) => t.name === name);
+ assert.equal(tool.annotations.readOnlyHint, true, `${name} is read-only`);
+ }
+});
+
+test('the writing tools are not read-only and not destructive', () => {
+ for (const name of ['knock_send', 'knock_act']) {
+ const tool = TOOLS.find((t) => t.name === name);
+ assert.equal(tool.annotations.readOnlyHint, false);
+ assert.equal(tool.annotations.destructiveHint, false);
+ }
+});
+
+test('buildServer registers without a credential', () => {
+ const server = buildServer();
+ assert.ok(server, 'the tool surface is advertised with no key configured');
+});
+
+test('a priced door is quoted, never paid, by knock_send', async () => {
+ const send = TOOLS.find((t) => t.name === 'knock_send');
+ const realFetch = globalThis.fetch;
+ let posts = 0;
+ globalThis.fetch = async (url, init = {}) => {
+ if (init.method === 'POST') posts += 1;
+ return new Response(
+ JSON.stringify({
+ door: {
+ handle: 'ada', display_name: 'Ada', free: false, price: '$0.05', price_atomics: '50000',
+ currency: 'USDC', networks: ['solana'], max_chars: 600,
+ endpoint: 'https://three.ws/api/x402/knock?to=ada', protocol: 'x402',
+ },
+ }),
+ { status: 200, headers: { 'content-type': 'application/json' } },
+ );
+ };
+ try {
+ const out = await send.handler({ to: 'ada', from: 'Bob', message: 'a real message here' });
+ assert.equal(out.ok, false);
+ assert.equal(out.error, 'payment_required');
+ assert.equal(out.confirm.amount, '$0.05');
+ assert.deepEqual(out.confirm.chains, ['solana']);
+ assert.match(out.confirm.settles_to, /recipient directly/);
+ assert.equal(posts, 0, 'a priced door must not be posted to by this server');
+ } finally {
+ globalThis.fetch = realFetch;
+ }
+});
+
+test('a free door is sent immediately', async () => {
+ const send = TOOLS.find((t) => t.name === 'knock_send');
+ const realFetch = globalThis.fetch;
+ globalThis.fetch = async (url, init = {}) => {
+ const body = init.method === 'POST'
+ ? { ok: true, knock_id: 'k1', delivered_to: 'Ada', duplicate: false, paid: '$0.00', receipt_url: 'https://three.ws/api/knock/reply?id=k1&token=t' }
+ : { door: { handle: 'ada', display_name: 'Ada', free: true, price: '$0.00', price_atomics: '0', currency: 'USDC', networks: [], max_chars: 600, endpoint: 'https://three.ws/api/knock/send', protocol: 'http' } };
+ return new Response(JSON.stringify(body), { status: 200, headers: { 'content-type': 'application/json' } });
+ };
+ try {
+ const out = await send.handler({ to: '@ada', from: 'Bob', message: 'a real message here', subject: 'hi' });
+ assert.equal(out.ok, true);
+ assert.equal(out.knock_id, 'k1');
+ assert.match(out.receipt_url, /token=/);
+ } finally {
+ globalThis.fetch = realFetch;
+ }
+});
+
+test('the owner tools refuse clearly with no credential', async () => {
+ const inbox = TOOLS.find((t) => t.name === 'knock_inbox');
+ await assert.rejects(() => inbox.handler({}), (err) => {
+ assert.equal(err.code, 'missing_credential');
+ assert.match(err.message, /THREE_WS_API_KEY/);
+ return true;
+ });
+});