leglas-mcp 0.2.0 → 0.4.0

package/README.md

@@ -14,6 +14,12 @@
   <a href="LICENSE"><img src="https://img.shields.io/npm/l/leglas" alt="license"></a>
 </p>
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/pr-assets/rail-single.jpg" width="900" alt="The Leglas interface: a rail of three design directions on the left, and the selected one running as the real app filling the rest of the window" />
+</p>
+
+<p align="center"><i>Every direction in the rail, the selected one running as your actual app. Arrow keys flip between them.</i></p>
+
 Code is becoming the source of truth. Features go from prompt to
 working code in minutes, and mockups/design files eventually lag behind the product and drift out of sync. The
 fastest teams already design in the medium they ship. Leglas is built
@@ -39,6 +45,12 @@ and sessions that clean up after themselves.
 
 ## What you can do with Leglas
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/pr-assets/compare-artboards.jpg" width="900" alt="The Leglas interface: a rail of three design directions on the left, and two of them running side by side as the real app, each labelled with its name." />
+</p>
+
+<p align="center"><i>Two directions for the same page, running side by side as the actual app.</i></p>
+
 - Pick any two variations for side-by-side comparison when it gets hard to choose.
 - Name each direction, drag to reorder and organise your variants, set aside the ones that
   don't feel right. Your actions on every idea survive a long exploration.
@@ -51,12 +63,23 @@ and sessions that clean up after themselves.
   the spread, your agent supplies the taste.
 - Ask for changes without leaving the comparison: describe what you
   want on the direction you're looking at, and Leglas turns it into a
