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
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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsnew file mode 100755index 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.mjsnew file mode 100644index 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;+ });+});