@quo-systems/dock 0.2.0 → 0.2.2

package/mcp/quo-mcp.md

@@ -31,13 +31,24 @@ and needs no translation code beyond an envelope:
 | tool error result        | an error object she answered, `{ error }`, as JSON           |
 | protocol error           | silence and the ward's words, see the table below            |
 | auth token               | an invitation, used once, then keys                          |
-| resources, prompts       | not mapped. Notes in the blueprint may carry hints.          |
+| tool title, annotations  | her `look`: a title and the hints per ask, see below         |
+| resources, prompts       | not mapped.                                                  |
 
 A tool list is a describe. Because a being describes per asker, two models
 connected to the same user being see two different tool lists, and neither
 can call what it cannot see: the gate is one decision for describe and for
 dispatch.
 
+A being who answers `look`, the trunk's one optional ask, is listed with
+what it says: `asks.NAME.title` is the tool's title, and `readOnly`,
+`destructive` and `idempotent` are the annotations of the same names with
+`Hint` after them. The `look` ask itself is not a tool. A carried standing's
+asks, `acme-book` on the user being for a model the human let reach, carry
+the far being's hints the same way, read from the notes the carrier writes.
+The side asks `look` once per digest of the describe. Nothing else changes:
+a model sees a flat list with a dash, exactly as a screen sees a section
+per standing, and neither can do a thing the other cannot.
+
 The three words for "no object" cross the envelope like this:
 
 | the avatar heard | the client gets                                                     |
@@ -56,6 +67,13 @@ the two words give it what it needs to decide.
 
 ### A remote MCP client connects
 