-  precise request for your agent, file path included. Leave
-  `leglas watch --run "claude -p {prompt}"` running in another terminal
-  and your agent picks each request up as you send it. In Claude Code,
-  the Leglas MCP server can also push each request straight into your
-  open session as a channel event (channels are a research preview:
-  start Claude Code with `--dangerously-load-development-channels
+  precise request for your agent, file path included. The composer
+  carries its own agent picker, the way every chat you already use
+  carries a model picker: the CLIs found on your machine (Claude Code,
+  Codex, Cursor) are one click away next to the send button, each asked
+  for its login status so a signed-out CLI says so before a run instead
+  of failing one. Not on that list? Type the command that runs your
+  agent once, in the same menu, and Leglas hands it each request; or
+  connect an agent Leglas can't spawn (an IDE panel, an MCP host) with
+  the copy-paste MCP wiring behind "Connect another agent". Each run
+  reports in a card above the field: who is working, what file they
+  are touching, how long it has been, a stop button while it runs and
+  retry when it fails. Your agent, your subscription, no keys.
+  Prefer a terminal? `npx leglas watch` is the same loop with the
+  agent's own output scrolling by. In Claude Code, the Leglas MCP
+  server can also push each request straight into your open session as
+  a channel event (channels are a research preview: start Claude Code
+  with `--dangerously-load-development-channels
   server:<your leglas server name>`).
 - Keep the winner with one command. Leglas moves it into your source
   tree and clears the exploration away.
@@ -76,66 +99,110 @@ preview of your app root. Add a config file to compare more than one thing.
 
 It works with whatever you're building in. Leglas never imports or
 executes your framework, so the target can be Next, Vite, Remix,
-SvelteKit, Astro, or a folder of static files. Requires Node 24 or
-newer.
+SvelteKit, Astro, or a folder of static files.
+
+## Install
+
+There is nothing you have to install: `npx leglas` fetches the CLI on
+first use and starts from npm's cache after that, and every instruction
+Leglas writes for agents uses the same form, so a fresh clone works
+with no setup at all. Requires Node 24 or newer.
+
+Two optional upgrades:
+
+- `npm install -D leglas` pins the version in a project. Teammates and
+  CI get the same Leglas from their normal install, and `npx` resolves
+  the local copy from then on.
+- `npm install -g leglas` is for typing `leglas` without the prefix.
 
 ## Working with coding agents
 
-Run `leglas init` once. It writes a section into your project's
-`AGENTS.md`, creates a starter config, and gitignores Leglas's working
-directory. That section travels with the repo, so Claude Code, Cursor,
-Codex, or whatever you switch to next opens the project already knowing
-how to add design directions to it. Every command accepts `--json` and
-prints a single machine-readable envelope, so agents drive the same CLI
-you do.
+The fastest way in is the agent skill:
+
+```sh
+npx skills add FredAmartey/leglas
+```
+
+One install, and your agent recognises "give me a few directions for the
+pricing page" as a Leglas exploration in any project, including ones
+that have never seen Leglas. It sets the project up itself and gets to
+work.
+
+In a project, run `npx leglas init` once. It writes a section into your
+project's `AGENTS.md`, creates a starter config, and gitignores Leglas's
+working directory. That section travels with the repo, so Claude Code,
+Cursor, Codex, or whatever you switch to next opens the project already
+knowing how to add design directions to it. Every command accepts
+`--json` and prints a single machine-readable envelope, so agents drive
+the same CLI you do.
 
 The instructions center on one rule: add beside what exists, never
 rewrite it. Two directions that rewrite the same file cannot render from
 one server, and asking an agent to "make the hero calmer" tempts it to
 edit the hero. The supporting commands:
 
-- `leglas explore hero --count 6` briefs the exploration: what the set
+- `npx leglas explore hero --count 6` briefs the exploration: what the set
   is for, why it only works if the six genuinely disagree, and how each
   direction registers. Unbriefed, six requests come back as six variants
   of one idea. With `--based-on "Aurora"` the goal flips: six deliberate
   variants of a direction you already like, and drifting into a new
   direction is the failure. The designs themselves are the agent's;
   Leglas prescribes none.
-- `leglas new hero --from src/Hero.tsx` scaffolds a switcher under
+- `npx leglas new hero --from src/Hero.tsx` scaffolds a switcher under
   `.leglas/variants/hero/`. With `--from`, the baseline re-exports your
   real component, so you never compare against a stale copy. Leglas
   prints the one line to add in your component and does not edit it,
   because rewriting a file it does not understand is how a tool breaks a
   codebase. Scaffolded branch points return the fallback in production
   builds, so a committed one cannot expose an unreleased direction.
-- `leglas classify --change package.json --rewrite src/theme.css` answers
+- `npx leglas classify --change package.json --rewrite src/theme.css` answers
   where a direction should live before it is written. Changing
   dependencies, build configuration, or an existing file's behaviour
   cannot be additive, so those directions build on their own git branch
   and register with `leglas add --branch`. Everything else stays in-app,
   where switching is instant.
-- `leglas show "Aurora" --json` answers for one direction: its entry, the
+- `npx leglas show "Aurora" --json` answers for one direction: its entry, the
   source file behind it, the variants based on it, what it is being compared
   against, and anything still pending on it. Copying a direction from the
   rail hands over a block that ends in this command, so an agent given the
   block can go and get the rest.
-- `leglas keep "Aurora" --to src/components/hero.tsx` moves the winner
+- `npx leglas keep "Aurora" --to src/components/hero.tsx` moves the winner
   into real source and ends the exploration.
 
 Asking for a change works from the interface too. Type what you want
 changed into the field under the rail (or press `R`) and Leglas composes a
 prompt naming the direction and the file behind it, copies it to your
 clipboard, and queues it. The direction it means is the one highlighted
-directly above the field. Your agent drains the queue with `leglas requests --json` and clears
+directly above the field. Your agent drains the queue with `npx leglas requests --json` and clears
 it with `--clear`. Leglas runs no model of its own; your agent already
 knows your conventions and your taste.
 
+The line under the field is the whole status: whether anything is
+listening, what you have queued, and when it has been picked up.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/pr-assets/field-idle.png" width="290" alt="The change field reading: Enter queues it for npx leglas requests" />
+  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/pr-assets/field-queued.png" width="290" alt="The change field reading: one change queued for your agent" />
+  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/pr-assets/field-pickedup.png" width="290" alt="The change field reading: Your agent is on it" />
+</p>
+
+<p align="center"><i>Nothing waiting, then a request queued, then an agent that has taken it.</i></p>
+
+Pick an agent once and the same line shows it working: which file it is
+editing, a cancel if you change your mind, a retry when a run goes
+wrong. `npx leglas watch` in another terminal is the same loop with the
+agent's own output in view, and it needs no flag once an agent has been
+picked in the interface.
+
 ### MCP server
 
 For agent hosts that cannot run shell commands, `leglas-mcp` exposes the
 same operations as MCP tools over stdio: `start`, `add`, `list`, `show`,
 `classify`, `explore`, `scaffold`, `keep`, `requests`, and `init`. Each
 tool calls exactly what the CLI calls and returns the same envelope.
+`watch` is the one command with no tool behind it: it is a loop that
+holds a terminal open, and on a host that speaks channels the server
+already pushes each request into the session as it arrives.
 
 ```sh
 claude mcp add leglas -- npx -y leglas-mcp
@@ -147,9 +214,34 @@ Or in `.mcp.json`:
 { "mcpServers": { "leglas": { "command": "npx", "args": ["-y", "leglas-mcp"] } } }
 ```
 
-The host's working directory names the project. The `start` tool boots
-the viewer and returns its URL, and anything it started stops when the
-session ends.
+The host's working directory names the project, the same contract as the
+CLI. A host that starts the server somewhere else is asked where the
+project is, over MCP roots. The `start` tool boots the viewer and returns
+its URL, and anything it started stops when the session ends.
+
+### As an Agent Plugin
+
+The repository is also an [Agent Plugin](https://agent-plugins.org), the
+open standard for shipping Agent Skills and MCP server configuration in
+one format. Clients that implement it install the skill and the server
+together, instead of the two steps above. It is a layout rather than a
+build: `plugin.json` and `mcp.json` at the root, the skill in
+`skills/leglas/`, nothing generated.
+
+An Agent Plugins client starts a plugin's server in the plugin's own
+install directory rather than the project, so on that path the working
+directory names a copy of Leglas and nothing else. The server therefore
+takes the project from the workspace the host declares over MCP roots,
+and the working directory only when it sits inside one. If a host offers
+neither, `LEGLAS_PROJECT_DIR` names the project outright; without it the
+tools report that there is no project rather than writing into a plugin
+cache. `mcp.json` passes `${PLUGIN_ROOT}` for exactly that check, and
+nothing else.
+
+The plugin's version covers the skill and the configuration, not the
+server it launches: `npx` fetches the current `leglas-mcp` the same way
+every `npx leglas` in these instructions fetches the current CLI, which
+keeps both faces of Leglas on one version in a project they share.
 
 ## Configuration
 
@@ -203,6 +295,15 @@ what you want for the last two directions in contention: press `C`, or
 hover a direction and press its compare button, and it becomes the right
 pane while the active direction holds the left.
 
+A split does not hand each side half the room. An app given half the room
+crosses its own breakpoints and draws a different design, so you would be
+choosing between two narrow renderings of directions meant for the wide
+one. Instead each side is drawn at the width it had on its own and scaled
+to fit, keeping the same proportions, so nothing reflows and flipping and
+splitting agree about what the design is. Each pane says the width it is
+drawn at and the scale it is shown at. If you want the narrow rendering,
+that is what the tools popover's "Scale each side to fit" switch is for.
+
 Arrows move between directions, `1` to `9` jump straight to one, `R` asks
 for a change to the one you are on, `Cmd K` (`Ctrl K` elsewhere) searches
 and `B` collapses the rail. Press `?` for the whole keymap.

package/dist/bin.js

@@ -3,10 +3,12 @@ import { createRequire } from "node:module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CHANNEL_CAPABILITY, CHANNEL_INSTRUCTIONS, startChannel } from "./channel.js";
+import { hostProject } from "./project.js";
 import { registerLeglasTools } from "./tools.js";
 /**
- * The stdio face. An agent host spawns this in the project directory, which
- * is the same contract as the CLI: the working directory names the project.
+ * The stdio face. A host that spawns this in the project directory gets the
+ * CLI's contract, where the working directory names the project; a host that
+ * spawns it somewhere else is asked where the project is. See project.ts.
  */
 function version() {
     const require = createRequire(import.meta.url);
@@ -18,7 +20,12 @@ const server = new McpServer({ name: "leglas", version: version() },
 // speak channels; on Claude Code they let change requests from the
 // interface arrive in the open session as events.
 { capabilities: { experimental: CHANNEL_CAPABILITY }, instructions: CHANNEL_INSTRUCTIONS });
-const tools = registerLeglasTools(server, { cwd: process.cwd() });
+const project = hostProject(server.server, {
+    cwd: process.cwd(),
+    override: process.env["LEGLAS_PROJECT_DIR"],
+    pluginRoot: process.env["LEGLAS_PLUGIN_ROOT"],
+});
+const tools = registerLeglasTools(server, { project });
 let channel = null;
 let stopping = false;
 const shutdown = async () => {
@@ -39,4 +46,4 @@ transport.onclose = () => {
 };
 await server.connect(transport);
 // Only after connect: a notification with no transport throws.
-channel = startChannel(server, { cwd: process.cwd() });
+channel = startChannel(server, { project });

package/dist/channel.d.ts

@@ -1,5 +1,6 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type PendingRequest } from "leglas";
+import type { Project } from "./project.js";
 /**
  * The push face, for hosts that treat an MCP server as a channel.
  *
@@ -51,7 +52,7 @@ export type Channel = {
  * because the queue file still holds the request.
  */
 export declare function startChannel(server: McpServer, options: {
-    cwd: string;
+    project: Project;
     pollMs?: number;
     /** Tests gate this to force overlapping polls; production reads the file. */
     read?: (cwd: string) => Promise<PendingRequest[]>;

package/dist/channel.js

@@ -70,7 +70,16 @@ export function startChannel(server, options) {
         }
     };
     const push = async () => {
-        const fresh = unpushed(await read(options.cwd), pushed);
+        // The first poll waits here for the host to initialize, which is what
+        // makes the queue this reads the project's rather than whatever directory
+        // the process happened to start in.
+        const located = await options.project.locate();
+        if (!located.ok) {
+            // Settled for the life of the process, so there is no queue coming.
+            clearInterval(timer);
+            return;
+        }
+        const fresh = unpushed(await read(located.directory), pushed);
         for (const request of fresh) {
             pushed.add(request.id);
             try {

package/dist/engagement.d.ts

@@ -0,0 +1,19 @@
+export type EngagementDeps = {
+    post?: (watching: boolean) => Promise<void>;
+    setInterval?: (callback: () => void, milliseconds: number) => unknown;
+    clearInterval?: (handle: unknown) => void;
+    now?: () => number;
+};
+export type Engagement = {
+    /**
+     * Note queue activity: starts the beat, or extends it. The returned
+     * promise settles once the server has had its chance to register the
+     * engagement; the caller awaits it before reading the queue, because the
+     * embedded runner backs off only after that registration lands. Watch
+     * closes the same handoff race the same way with its first heartbeat.
+     */
+    touch(): Promise<void>;
+    /** End the engagement and say so, as far as one best-effort post goes. */
+    stop(): Promise<void>;
+};
+export declare function createEngagement(deps?: EngagementDeps): Engagement;

package/dist/engagement.js

@@ -0,0 +1,68 @@
+import { DEFAULT_PORT, LEGLAS_PREFIX } from "leglas";
+/**
+ * Tell the Leglas server an agent is working the queue over MCP.
+ *
+ * The embedded runner yields to an attached watcher, and an MCP host driving
+ * the requests tool deserves the same right of way: without this, the runner
+ * could grab a request that arrives while the host's agent is mid-change in
+ * the same tree. Attachment is engagement, not connection: an MCP server sits
+ * connected to its host for hours doing nothing, so merely being alive proves
+ * nothing. Touch marks real queue activity, the beat keeps the server's
+ * window fresh, and a quiet spell lets it lapse.
+ */
+/** How often the server hears from an engaged session; matches watch. */
+const BEAT_MS = 2000;
+/** Queue work older than this no longer counts as engagement. */
+const ENGAGEMENT_MS = 120_000;
+/** A beat is worth a moment, never a stall. */
+const POST_TIMEOUT_MS = 1000;
+function defaultPost(watching) {
+    // Best effort at the default port: the queue is a file and every tool works
+    // without the server, so a beat that lands nowhere costs nothing. LEGLAS_PORT
+    // covers the server that had to bind elsewhere.
+    const port = Number(process.env.LEGLAS_PORT ?? "") || DEFAULT_PORT;
+    return fetch(`http://localhost:${port}${LEGLAS_PREFIX}/api/watch`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ watching }),
+        signal: AbortSignal.timeout(POST_TIMEOUT_MS),
+    }).then(() => { }, () => { });
+}
+export function createEngagement(deps = {}) {
+    const post = deps.post ?? defaultPost;
+    const setEvery = deps.setInterval ?? ((callback, milliseconds) => setInterval(callback, milliseconds));
+    const clearEvery = deps.clearInterval ?? ((handle) => clearInterval(handle));
+    const now = deps.now ?? (() => Date.now());
+    let timer = null;
+    let lastTouch = 0;
+    const quiet = () => {
+        if (timer === null)
+            return;
+        clearEvery(timer);
+        timer = null;
+    };
+    const beat = () => {
+        if (now() - lastTouch > ENGAGEMENT_MS) {
+            quiet();
+            void post(false);
+            return;
+        }
+        void post(true);
+    };
+    return {
+        touch() {
+            lastTouch = now();
+            // Mid-cycle the server already knows: nothing to wait for.
+            if (timer !== null)
+                return Promise.resolve();
+            timer = setEvery(beat, BEAT_MS);
+            return post(true).catch(() => { });
+        },
+        async stop() {
+            const wasBeating = timer !== null;
+            quiet();
+            if (wasBeating)
+                await post(false);
+        },
+    };
+}

