@homie-rocks/studio 0.38.0 → 0.39.0

package/CHANGELOG.md

@@ -17,6 +17,35 @@ To bring a studio up to date, tell Claude: "Upgrade my studio to the newest Homi
 `npx -y @homie-rocks/studio@latest upgrade`, which shows what's new since the version your studio pins (from this
 file) and what the upgrade would change, and changes nothing until you agree.
 
+## [0.39.0] - 2026-10-09
+
+**Plugin 0.39.0** · [#78](https://github.com/homie-rocks/homie/pull/78)
+
+Your studio has its own MCP server. Connect your AI with one browser approval and add tools for the work your studio does.
+
+### Added
+
+- Connect Claude, ChatGPT or Grok to your studio's own `/mcp` address. Use your existing studio account; there is no key to find or copy. Client setup and workspace policies still apply.
+- Let your AI use the office, app records, shared parts and marked guide seats in rooms. Staff keep their own app permissions. Destructive office controls still wait for your confirmation.
+- Add a typed tool with `homie-studio tool new`, test it with `tool call` and share its code as a part. Tools can also supply prompts and signed inbound integrations; readable app records are resources.
+- Review AI connections and recent tool calls in the office. Revoke a connection there. Role checks, validated input and configurable call limits apply on the server.
+
+### Changed
+
+- Worker builds keep MCP libraries in separate modules, loaded when that surface is used. Ordinary page traffic performs no MCP storage work.
+
+### Fixed
+
+- Browser input checks wait for the final touch movement to reach the game before measuring its response, including when Chrome delays delivery. Successful browser calls clear their timeout timers.
+
+- Clean installs on Node 24 include the MCP SDK required by the payment library, so purchase tools and selling builds work alongside the studio MCP server.
+- MCP integration tests close clients after failures as well as successes. The desktop check clears request timers instead of waiting an extra minute after success. Package and plugin test files have a hard timeout.
+
+### Upgrade notes
+
+- Ask your AI to upgrade and build your studio. The build writes Worker modules and the normal deploy applies the new connection and audit tables. No separate Homie service or Cloudflare resource is needed.
+- Studio tools are trusted code in your Worker. Review tools received as parts before adding them. The tool context does not expose raw credentials.
+
 ## [0.38.0] - 2026-10-09
 
 **Plugin 0.39.0**

package/bin/homie-studio.mjs

@@ -155,6 +155,8 @@
  *   homie-studio servers new <game> "<Name>" --policy open|humans-only|hybrid|beginner [--ai <n>] [--guides <n>]
  *                                        [--kids] [--door open|accounts|invite] [--level 1-5] [--level-max 1-5]
  *                                        [--speech game|lines|off] [--bots fill|off] [--rooms <n>] [--listed on|off]
+ *   homie-studio tool new <name> [--app <id>]
+ *   homie-studio tool call <name> --input <JSON> [--url <site>] [--public]
  *   homie-studio servers set <game> <server> [the same flags]
  *   homie-studio servers close <game> <server> [--reopen]
  *   homie-studio servers level <game> <room> <1-5>   (the AI's level in one room: Rookie, Steady, Fair, Strong, Maxed)
@@ -377,7 +379,7 @@ import { standaloneDeployNotes } from '../lib/standalone.mjs';
 
 const argv = process.argv.slice(2);
 const flags = new Map();
-const BOOL_FLAGS = ['lan', 'off', 'revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids', 'remote-ai', 'dry-run', 'verify', 'maps', 'profile', 'hands-on', 'automatic', 'unlock', 'confirm', 'no-library', 'no-validate', 'rigged', 'no-rig', 'supporter', 'managed', 'live', 'manual', 'renew', 'send', 'accept-tos', 'quiet', 'no-local-ai', 'timestamps', 'overwrite', 'own-route', 'before', 'release', 'device'];
+const BOOL_FLAGS = ['public', 'lan', 'off', 'revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids', 'remote-ai', 'dry-run', 'verify', 'maps', 'profile', 'hands-on', 'automatic', 'unlock', 'confirm', 'no-library', 'no-validate', 'rigged', 'no-rig', 'supporter', 'managed', 'live', 'manual', 'renew', 'send', 'accept-tos', 'quiet', 'no-local-ai', 'timestamps', 'overwrite', 'own-route', 'before', 'release', 'device'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -487,7 +489,15 @@ function print(result) {
       lines.push(`R2 holds about ${sizeOf(result.inR2)} of this studio's media. ${result.cost}`, ...(result.warning ? [`Warning: ${result.warning}`] : []));
       break;
     }
+    case 'tool new':
+      lines.push(result.file, result.next);
+      break;
+    case 'tool call':
+    case 'tool list':
+      lines.push(JSON.stringify(result.result, null, 2));
+      break;
     case 'deploy':
+      if (result.mcp) lines.push(`Connect your AI: ${result.mcp} (approve in your studio's browser page; no key)`);
       if (result.ci) {
         lines.push(`Live: ${result.url ?? '(Wrangler printed no address)'}${result.commit ? ` (commit ${result.commit.slice(0, 7)}${result.branch ? ` on ${result.branch}` : ''})` : ''}`, ...result.steps.map((x) => `  ${x.what}`), ...result.games.map((g) => `  ${g.id}: ${g.play}${g.hash ? `  [${deployWords(g)}]` : ''}`));
         break;
@@ -823,6 +833,7 @@ const OUTWARD_FLAGS = {
   'shop connect': ['url', 'managed', 'live', 'manual', 'renew', 'from-clipboard'], 'shop disconnect': ['url'], 'shop refund': ['url', 'reason', 'note', 'manual-transaction'], 'shop statements': ['url', 'period', 'send', 'cursor'],
   'agents pass': ['url', 'label', 'server', 'hands', 'role', 'days'], 'agents revoke': ['url'], 'agents brain': ['url', 'budget', 'remove'],
   'agents sit': ['url', 'server', 'pass', 'label', 'brain'],
+  'tool new': ['app'], 'tool call': ['url', 'input', 'public'], 'tool list': ['url', 'public'],
   // With --device it adds a phone to the person's Apple team and installs on it: a flag it does not know stops it.
   'standalone run': ['for', 'device', 'site'],
 };
@@ -883,6 +894,7 @@ async function main() {
   // The starter library and the optimiser work anywhere; the rest of style and assets inside a studio (lib/art-cli.mjs).
   if (cmd === 'assets' && ['find', 'optimise', 'optimize'].includes(sub)) return assetsCommand(null, sub, positional, flags, { log });
   const root = requireStudio();
+  if (cmd === 'tool') return (await import('../lib/tools-cli.mjs')).toolCommand(root, sub, positional, flags, { log });
   // A trailer is the plugin's video skill; this hands the words after the id over to it (lib/trailer.mjs).
   if (cmd === 'trailer') return trailerCommand(root, sub, argv.slice(argv.indexOf(sub) + 1), { skills: flags.get('skills') ?? null, slug: flags.get('slug') ?? null });
   if (cmd === 'style') return styleCommand(root, sub, positional, flags, { log });

package/lib/build.mjs

@@ -491,6 +491,7 @@ export function orderGames(games, order, log = () => {}) {
 export async function build(root, { only = null, log = () => {}, deploy = process.env.WORKERS_CI === '1', maps = false, types = false, beforePublish = async () => {}, longCheck = false } = {}) {
   const esbuild = await studioEsbuild(root);
   const studio = readStudio(root);
+  await (await import('./tools-build.mjs')).buildTools(root, esbuild);
   // The shop first (shop/SHOP.md): invalid shop settings stop the build before anything is built.
   const shop = shopForBuild(root, { log });
   const live = join(root, 'site', 'dist');
@@ -689,6 +690,7 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
       ...(audienceOf(studio) !== 'general' ? { audience: audienceOf(studio) } : {}),
       ...(studio.referrals === false ? { referrals: false } : {}),
       ...(lounge ? { lounge } : {}),
+      ...(studio.mcp ? { mcp: studio.mcp } : {}),
       build: buildInfo(root),
     },
     games: rows,
@@ -723,6 +725,7 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
   // site, never before: a game that did not build has left both as they were.
   await beforePublish();
   const hosted = (await rulesBuild()).writeRules(root, ruled, all.filter((g) => rulesOf.get(g.id)?.host === 'server').map((g) => g.id));
+  await (await import('./worker-build.mjs')).buildWorker(root, esbuild);
   // All of it is there: now, and only now, it becomes site/dist (lib/stage.mjs).
   const swapped = swapIn(dist, live);
   return {

package/lib/cloudflare.mjs

@@ -466,7 +466,7 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRo
   const next = { ...kept, ...(cf.url && !isWorkersDev(cf.url) ? { url: cf.url } : {}), accountId, d1Id: db.uuid, r2: cf.r2 ?? null, created: [...created].sort() };
   writeStudio(root, { ...readStudio(root), cloudflare: next });
   return {
-    ok: true, command: 'deploy', url, ...(workersDev ? { workersDev, local: LOCAL_STATE } : {}), worker: cf.worker, d1: cf.d1, r2, account: accountId, announced, steps,
+    ok: true, command: 'deploy', url, mcp: url ? `${url}/mcp` : null, connectAI: url ? `${url}/_studio/office/connections` : null, ...(workersDev ? { workersDev, local: LOCAL_STATE } : {}), worker: cf.worker, d1: cf.d1, r2, account: accountId, announced, steps,
     ...(media ? { media: { moved: media.moved ?? [], failed: media.failed ?? [], inR2: media.inR2 ?? null } } : {}),
     games: b.catalogue.map((id) => { const g = delta.games.find((x) => x.id === id); return { id, page: url ? `${url}/${id}/` : null, play: url ? `${url}/${id}/play` : null, hash: g?.hash ?? null, change: delta.first ? 'first deploy from this computer' : g?.change ?? null }; }),
     ...(delta.removed.length ? { removed: delta.removed } : {}),
@@ -628,7 +628,7 @@ export async function ciDeploy(root, { log = () => {} } = {}) {
   const hashes = builtGames(root, games);
   for (const id of games) if (hashes[id]?.hash) step(`${id}: ${deployWords(hashes[id])}`);
   return {
-    ok: true, command: 'deploy', ci: true, url, worker: names.worker, d1: names.d1, r2: null, steps, announced: [],
+    ok: true, command: 'deploy', ci: true, url, mcp: url ? `${url}/mcp` : null, connectAI: url ? `${url}/_studio/office/connections` : null, worker: names.worker, d1: names.d1, r2: null, steps, announced: [],
     commit: process.env.WORKERS_CI_COMMIT_SHA ?? null, branch: process.env.WORKERS_CI_BRANCH ?? null,
     // A CI checkout has no earlier deploy to compare with: each game's content hash only (lib/deploy-state.mjs).
     games: games.map((id) => ({ id, page: url ? `${url}/${id}/` : null, play: url ? `${url}/${id}/play` : null, hash: hashes[id]?.hash ?? null })), songs: [], videos: [],

package/lib/dev.mjs

@@ -459,7 +459,18 @@ export async function dev(root, { lan = false, port: askedPort = 8787, remoteAi
       return;
     }
   };
-  const timer = setInterval(() => { look().catch(() => {}); rulesLook().catch(() => {}); }, watchMs);
+  const { toolFiles } = await import('./tools-build.mjs');
+  const toolsStamp = () => toolFiles(root).map(file => `${file}:${statSync(file).mtimeMs}:${statSync(file).size}`).join('|');
+  let lastTools = toolsStamp();
+  const toolsLook = async () => {
+    if (rebuilding || ending) return;
+    const stamp = toolsStamp(); if (stamp === lastTools) return;
+    lastTools = stamp; rebuilding = true;
+    try { log('Studio tools changed: type-checking and rebuilding…'); await build(root, { log }); }
+    catch (error) { log(`Studio tools did not build: ${error.message}`); }
+    finally { rebuilding = false; }
+  };
+  const timer = setInterval(() => { look().catch(() => {}); rulesLook().catch(() => {}); toolsLook().catch(() => {}); }, watchMs);
   timer.unref?.();
 
   /** Wait for the local site, then hold it to its own address (socketOriginProblem); a mismatch ends dev. */

package/lib/mcp-tools.mjs

@@ -782,6 +782,16 @@ export function toolDefs(ctx, avail = {}) {
         return r.ok ? ok('Node and npm are ready. AI: continue studio_scaffold.', r) : fail(r.next, r);
       },
     },
+    {
+      name: 'studio_connect_ai', title: 'Connect your AI to the studio',
+      description: 'Give the person this studio’s own remote MCP address and connection page. Their AI connects directly with browser approval and their existing studio account; no key or local server.',
+      inputSchema: { type: 'object', properties: { ...STUDIO_ARG } },
+      annotations: { title: 'Connect your AI', ...RO },
+      run: async (a) => {
+        const root = ctx.root(a.studio), site = siteUrl(root);
+        return site ? ok(`Connect your AI to ${site}/mcp. Approve with your studio account in the browser. Manage connections at ${site}/_studio/office/connections. Client setup varies; do not promise a one-click import a client does not support.`, { mcp: `${site}/mcp`, connections: `${site}/_studio/office/connections` }) : fail('This studio has no published address yet. Local tools can be tested with homie-studio dev.');
+      },
+    },
     {
       name: 'studio_domain', title: 'Set the studio domain',
       description: 'Prepare a requested custom hostname for deployment. Cloudflare creates DNS and TLS using its existing browser sign-in. The AI handles configuration; never ask for an account id, zone id or DNS value. Does not deploy or change the domain registrar.',

package/lib/port-check.mjs

@@ -44,7 +44,11 @@ const GPU = [
 const TAG = 'homie-studio-check';
 const ANDROID_UA = 'Mozilla/5.0 (Linux; Android 14; Pixel 7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/145.0.0.0 Mobile Safari/537.36';
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-const T = (p, ms, v = null) => Promise.race([Promise.resolve(p).catch(() => v), sleep(ms).then(() => v)]);
+const T = async (p, ms, v = null) => {
+  let timer;
+  try { return await Promise.race([Promise.resolve(p).catch(() => v), new Promise(resolve => { timer = setTimeout(() => resolve(v), ms); })]); }
+  finally { clearTimeout(timer); }
+};
 const DIRV = { up: [0, -1], down: [0, 1], left: [-1, 0], right: [1, 0] };
 const ALL = ['owner-desk', 'owner-phone', 'owner-iphone', 'round', 'life', 'tv'];
 
@@ -328,17 +332,36 @@ async function touchDrag(h, from, dir, reach, holdMs, ready) {
 /** Timestamp real input delivery, then keep it held until four frames can judge its direction.
  * The response limit stays 600 ms; slow automation delivery and the thumb's ramp are not game latency. */
 export async function measuredPress(h, how, code, from, dir) {
+  // CDP points use page coordinates; DOM touch receipts use frame coordinates.
+  let offset = { x: 0, y: 0 };
+  if (how !== 'keys') {
+    const element = await frameOf(h)?.frameElement();
+    if (element) {
+      try { offset = await element.boundingBox() ?? offset; }
+      finally { await element.dispose(); }
+    }
+  }
   await inFrame(h, `(() => {
     if (!window.__homieCheckInput) {
       const state = window.__homieCheckInput = {};
       addEventListener('keydown', e => { if (state.code === e.code && state.key === null) state.key = performance.now(); }, true);
-      addEventListener('touchmove', () => { state.touch = performance.now(); }, { capture: true, passive: true });
+      addEventListener('touchmove', e => {
+        const touch = e.touches[0];
+        if (state.touch === null && touch && touch.clientX === state.touchX && touch.clientY === state.touchY) state.touch = performance.now();
+      }, { capture: true, passive: true });
     }
-    Object.assign(window.__homieCheckInput, { code: ${JSON.stringify(code)}, key: null, touch: null });
+    Object.assign(window.__homieCheckInput, { code: ${JSON.stringify(code)}, key: null, touch: null, touchX: ${Math.round(from[0] + DIRV[dir][0] * 70) - offset.x}, touchY: ${Math.round(from[1] + DIRV[dir][1] * 70) - offset.y} });
   })()`);
   let a = null, b = null;
   const ready = async () => {
-    a = await inFrame(h, `window.__homieCheckInput.${how === 'keys' ? 'key' : 'touch'}`);
+    // CDP acknowledgement is not DOM delivery. Wait for the final ramp point,
+    // then latch that receipt so later/coalesced moves cannot change it.
+    const deliveryDeadline = Date.now() + 3000;
+    do {
+      a = await inFrame(h, `window.__homieCheckInput.${how === 'keys' ? 'key' : 'touch'}`);
+      if (Number.isFinite(a)) break;
+      await sleep(20);
+    } while (Date.now() < deliveryDeadline);
     if (!Number.isFinite(a)) throw new Error('the game frame did not receive the measured input');
     await sleep(420);
     const until = Date.now() + 3000;

package/lib/scaffold.mjs

@@ -1,3 +1,4 @@
+import { MCP_MIGRATION, MCP_MIGRATION_FILE } from '../worker/mcp-store.mjs';
 import { APPS_MIGRATION, APPS_MIGRATION_FILE } from '../worker/app-records.mjs';
 import { PURCHASE_MIGRATION, PURCHASE_MIGRATION_FILE, PURCHASE_STATE, PURCHASE_STATE_FILE } from '../worker/purchase-schema.mjs';
 /**
@@ -67,8 +68,8 @@ export function slugify(name) {
  * the binding names and keep it linked.
  */
 export function wranglerConfig({ worker, name, d1, d1Id = null, r2 = null, layout = 'root', ai = false, routes = null, paidParts = false, partsRateLimit = null, triggers = null }) {
-  const at = layout === 'site' ? { schema: '../node_modules', main: 'src/worker.mjs', dist: './dist', migrations: 'migrations' }
-    : { schema: 'node_modules', main: 'site/src/worker.mjs', dist: './site/dist', migrations: 'site/migrations' };
+  const at = layout === 'site' ? { schema: '../node_modules', main: 'src/runtime/worker.js', dist: './dist', migrations: 'migrations' }
+    : { schema: 'node_modules', main: 'site/src/runtime/worker.js', dist: './site/dist', migrations: 'site/migrations' };
   const rooms = [{ name: 'TABLE', class_name: 'Table' }, { name: 'LOBBY', class_name: 'Lobby' }];
   const config = {
     $schema: `${at.schema}/wrangler/config-schema.json`,
@@ -80,7 +81,8 @@ export function wranglerConfig({ worker, name, d1, d1Id = null, r2 = null, layou
     // subdomain) reaches it instead of failing with 1042.
     // `disallow_eval_during_startup`: no code is made from a string while the Worker loads (Cloudflare never allows it
     // later). A game's rules run in this Worker (NETPLAY.md section 29), and nothing in them is ever made from text.
-    compatibility_flags: ['global_fetch_strictly_public', 'disallow_eval_during_startup', ...(paidParts ? ['nodejs_compat'] : [])],
+    no_bundle: true, find_additional_modules: true, rules: [{ type: 'ESModule', globs: ['**/*.js'], fallthrough: true }],
+    compatibility_flags: ['nodejs_compat', 'global_fetch_strictly_public', 'disallow_eval_during_startup'],
     ...(paidParts ? { alias: { '@homie-rocks/studio/worker': '@homie-rocks/studio/worker/selling' }, triggers: { crons: ['*/5 * * * *'] }, ratelimits: [partsRateLimit ?? { name: 'PURCHASE_RATE_LIMITER', namespace_id: '1001', simple: { limit: 60, period: 60 } }] } : {}),
     workers_dev: true,
     preview_urls: true,
@@ -152,6 +154,8 @@ An app is ONE screen that morphs with context: camera moves, panels unfold, its
 
 Declare roles, surfaces, words and lasting record collections in app.json. Netplay's host is not a staff permission. Use \`@homie-rocks/studio/apps\` for authorized lasting records and \`@homie-rocks/studio/links\` for ticket links, QR and HTTP-safe IDs. Staff use private role links plus existing account grants; keep private records out of public collections. Look for engine mechanisms and shared parts before writing a component. Credit licences; sharing is optional and separate from selling.
 
+Your studio also serves MCP at \`/mcp\`. Staff connect their own AI with their existing account and one browser approval; never ask them for a key. Add business actions with \`homie-studio tool new <name> --app <id>\`, keep their declared role narrow, and reuse the app's existing record IDs, field formats and versions. Test owner, staff and public calls locally. Read \`node_modules/@homie-rocks/studio/tools/TOOLS.md\` and the Homie plugin's \`tools\` skill.
+
 Build normally, run \`homie-studio dev --lan\`, then \`homie-studio check <id> --url <origin>\`: the app check proves an actual action across a wall and two phones plus reconnect. The public screen is \`/<id>/open\`, the wall \`/<id>/tv\`. Customer apps use the same \`standalone\` build for desktop/iOS/Android; its existing sign-in and store limitations still apply. See \`node_modules/@homie-rocks/studio/apps/APPS.md\`.
 
 ## Commands (all through the pinned CLI in node_modules)
@@ -645,6 +649,8 @@ anything here wins. The whole list is in \`node_modules/@homie-rocks/studio/site
 `;
 
 const GITIGNORE = `node_modules/
+site/src/runtime/
+site/src/tools/
 # This computer's own state: the site's workers.dev address (it names the Cloudflare account, often after its owner).
 .studio/
 # This person's own Claude Code settings for this studio (the status line, for one).
@@ -734,11 +740,12 @@ export function studioFiles({ name, slug, homie, template = false }) {
     'site/README.md': SITE_README,
     'site/src/worker.mjs': `// This studio's site: pages, public rooms (Table + Lobby Durable Objects), D1, and R2 once storage is added.
 // The code is @homie-rocks/studio's, pinned in package.json, so an update never changes a published game by surprise.
-import { hostRules } from '@homie-rocks/studio/worker';
+import { hostRules, useTools } from '@homie-rocks/studio/worker';
 // The rules of this studio's games that run on the server (written by homie-studio build; empty until a game has some).
 import rules from './rules/index.mjs';
 
 hostRules(rules);
+useTools(async () => (await import('./tools/index.mjs')).default);
 export { default, Table, Lobby } from '@homie-rocks/studio/worker';
 `,
     'site/src/rules/index.mjs': rulesIndex([]),
@@ -755,6 +762,7 @@ export { default, Table, Lobby } from '@homie-rocks/studio/worker';
     [`site/migrations/${SHOP_STATEMENTS_FILE}`]: SHOP_STATEMENTS,
     [`site/migrations/${SHOP_LINES_FILE}`]: SHOP_LINES,
     [`site/migrations/${APPS_MIGRATION_FILE}`]: APPS_MIGRATION,
+    [`site/migrations/${MCP_MIGRATION_FILE}`]: MCP_MIGRATION,
     [`site/migrations/${LOUNGE_MIGRATION_FILE}`]: LOUNGE_MIGRATION,
     'wrangler.jsonc': wranglerConfig({ worker, name, d1: studio.cloudflare.d1, r2: studio.cloudflare.r2, layout: 'root' }),
     '.claude/skills/.gitkeep': '',
@@ -926,13 +934,18 @@ function ensurePartsStateMigration(root) {
   return `site/migrations/${PURCHASE_STATE_FILE}`;
 }
 
+function ensureMcpMigration(root) {
+  const file=join(root,'site','migrations',MCP_MIGRATION_FILE);
+  if(existsSync(file))return null;
+  mkdirSync(dirname(file),{recursive:true});writeFileSync(file,MCP_MIGRATION);return `site/migrations/${MCP_MIGRATION_FILE}`;
+}
 export function ensureMigrations(root) {
-  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root), ensureServersMigration(root), ensureChatMigration(root), ensureShopMigration(root), ensureLoungeMigration(root), ensureShopReservations(root), ensureShopStatements(root), ensureShopLines(root), ensureAppsMigration(root), ensurePartsMigration(root), ensurePartsStateMigration(root)].filter(Boolean);
+  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root), ensureServersMigration(root), ensureChatMigration(root), ensureShopMigration(root), ensureLoungeMigration(root), ensureShopReservations(root), ensureShopStatements(root), ensureShopLines(root), ensureAppsMigration(root), ensurePartsMigration(root), ensurePartsStateMigration(root), ensureMcpMigration(root)].filter(Boolean);
 }
 
 /** What a migration file the template added is for, in a few words (deploy and dev say it). */
 export function migrationWord(file) {
-  return /studio_apps/.test(file) ? 'apps: lasting records and signed-in role grants' : /lounge/.test(file) ? 'the Lounge and kept chat: play nights, moderators, and what was said only where an owner turns history on' : /shop/.test(file) ? 'the shop: orders, what players own, refunds and referral books (paid sales wait until shop.json and the studio\'s Stripe connection are ready)' : /players/.test(file) ? 'player accounts and cloud saves' : /chat/.test(file) ? 'room chat: the owner\'s chat rules and players\' reports (never the chat itself)' : /servers/.test(file) ? 'servers and agent seats: room pools with their own rules, AI passes' : /office/.test(file) ? 'the back office: launch states, invites, the owner\'s controls' : 'the studio\'s own stats: counts, never tracks';
+  return /studio_mcp/.test(file) ? 'AI connections and tool call history' : /studio_apps/.test(file) ? 'apps: lasting records and signed-in role grants' : /lounge/.test(file) ? 'the Lounge and kept chat: play nights, moderators, and what was said only where an owner turns history on' : /shop/.test(file) ? 'the shop: orders, what players own, refunds and referral books (paid sales wait until shop.json and the studio\'s Stripe connection are ready)' : /players/.test(file) ? 'player accounts and cloud saves' : /chat/.test(file) ? 'room chat: the owner\'s chat rules and players\' reports (never the chat itself)' : /servers/.test(file) ? 'servers and agent seats: room pools with their own rules, AI passes' : /office/.test(file) ? 'the back office: launch states, invites, the owner\'s controls' : 'the studio\'s own stats: counts, never tracks';
 }
 
 /**

package/lib/studio.mjs

@@ -8,7 +8,7 @@ import { fileURLToPath } from 'node:url';
 
 export const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 export const GAME_ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
-const RESERVED_IDS = new Set(['api', 'media', 'games', 'apps', 'assets', '_homie', '_site', '_studio', 'well-known', 'index', 'play', 'studio', 'studios', 'music', 'videos', 'posts', 'rooms', 'feed', 'account']);
+const RESERVED_IDS = new Set(['mcp', 'oauth', 'hooks', 'api', 'media', 'games', 'apps', 'assets', '_homie', '_site', '_studio', 'well-known', 'index', 'play', 'studio', 'studios', 'music', 'videos', 'posts', 'rooms', 'feed', 'account']);
 
 export function findStudio(from = process.cwd()) {
   let at = resolve(from);

package/lib/template-history.json

@@ -2156,6 +2156,47 @@
      }
     }
    }
+  },
+  "0.39.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "732894273a32dc3f",
+    "site/src/worker.mjs": "34444a6ca4b14437"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "c18362ed28975d81",
+     "## Apps: one screen, roles and parts": "be6f8fa45f93211a",
+     "## Commands (all through the pinned CLI in node_modules)": "a7f290579585368c",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "2da7fa74c8884834",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "98d08705087a33ec",
+     "## Selling things (the shop)": "9e020d69dd6a954e",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "2e6b29afb85dcf7e",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "7cad8fd10f62fef1"
+      }
+     }
+    }
+   }
   }
  }
 }

package/lib/tools-build.mjs

@@ -0,0 +1,55 @@
+import { existsSync, readdirSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createRequire } from 'node:module';
+import { partsPlugin, resolvePartImport } from './parts-build.mjs';
+const require=createRequire(import.meta.url);
+export function toolFiles(root) {
+  const dirs=[join(root,'tools')];
+  const apps=join(root,'apps');if(existsSync(apps))for(const app of readdirSync(apps,{withFileTypes:true}))if(app.isDirectory())dirs.push(join(apps,app.name,'tools'));
+  return dirs.flatMap(dir=>existsSync(dir)?readdirSync(dir).filter(f=>/^[a-z][a-z0-9-]*\.ts$/.test(f)).sort().map(f=>join(dir,f)):[]);
+}
+export async function buildTools(root,esbuild) {
+  const files=toolFiles(root),dir=join(root,'site/src/tools');
+  mkdirSync(dir,{recursive:true});
+  if(files.length){
+    const ts=require('typescript');
+    const options={target:ts.ScriptTarget.ES2022,module:ts.ModuleKind.ESNext,moduleResolution:ts.ModuleResolutionKind.Bundler,strict:true,noEmit:true,skipLibCheck:true,allowImportingTsExtensions:true};
+    const host=ts.createCompilerHost(options);
+    host.resolveModuleNames=(names,containing)=>names.map(name=>{
+      if(name.startsWith('@parts/')){const part=resolvePartImport(root,name);if(part.path)return {resolvedFileName:part.path,extension:part.path.endsWith('.ts')?ts.Extension.Ts:ts.Extension.Js};}
+      return ts.resolveModuleName(name,containing,options,host).resolvedModule;
+    });
+    const program=ts.createProgram(files,options,host);
+    const errors=ts.getPreEmitDiagnostics(program);
+    if(errors.length)throw new Error(ts.formatDiagnosticsWithColorAndContext(errors,{getCurrentDirectory:()=>root,getCanonicalFileName:f=>f,getNewLine:()=> '\n'}));
+  }
+  const contents=files.map((f,i)=>`import t${i} from ${JSON.stringify(f)};`).join('\n')+`\nexport default [${files.map((_,i)=>'t'+i).join(',')}];\n`;
+  const result=await esbuild.build({stdin:{contents,resolveDir:root},bundle:true,format:'esm',platform:'neutral',target:'es2022',write:false,plugins:[partsPlugin(root)],logLevel:'silent'});
+  const temp=join(dir,'index.mjs');writeFileSync(temp,result.outputFiles[0].text);
+  // Trusted studio code, as with the existing build command. No Worker bindings exist during build.
+  const defs=(await import(pathToFileURL(temp).href+'?build='+Date.now())).default;
+  const { CfWorkerJsonSchemaValidator }=await import('@modelcontextprotocol/server/validators/cf-worker');
+  const validator=new CfWorkerJsonSchemaValidator(),seen=new Set();
+  for(const t of defs){
+    if(!/^[a-z][a-z0-9_]{0,63}$/.test(t.name)||/^(studio_|app_|agent_|room_|shop_)/.test(t.name)||seen.has(t.name))throw new Error(`tool name is invalid, reserved or duplicated: ${t.name}`);
+    seen.add(t.name);
+    if(typeof t.description!=='string'||!t.description.trim()||typeof t.handler!=='function')throw new Error(`tool ${t.name} needs description and handler`);
+    if(!['owner','signed-in','public'].includes(t.audience)&&!(t.audience&&typeof t.audience.app==='string'&&typeof t.audience.role==='string'))throw new Error(`tool ${t.name} needs an audience`);
+    if(t.inputSchema?.type!=='object')throw new Error(`tool ${t.name} input schema must be an object`);
+    validator.getValidator(t.inputSchema);
+    if(t.kind!==undefined&&!['tool','prompt'].includes(t.kind))throw new Error(`tool ${t.name}: invalid kind`);
+    if(t.webhook&&(!/^[A-Z][A-Z0-9_]{0,63}$/.test(t.webhook.secret)||typeof t.webhook.person!=='string'||!t.webhook.person))throw new Error(`tool ${t.name}: webhook needs a named secret and account`);
+    for(const [name,event] of Object.entries(t.events??{})){
+      if(!/^external:[a-z][a-z0-9_-]{0,40}$/.test(name)||!event.game||!event.schema)throw new Error(`tool ${t.name}: invalid external event`);
+      validator.getValidator(event.schema);
+    }
+  }
+  // Existing studios retain their Worker customization; install the small registry hook once.
+  const worker=join(root,'site/src/worker.mjs');
+  if(existsSync(worker)){
+    let text=readFileSync(worker,'utf8');
+    if(!text.includes('useTools(')){text += "\nimport { useTools } from '@homie-rocks/studio/worker';\nuseTools(async () => (await import('./tools/index.mjs')).default);\n";writeFileSync(worker,text);}
+  }
+  return defs.map(t=>t.name);
+}

package/lib/tools-cli.mjs

@@ -0,0 +1,55 @@
+import {existsSync,mkdirSync,writeFileSync,readFileSync,chmodSync} from 'node:fs';
+import {join,dirname} from 'node:path';
+import {createServer} from 'node:http';
+import {randomUUID} from 'node:crypto';
+import {spawn} from 'node:child_process';
+export function newTool(root,name,{app=null}={}) {
+  if(!/^[a-z][a-z0-9-]{0,39}$/.test(name??'') || app!==null&&!/^[a-z][a-z0-9-]{0,39}$/.test(app))throw new Error('name uses lowercase letters, numbers and hyphens');
+  if(app&&!existsSync(join(root,'apps',app,'app.json')))throw new Error('unknown app');
+  const file=join(root,...(app?['apps',app,'tools']:['tools']),name+'.ts');if(existsSync(file))throw new Error('tool already exists');
+  mkdirSync(dirname(file),{recursive:true});writeFileSync(file,`import { defineTool } from '@homie-rocks/studio/tools';\n\nexport default defineTool<{ message: string }>({\n  name: '${name.replaceAll('-','_')}',\n  description: 'Describe what this tool does and when to use it.',\n  audience: ${app?JSON.stringify({app,role:'staff'}):"'owner'"},\n  inputSchema: { type: 'object', properties: { message: { type: 'string', maxLength: 200 } }, required: ['message'], additionalProperties: false },\n  async handler({ message }, context) {\n    return { message, by: context.caller.id };\n  },\n});\n`);
+  return {ok:true,command:'tool new',file,next:'Edit the definition, then homie-studio dev. Call it with homie-studio tool call '+name.replaceAll('-','_')+' --input \'{"message":"Hello"}\' --url http://localhost:8787'};
+}
+/** The official SDK owns discovery, registration, PKCE, refresh and issuer checks. */
+export async function connectToolClient(root,site,{publicOnly=false,open=defaultOpen,log=()=>{}}={}) {
+  const {Client,StreamableHTTPClientTransport,auth}=await import('mcp-studio-client');
+  const url=new URL('/mcp',site);if(url.protocol!=='https:'&&!['localhost','127.0.0.1','[::1]'].includes(url.hostname))throw new Error('Use HTTPS, or localhost for local development');
+  const client=new Client({name:'Homie studio tool CLI',version:'1.0.0'});
+  if(publicOnly){await client.connect(new StreamableHTTPClientTransport(url));return client;}
+  const file=join(root,'.studio','mcp',Buffer.from(url.origin).toString('base64url')+'.json');
+  let state={};try{state=JSON.parse(readFileSync(file,'utf8'));}catch{}
+  // Credentials without an issuer predate the SDK's OAuth binding fix; reconnect safely.
+  if((state.tokens&&!state.tokens.issuer)||(state.client&&!state.client.issuer))state={};
+  const save=()=>{mkdirSync(dirname(file),{recursive:true});writeFileSync(file,JSON.stringify(state),{mode:0o600});chmodSync(file,0o600);};
+  let accept;const returned=new Promise(resolve=>{accept=resolve;});
+  const csrf=randomUUID();
+  const server=createServer((req,res)=>{const back=new URL(req.url,'http://localhost');if(back.pathname!=='/callback'||back.searchParams.get('state')!==csrf){res.writeHead(400);res.end('Invalid callback');return;}res.end('Your AI is connected. You can close this tab.');accept(back);});
+  await new Promise(resolve=>server.listen(0,'127.0.0.1',resolve));
+  const redirect=`http://127.0.0.1:${server.address().port}/callback`;
+  const provider={redirectUrl:redirect,clientMetadata:{client_name:'Homie studio tool CLI',redirect_uris:[redirect],grant_types:['authorization_code','refresh_token'],response_types:['code'],token_endpoint_auth_method:'none'},state:()=>csrf,
+    clientInformation:()=>state.client,saveClientInformation:v=>{state.client=v;save();},tokens:()=>state.tokens,saveTokens:v=>{state.tokens=v;save();},
+    codeVerifier:()=>state.verifier,saveCodeVerifier:v=>{state.verifier=v;save();},
+    discoveryState:()=>state.discovery,saveDiscoveryState:v=>{state.discovery=v;save();},
+    invalidateCredentials:scope=>{if(scope==='all')state={};else {delete state[scope==='tokens'?'tokens':scope];if(scope==='tokens')delete state.client;}save();},
+    redirectToAuthorization:async u=>{log('Approve this connection in your browser.');await open(u.href);},
+  };
+  try{
+    // A new loopback port needs a matching registered redirect; refresh still uses the prior client.
+    if(!state.tokens){delete state.client;delete state.discovery;}
+    const result=await auth(provider,{serverUrl:url,scope:'studio offline_access'});
+    if(result==='REDIRECT'){
+      let timer;const timeout=new Promise((_,reject)=>{timer=setTimeout(()=>reject(new Error('Browser approval timed out')),300000);});
+      const back=await Promise.race([returned,timeout]).finally(()=>clearTimeout(timer));
+      if(back.searchParams.has('error'))throw new Error('Connection declined');
+      await auth(provider,{serverUrl:url,authorizationCode:back.searchParams.get('code'),iss:back.searchParams.get('iss')??undefined});
+    }
+    await client.connect(new StreamableHTTPClientTransport(url,{authProvider:provider}));return client;
+  }finally{server.close();}
+}
+function defaultOpen(url){const cmd=process.platform==='darwin'?'open':process.platform==='win32'?'explorer':'xdg-open';const child=spawn(cmd,[url],{stdio:'ignore',detached:true});child.unref();}
+export async function toolCommand(root,sub,positional,flags,{log=()=>{}}={}) {
+  if(sub==='new')return newTool(root,positional[2],{app:flags.get('app')??null});
+  if(!['call','list'].includes(sub))throw new Error('Use tool new <name>, tool list, or tool call <name> --input <JSON>');
+  const client=await connectToolClient(root,flags.get('url')??'http://localhost:8787',{publicOnly:flags.has('public'),log});
+  try{const result=sub==='list'?await client.listTools():await client.callTool({name:positional[2],arguments:JSON.parse(flags.get('input')??'{}')});return {ok:result.isError!==true,command:'tool '+sub,result,...(result.isError?{why:'The tool refused or failed; see its result.'}:{})};}finally{await client.close();}
+}

package/lib/worker-build.mjs

@@ -0,0 +1,35 @@
+import {existsSync,mkdirSync,readFileSync,writeFileSync,rmSync} from 'node:fs';
+import {join,relative,dirname} from 'node:path';
+import {readConfig} from './routes.mjs';
+import {paidReleases} from './parts-upload.mjs';
+import {configPath} from './studio.mjs';
+/** Preserve dynamic imports as real Worker modules: page startup never evaluates MCP libraries. */
+export async function buildWorker(root,esbuild) {
+  const source=join(root,'site/src/worker.mjs');if(!existsSync(source))return;
+  const out=join(root,'site/src/runtime');
+  const alias={...(readConfig(root)?.alias??{})};
+  if(paidReleases(root).length)alias['@homie-rocks/studio/worker']='@homie-rocks/studio/worker/selling';
+  const result=await esbuild.build({entryPoints:[source],absWorkingDir:root,alias,outdir:out,bundle:true,splitting:true,format:'esm',platform:'browser',mainFields:['module','main'],conditions:['workerd','worker','browser'],external:['node:*','cloudflare:*'],target:'es2022',write:false,minify:true,metafile:true,logLevel:'silent'});
+  rmSync(out,{recursive:true,force:true});
+  mkdirSync(out,{recursive:true});
+  for(const file of result.outputFiles)writeFileSync(file.path,file.contents);
+  const config=configPath(root);
+  if(existsSync(config)){
+    const original=readFileSync(config,'utf8');
+    const json=JSON.parse(original.replace(/^\s*\/\/.*$/gm,''));
+    const before=JSON.stringify(json);
+    json.main=relative(dirname(config),join(out,'worker.js')).split('\\').join('/');
+    json.no_bundle=true;json.find_additional_modules=true;
+    json.rules=[...(json.rules??[]).filter(r=>!r.homieMcp),{type:'ESModule',globs:['**/*.js'],fallthrough:true}];
+    // No duplicate rule on rebuild.
+    json.rules=json.rules.filter((r,i,all)=>all.findIndex(x=>JSON.stringify(x)===JSON.stringify(r))===i);
+    json.compatibility_flags=[...new Set([...(json.compatibility_flags??[]),'nodejs_compat'])];
+    if(JSON.stringify(json)!==before) {
+      const comments=original.match(/^(?:\s*\/\/[^\n]*\n)*/)?.[0]??'';
+      writeFileSync(config,comments+JSON.stringify(json,null,2)+'\n');
+    }
+  }
+  const sizes=Object.entries(result.metafile.outputs).map(([path,value])=>({path:relative(root,path),bytes:value.bytes,imports:value.imports}));
+  writeFileSync(join(out,'modules.json'),JSON.stringify(sizes,null,2)+'\n');
+  return sizes;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), a site with the hub's sections (Home, Games, Music, Videos, Rooms, Posts with feeds) in the studio's own look, an epic landing page for every game, big songs and videos in the studio's own R2 once it has storage (uploaded, checked by SHA-256, served at the same addresses), deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",
@@ -84,7 +84,11 @@
       "types": "./apps/apps.ts",
       "default": "./apps/apps.ts"
     },
-    "./worker/selling": "./worker/selling/index.mjs"
+    "./worker/selling": "./worker/selling/index.mjs",
+    "./tools": {
+      "types": "./tools/tools.ts",
+      "default": "./tools/tools.ts"
+    }
   },
   "files": [
     "bin/",
@@ -111,7 +115,8 @@
     "NOTICE",
     "links/",
     "apps/",
-    "app-starters/"
+    "app-starters/",
+    "tools/"
   ],
   "engines": {
     "node": ">=22"
@@ -122,17 +127,22 @@
     "@babel/parser": "8.0.7",
     "@babel/traverse": "8.0.7",
     "@babel/types": "8.0.6",
+    "@cloudflare/workers-oauth-provider": "1.2.3",
     "@coinbase/x402": "2.1.0",
     "@gltf-transform/core": "4.5.1",
     "@gltf-transform/extensions": "4.5.1",
     "@gltf-transform/functions": "4.5.1",
     "@jridgewell/trace-mapping": "0.3.31",
-    "@modelcontextprotocol/sdk": "1.32.1",
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "@modelcontextprotocol/server": "2.0.0",
     "@x402/core": "2.28.0",
     "@x402/evm": "2.28.0",
+    "agents": "0.28.0",
     "esbuild": "0.28.1",
     "gltf-validator": "2.0.0-dev.3.10",
     "jose": "6.2.12",
+    "mcp-purchase-sdk": "npm:@modelcontextprotocol/sdk@1.32.1",
+    "mcp-studio-client": "npm:@modelcontextprotocol/client@2.3.1",
     "meshoptimizer": "1.3.0",
     "mppx": "0.13.2",
     "puppeteer-core": "25.8.0",
@@ -140,10 +150,11 @@
     "spdx-expression-parse": "5.0.0",
     "stripe": "23.0.0",
     "three": "0.185.1",
+    "typescript": "5.9.3",
     "viem": "2.57.4",
-    "typescript": "5.9.3"
+    "zod": "4.3.6"
   },
   "scripts": {
-    "test": "node --test test/*.test.mjs"
+    "test": "node --test --test-concurrency=2 --test-timeout=1800000 test/*.test.mjs"
   }
 }