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): implement the knock tools and license the brownout package

nirholasaee1eafa7b6b
diff --git a/packages/brownout/LICENSE b/packages/brownout/LICENSE
new file mode 100644
index 000000000..dff21b7f4
--- /dev/null
+++ b/packages/brownout/LICENSE
@@ -0,0 +1,20 @@
+Copyright 2026 nirholas
+
+All rights reserved.
+
+This software is proprietary and may not be used, copied, modified, distributed,
+translated, or made available to any third party without the express written
+permission of the copyright owner.
+
+No rights are granted by implication, estoppel, or otherwise. Use of this
+software is subject to the terms of a separate license agreement with the
+copyright owner.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+IN NO EVENT SHALL THE COPYRIGHT OWNER BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE,
+ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
diff --git a/packages/knock-mcp/src/config.js b/packages/knock-mcp/src/config.js
new file mode 100644
index 000000000..e1a1be9e5
--- /dev/null
+++ b/packages/knock-mcp/src/config.js
@@ -0,0 +1,13 @@
+// Environment for the knock MCP server.
+//
+// Most of this server needs no credential at all: reading a door, browsing the
+// directory, knocking on a free door and reading a receipt are public acts, and
+// requiring a key for them would defeat the point of a public door. A key is
+// needed only for the two owner-side tools (reading your own knocks and
+// replying to one).
+
+export const THREE_WS_BASE = (process.env.THREE_WS_BASE || 'https://three.ws').replace(/\/+$/, '');
+export const THREE_WS_API_KEY =
+ process.env.THREE_WS_API_KEY || process.env.THREE_WS_TOKEN || process.env.THREE_WS_BEARER || '';
+export const HTTP_TIMEOUT_MS = Number(process.env.THREE_WS_TIMEOUT_MS) || 20000;
+export const USER_AGENT = 'three-ws-knock-mcp';
diff --git a/packages/knock-mcp/src/lib/api.js b/packages/knock-mcp/src/lib/api.js
new file mode 100644
index 000000000..c022125cd
--- /dev/null
+++ b/packages/knock-mcp/src/lib/api.js
@@ -0,0 +1,73 @@
+// Live HTTP against the three.ws Knock API. No fixtures, no mocks.
+//
+// Two modes on one client. Public calls go out unauthenticated, because a door
+// is public. Owner calls attach the Bearer credential and fail early with a
+// clear config error when there is none, rather than surfacing a bare upstream
+// 401 the agent cannot act on.
+
+import { HTTP_TIMEOUT_MS, THREE_WS_API_KEY, THREE_WS_BASE, USER_AGENT } from '../config.js';
+
+export class MissingCredentialError extends Error {
+ constructor() {
+ super(
+ 'No three.ws credential configured. Set THREE_WS_API_KEY to an API key (sk_live_… / sk_test_…) ' +
+ 'or OAuth access token for the account whose door you are managing. Reading a door, browsing ' +
+ 'the directory, knocking, and reading a receipt all work without one.',
+ );
+ this.code = 'missing_credential';
+ this.status = 401;
+ }
+}
+
+export async function apiRequest(path, { method = 'GET', query, body, auth = false } = {}) {
+ if (auth && !THREE_WS_API_KEY) throw new MissingCredentialError();
+
+ const url = path.startsWith('http') ? new URL(path) : new URL(`${THREE_WS_BASE}${path}`);
+ if (query) {
+ for (const [key, value] of Object.entries(query)) {
+ if (value === undefined || value === null || value === '') continue;
+ url.searchParams.set(key, String(value));
+ }
+ }
+
+ const controller = new AbortController();
+ const timer = setTimeout(() => controller.abort(), HTTP_TIMEOUT_MS);
+ let res;
+ try {
+ res = await fetch(url, {
+ method,
+ headers: {
+ accept: 'application/json',
+ 'user-agent': USER_AGENT,
+ // Capital-B "Bearer " so the server's CSRF guard exempts the write.
+ ...(auth ? { authorization: `Bearer ${THREE_WS_API_KEY}` } : {}),
+ ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+ },
+ body: body !== undefined ? JSON.stringify(body) : undefined,
+ signal: controller.signal,
+ });
+ } catch (err) {
+ clearTimeout(timer);
+ if (err?.name === 'AbortError') {
+ throw Object.assign(new Error(`three.ws ${path} timed out after ${HTTP_TIMEOUT_MS}ms`), { code: 'timeout' });
+ }
+ throw Object.assign(new Error(`three.ws ${path} request failed: ${err?.message || err}`), { code: 'network_error' });
+ }
+ clearTimeout(timer);
+
+ const text = await res.text();
+ let data;
+ try {
+ data = text ? JSON.parse(text) : {};
+ } catch {
+ data = { raw: text };
+ }
+ if (!res.ok) {
+ throw Object.assign(new Error(data?.error_description || data?.message || `three.ws ${path} returned ${res.status}`), {
+ code: data?.error || 'upstream_error',
+ status: res.status,
+ body: data,
+ });
+ }
+ return data;
+}