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.

fix(timeouts): bound Discord, wallet-whitelist and weather fetches; mark polling domain tools non-read-only; add install.md

nirholasfac44f040d7d
diff --git a/api/_lib/gateway/discord-activity-auth.js b/api/_lib/gateway/discord-activity-auth.js
index efd2f8320..2532ea3c5 100644
--- a/api/_lib/gateway/discord-activity-auth.js
+++ b/api/_lib/gateway/discord-activity-auth.js
@@ -40,6 +40,7 @@ export async function exchangeActivityCode(code) {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({ client_id: clientId, client_secret: clientSecret, grant_type: 'authorization_code', code }),
+ signal: AbortSignal.timeout(8000),
});
const data = await resp.json().catch(() => null);
if (!resp.ok || !data?.access_token) {
@@ -51,7 +52,7 @@ export async function exchangeActivityCode(code) {
/** Verify an access token is real by asking Discord who it belongs to. */
export async function fetchDiscordUser(accessToken) {
if (typeof accessToken !== 'string' || !accessToken) throw new DiscordActivityAuthError('bad_token', 'access_token is required', 400);
- const resp = await fetch(DISCORD_USER_URL, { headers: { Authorization: `Bearer ${accessToken}` } });
+ const resp = await fetch(DISCORD_USER_URL, { headers: { Authorization: `Bearer ${accessToken}` }, signal: AbortSignal.timeout(8000) });
const data = await resp.json().catch(() => null);
if (!resp.ok || !data?.id) {
throw new DiscordActivityAuthError('user_fetch_failed', data?.message || 'Discord rejected the access token', 502);
diff --git a/api/_mcp/tools/domains.js b/api/_mcp/tools/domains.js
index a925f7dbd..ab9eb0e3c 100644
--- a/api/_mcp/tools/domains.js
+++ b/api/_mcp/tools/domains.js
@@ -25,6 +25,8 @@ import { limits } from '../../_lib/rate-limit.js';
const READ = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
const WRITE = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true };
+// Polling tools: the call settles server-side state (registration outcome, host promotion), so it is not read-only, but repeating it changes nothing further.
+const SETTLE = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true };
const MONEY = { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true };
const CONTACT = {
@@ -228,7 +230,7 @@ export const toolDefs = [
title: 'Poll a domain registration',
group: 'domains',
scope: 'wallet:read',
- annotations: READ,
+ annotations: SETTLE,
description: 'The state of a registration you started: registering, active (with its expiry) or failed (credits refunded). Polls the registrar and settles the registration. Pass the registration id from domain_register or the domain name. Use this after domain_register to follow a registration until it is active or failed.',
inputSchema: {
type: 'object',
@@ -274,7 +276,7 @@ export const toolDefs = [
title: 'Check a connected domain',
group: 'domains',
scope: 'agents:read',
- annotations: READ,
+ annotations: SETTLE,
description: 'Whether a connected domain is live: the certificate state, the DNS nameservers in use and the URL once HTTPS is serving. Promotes the host to live when its certificate turns active. Use this after domain_connect to check when the domain is serving over HTTPS.',
inputSchema: { type: 'object', properties: { domain: { type: 'string', maxLength: 253 } }, required: ['domain'], additionalProperties: false },
async handler(args, auth) {
diff --git a/api/wallet-whitelist/index.js b/api/wallet-whitelist/index.js
index 20f217c80..d5e599b72 100644
--- a/api/wallet-whitelist/index.js
+++ b/api/wallet-whitelist/index.js
@@ -41,7 +41,7 @@ function cancelPage(token) {
<script>
const btn=document.getElementById('go'),msg=document.getElementById('msg');
btn.addEventListener('click',async()=>{btn.disabled=true;msg.textContent='Cancelling...';
-try{const r=await fetch(location.pathname,{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({action:'cancel',token:${JSON.stringify(token).replace(/</g, '\\u003c')}})});
+try{const r=await fetch(location.pathname,{signal:AbortSignal.timeout(15000),method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({action:'cancel',token:${JSON.stringify(token).replace(/</g, '\\u003c')}})});
const j=await r.json().catch(()=>({}));
if(r.ok){msg.textContent=j.already?'Already cancelled.':'Cancelled. That address cannot receive funds.';}
else{msg.textContent=j.error_description||'Could not cancel. Sign in and cancel it from the allowlist page.';btn.disabled=false;}
diff --git a/public/install.md b/public/install.md
new file mode 100644
index 000000000..aa8102334
--- /dev/null
+++ b/public/install.md
@@ -0,0 +1,129 @@
+# Install three.ws in your agent
+
+> three.ws is a set of hosted MCP servers (Streamable HTTP, JSON-RPC 2.0). Add one URL to any MCP client, or run one command to configure several clients at once.
+
+## One command
+
+Signs you in, writes the servers into every MCP client it finds, and verifies each with a live `tools/list`. Requires Node.js 20.12 or newer.
+
+```bash
+npx three-ws setup
+```
+
+One command signs you in (OAuth or API key), writes these servers into Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Codex, Gemini CLI or Hermes, prints a ready Grok Bot connector (npx three-ws setup --client grok-bot), and verifies each with a live tools/list.
+
+Full CLI reference: https://three.ws/docs/cli.md
+
+## Per client
+
+### Claude (claude.ai and Claude desktop)
+
+Server: https://three.ws/api/mcp. Auth: oauth2.1.
+Where: Customize, Connectors, Add custom connector.
+
+- name: three.ws
+- url: https://three.ws/api/mcp
+
+### Claude Code
+
+Server: https://three.ws/api/mcp. Auth: oauth2.1.
+Where: claude mcp add, or /mcp inside Claude Code.
+
+```bash
+claude mcp add --transport http three-ws-main https://three.ws/api/mcp
+```
+
+### ChatGPT
+
+Server: https://three.ws/api/mcp. Auth: oauth2.1.
+Where: Settings, Apps and Connectors, Advanced settings (turn on Developer mode), then Create.
+
+- name: three.ws
+- url: https://three.ws/api/mcp
+- authentication: OAuth
+
+### Cursor
+
+Server: https://three.ws/api/mcp. Auth: oauth2.1.
+Where: mcp.json or the Add to Cursor button on the connect page.
+
+```json
+{
+ "mcpServers": {
+ "three-ws": {
+ "url": "https://three.ws/api/mcp"
+ }
+ }
+}
+```
+
+### VS Code
+
+Server: https://three.ws/api/mcp. Auth: oauth2.1.
+Where: .vscode/mcp.json or the Add to VS Code button on the connect page.
+
+```json
+{
+ "servers": {
+ "three-ws": {
+ "type": "http",
+ "url": "https://three.ws/api/mcp"
+ }
+ }
+}
+```
+
+### Grok Bot (xAI)
+
+Server: https://three.ws/api/mcp-grok. Auth: none.
+Where: Connectors, add a custom MCP connector.
+
+- transport: streamable-http
+- url: https://three.ws/api/mcp-grok
+- authentication: none
+
+The URL must be public: Grok Bot connects from xAI's cloud, so a localhost URL never works.
+
+Add sign-in later for the account's agent, memory, skill and avatar tools; never a wallet or payment tool: https://three.ws/api/mcp-grok?auth=oauth
+
+### IBM Bob
+
+Server: https://three.ws/api/mcp-studio. Auth: none.
+Where: .bob/mcp.json in the project, or ~/.bob/settings/mcp.json for every workspace (Bob panel, MCP tab, Edit Project MCP or Edit Global MCP).
+
+```json
+{
+ "mcpServers": {
+ "three-ws": {
+ "type": "streamable-http",
+ "url": "https://three.ws/api/mcp-studio"
+ }
+ }
+}
+```
+
+Bob Shell reads the same files but names the URL key httpURL.
+
+Add sign-in later for the account's agents, memory, wallets and x402 tools, through Bob's built-in OAuth on first connect: https://three.ws/api/mcp
+
+## Hosted MCP servers
+
+| Server | Endpoint | Auth |
+|---|---|---|
+| three.ws | https://three.ws/api/mcp | OAuth 2.1 (end-user), API key (server-to-server), or x402 pay-per-call |
+| 3D Studio | https://three.ws/api/mcp-3d | OAuth 2.1 or x402 pay-per-call |
+| 3D Studio (free) | https://three.ws/api/mcp-studio | none |
+| Grok | https://three.ws/api/mcp-grok | OAuth 2.1 or a connector API key for the account's agent tools; none needed for the free 3D tools |
+| Agent wallet | https://three.ws/api/mcp-agent | OAuth 2.1 |
+| x402 Bazaar | https://three.ws/api/mcp-bazaar | OAuth 2.1 or x402 |
+| pump.fun | https://three.ws/api/pump-fun-mcp | none for the read-only tools; API key or x402 for pumpfun_upload_metadata |
+| IBM x402 | https://three.ws/api/ibm-mcp | x402 pay-per-call (authenticated three.ws principals call without per-call payment) |
+
+No account is needed for the keyless servers (3D Studio free, read-only pump.fun tools).
+
+## More
+
+- [Connect page](https://three.ws/connect): one-click install for Claude, Cursor and VS Code.
+- [MCP directory](https://three.ws/.well-known/mcp.json): every endpoint, machine-readable.
+- [MCP guide](https://three.ws/docs/mcp.md): tools, authentication and local testing.
+- [llms.txt](https://three.ws/llms.txt): curated index for AI agents.
diff --git a/src/desktop/os/apps/weather-data.js b/src/desktop/os/apps/weather-data.js
index faeba9e34..6d414cf57 100644
--- a/src/desktop/os/apps/weather-data.js
+++ b/src/desktop/os/apps/weather-data.js
@@ -63,12 +63,20 @@ export function saveUnit(u) {
ls.set('tws:weather:unit', u === 'F' ? 'F' : 'C');
}
+// Bound every request so a stalled network falls through to the cached forecast
+// instead of hanging the window; the caller's own signal still cancels first.
+const REQUEST_TIMEOUT_MS = 10_000;
+function withDeadline(signal) {
+ const deadline = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+ return signal ? AbortSignal.any([signal, deadline]) : deadline;
+}
+
/** Geocoding search. Returns [{ name, admin1, country, lat, lon, tz }]. Throws on network failure. */
export async function searchCity(query, { signal } = {}) {
const q = String(query).trim();
if (q.length < 2) return [];
const url = `https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(q)}&count=8&language=en&format=json`;
- const r = await fetch(url, { signal });
+ const r = await fetch(url, { signal: withDeadline(signal) });
if (!r.ok) throw new Error(`Search failed (HTTP ${r.status})`);
const j = await r.json();
return (j.results || []).map((x) => ({ name: x.name, admin1: x.admin1 || '', country: x.country || '', lat: x.latitude, lon: x.longitude, tz: x.timezone || '' }));
@@ -103,7 +111,7 @@ export async function fetchWeather(lat, lon, unit = 'C', { signal } = {}) {
wind_speed_unit: f ? 'mph' : 'kmh',
});
try {
- const r = await fetch(`https://api.open-meteo.com/v1/forecast?${q}`, { signal });
+ const r = await fetch(`https://api.open-meteo.com/v1/forecast?${q}`, { signal: withDeadline(signal) });
if (!r.ok) throw new Error(`Forecast failed (HTTP ${r.status})`);
const data = normalise(await r.json(), unit);
ls.set(cacheKey(lat, lon, unit), JSON.stringify(data));