+One harbor holds many worlds, and the allow page names the one the client
+is let into; the grant remembers it, so a bearer is an identity in a world
+and a session is that identity's there. `/mcp` stays one endpoint per
+harbor: `mcp/route.ts` is the route the daemon mounts, the exchange in
+`oauth.ts` in front and the endpoint in `http.ts` behind it, with the
+route's store, `<dir>/oauth.json`, the route's own and never a ward's.
+
 ```
 client            mcp. route          front desk         user being        avatar
   |-- OAuth ------->|                     |                  |                |
@@ -205,7 +223,7 @@ avatar. The ward is a being to her owner, and `packages/quo/SPEC.md` says her
 describe carries her asks with a description and an input each, so the
 pilot holds no list of its own: tools/list is the ward's describe, the
 `describe` tool is the census, and a tool call is an owner ask, boot,
-public, invite, knock or remove, in the ward's own words. It reaches those
+public, invite, knock, remove or unboot, in the ward's own words. It reaches those
 asks either as the root through the daemon's socket on the device, or as an
 owner the root invited, through a standing over the sealed door. It keeps
 nothing and logs nothing: what a model did with it is in the host's own

package/mcp/route.ts

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: Apache-2.0
+// The mcp. route: the credential exchange and the MCP endpoint, served by
+// the daemon under `/mcp` and mapped by the proxy from the mcp. hostname.
+// The OAuth store is `<dir>/oauth.json`, the route's own and never a
+// ward's: clients, pending requests, codes and tokens, each mapping to a
+// client identity at most. A bearer names an identity in a world; the
+// endpoint hands both to the model side, which runs beside her avatar.
+import { readFile, writeFile, rename } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { OAuth, emptyStore, type Store } from './oauth.ts';
+import type { McpHttp } from './http.ts';
+import type { Handler } from '../cli/http.ts';
+
+// The routes' public faces, as the exchange and the metadata name them.
+export type Routes = { mcp: string; web: string; quo?: string };
+
+export async function mcpRoute(dir: string, routes: Routes, mcp: McpHttp | null): Promise<{ oauth: OAuth; handler: Handler }> {
+  const file = join(dir, 'oauth.json');
+  const store: Store = existsSync(file) ? { ...emptyStore(), ...(JSON.parse(await readFile(file, 'utf8')) as Partial<Store>) } : emptyStore();
+  let queue = Promise.resolve();
+  const persist = (s: Store) =>
+    (queue = queue.then(async () => {
+      await writeFile(file + '.tmp', JSON.stringify(s), { mode: 0o600 });
+      await rename(file + '.tmp', file);
+    }));
+  const oauth = new OAuth({ issuer: routes.mcp, resource: `${routes.mcp}/mcp`, finish: (id) => `${routes.web}/login?request=${id}`, store, persist });
+  const handler: Handler = async (req, res, rest) => {
+    if (await oauth.handle(req, res, rest)) return;
+    if (rest === '/mcp') {
+      const grant = oauth.bearer(req);
+      if (grant === null || !mcp) return oauth.challenge(res);
+      return mcp.handle(req, res, grant.identity, grant.ward);
+    }
+    res.writeHead(404, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ error: 'no such route' }));
+  };
+  return { oauth, handler };
+}

package/mcp/server.ts

@@ -11,32 +11,40 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import { ListToolsRequestSchema, CallToolRequestSchema, type CallToolResult, type Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { Answer, Blueprint, JsonObject } from '@quo-systems/quo';
-import { word, wordText, SILENCE_TEXT, UNREACHED_TEXT, type Serving } from '../beings/side.ts';
+import type { Blueprint, JsonObject } from '@quo-systems/quo';
+import { word, wordText, SILENCE_TEXT, UNREACHED_TEXT, type Serving, type Subject } from '../beings/side.ts';
+import { hintFor, sanitise, type Look } from '../beings/look.ts';
+import { isSilence, isWord, digest } from '@quo-systems/quo';
+import type { Json } from '@quo-systems/quo';
 
 export const NAME = 'quo';
 export const VERSION = '0.0.0';
 
-// What a side speaks for: the empty ask and a named one, and the ears a
-// push reaches. An avatar is one; the owner's asks on a ward are another.
-export type Subject = {
-  tools(): Promise<Blueprint | { error: string }>;
-  call(name: string, args: JsonObject): Promise<Answer>;
-  ears: Set<(object: JsonObject) => void>;
-};
+export type { Subject } from '../beings/side.ts';
 
 // The empty ask as a tool: her describe whole, asks and notes.
 export const DESCRIBE: Tool = { name: 'describe', description: 'the empty ask: her describe, the asks and the notes', inputSchema: { type: 'object' } };
 
 // Her describe, spoken as tools, the empty ask first. Name, description and
-// input are verbatim; an output schema crosses when she declared one.
-export function tools(bp: Blueprint): Tool[] {
-  const asks = bp.asks.map((a) => {
-    const t: Tool = { name: a.name, inputSchema: { ...a.input, type: 'object' } };
-    if (a.description !== undefined) t.description = a.description;
-    if (a.output !== undefined) t.outputSchema = { ...a.output, type: 'object' };
-    return t;
-  });
+// input are verbatim; an output schema crosses when she declared one. Her
+// look, when she has one, is the hints: a title, and the annotations a host
+// reads. The `look` ask itself is presentation, and is not a tool.
+export function tools(bp: Blueprint, look: Look = {}): Tool[] {
+  const asks = bp.asks
+    .filter((a) => a.name !== 'look')
+    .map((a) => {
+      const t: Tool = { name: a.name, inputSchema: { ...a.input, type: 'object' } };
+      if (a.description !== undefined) t.description = a.description;
+      if (a.output !== undefined) t.outputSchema = { ...a.output, type: 'object' };
+      const h = hintFor(bp, look, a.name);
+      if (h.title !== undefined) t.title = h.title;
+      const notes: Record<string, boolean> = {};
+      if (h.readOnly !== undefined) notes.readOnlyHint = h.readOnly;
+      if (h.destructive !== undefined) notes.destructiveHint = h.destructive;
+      if (h.idempotent !== undefined) notes.idempotentHint = h.idempotent;
+      if (Object.keys(notes).length) t.annotations = notes;
+      return t;
+    });
   return [DESCRIBE, ...asks];
 }
 
@@ -45,10 +53,21 @@ export function tools(bp: Blueprint): Tool[] {
 export async function mcpSide(avatar: Subject, transport: Transport, after: () => Promise<void> = async () => {}): Promise<Serving> {
   const server = new Server({ name: NAME, version: VERSION }, { capabilities: { tools: { listChanged: true }, logging: {} } });
 
+  // Her look, asked once per digest of her describe.
+  let seen: string | null = null;
+  let look: Look = {};
   server.setRequestHandler(ListToolsRequestSchema, async () => {
     const bp = await avatar.tools();
     if ('error' in bp && !('asks' in bp)) return { tools: [] }; // not joined: nothing to show, and nothing to call
-    return { tools: tools(bp as Blueprint) };
+    const d = await digest(bp as Blueprint);
+    if (d !== seen) {
+      seen = d;
+      if ((bp as Blueprint).asks.some((a) => a.name === 'look')) {
+        const l = await avatar.call('look', {});
+        look = isSilence(l) || isWord(l) ? {} : sanitise(l as Json);
+      } else look = {};
+    }
+    return { tools: tools(bp as Blueprint, look) };
   });
 
   server.setRequestHandler(CallToolRequestSchema, async (req): Promise<CallToolResult> => {

package/mcp/web/exchange.ts

@@ -20,12 +20,12 @@ import { readForm } from '../oauth.ts';
 export const SESSION_TTL = 10 * 60 * 1000; // a login lives as long as a request: ten minutes
 const COOKIE = 'quo_exchange';
 
-export type Admit = (identity: string, wake: boolean) => Promise<{ error?: string }>;
+export type Admit = (identity: string, wake: boolean, reach: boolean, ward: string) => Promise<{ error?: string }>;
 export type Options = {
   oauth: OAuth;
   password: () => string | undefined; // QUO_OWNER_PASSWORD, read at every login
-  admit: Admit; // the daemon: boot or find the avatar for this identity, and enter her
-  user: string; // the user being's name, for the page
+  admit: Admit; // the daemon: boot or find the avatar for this identity in that world, and enter her
+  worlds: () => { ward: string; user: string }[]; // the worlds of this harbor, the first the default: a ward with a public being, and its user being's name
   now?: () => number;
 };
 
@@ -101,7 +101,7 @@ export class Exchange {
       const p = this.o.oauth.pending(request);
       if (!p) return page(400, `<h1>Nothing to allow</h1><p>This request is gone.</p>`), true;
       if (!this.valid(req)) return go(`/login?request=${encodeURIComponent(request)}`), true;
-      return page(200, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), this.o.user)), true;
+      return page(200, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), this.o.worlds())), true;
     }
     if (rest === '/allow' && req.method === 'POST') {
       const f = await readForm(req);
@@ -113,11 +113,14 @@ export class Exchange {
         const out = await this.o.oauth.deny(request);
         return 'redirect' in out ? go(out.redirect) : page(400, `<h1>Gone</h1>`), true;
       }
+      const worlds = this.o.worlds();
+      const world = worlds.find((w) => w.ward === (f.get('ward') ?? worlds[0]?.ward));
+      if (!world) return page(400, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), worlds, 'That is not a world of this harbor.')), true;
       const identity = word(f.get('identity'));
-      if (identity === null || identity === this.o.user || identity === 'desk') return page(400, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), this.o.user, 'An identity is one word, and not the user or the desk.')), true;
-      const admitted = await this.o.admit(identity, f.get('wake') === 'on');
+      if (identity === null || identity === world.user || identity === 'desk') return page(400, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), worlds, 'An identity is one word, and not the user or the desk.')), true;
+      const admitted = await this.o.admit(identity, f.get('wake') === 'on', f.get('reach') === 'on', world.ward);
       if (admitted.error) return page(500, `<h1>Not admitted</h1><p>${esc(admitted.error)}</p>`), true;
-      const out = await this.o.oauth.complete(request, identity);
+      const out = await this.o.oauth.complete(request, identity, world.ward);
       return 'redirect' in out ? go(out.redirect, { 'set-cookie': `${COOKIE}=; Path=/; Max-Age=0` }) : page(400, `<h1>Gone</h1>`), true;
     }
     return false;
@@ -135,12 +138,23 @@ ${err ? `<p class="err">${esc(err)}</p>` : ''}
 <label for="p">Owner password</label><input id="p" name="password" type="password" autocomplete="current-password" autofocus required>
 <button type="submit">Log in</button></form>`;
 