package/dist/index.d.ts

@@ -2,3 +2,5 @@ export { registerLeglasTools } from "./tools.js";
 export type { LeglasTools } from "./tools.js";
 export { CHANNEL_CAPABILITY, CHANNEL_INSTRUCTIONS, CHANNEL_POLL_MS, channelEvent, startChannel, unpushed, } from "./channel.js";
 export type { Channel, ChannelEvent } from "./channel.js";
+export { UNRESOLVED_PROJECT, fixedProject, hostProject } from "./project.js";
+export type { HostProjectOptions, Located, Project, RootsHost } from "./project.js";

package/dist/index.js

@@ -1,2 +1,3 @@
 export { registerLeglasTools } from "./tools.js";
 export { CHANNEL_CAPABILITY, CHANNEL_INSTRUCTIONS, CHANNEL_POLL_MS, channelEvent, startChannel, unpushed, } from "./channel.js";
+export { UNRESOLVED_PROJECT, fixedProject, hostProject } from "./project.js";

package/dist/project.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Which project the tools act on.
+ *
+ * Every other face of Leglas learns this the same easy way: the CLI runs in
+ * the project, so the working directory is the answer. An MCP server is not
+ * always so lucky. An Agent Plugins client starts a plugin's server in the
+ * plugin's own install directory (Agent Plugins 1.0.0 §7.2.1), which holds a
+ * copy of Leglas and never a project anyone is designing. Taken at face value
+ * there, the working directory would send `init` into a plugin cache, leave
+ * the rail empty, and report all of it as success.
+ *
+ * So the directory is asked for rather than assumed:
+ *
+ * 1. `LEGLAS_PROJECT_DIR`, when someone has said outright where to work.
+ * 2. The workspace the host declares over MCP roots, which is the project it
+ *    has open. The working directory wins when it sits inside one of those
+ *    roots, because a host started in `packages/app` means that, not the
+ *    repository above it. Several roots and no match takes the first, which
+ *    is a guess, and the reason the override above exists.
+ * 3. The working directory, which is the right answer for every host that
+ *    starts the server in the project, and the reason nothing changes for
+ *    `claude mcp add` or a hand-written `.mcp.json`.
+ *
+ * When none of those name a project, the tools say so. Refusing is the whole
+ * point: a wrong directory is worse than no directory, because it writes.
+ */
+export type Located = {
+    ok: true;
+    directory: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export type Project = {
+    /**
+     * The project directory, resolved once and held for the life of the process.
+     * A viewer, a request queue, and a channel all bind to one project, so a
+     * session that changed its mind halfway would already have a server running
+     * against the old one.
+     */
+    locate(): Promise<Located>;
+};
+/** A project fixed to one directory: what an embedder or a test already knows. */
+export declare function fixedProject(directory: string): Project;
+/**
+ * The part of an MCP server this needs. The SDK's `Server` satisfies it
+ * structurally, which keeps the resolution testable without a transport.
+ */
+export type RootsHost = {
+    getClientCapabilities(): {
+        roots?: unknown;
+    } | undefined;
+    listRoots(): Promise<{
+        roots: {
+            uri: string;
+        }[];
+    }>;
+    oninitialized?: (() => void) | undefined;
+};
+export type HostProjectOptions = {
+    /** The process working directory. */
+    cwd: string;
+    /** `LEGLAS_PROJECT_DIR`: an explicit answer that ends the search. */
+    override?: string | undefined;
+    /**
+     * `LEGLAS_PLUGIN_ROOT`: where an Agent Plugins client installed us, which
+     * the plugin's own `mcp.json` passes as `${PLUGIN_ROOT}`. Its only use is
+     * recognising a working directory that means nothing.
+     */
+    pluginRoot?: string | undefined;
+};
+/**
+ * Worded for every way the search comes up empty: a host with no roots, a host
+ * with an empty workspace, and a host that failed to answer. Naming only the
+ * first would describe the others wrongly.
+ */
+export declare const UNRESOLVED_PROJECT: string;
+export declare function hostProject(host: RootsHost, options: HostProjectOptions): Project;

package/dist/project.js

@@ -0,0 +1,102 @@
+import { realpathSync } from "node:fs";
+import { isAbsolute, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+/** A project fixed to one directory: what an embedder or a test already knows. */
+export function fixedProject(directory) {
+    const located = { ok: true, directory };
+    return { locate: async () => located };
+}
+/**
+ * Worded for every way the search comes up empty: a host with no roots, a host
+ * with an empty workspace, and a host that failed to answer. Naming only the
+ * first would describe the others wrongly.
+ */
+export const UNRESOLVED_PROJECT = "Leglas could not tell which project to work in. This agent host started the " +
+    "Leglas MCP server in the plugin's own directory and named no workspace to " +
+    "work in, so there is no project here to act on. Set LEGLAS_PROJECT_DIR to " +
+    "the project directory, or run the leglas CLI in the project instead.";
+export function hostProject(host, options) {
+    let pending = null;
+    return { locate: () => (pending ??= discover(host, options)) };
+}
+async function discover(host, options) {
+    const override = options.override?.trim();
+    if (override !== undefined && override !== "") {
+        return { ok: true, directory: resolve(override) };
+    }
+    const cwd = canonical(options.cwd);
+    const roots = await declaredRoots(host);
+    if (roots.some((root) => contains(canonical(root), cwd))) {
+        return { ok: true, directory: options.cwd };
+    }
+    const first = roots[0];
+    if (first !== undefined)
+        return { ok: true, directory: first };
+    const pluginRoot = options.pluginRoot?.trim();
+    // A client that does not expand ${PLUGIN_ROOT} leaves the literal behind; it
+    // matches no real directory, so the check simply does not fire.
+    if (pluginRoot !== undefined && pluginRoot !== "" && contains(canonical(pluginRoot), cwd)) {
+        return { ok: false, reason: UNRESOLVED_PROJECT };
+    }
+    return { ok: true, directory: options.cwd };
+}
+async function declaredRoots(host) {
+    await initialized(host);
+    if (host.getClientCapabilities()?.roots === undefined)
+        return [];
+    try {
+        const { roots } = await host.listRoots();
+        return roots
+            .map((root) => toDirectory(root.uri))
+            .filter((directory) => directory !== null);
+    }
+    catch {
+        // A host that advertises roots and then refuses to list them has told us
+        // nothing, which leaves the working directory as good a guess as before.
+        return [];
+    }
+}
+/**
+ * Roots can only be asked for once the client has initialized; asking earlier
+ * is a protocol error. A stdio server is connected well before a host gets
+ * around to initializing, and the channel starts polling immediately, so this
+ * wait is the ordinary path rather than an edge case.
+ */
+function initialized(host) {
+    if (host.getClientCapabilities() !== undefined)
+        return Promise.resolve();
+    return new Promise((ready) => {
+        const previous = host.oninitialized;
+        host.oninitialized = () => {
+            previous?.();
+            ready();
+        };
+    });
+}
+/** Roots are file URIs by the spec; a host that sends a bare path still reads. */
+function toDirectory(uri) {
+    if (uri.startsWith("file:")) {
+        try {
+            return fileURLToPath(uri);
+        }
+        catch {
+            return null;
+        }
+    }
+    return isAbsolute(uri) ? uri : null;
+}
+function contains(parent, child) {
+    if (child === parent)
+        return true;
+    return child.startsWith(parent.endsWith(sep) ? parent : parent + sep);
+}
+/** Compared paths are real paths: /tmp is a symlink on macOS, among others. */
+function canonical(directory) {
+    const absolute = resolve(directory);
+    try {
+        return realpathSync(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}

package/dist/tools.d.ts

@@ -1,8 +1,11 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type Engagement } from "./engagement.js";
+import type { Project } from "./project.js";
 export type LeglasTools = {
     /** Stop anything the tools started. Wired to the transport's close. */
     shutdown(): Promise<void>;
 };
 export declare function registerLeglasTools(server: McpServer, options: {
-    cwd: string;
+    project: Project;
+    engagement?: Engagement;
 }): LeglasTools;

package/dist/tools.js

@@ -1,5 +1,6 @@
 import { run, runAdd, runClassify, runExplore, runInit, runKeep, runList, runNew, runRequests, runShow, } from "leglas";
 import { z } from "zod";
+import { createEngagement } from "./engagement.js";
 async function capture(invoke) {
     const lines = [];
     const deps = {
@@ -23,11 +24,30 @@ async function capture(invoke) {
     }
     return { content: [{ type: "text", text: lines.join("\n") }], isError: exitCode !== 0 };
 }
+/**
+ * Run a command in the project, or report that there is no project to run it
+ * in. Resolution is asked for on the first call and held after that, so the
+ * cost lands once and every tool acts on the same directory.
+ */
+async function inProject(project, invoke) {
+    const located = await project.locate();
+    if (!located.ok) {
+        // The CLI's shape for a failure, so a host parses this like any other.
+        return {
+            content: [{ type: "text", text: JSON.stringify({ ok: false, error: located.reason }) }],
+            isError: true,
+        };
+    }
+    return capture((deps) => invoke(located.directory, deps));
+}
 export function registerLeglasTools(server, options) {
-    const cwd = options.cwd;
+    const project = options.project;
     // One viewer per MCP process. The handle is held so a host that dies or
     // disconnects never leaves a dev server running on a port nobody remembers.
     let viewer = null;
+    // Working the queue over MCP counts as attachment, exactly like watch: the
+    // embedded runner must not race a host's agent for the same tree.
+    const engagement = options.engagement ?? createEngagement();
     server.registerTool("start", {
         title: "Start the Leglas viewer",
         description: "Boot the Leglas server for this project and return the interface URL. " +
@@ -46,7 +66,7 @@ export function registerLeglasTools(server, options) {
                 ],
             };
         }
-        return capture(async (deps) => {
+        return inProject(project, async (cwd, deps) => {
             const result = await run({ port, userPort: undefined, configPath: undefined, open: false, json: true, cwd }, { open: async () => { }, log: deps.log });
             viewer = result;
             return result;
@@ -71,12 +91,12 @@ export function registerLeglasTools(server, options) {
             basedOn: z.string().optional()
                 .describe("Title of the direction this is a variant of; the rail groups the family."),
         },
-    }, async ({ title, url, note, tags, branch, file, basedOn }) => capture((deps) => runAdd({ preview: { title, url, note, tags, branch, file, basedOn }, json: true, cwd }, deps)));
+    }, async ({ title, url, note, tags, branch, file, basedOn }) => inProject(project, (cwd, deps) => runAdd({ preview: { title, url, note, tags, branch, file, basedOn }, json: true, cwd }, deps)));
     server.registerTool("list", {
         title: "List previews",
         description: "Every preview, shared and local, with its URL and backing branch if any.",
         inputSchema: {},
-    }, async () => capture((deps) => runList({ json: true, cwd }, deps)));
+    }, async () => inProject(project, (cwd, deps) => runList({ json: true, cwd }, deps)));
     server.registerTool("show", {
         title: "Inspect one direction",
         description: "Everything Leglas knows about one direction: its full entry, the source file behind " +
@@ -89,7 +109,7 @@ export function registerLeglasTools(server, options) {
                 .min(1)
                 .describe("The direction's title as the config spells it, not a renamed display name."),
         },
-    }, async ({ title }) => capture((deps) => runShow({ title, json: true, cwd }, deps)));
+    }, async ({ title }) => inProject(project, (cwd, deps) => runShow({ title, json: true, cwd }, deps)));
     server.registerTool("classify", {
         title: "Decide where a direction should live",
         description: "Before writing a direction, declare what it will touch and learn whether it can be " +
@@ -103,7 +123,7 @@ export function registerLeglasTools(server, options) {
             }))
                 .min(1),
         },
