@openshain/mcp 0.1.1 → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createMcpServer, type McpServerOptions } from "./server.ts";
+export { Session } from "./session.ts";

package/dist/index.js

@@ -0,0 +1,3 @@
+// @openshain/mcp: MCP server that exposes the runtime to any agent
+export { createMcpServer } from "./server.js";
+export { Session } from "./session.js";

package/dist/server.d.ts

@@ -0,0 +1,13 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { type RuntimeProviders } from "@openshain/core";
+export interface McpServerOptions {
+    workspaceRoot: string;
+    /** Tool providers by the id used in openshain.yaml. */
+    tools: RuntimeProviders["tools"];
+}
+/**
+ * An MCP server over one workspace. The agent on the other side thinks; the server keeps the
+ * work's state, runs the workspace's tools and records everything. Needs no model provider.
+ * Calls are handled one at a time per connection.
+ */
+export declare function createMcpServer(options: McpServerOptions): Promise<Server>;

package/dist/server.js

@@ -0,0 +1,286 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { compileInputValidator, createToolCaller, createToolRegistry, isOpenshainError, isTerminal, loadConfig, parseWorkId, resolveWorkspacePath, SESSION_WORK_TYPE, uuidv7, verifyArtifact, WorkStore, } from "@openshain/core";
+import pkg from "../package.json" with { type: "json" };
+import { Session } from "./session.js";
+/** The tools every session has, before the workspace's own. Their names are reserved in the runtime. */
+const WORK_TOOLS = [
+    {
+        name: "work_create",
+        description: "Start a work for a request from the person you work for, and make it the current work. Tool calls are recorded against the current work. Finish the current work with work_complete or work_fail before starting another.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                objective: { type: "string", description: "The request, in the person's words." },
+                type: {
+                    type: "string",
+                    description: "A short label for the kind of work. Defaults to request.",
+                },
+            },
+            required: ["objective"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "work_select",
+        description: "Make an existing work the current one. A finished work cannot be selected.",
+        inputSchema: {
+            type: "object",
+            properties: { id: { type: "string" } },
+            required: ["id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "work_get",
+        description: "The state of the current work, or of the work with the given id.",
+        inputSchema: {
+            type: "object",
+            properties: { id: { type: "string" } },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "work_list",
+        description: "Every work in this workspace, oldest first, with the ones that cannot be read.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    },
+    {
+        name: "work_complete",
+        description: "Finish the current work. Say what was done; name the files you produced with their sha256 if you know it. Paths are relative to the workspace. The runtime checks every file and records its own hash.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                summary: { type: "string" },
+                artifacts: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: { path: { type: "string" }, sha256: { type: "string" } },
+                        required: ["path"],
+                        additionalProperties: false,
+                    },
+                },
+            },
+            required: ["summary"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "work_fail",
+        description: "Give up on the current work. Say why in a short reason and, if useful, a detail.",
+        inputSchema: {
+            type: "object",
+            properties: { reason: { type: "string" }, detail: { type: "string" } },
+            required: ["reason"],
+            additionalProperties: false,
+        },
+    },
+];
+const NO_WORK = "no current work: call work_create to start one for the person's request, or work_select to pick an existing one";
+const validators = new Map(WORK_TOOLS.map((tool) => [tool.name, compileInputValidator(tool.inputSchema)]));
+/**
+ * An MCP server over one workspace. The agent on the other side thinks; the server keeps the
+ * work's state, runs the workspace's tools and records everything. Needs no model provider.
+ * Calls are handled one at a time per connection.
+ */
+export async function createMcpServer(options) {
+    const { workspaceRoot } = options;
+    const config = await loadConfig(workspaceRoot);
+    const registry = await createToolRegistry(workspaceRoot, config, options.tools);
+    const callTool = createToolCaller({ registry, config, workspaceRoot });
+    const works = new WorkStore(workspaceRoot);
+    const session = new Session();
+    const server = new Server({ name: "openshain", version: pkg.version }, { capabilities: { tools: {} } });
+    /** The current work when it can still take events; otherwise the reason it cannot. */
+    async function openWork() {
+        const id = session.current;
+        if (!id)
+            return { refused: failure(NO_WORK) };
+        const work = await works.get(id);
+        if (isTerminal(work.status)) {
+            session.clear();
+            return { refused: failure(`work ${id} is already ${work.status}; ${NO_WORK}`) };
+        }
+        return { id };
+    }
+    async function handle(name, input) {
+        const validate = validators.get(name);
+        if (validate) {
+            const checked = validate(input);
+            if (!checked.ok) {
+                return failure(`schema_mismatch: input does not match the schema of ${name}: ${checked.reason}`);
+            }
+        }
+        switch (name) {
+            case "work_create": {
+                const current = session.current;
+                if (current && !isTerminal((await works.get(current)).status)) {
+                    return failure(`work ${current} is still in progress; finish it with work_complete or work_fail before starting another`);
+                }
+                const { objective, type } = input;
+                if (type === SESSION_WORK_TYPE) {
+                    return failure(`type "${SESSION_WORK_TYPE}" is reserved for conversations; use another label, such as request`);
+                }
+                const work = await works.create({
+                    objective,
+                    principal: config.principal.id,
+                    profession: config.profession.id,
+                    ...(type && { type }),
+                });
+                await works.transition(work.id, "in_progress", "an agent took the work over MCP");
+                session.select(work.id);
+                return json(await works.get(work.id));
+            }
+            case "work_select": {
+                const id = parseWorkId(input.id);
+                const work = await works.get(id);
+                if (isTerminal(work.status))
+                    return failure(`work ${id} is already ${work.status}`);
+                session.select(id);
+                return json(work);
+            }
+            case "work_get": {
+                const given = input.id;
+                const id = given ? parseWorkId(given) : session.current;
+                if (!id)
+                    return failure(NO_WORK);
+                return json(await works.get(id));
+            }
+            case "work_list": {
+                const { works: all, problems } = await works.list();
+                return json({
+                    works: all.map((w) => ({
+                        id: w.id,
+                        status: w.status,
+                        objective: w.objective,
+                        createdAt: w.createdAt,
+                    })),
+                    problems: problems.map((p) => ({
+                        id: p.id,
+                        code: p.error.code,
+                        message: p.error.message,
+                    })),
+                });
+            }
+            case "work_complete": {
+                const gate = await openWork();
+                if ("refused" in gate)
+                    return gate.refused;
+                const { summary, artifacts } = input;
+                const work = await complete(works, workspaceRoot, gate.id, summary, artifacts ?? []);
+                session.clear();
+                return json(work);
+            }
+            case "work_fail": {
+                const gate = await openWork();
+                if ("refused" in gate)
+                    return gate.refused;
+                const { reason, detail } = input;
+                const opened = await works.open(gate.id);
+                try {
+                    await opened.append({ type: "work.failed", payload: { reason, detail: detail ?? "" } });
+                }
+                finally {
+                    await opened.close();
+                }
+                session.clear();
+                return json(await works.get(gate.id));
+            }
+            default: {
+                const gate = await openWork();
+                if ("refused" in gate)
+                    return gate.refused;
+                const opened = await works.open(gate.id);
+                try {
+                    const result = await callTool(opened, { id: newCallId(), name, input });
+                    return toMcpResult(result);
+                }
+                finally {
+                    await opened.close();
+                }
+            }
+        }
+    }
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [...WORK_TOOLS, ...registry.list().map((t) => toMcpTool(t.definition))],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, (request) => session.run(async () => {
+        try {
+            return await handle(request.params.name, request.params.arguments ?? {});
+        }
+        catch (err) {
+            if (isOpenshainError(err))
+                return failure(`${err.code}: ${err.message}`);
+            throw err;
+        }
+    }));
+    return server;
+}
+/**
+ * Records the evidence and the completion. Artifacts named by the agent join the ones the tools
+ * wrote; every path must be inside the workspace, and the runtime hashes them all. A path no tool
+ * of this work wrote is marked claimed, so a reader can tell the agent's word from the record.
+ */
+async function complete(works, workspaceRoot, id, summary, claimed) {
+    for (const { path } of claimed)
+        await resolveWorkspacePath(workspaceRoot, path);
+    const opened = await works.open(id);
+    try {
+        const events = await opened.events();
+        const refs = [];
+        const byPath = new Map();
+        for (const event of writesWithAfter(events)) {
+            refs.push(event.id);
+            for (const { path, sha256 } of event.payload.after ?? [])
+                byPath.set(path, sha256);
+        }
+        const written = new Set(byPath.keys());
+        for (const { path, sha256 } of claimed)
+            if (!byPath.has(path))
+                byPath.set(path, sha256 ?? "");
+        const artifacts = [];
+        for (const [path, reported] of byPath) {
+            const artifact = await verifyArtifact(workspaceRoot, path, reported);
+            artifacts.push(written.has(path) ? artifact : { ...artifact, claimed: true });
+        }
+        await opened.append({
+            type: "evidence.recorded",
+            payload: { claim: summary, refs, artifacts },
+        });
+        await opened.append({ type: "work.completed", payload: { summary } });
+        return opened.current();
+    }
+    finally {
+        await opened.close();
+    }
+}
+function writesWithAfter(events) {
+    return events.filter((e) => e.type === "tool.completed" &&
+        !e.payload.isError &&
+        e.payload.after !== undefined);
+}
+function toMcpTool(definition) {
+    return {
+        name: definition.name,
+        description: definition.description,
+        inputSchema: definition.inputSchema,
+    };
+}
+function toMcpResult(result) {
+    return {
+        content: result.content.map((part) => part.type === "text"
+            ? { type: "text", text: part.text }
+            : { type: "text", text: JSON.stringify(part.value) }),
+        ...(result.isError && { isError: true }),
+    };
+}
+function json(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value) }] };
+}
+function failure(text) {
+    return { content: [{ type: "text", text }], isError: true };
+}
+function newCallId() {
+    return `call_${uuidv7()}`;
+}