-const allowForm = (request: string, client: string, redirect: string, identity: string, user: string, err = '') => `<h1>Allow ${esc(client)}?</h1>
-<div class="who"><p><strong>${esc(client)}</strong> asks to be an occupant of <strong>${esc(user)}</strong>.</p>
+// The world is a choice when the harbor has more than one; the user named
+// is the first world's, and the page says which world each identity lands in.
+const allowForm = (request: string, client: string, redirect: string, identity: string, worlds: { ward: string; user: string }[], err = '') => {
+  const user = worlds[0]?.user ?? '';
+  const pick =
+    worlds.length > 1
+      ? `<label for="wd">World</label><select id="wd" name="ward">${worlds.map((w) => `<option value="${esc(w.ward)}">${esc(w.ward)}, ${esc(w.user)}'s</option>`).join('')}</select>`
+      : `<input type="hidden" name="ward" value="${esc(worlds[0]?.ward ?? 'main')}">`;
+  return `<h1>Allow ${esc(client)}?</h1>
+<div class="who"><p><strong>${esc(client)}</strong> asks to be an occupant of <strong>${esc(user)}</strong>${worlds.length > 1 ? ', or of another world below' : ''}.</p>
 <p>It will see exactly what ${esc(user)} shows the identity below, and nothing else. You can remove it any time.</p>
 <p>It returns to <code>${esc(redirect)}</code>.</p></div>
 ${err ? `<p class="err">${esc(err)}</p>` : ''}
 <form method="post" action="/allow"><input type="hidden" name="request" value="${esc(request)}">
+${pick}
 <label for="i">Identity</label><input id="i" name="identity" value="${esc(identity)}" pattern="[\\w.-]{1,40}" required>
+<label for="r"><input id="r" name="reach" type="checkbox" style="width:auto"> May reach what ${esc(user)} holds: her standings, acme and the rest, as asks of hers</label>
 <label for="w"><input id="w" name="wake" type="checkbox" style="width:auto"> May wake your other devices: hand an agent an event through ${esc(user)}</label>
 <button type="submit" name="decision" value="allow">Allow</button><button type="submit" name="decision" value="deny">Deny</button></form>`;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quo-systems/dock",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "The dock: what every estate on Quo needs and nobody writes twice. A daemon and the quo command, the front desk, the user being and the avatar, harbors on disk, in a tab and on the edge, the model sides and the screen.",
   "keywords": [
     "quo",
@@ -68,7 +68,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@quo-systems/quo": "^0.2.0",
+    "@quo-systems/quo": "^0.2.2",
     "esbuild": "^0.28.2",
     "ws": "^8.21.3"
   },