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(mcp): publish per-client setup in /.well-known/mcp.json so an agent can connect Grok Bot, Claude, ChatGPT, Cursor and VS Code from one fetch
nirholasea48329640d3
diff --git a/data/changelog.json b/data/changelog.jsonindex 80d7144e7..3962feac3 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -1,6 +1,16 @@{"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security, desktop (desktop entries become the desktop app's release notes). `link` is optional and must be a live three.ws path.","entries": [+ {+ "date": "2026-10-09",+ "title": "AI agents can now read how to connect three.ws to their client",+ "summary": "The public server directory at three.ws/.well-known/mcp.json now carries setup for each AI client: Claude, ChatGPT, Grok Bot, Cursor, VS Code and Claude Code. For each one it names the server to add, whether to pick no sign-in, OAuth or an API key, and the exact values for that client's connector form or config file, plus one-click install links where the client has them. An agent asked to connect three.ws to Grok Bot can now do it from that one file, without a person reading the setup page. The site index for AI agents (three.ws/llms.txt) points to it too.",+ "tags": [+ "feature",+ "docs"+ ],+ "link": "/docs/mcp"+ },{"date": "2026-10-08","title": "Use three.ws from Grok Bot",diff --git a/data/pages.json b/data/pages.jsonindex 2f14b9ab4..fdb1ba794 100644--- a/data/pages.json+++ b/data/pages.json@@ -6863,13 +6863,13 @@{"path": "/api/mcp","title": "MCP server",- "description": "Hosted Model Context Protocol server (Streamable HTTP): avatars, glTF validation, agent data, and memory as tools. Six more hosted servers are listed in /.well-known/mcp.json.",+ "description": "Hosted Model Context Protocol server (Streamable HTTP): avatars, glTF validation, agent data, and memory as tools. Every other hosted server, including the Grok Bot connector, is listed in /.well-known/mcp.json.","indexable": false},{"path": "/.well-known/mcp.json","title": ".well-known/mcp.json",- "description": "Directory of every hosted three.ws MCP server: endpoint, transport, auth, and what each one does.",+ "description": "Directory of every hosted three.ws MCP server (endpoint, transport, auth, what each one does) plus a clients block with setup for Claude, ChatGPT, Grok Bot, Cursor, VS Code and Claude Code: the recommended server, the auth mode and the exact connector settings or config file.","indexable": false,"added": "2026-07-31"},diff --git a/docs/mcp.md b/docs/mcp.mdindex 2a6df22b4..05d5b46b3 100644--- a/docs/mcp.md+++ b/docs/mcp.md@@ -47,7 +47,7 @@ The MCP server configuration is at `.mcp.json` in the project root, which ClaudeThis page documents the hosted avatar/3D server at `/api/mcp`, but it's one of **73 three.ws MCP servers**, all listed in the [official MCP registry](https://registry.modelcontextprotocol.io/?q=io.github.nirholas), so any MCP-compatible client can discover them by name.-The hosted servers are also self-describing: [`https://three.ws/.well-known/mcp.json`](https://three.ws/.well-known/mcp.json) is a machine-readable directory of every hosted endpoint with its transport, auth model, and a one-line description, so an agent can enumerate all of them with a single fetch.+The hosted servers are also self-describing: [`https://three.ws/.well-known/mcp.json`](https://three.ws/.well-known/mcp.json) is a machine-readable directory of every hosted endpoint with its transport, auth model, and a one-line description, so an agent can enumerate all of them with a single fetch. Its `clients` block adds per-client setup (recommended server, auth mode, exact connector settings); see [Setup an agent can read](#setup-an-agent-can-read-the-clients-block).There are two kinds. **Hosted remote servers** run over Streamable HTTP with nothing to install — add them by URL. **Install-and-run servers** are published on npm under the `@three-ws` scope and run locally over stdio — add them in one line with `npx`.@@ -299,6 +299,38 @@ This uses the standalone npm package, which handles OAuth locally. The `--url` fGrok Bot connects from xAI's cloud as a custom MCP connector: transport Streamable HTTP, server URL `https://three.ws/api/mcp-grok`, authentication None for the free studio, a connector key for your agents, or OAuth 2.1 at `https://three.ws/api/mcp-grok?auth=oauth`. The [Grok Bot connector reference](./grok-bot.md) has the exact fields for each mode, which server to pick, the result and job contracts, the limits, and a fix for every failure the connector probe reports.+### Setup an agent can read: the `clients` block++[`/.well-known/mcp.json`](https://three.ws/.well-known/mcp.json) also carries a `clients` object, so an agent that is asked to "connect three.ws to Grok Bot" (or Claude, ChatGPT, Cursor, VS Code, Claude Code) can do it from one fetch, without reading this page. `clients` is a three.ws extension; no MCP spec defines it, so a consumer should ignore client ids and fields it does not recognize, and new ones may appear. Each entry has:++| Field | Meaning |+|---|---|+| `name` | The client's display name. |+| `server` | The recommended server, always one of `servers[].endpoint` in the same file. |+| `auth` | `none`, `oauth` or `api-key`: what to pick in the client's authentication setting. |+| `settings` | The exact values for the client's own form (keyed by the form's field labels), or `file` plus `config` for a client configured by a JSON file. |+| `command` | The shell command, for a CLI client such as Claude Code. |+| `installLink` | A one-click install link with the server filled in, where the client supports one. |+| `say` | For Grok Bot: the sentence that adds the connector from chat. |+| `alternatives` | Other auth modes for the same client, each with its `auth` and what it is for: an install-token URL for scheduled tasks, a connector API key (header and value shape), or the OAuth sign-in URL. |+| `steps` | The client's own steps, in order. |+| `setup` | The human page for the same setup, `https://three.ws/connect?client=<id>`. |++```bash+curl -s https://three.ws/.well-known/mcp.json | jq '.clients["grok-bot"].settings'+```++```json+{+ "Name": "three-ws-grok",+ "Transport": "Streamable HTTP",+ "Server URL": "https://three.ws/api/mcp-grok",+ "Authentication": "None"+}+```++`tests/mcp-directory.test.js` pins the shape, checks that every Grok Bot field matches what the [/connect](/connect?client=grok) card renders, and resolves every three.ws URL in the file against the production route table, so a recommended server or setup link that stops being served fails the test suite.+### Any MCP-compatible clientSend `POST /api/mcp` with valid JSON-RPC 2.0 messages and a bearer token. The server is stateless, so no session setup is needed beyond the `initialize` handshake. `initialize` returns an `Mcp-Session-Id` header; echo it on later requests, as the MCP SDKs do, so your calls are attributed to your client in the platform's [client analytics](./ops/mcp-clients.md). It holds no state, and a request without it is served the same way.diff --git a/public/.well-known/mcp.json b/public/.well-known/mcp.jsonindex ce6f38513..ca3729c97 100644--- a/public/.well-known/mcp.json+++ b/public/.well-known/mcp.json@@ -161,5 +161,134 @@"description": "Pay-per-use IBM Granite AI.","documentation": "https://three.ws/docs/ibm-x402-mcp"}- ]+ ],+ "clients": {+ "$comment": "Per-client setup for the servers above, so an agent can connect three.ws without a human. A three.ws extension that no MCP spec defines: ignore clients and fields you do not recognize. 'server' is always one of servers[].endpoint, 'auth' is one of none, oauth or api-key, and 'settings' holds the exact values for the client's own form or config file. Human version: https://three.ws/connect",+ "claude": {+ "name": "Claude (claude.ai and Claude Desktop)",+ "server": "https://three.ws/api/mcp",+ "auth": "oauth",+ "settings": {+ "Name": "three.ws",+ "Remote MCP server URL": "https://three.ws/api/mcp"+ },+ "installLink": "https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=three.ws&connectorUrl=https%3A%2F%2Fthree.ws%2Fapi%2Fmcp",+ "steps": [+ "Open the install link, check the name and URL, then click Add. By hand: Customize, Connectors, Add custom connector, paste the URL.",+ "Click Connect and sign in to three.ws. Read the permissions before you approve.",+ "In a chat, open the + menu, then Connectors, and switch three.ws on for that conversation."+ ],+ "setup": "https://three.ws/connect?client=claude"+ },+ "chatgpt": {+ "name": "ChatGPT",+ "server": "https://three.ws/api/mcp",+ "auth": "oauth",+ "settings": {+ "Name": "three.ws",+ "MCP Server URL": "https://three.ws/api/mcp",+ "Authentication": "OAuth"+ },+ "steps": [+ "In Settings, Apps & Connectors, Advanced settings, turn on Developer mode.",+ "Back in Apps & Connectors, click Create, enter the settings and create it.",+ "Sign in to three.ws when ChatGPT asks, and approve the permissions.",+ "In a new chat, open the + menu, choose Developer mode, and tick three.ws."+ ],+ "setup": "https://three.ws/connect?client=chatgpt"+ },+ "grok-bot": {+ "name": "Grok Bot",+ "server": "https://three.ws/api/mcp-grok",+ "auth": "none",+ "settings": {+ "Name": "three-ws-grok",+ "Transport": "Streamable HTTP",+ "Server URL": "https://three.ws/api/mcp-grok",+ "Authentication": "None"+ },+ "say": "Add a custom MCP server called three-ws-grok at https://three.ws/api/mcp-grok",+ "alternatives": [+ {+ "auth": "none",+ "use": "A free quota of its own that survives reconnects, for scheduled tasks: POST the install endpoint and connect the connector_urls.grok value it returns.",+ "install": "https://three.ws/api/mcp-studio/install"+ },+ {+ "auth": "api-key",+ "use": "The account's agents, memory and skills. Make a key for an AI agent at the keys page and store it as a Bot secret. A connector key never spends.",+ "keys": "https://three.ws/dashboard/api",+ "header": "Authorization",+ "value": "Bearer <three.ws API key>"+ },+ {+ "auth": "oauth",+ "use": "The account's agents, memory and skills, signed in once in the browser.",+ "url": "https://three.ws/api/mcp-grok?auth=oauth"+ }+ ],+ "steps": [+ "In Grok Bot, open Connectors and add a custom MCP server with the settings above, or send Grok Bot the say sentence and confirm what it shows.",+ "Check the name and URL Grok Bot shows, then confirm.",+ "Ask for 3D in any task, or attach the server with @ and its name."+ ],+ "notes": "Grok Bot connects from xAI's cloud, so only a public URL works; never localhost.",+ "setup": "https://three.ws/connect?client=grok",+ "documentation": "https://three.ws/docs/grok-bot"+ },+ "cursor": {+ "name": "Cursor",+ "server": "https://three.ws/api/mcp",+ "auth": "oauth",+ "settings": {+ "file": "~/.cursor/mcp.json",+ "config": {+ "mcpServers": {+ "three-ws-main": {+ "url": "https://three.ws/api/mcp"+ }+ }+ }+ },+ "installLink": "cursor://anysphere.cursor-deeplink/mcp/install?name=three-ws-main&config=eyJ1cmwiOiJodHRwczovL3RocmVlLndzL2FwaS9tY3AifQ%3D%3D",+ "steps": [+ "Open the install link, or add the config to the file.",+ "Cursor runs the three.ws sign-in on first use."+ ],+ "setup": "https://three.ws/connect?client=cursor"+ },+ "vscode": {+ "name": "VS Code (GitHub Copilot agent mode)",+ "server": "https://three.ws/api/mcp",+ "auth": "oauth",+ "settings": {+ "file": ".vscode/mcp.json",+ "config": {+ "servers": {+ "three-ws-main": {+ "type": "http",+ "url": "https://three.ws/api/mcp"+ }+ }+ }+ },+ "installLink": "vscode:mcp/install?%7B%22name%22%3A%22three-ws-main%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fthree.ws%2Fapi%2Fmcp%22%7D",+ "steps": [+ "Open the install link, or add the config to the file.",+ "The server signs you in on first use."+ ],+ "setup": "https://three.ws/connect?client=vscode"+ },+ "claude-code": {+ "name": "Claude Code",+ "server": "https://three.ws/api/mcp",+ "auth": "oauth",+ "command": "claude mcp add --transport http three-ws-main https://three.ws/api/mcp",+ "steps": [+ "Run the command.",+ "In Claude Code, type /mcp, pick three-ws-main and choose Authenticate."+ ],+ "setup": "https://three.ws/connect?client=claude-code"+ }+ }}diff --git a/public/features.json b/public/features.jsonindex bc7f1108f..af0b832e6 100644--- a/public/features.json+++ b/public/features.json@@ -56,6 +56,7 @@"title": "Developers","paths": ["/connect",+ "/grok","/mcp-tools","/docs/start-here","/docs/mcp",@@ -5038,6 +5039,26 @@"tags": [],"showcase": false},+ {+ "path": "/docs/grok",+ "title": "Docs · three.ws for Grok",+ "description": "Connect Grok Bot, Grok connectors and the xAI API to one free remote MCP server that turns text or an image into a textured 3D model, a rigged avatar, or a named 3D persona that lip-syncs its replies. No account, payment or API key.",+ "added": "2026-10-08",+ "auth": null,+ "indexable": true,+ "tags": [],+ "showcase": false+ },+ {+ "path": "/docs/grok-bot",+ "title": "Docs · Grok Bot connector reference",+ "description": "Connect Grok Bot to three.ws as a custom MCP connector: exact fields for each sign-in mode, which server to pick, the links every result carries, jobs and safe retries, free limits and install tokens, why a connector key can never spend, guided prompts, and a fix for every connection failure.",+ "added": "2026-10-09",+ "auth": null,+ "indexable": true,+ "tags": [],+ "showcase": false+ },{"path": "/docs/prompts","title": "Docs · The prompt library",@@ -7360,8 +7381,8 @@},{"path": "/connect",- "title": "Connect three.ws to Claude, ChatGPT, Cursor & VS Code",- "description": "Add three.ws to your AI client in two clicks: one connector URL gives Claude, ChatGPT, Cursor, VS Code or Claude Code the three.ws MCP tools for 3D generation, agents, wallets and x402 payments. Sign in once in your browser, with no API key to copy.",+ "title": "Connect three.ws to Claude, ChatGPT, Grok Bot, Cursor & VS Code",+ "description": "Add three.ws to your AI client in two clicks: one connector URL gives Claude, ChatGPT, Grok Bot, Cursor, VS Code or Claude Code the three.ws MCP tools for 3D generation, agents, wallets and x402 payments. Sign in once in your browser, with no API key to copy.","added": "2026-09-29","auth": null,"indexable": true,@@ -7388,6 +7409,16 @@"tags": [],"showcase": false},+ {+ "path": "/grok",+ "title": "three.ws for Grok Bot: a free 3D studio and a body for Grok",+ "description": "Everything Grok Bot can do with three.ws on one page: generate textured 3D models, rig avatars, find ready-made CC0 assets and run your agents through one custom MCP connector. Real models made minutes ago, the exact connector settings, three recipes to schedule and the Grok skill file. Free, no account, no key.",+ "added": "2026-10-09",+ "auth": null,+ "indexable": true,+ "tags": [],+ "showcase": false+ },{"path": "/docs/experiments","title": "Docs · How we run and publish experiments",@@ -8719,6 +8750,16 @@"tags": [],"showcase": false},+ {+ "path": "/grok-skill.md",+ "title": "grok-skill.md",+ "description": "The three.ws skill for Grok and Grok Bot: the connector that adds a free 3D studio, runnable curl calls for a Grok with no connector, the links every model comes back with, what needs an account, and the rule that it never spends. Upload it to Grok's Skills.",+ "added": "2026-10-08",+ "auth": null,+ "indexable": false,+ "tags": [],+ "showcase": false+ },{"path": "/.well-known/x402","title": ".well-known/x402",@@ -8762,7 +8803,7 @@{"path": "/api/mcp","title": "MCP server",- "description": "Hosted Model Context Protocol server (Streamable HTTP): avatars, glTF validation, agent data, and memory as tools. Six more hosted servers are listed in /.well-known/mcp.json.",+ "description": "Hosted Model Context Protocol server (Streamable HTTP): avatars, glTF validation, agent data, and memory as tools. Every other hosted server, including the Grok Bot connector, is listed in /.well-known/mcp.json.","added": null,"auth": null,"indexable": false,@@ -8772,7 +8813,7 @@{"path": "/.well-known/mcp.json","title": ".well-known/mcp.json",- "description": "Directory of every hosted three.ws MCP server: endpoint, transport, auth, and what each one does.",+ "description": "Directory of every hosted three.ws MCP server (endpoint, transport, auth, what each one does) plus a clients block with setup for Claude, ChatGPT, Grok Bot, Cursor, VS Code and Claude Code: the recommended server, the auth mode and the exact connector settings or config file.","added": "2026-07-31","auth": null,"indexable": false,diff --git a/public/llms-full.txt b/public/llms-full.txtindex 5c001e095..07a74af69 100644--- a/public/llms-full.txt+++ b/public/llms-full.txt@@ -3029,6 +3029,18 @@ URL: https://three.ws/docs/vscodeThe VS Code extension that renders .glb and .gltf files in an editor tab, reports on them, generates and rigs new models on the free lane, and writes a pinned <agent-3d> embed.+### Docs · three.ws for Grok++URL: https://three.ws/docs/grok++Connect Grok Bot, Grok connectors and the xAI API to one free remote MCP server that turns text or an image into a textured 3D model, a rigged avatar, or a named 3D persona that lip-syncs its replies. No account, payment or API key.++### Docs · Grok Bot connector reference++URL: https://three.ws/docs/grok-bot++Connect Grok Bot to three.ws as a custom MCP connector: exact fields for each sign-in mode, which server to pick, the links every result carries, jobs and safe retries, free limits and install tokens, why a connector key can never spend, guided prompts, and a fix for every connection failure.+### Docs · The prompt libraryURL: https://three.ws/docs/prompts@@ -4421,11 +4433,17 @@ URL: https://three.ws/docs/mcp-safetyWhat an MCP tool's safety annotations mean on three.ws and why you can trust them: read-only tools never change what you asked about, anything that spends is labelled as spending, and a build check verifies every hint against the tool's own code before it can ship.-### Connect three.ws to Claude, ChatGPT, Cursor & VS Code+### Connect three.ws to Claude, ChatGPT, Grok Bot, Cursor & VS CodeURL: https://three.ws/connect-Add three.ws to your AI client in two clicks: one connector URL gives Claude, ChatGPT, Cursor, VS Code or Claude Code the three.ws MCP tools for 3D generation, agents, wallets and x402 payments. Sign in once in your browser, with no API key to copy.+Add three.ws to your AI client in two clicks: one connector URL gives Claude, ChatGPT, Grok Bot, Cursor, VS Code or Claude Code the three.ws MCP tools for 3D generation, agents, wallets and x402 payments. Sign in once in your browser, with no API key to copy.++### three.ws for Grok Bot: a free 3D studio and a body for Grok++URL: https://three.ws/grok++Everything Grok Bot can do with three.ws on one page: generate textured 3D models, rig avatars, find ready-made CC0 assets and run your agents through one custom MCP connector. Real models made minutes ago, the exact connector settings, three recipes to schedule and the Grok skill file. Free, no account, no key.### MCP Tool Catalog@@ -5242,6 +5260,13 @@ Crawler directives.URL: https://three.ws/openapi.jsonIndexable: no (excluded from sitemap)+### grok-skill.md++URL: https://three.ws/grok-skill.md+Indexable: no (excluded from sitemap)++The three.ws skill for Grok and Grok Bot: the connector that adds a free 3D studio, runnable curl calls for a Grok with no connector, the links every model comes back with, what needs an account, and the rule that it never spends. Upload it to Grok's Skills.+Machine-readable HTTP API spec.### .well-known/x402@@ -5277,14 +5302,14 @@ ChatGPT-style plugin manifest.URL: https://three.ws/api/mcpIndexable: no (excluded from sitemap)-Hosted Model Context Protocol server (Streamable HTTP): avatars, glTF validation, agent data, and memory as tools. Six more hosted servers are listed in /.well-known/mcp.json.+Hosted Model Context Protocol server (Streamable HTTP): avatars, glTF validation, agent data, and memory as tools. Every other hosted server, including the Grok Bot connector, is listed in /.well-known/mcp.json.### .well-known/mcp.jsonURL: https://three.ws/.well-known/mcp.jsonIndexable: no (excluded from sitemap)-Directory of every hosted three.ws MCP server: endpoint, transport, auth, and what each one does.+Directory of every hosted three.ws MCP server (endpoint, transport, auth, what each one does) plus a clients block with setup for Claude, ChatGPT, Grok Bot, Cursor, VS Code and Claude Code: the recommended server, the auth mode and the exact connector settings or config file.### .well-known/agent-card.jsondiff --git a/public/llms.txt b/public/llms.txtindex 948aa20c7..dbdad12f3 100644--- a/public/llms.txt+++ b/public/llms.txt@@ -38,8 +38,8 @@ Machine-readable entry points. Fetch these instead of scraping HTML.- [.well-known/agent-attestation-schemas](https://three.ws/.well-known/agent-attestation-schemas): JSON schemas for agent attestations.- [.well-known/oauth-authorization-server](https://three.ws/.well-known/oauth-authorization-server): OAuth 2.1 authorization-server metadata.- [.well-known/chat-plugin.json](https://three.ws/.well-known/chat-plugin.json): ChatGPT-style plugin manifest.-- [MCP server](https://three.ws/api/mcp): Hosted Model Context Protocol server (Streamable HTTP): avatars, glTF validation, agent data, and memory as tools. Six more hosted servers are listed in /.well-known/mcp.json.-- [.well-known/mcp.json](https://three.ws/.well-known/mcp.json): Directory of every hosted three.ws MCP server: endpoint, transport, auth, and what each one does.+- [MCP server](https://three.ws/api/mcp): Hosted Model Context Protocol server (Streamable HTTP): avatars, glTF validation, agent data, and memory as tools. Every other hosted server, including the Grok Bot connector, is listed in /.well-known/mcp.json.+- [.well-known/mcp.json](https://three.ws/.well-known/mcp.json): Directory of every hosted three.ws MCP server (endpoint, transport, auth, what each one does) plus a clients block with setup for Claude, ChatGPT, Grok Bot, Cursor, VS Code and Claude Code: the recommended server, the auth mode and the exact connector settings or config file.- [.well-known/agent-card.json](https://three.ws/.well-known/agent-card.json): A2A agent card: what three.ws is, what it can do, and where the paid-service catalog lives.- [.well-known/x402.json](https://three.ws/.well-known/x402.json): x402 service catalog: every paid pay-per-call endpoint with price, network, and input schema.@@ -98,6 +98,6 @@ Machine-readable entry points. Fetch these instead of scraping HTML.## Optional-- [llms-full.txt](https://three.ws/llms-full.txt): Every public page (929), grouped by section, with full descriptions.+- [llms-full.txt](https://three.ws/llms-full.txt): Every public page (930), grouped by section, with full descriptions.- [Sitemap](https://three.ws/sitemap): The same index for people, with search.- [sitemap.xml](https://three.ws/sitemap.xml): XML sitemap for crawlers, including every agent and avatar page.diff --git a/tests/mcp-directory.test.js b/tests/mcp-directory.test.jsnew file mode 100644index 000000000..da5af90b8--- /dev/null+++ b/tests/mcp-directory.test.js@@ -0,0 +1,139 @@+// The public MCP directory at /.well-known/mcp.json is what an agent fetches to+// learn which three.ws servers exist and, through its `clients` block, how to+// connect each AI client to them without a human. This pins its shape and+// checks that every three.ws URL it names is actually served, resolved with the+// production resolver (server/route-resolve.mjs) over vercel.json, so a renamed+// handler or a dropped route fails here instead of in an agent's setup run.+import { describe, it, expect } from 'vitest';+import fs from 'node:fs';+import path from 'node:path';++import { loadRouteTable, resolvePhase1, resolveApiHandler } from '../server/route-resolve.mjs';+import { slugForEndpoint, grokAuthFor } from '../src/grok-connector.js';++const ROOT = path.resolve(import.meta.dirname, '..');+const SITE = 'https://three.ws';+const directory = JSON.parse(fs.readFileSync(path.join(ROOT, 'public/.well-known/mcp.json'), 'utf8'));+const { phase1Routes } = loadRouteTable(path.join(ROOT, 'vercel.json'));+const API_ROOT = path.join(ROOT, 'api');+const pages = JSON.parse(fs.readFileSync(path.join(ROOT, 'data/pages.json'), 'utf8'));+const pagePaths = new Set(pages.sections.flatMap((s) => s.pages.map((p) => p.path)));++const CLIENTS = ['claude', 'chatgpt', 'cursor', 'vscode', 'grok-bot'];+const AUTH_MODES = new Set(['none', 'oauth', 'api-key']);+const endpoints = new Set(directory.servers.map((s) => s.endpoint));++// After the phase-1 rewrites, the filesystem phase serves a page or a public/+// file. These are the source locations each of those comes from.+function staticServed(pathname) {+ const rel = decodeURIComponent(pathname).replace(/^\/+|\/+$/g, '');+ if (pagePaths.has(`/${rel}`)) return true;+ return [`public/${rel}`, `pages/${rel}`, rel].some((c) => {+ const full = path.join(ROOT, c);+ return fs.existsSync(full) && fs.statSync(full).isFile();+ });+}++/** Does production answer this three.ws URL with a handler, page or file? */+function served(raw) {+ const url = new URL(raw);+ const r = resolvePhase1(phase1Routes, { headers: {}, method: 'GET' }, url);+ if (r.terminal === 'status') return r.status < 400;+ if (r.terminal === 'external') return true;+ if (r.status && r.status >= 400) return false;+ if (r.path.startsWith('/api/')) return Boolean(resolveApiHandler(API_ROOT, r.path));+ if (!staticServed(r.path)) return false;+ // /docs/<slug> is one shell page that fetches the doc; without the doc it 404s.+ const doc = url.pathname.match(/^\/docs\/([a-z0-9-]+)\/?$/);+ return doc ? fs.existsSync(path.join(ROOT, 'docs', `${doc[1]}.md`)) : true;+}++/** Every https://three.ws URL anywhere in a JSON value. */+function siteUrls(value, out = new Set()) {+ if (typeof value === 'string') {+ for (const m of value.matchAll(/https:\/\/three\.ws[^\s"',)]*/g)) out.add(m[0].replace(/[.;:]+$/, ''));+ } else if (value && typeof value === 'object') {+ for (const v of Object.values(value)) siteUrls(v, out);+ }+ return out;+}++describe('/.well-known/mcp.json shape', () => {+ it('carries the top-level directory fields', () => {+ for (const key of ['name', 'description', 'website', 'documentation', 'setup', 'llms', 'servers', 'clients']) {+ expect(directory, key).toHaveProperty(key);+ }+ expect(directory.website).toBe(SITE);+ expect(Array.isArray(directory.servers) && directory.servers.length > 0).toBe(true);+ });++ it('describes every server with the fields clients read', () => {+ for (const s of directory.servers) {+ for (const field of ['name', 'endpoint', 'transport', 'auth', 'description', 'documentation']) {+ expect(typeof s[field], `${s.name}.${field}`).toBe('string');+ }+ expect(s.endpoint.startsWith(`${SITE}/`), s.endpoint).toBe(true);+ expect(s.transport, s.name).toBe('streamable-http');+ if (s.signIn) expect(s.signIn.startsWith(s.endpoint), s.name).toBe(true);+ }+ expect(endpoints.size, 'an endpoint is listed twice').toBe(directory.servers.length);+ });++ it('gives setup for every supported client', () => {+ expect(typeof directory.clients.$comment).toBe('string');+ for (const id of CLIENTS) expect(directory.clients, id).toHaveProperty(id);+ });++ for (const [id, client] of Object.entries(directory.clients).filter(([k]) => !k.startsWith('$'))) {+ describe(`client ${id}`, () => {+ it('names a listed server, a known auth mode, steps and a setup page', () => {+ expect(typeof client.name).toBe('string');+ expect(endpoints.has(client.server), client.server).toBe(true);+ expect(AUTH_MODES.has(client.auth), client.auth).toBe(true);+ expect(client.settings || client.command, 'settings or command').toBeTruthy();+ expect(Array.isArray(client.steps) && client.steps.length > 0).toBe(true);+ expect(client.setup).toMatch(/^https:\/\/three\.ws\/connect\?client=[a-z-]+$/);+ for (const alt of client.alternatives ?? []) expect(AUTH_MODES.has(alt.auth), alt.auth).toBe(true);+ });++ it('puts the recommended server in its settings and install link', () => {+ const text = JSON.stringify({ settings: client.settings, command: client.command });+ expect(text.includes(client.server), 'settings name the server').toBe(true);+ if (!client.installLink) return;+ const link = client.installLink;+ if (link.startsWith('cursor://')) {+ const config = new URL(link).searchParams.get('config');+ expect(JSON.parse(Buffer.from(config, 'base64').toString()).url).toBe(client.server);+ } else if (link.startsWith('vscode:')) {+ expect(JSON.parse(decodeURIComponent(link.slice(link.indexOf('?') + 1))).url).toBe(client.server);+ } else {+ expect(decodeURIComponent(link).includes(client.server), link).toBe(true);+ }+ });+ });+ }++ it('gives Grok Bot the exact connector form the /connect card shows', () => {+ const grok = directory.clients['grok-bot'];+ const server = directory.servers.find((s) => s.endpoint === grok.server);+ expect(grok.settings.Name).toBe(slugForEndpoint(grok.server));+ expect(grok.settings['Server URL']).toBe(grok.server);+ expect(grok.settings.Transport).toBe('Streamable HTTP');+ expect(grok.auth).toBe(grokAuthFor(server));+ expect(grok.say).toContain(grok.server);+ const oauth = grok.alternatives.find((a) => a.auth === 'oauth');+ expect(oauth.url).toBe(server.signIn);+ });+});++describe('/.well-known/mcp.json routing', () => {+ const urls = [...siteUrls(directory)];++ it('names three.ws URLs to check', () => {+ expect(urls.length).toBeGreaterThan(directory.servers.length);+ });++ it.each(urls)('%s is served', (url) => {+ expect(served(url)).toBe(true);+ });+});