package/dist/session.d.ts

@@ -0,0 +1,11 @@
+import type { WorkId } from "@openshain/core";
+/** What one connection remembers: the work the agent is on, and the order of its calls. */
+export declare class Session {
+    private currentId;
+    private queue;
+    get current(): WorkId | undefined;
+    select(id: WorkId): void;
+    clear(): void;
+    /** Runs one call after the previous one finished, so calls the agent makes in parallel do not fight over the work's lock. */
+    run<T>(fn: () => Promise<T>): Promise<T>;
+}

package/dist/session.js

@@ -0,0 +1,20 @@
+/** What one connection remembers: the work the agent is on, and the order of its calls. */
+export class Session {
+    currentId;
+    queue = Promise.resolve();
+    get current() {
+        return this.currentId;
+    }
+    select(id) {
+        this.currentId = id;
+    }
+    clear() {
+        this.currentId = undefined;
+    }
+    /** Runs one call after the previous one finished, so calls the agent makes in parallel do not fight over the work's lock. */
+    run(fn) {
+        const next = this.queue.then(fn, fn);
+        this.queue = next.catch(() => undefined);
+        return next;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openshain/mcp",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "MCP server that exposes an openshain workspace to any agent",
   "keywords": [
     "openshain",
@@ -21,25 +21,36 @@
   "bugs": "https://github.com/openshain/openshain/issues",
   "type": "module",
   "engines": {
+    "node": ">=22",
     "bun": ">=1.3"
   },
   "files": [
+    "dist",
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
     "README.md",
     "LICENSE"
   ],
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
-  "publishConfig": {
-    "access": "public"
+  "scripts": {
+    "build": "../../node_modules/.bin/tsc -p tsconfig.build.json",
+    "prepublishOnly": "rm -rf dist && ../../node_modules/.bin/tsc -p tsconfig.build.json"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
-    "@openshain/core": "0.1.0"
+    "@openshain/core": "0.2.0"
   },
   "devDependencies": {
-    "@openshain/tools": "0.1.0"
+    "@openshain/tools": "0.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/server.ts

@@ -22,11 +22,13 @@ import {
   SESSION_WORK_TYPE,
   type ToolDefinition,
   type ToolResult,
+  uuidv7,
   verifyArtifact,
   type Work,
   type WorkId,
   WorkStore,
 } from "@openshain/core";
+import pkg from "../package.json" with { type: "json" };
 import { Session } from "./session.ts";
 
 export interface McpServerOptions {
@@ -132,7 +134,7 @@ export async function createMcpServer(options: McpServerOptions): Promise<Server
   const works = new WorkStore(workspaceRoot);
   const session = new Session();
   const server = new Server(
-    { name: "openshain", version: "0.0.0" },
+    { name: "openshain", version: pkg.version },
     { capabilities: { tools: {} } },
   );
 
@@ -344,5 +346,5 @@ function failure(text: string): CallToolResult {
 }
 
 function newCallId(): string {
-  return `call_${Bun.randomUUIDv7()}`;
+  return `call_${uuidv7()}`;
 }