-    }, async ({ changes }) => capture((deps) => runClassify({ changes, json: true, cwd }, deps)));
+    }, async ({ changes }) => inProject(project, (cwd, deps) => runClassify({ changes, json: true, cwd }, deps)));
     server.registerTool("explore", {
         title: "Brief an exploration",
         description: "What a set for a surface needs and how it registers here. Directions must genuinely " +
@@ -118,7 +138,9 @@ export function registerLeglasTools(server, options) {
                 .optional()
                 .describe("An existing direction's title: ask for variants of it instead of new directions."),
         },
-    }, async ({ surface, count, basedOn }) => capture((deps) => runExplore({ surface, count: count ?? 3, basedOn: basedOn ?? null, json: true }, deps)));
+    }, async ({ surface, count, basedOn }) => capture((deps) => 
+    // The brief is the same wherever it is read from; it touches no project.
+    runExplore({ surface, count: count ?? 3, basedOn: basedOn ?? null, json: true }, deps)));
     server.registerTool("scaffold", {
         title: "Scaffold a branch point",
         description: "Create a switcher and a first direction for a surface under .leglas/variants/. " +
@@ -128,7 +150,7 @@ export function registerLeglasTools(server, options) {
             from: z.string().optional().describe("Path of the component rendering this surface today."),
             print: z.boolean().optional().describe("Print the scaffold instead of writing it."),
         },
-    }, async ({ surface, from, print }) => capture((deps) => runNew({ surface, print: print ?? false, json: true, from, cwd }, deps)));
+    }, async ({ surface, from, print }) => inProject(project, (cwd, deps) => runNew({ surface, print: print ?? false, json: true, from, cwd }, deps)));
     server.registerTool("keep", {
         title: "Keep a winner",
         description: "Move the winning direction into real source, delete the rest of the exploration, and " +
@@ -137,28 +159,37 @@ export function registerLeglasTools(server, options) {
             title: z.string().min(1).describe("Title of the direction to keep."),
             to: z.string().min(1).describe("Path in real source where the winner should live."),
         },
-    }, async ({ title, to }) => capture((deps) => runKeep({ title, to, json: true, cwd }, deps)));
+    }, async ({ title, to }) => inProject(project, (cwd, deps) => runKeep({ title, to, json: true, cwd }, deps)));
     server.registerTool("requests", {
         title: "Collect change requests",
         description: "Pending change requests made from the interface, each naming the direction and the file " +
             "behind it. Call this when starting work in a project that uses Leglas, and again before " +
             "changing any direction: the user may have described the change from the interface while " +
-            "you worked, and collecting marks it picked up there. Pass clear once they are done.",
+            "you worked, and collecting marks it picked up there. Pass clear once they are done: it " +
+            "drops what you collected and reports anything that arrived since, which is yours to do next.",
         inputSchema: {
             clear: z.boolean().optional(),
         },
-    }, async ({ clear }) => capture((deps) => runRequests({ json: true, clear: clear ?? false, cwd }, deps)));
+    }, async ({ clear }) => {
+        // Touched on every call, empty queue included: an agent that just asked
+        // is an agent about to act, and the beat lapses on its own once the
+        // asking stops. Awaited before the queue is read so the runner has
+        // backed off by the time this session could collect anything.
+        await engagement.touch();
+        return inProject(project, (cwd, deps) => runRequests({ json: true, clear: clear ?? false, cwd }, deps));
+    });
     server.registerTool("init", {
         title: "Prepare a project",
         description: "Write the AGENTS.md section, a starter config, and the gitignore entry into this project.",
         inputSchema: {
             force: z.boolean().optional().describe("Rewrite the AGENTS.md section if it exists."),
         },
-    }, async ({ force }) => capture((deps) => runInit({ cwd, force: force ?? false, json: true }, deps)));
+    }, async ({ force }) => inProject(project, (cwd, deps) => runInit({ cwd, force: force ?? false, json: true }, deps)));
     return {
         shutdown: async () => {
             const running = viewer;
             viewer = null;
+            await engagement.stop().catch(() => { });
             await running?.stop().catch(() => { });
         },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "leglas-mcp",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Stdio MCP server exposing Leglas to agent hosts that cannot run a shell.",
   "type": "module",
   "bin": {
@@ -15,7 +15,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^3.25.76",
-    "leglas": "^0.2.0"
+    "leglas": "^0.4.0"
   },
   "license": "MIT",
   "repository": {