@intentius/chant 0.89.0 → 0.90.0

package/src/cli/mcp/server.ts

@@ -8,7 +8,9 @@ import { scaffoldTool, createScaffoldHandler } from "./tools/scaffold";
 import { searchTool, createSearchHandler } from "./tools/search";
 import { compositesTool, createCompositesHandler } from "./tools/composites";
 import type { LexiconPlugin } from "../../lexicon";
-import type { McpRequest, McpResponse, McpRequestMeta, ToolDefinition, ToolHandler, ResourceDefinition } from "./types";
+import type { McpClientInfo, McpRequest, McpResponse, McpRequestMeta, ToolDefinition, ToolHandler, ResourceDefinition } from "./types";
+import { findWorkspaceRoot } from "../../project-root";
+import { createWorkspaceTools, type WorkspaceToolsOptions } from "./workspace-tools";
 import { createSnapshotTool, createDiffTool } from "./lifecycle-tools";
 import { setGateOrigin } from "../../lifecycle/gate-origin";
 import { createOpListTool, createOpRunTool, createOpStatusTool, createOpApproveTool, createOpReportTool } from "./op-tools";
@@ -47,14 +49,14 @@ export function negotiateProtocolVersion(requested: string | undefined): string
  * sends on `initialize`. Read-side only — the server holds no handshake
  * state to update (#1194).
  */
-export function parseMeta(params: Record<string, unknown>): { protocolVersion?: string; clientInfo?: { name: string; version?: string } } {
+export function parseMeta(params: Record<string, unknown>): { protocolVersion?: string; clientInfo?: McpClientInfo } {
   const meta = (params._meta ?? {}) as McpRequestMeta;
   const protocolVersion =
     (typeof meta.protocolVersion === "string" ? meta.protocolVersion : undefined) ??
     (typeof params.protocolVersion === "string" ? params.protocolVersion : undefined);
   const clientInfo =
     meta["io.modelcontextprotocol/clientInfo"] ??
-    (params.clientInfo as { name: string; version?: string } | undefined);
+    (params.clientInfo as McpClientInfo | undefined);
   return { protocolVersion, clientInfo };
 }
 
@@ -94,14 +96,20 @@ export class McpServer {
   private pluginResources: Map<string, { definition: ResourceDefinition; handler: () => Promise<string> }> = new Map();
   private plugins: LexiconPlugin[];
   private instructions: string | undefined;
+  /** The `clientInfo` the client gave on `initialize`, for a request that carries none in `_meta` (#2707). */
+  private clientInfo: McpClientInfo | undefined;
 
   /**
    * `options.instructions` is sent as the `initialize` result's
    * `instructions`, the text a client may give its model about this server.
    * Only a workspace root with no lexicon of its own sets it (#2700), to say
    * which members' lexicons were loaded.
+   *
+   * `options.workspace` names the directory the server serves (#2707). When
+   * it is at or inside a declared workspace, the workspace read-contract and
+   * record-write tools are served too.
    */
-  constructor(plugins?: LexiconPlugin[], options: { instructions?: string } = {}) {
+  constructor(plugins?: LexiconPlugin[], options: { instructions?: string; workspace?: WorkspaceToolsOptions } = {}) {
     this.plugins = plugins ?? [];
     this.instructions = options.instructions;
     // Register core tools
@@ -126,6 +134,11 @@ export class McpServer {
       this.registerTool(t.definition, t.handler);
     }
 
+    // Workspace reads and record writes (#2707), inside a declared workspace only.
+    if (options.workspace && findWorkspaceRoot(options.workspace.cwd)) {
+      for (const t of createWorkspaceTools(options.workspace)) this.registerTool(t.definition, t.handler);
+    }
+
     // Register plugin contributions
     if (plugins) {
       for (const plugin of plugins) {
@@ -244,6 +257,8 @@ export class McpServer {
   private async dispatch(method: string, params: Record<string, unknown>): Promise<unknown> {
     switch (method) {
       case "initialize":
+        // Kept for a write's source block (#2707): a prior-revision client names itself only here.
+        this.clientInfo = parseMeta(params).clientInfo ?? this.clientInfo;
         // Answered for prior-revision clients too — negotiated, not hard-coded (#1194).
         return this.buildInitializeResult(params);
 
@@ -290,7 +305,9 @@ export class McpServer {
     }
 
     try {
-      const result = await handler(toolParams);
+      // The client, from this request's _meta (2026-07-28) or else from initialize.
+      const clientInfo = parseMeta(params).clientInfo ?? this.clientInfo;
+      const result = await handler(toolParams, clientInfo ? { clientInfo } : {});
       const isStructured = typeof result === "object" && result !== null;
       return {
         content: [
@@ -374,6 +391,6 @@ export async function startMcpServer(): Promise<void> {
     // Start without plugins if resolution fails
   }
 
-  const server = new McpServer(plugins);
+  const server = new McpServer(plugins, { workspace: { cwd: process.cwd() } });
   server.start();
 }

package/src/cli/mcp/types.ts

@@ -32,7 +32,7 @@ export interface McpResponse {
  */
 export interface McpRequestMeta {
   protocolVersion?: string;
-  "io.modelcontextprotocol/clientInfo"?: { name: string; version?: string };
+  "io.modelcontextprotocol/clientInfo"?: McpClientInfo;
 }
 
 /**
@@ -68,4 +68,17 @@ export interface ResourceDefinition {
   mimeType?: string;
 }
 
-export type ToolHandler = (params: Record<string, unknown>) => Promise<unknown>;
+/** The MCP client's `clientInfo`, as it gave it on `initialize` or in a request's `_meta`. */
+export interface McpClientInfo {
+  name: string;
+  version?: string;
+  title?: string;
+}
+
+/** What a handler knows about the call beyond its arguments (#2707). */
+export interface ToolContext {
+  /** The client that made the call, when it said. */
+  clientInfo?: McpClientInfo;
+}
+
+export type ToolHandler = (params: Record<string, unknown>, context?: ToolContext) => Promise<unknown>;

package/src/cli/mcp/workspace-tools.test.ts

@@ -0,0 +1,198 @@
+/**
+ * #2707 — chant serve mcp's workspace tools: served at or inside a declared
+ * workspace, reads that return the CLI's documents, and writes that keep the
+ * CLI's rules and say they came through MCP in the record's source block
+ * (#2708). Run against the workspace the reader conformance suite generates.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { createConformanceWorkspace, defaultChantCommand, mcpToolCall, type ConformanceWorkspace } from "../../workspace/conformance";
+import { McpServer } from "./server";
+import { workspaceReadTools, workspaceWriteTools } from "./workspace-tools";
+
+const KIND = "decisions/decision.kind.mjs";
+const chant = defaultChantCommand();
+
+let ws: ConformanceWorkspace;
+beforeAll(() => {
+  ws = createConformanceWorkspace({ chantCommand: chant });
+}, 300_000);
+afterAll(() => ws?.dispose());
+
+type Result = { isError?: boolean; structuredContent?: Record<string, unknown>; content: { text: string }[] };
+
+function server(cwd = ws.dir): McpServer {
+  return new McpServer([], { workspace: { cwd, chantCommand: chant } });
+}
+
+let nextId = 1;
+async function rpc(s: McpServer, method: string, params: Record<string, unknown> = {}): Promise<unknown> {
+  const res = await s.handleRequest({ jsonrpc: "2.0", id: nextId++, method, params });
+  if (res.error) throw new Error(res.error.message);
+  return res.result;
+}
+
+async function call(s: McpServer, name: string, args: Record<string, unknown>, meta?: Record<string, unknown>): Promise<Result> {
+  return (await rpc(s, "tools/call", { name, arguments: args, ...(meta ? { _meta: meta } : {}) })) as Result;
+}
+
+function cli(argv: string[], env: NodeJS.ProcessEnv = {}): unknown {
+  let out: string;
+  try {
+    out = execFileSync(chant[0], [...chant.slice(1), ...argv], { cwd: ws.dir, encoding: "utf-8", env: { ...process.env, NO_COLOR: "1", ...env }, stdio: ["ignore", "pipe", "pipe"] });
+  } catch (e) {
+    out = String((e as { stdout?: string }).stdout ?? "");
+  }
+  return JSON.parse(out);
+}
+
+/** A proposed decision's fields, with no id, state or source. */
+function proposal(title: string): Record<string, unknown> {
+  return {
+    schema: 1,
+    title,
+    area: "delivery",
+    question: "Where do the app's logs go?",
+    options: [
+      { id: "a", label: "stdout", how: "The app writes to stdout and the runtime collects it.", tradeoff: "Nothing to configure." },
+      { id: "b", label: "a file", how: "The app writes a file.", tradeoff: "A volume to manage." },
+    ],
+    choice: null,
+    rejected: [],
+    supersedes: [],
+    evidence: [],
+    decided_by: null,
+    decided_on: null,
+    reviews: [],
+    constrains: ["member:app"],
+  };
+}
+
+type RecordView = { id: string; state: string; valid: boolean; data: Record<string, unknown>; quorum?: { agreed: number; met: boolean } };
+function recordsOf(doc: unknown): RecordView[] {
+  return (doc as { records: RecordView[] }).records;
+}
+
+describe("which servers have the workspace tools", () => {
+  const names = [...workspaceReadTools, ...workspaceWriteTools].map((t) => t.name);
+
+  test("a server at or inside a declared workspace lists them", async () => {
+    for (const cwd of [ws.dir, join(ws.dir, "decisions")]) {
+      const { tools } = (await rpc(server(cwd), "tools/list")) as { tools: { name: string }[] };
+      expect(tools.map((t) => t.name)).toEqual(expect.arrayContaining(names));
+    }
+    expect(names).toEqual(["workspace-ls", "workspace-status", "workspace-graph", "workspace-records", "records-new", "records-amend", "records-review", "records-close"]);
+  });
+
+  test("a server outside any workspace, or given none, does not", async () => {
+    const outside = realpathSync(mkdtempSync(join(tmpdir(), "chant-mcp-no-ws-")));
+    try {
+      for (const s of [server(outside), new McpServer([])]) {
+        const { tools } = (await rpc(s, "tools/list")) as { tools: { name: string }[] };
+        expect(tools.map((t) => t.name).filter((n) => names.includes(n))).toEqual([]);
+      }
+    } finally {
+      rmSync(outside, { recursive: true, force: true });
+    }
+  });
+
+  test("the descriptions say records are proposals and by names who decided", () => {
+    for (const t of workspaceWriteTools) expect(t.description).toMatch(/proposals until they are reviewed.*by must name the person or agent that actually decided/s);
+  });
+});
+
+describe("reads", () => {
+  test("workspace-records returns the document chant workspace records --json prints", async () => {
+    const s = server();
+    const res = await call(s, "workspace-records", { kind: KIND });
+    expect(res.isError).toBeUndefined();
+    expect(res.structuredContent).toEqual(cli(["workspace", "records", "--kind", KIND, "--json"]));
+    const only = await call(s, "workspace-records", { kind: KIND, id: "fix-001" });
+    expect(recordsOf(only.structuredContent).map((r) => r.id)).toEqual(["fix-001"]);
+  }, 120_000);
+
+  test("an error document is returned as a document, and a flag-shaped value is refused before chant runs", async () => {
+    const s = server();
+    const missing = await call(s, "workspace-records", { kind: "nowhere/none.kind.mjs" });
+    expect(missing.structuredContent).toMatchObject({ error: { code: "kind-unreadable" } });
+    const flag = await call(s, "workspace-ls", { at: "--output=/tmp/x" });
+    expect(flag.isError).toBe(true);
+    expect(flag.content[0].text).toMatch(/at may not start with -/);
+  }, 120_000);
+
+  test("the conformance suite's argv maps to the tool that answers it", () => {
+    expect(mcpToolCall(["workspace", "records", "--kind", KIND, "--json"])).toEqual({ name: "workspace-records", arguments: { kind: KIND } });
+    expect(mcpToolCall(["workspace", "status", "dev", "--json"])).toEqual({ name: "workspace-status", arguments: { env: "dev" } });
+    expect(mcpToolCall(["workspace", "graph", "--intent", "a.mjs:1", "--kind", KIND, "--json"])).toEqual({ name: "workspace-graph", arguments: { intent: "a.mjs:1", kind: [KIND] } });
+    expect(mcpToolCall(["workspace", "graph", "--composites", "--json"])).toEqual({ name: "workspace-graph", arguments: { composites: true } });
+    expect(mcpToolCall(["workspace", "check", "--format", "json"])).toBeUndefined();
+  });
+});
+
+describe("writes", () => {
+  test("records-new proposes a decision with MCP in its source, records reads it, and reviews move its quorum", async () => {
+    const s = server();
+    await rpc(s, "initialize", { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "claude-code", version: "2.1.0" } });
+    const made = await call(s, "records-new", { kind: KIND, record: proposal("Where the logs go") });
+    expect(made.structuredContent).toMatchObject({ id: "fix-002", dryRun: false });
+    const read = recordsOf(cli(["workspace", "records", "--kind", KIND, "--json"])).find((r) => r.id === "fix-002")!;
+    expect(read).toMatchObject({ state: "proposed", valid: true });
+    expect(read.data.source).toEqual({ via: "mcp", client: { name: "claude-code", version: "2.1.0" } });
+
+    for (const by of ["bob", "carol"]) {
+      const res = await call(s, "records-review", { kind: KIND, id: "fix-002", verdict: "agree", by });
+      expect(res.structuredContent).toMatchObject({ review: { reviewer: by, verdict: "agree" } });
+    }
+    const after = await call(s, "workspace-records", { kind: KIND, id: "fix-002" });
+    expect(recordsOf(after.structuredContent)[0].quorum).toMatchObject({ agreed: 2, met: true });
+  }, 180_000);
+
+  test("a second client is recorded as itself, from the request's _meta", async () => {
+    const s = server();
+    await rpc(s, "initialize", { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "claude-code", version: "2.1.0" } });
+    const made = await call(s, "records-new", { kind: KIND, record: { ...proposal("Where the metrics go"), source: { kind: "workspace", member: "app" } } }, {
+      "io.modelcontextprotocol/clientInfo": { name: "codex", version: "0.40.0" },
+    });
+    const id = (made.structuredContent as { id: string }).id;
+    const read = recordsOf(cli(["workspace", "records", "--kind", KIND, "--json"])).find((r) => r.id === id)!;
+    expect(read.data.source).toEqual({ kind: "workspace", member: "app", via: "mcp", client: { name: "codex", version: "0.40.0" } });
+  }, 120_000);
+
+  test("keeps the CLI's rules: a record opens proposed, a decided record's reasoning stays, by and sign", async () => {
+    const s = server();
+    const decided = await call(s, "records-new", {
+      kind: KIND,
+      record: { ...proposal("Decided at once"), state: "decided", choice: { option: "a", reason: "Simplest." }, decided_by: "lex00", decided_on: "2026-09-25" },
+    });
+    expect(decided.structuredContent).toMatchObject({ error: { code: "record-state-not-initial", message: expect.stringContaining("opens proposed") } });
+
+    const reasoning = await call(s, "records-amend", { kind: KIND, id: "fix-001", fields: { question: "Something else?" } });
+    expect(reasoning.structuredContent).toMatchObject({ error: { code: "amend-supersede-instead" } });
+
+    const both = await call(s, "records-new", { kind: KIND, record: { ...proposal("Two authors"), decided_by: "alice" }, by: "bob", dryRun: true });
+    expect(both.structuredContent).toMatchObject({ error: { code: "write-input-invalid" } });
+    const by = await call(s, "records-new", { kind: KIND, record: proposal("One author"), by: "alice", dryRun: true });
+    expect(by.structuredContent, JSON.stringify(by.structuredContent)).toHaveProperty("text");
+    expect((by.structuredContent as { text: string }).text).toContain('decided_by: "alice"');
+
+    // No key configured on this host: the CLI's refusal and remedy.
+    const home = { GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_NOSYSTEM: "1" };
+    const saved = { ...process.env };
+    Object.assign(process.env, home);
+    try {
+      const signed = await call(s, "records-new", { kind: KIND, record: proposal("Signed"), by: "alice", sign: true, dryRun: true });
+      expect(signed.structuredContent).toMatchObject({ error: { code: "record-sign-failed", message: expect.stringContaining("pass --sign <key file>") } });
+    } finally {
+      for (const k of Object.keys(home)) {
+        if (saved[k] === undefined) delete process.env[k];
+        else process.env[k] = saved[k];
+      }
+    }
+    // Nothing above wrote a file.
+    expect(readFileSync(join(ws.dir, "decisions", "fix-001-how-the-app-is-deployed.md"), "utf-8")).toContain('question: "What declares the app\'s deployment?"');
+  }, 180_000);
+});