@openshain/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

package/README.md

@@ -0,0 +1,7 @@
+# @openshain/mcp
+
+MCP server that exposes an openshain workspace to Claude Code and other agents.
+
+Part of [openshain](https://github.com/openshain/openshain). Requires Bun 1.3 or later: the package ships TypeScript source. Documentation, in Japanese, lives in the repository.
+
+License: Apache-2.0

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@openshain/mcp",
+  "version": "0.1.0",
+  "description": "MCP server that exposes an openshain workspace to any agent",
+  "keywords": [
+    "openshain",
+    "agent",
+    "runtime",
+    "mcp",
+    "accounting",
+    "japan"
+  ],
+  "author": "Hiroki Nakatani",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/openshain/openshain",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openshain/openshain.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": "https://github.com/openshain/openshain/issues",
+  "type": "module",
+  "engines": {
+    "bun": ">=1.3"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "@openshain/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@openshain/tools": "0.1.0"
+  }
+}

package/src/index.ts

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

package/src/server.ts

@@ -0,0 +1,348 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import {
+  CallToolRequestSchema,
+  type CallToolResult,
+  ListToolsRequestSchema,
+  type Tool,
+} from "@modelcontextprotocol/sdk/types.js";
+import {
+  type AnyEvent,
+  type Artifact,
+  compileInputValidator,
+  createToolCaller,
+  createToolRegistry,
+  type Event,
+  type InputValidation,
+  isOpenshainError,
+  isTerminal,
+  loadConfig,
+  parseWorkId,
+  type RuntimeProviders,
+  resolveWorkspacePath,
+  SESSION_WORK_TYPE,
+  type ToolDefinition,
+  type ToolResult,
+  verifyArtifact,
+  type Work,
+  type WorkId,
+  WorkStore,
+} from "@openshain/core";
+import { Session } from "./session.ts";
+
+export interface McpServerOptions {
+  workspaceRoot: string;
+  /** Tool providers by the id used in openshain.yaml. */
+  tools: RuntimeProviders["tools"];
+}
+
+/** The tools every session has, before the workspace's own. Their names are reserved in the runtime. */
+const WORK_TOOLS: Tool[] = [
+  {
+    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)] as const),
+);
+
+/**
+ * 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: McpServerOptions): Promise<Server> {
+  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: "0.0.0" },
+    { capabilities: { tools: {} } },
+  );
+
+  /** The current work when it can still take events; otherwise the reason it cannot. */
+  async function openWork(): Promise<{ id: WorkId } | { refused: CallToolResult }> {
+    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: string, input: Record<string, unknown>): Promise<CallToolResult> {
+    const validate = validators.get(name);
+    if (validate) {
+      const checked: InputValidation = 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 as { objective: string; type?: string };
+        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 as { id: string }).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 as { id?: string }).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 as {
+          summary: string;
+          artifacts?: { path: string; sha256?: string }[];
+        };
+        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 as { reason: string; detail?: string };
+        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: WorkStore,
+  workspaceRoot: string,
+  id: WorkId,
+  summary: string,
+  claimed: { path: string; sha256?: string }[],
+): Promise<Work> {
+  for (const { path } of claimed) await resolveWorkspacePath(workspaceRoot, path);
+  const opened = await works.open(id);
+  try {
+    const events = await opened.events();
+    const refs: string[] = [];
+    const byPath = new Map<string, string>();
+    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: Artifact[] = [];
+    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: AnyEvent[]): Event<"tool.completed">[] {
+  return events.filter(
+    (e): e is Event<"tool.completed"> =>
+      e.type === "tool.completed" &&
+      !(e as Event<"tool.completed">).payload.isError &&
+      (e as Event<"tool.completed">).payload.after !== undefined,
+  );
+}
+
+function toMcpTool(definition: ToolDefinition): Tool {
+  return {
+    name: definition.name,
+    description: definition.description,
+    inputSchema: definition.inputSchema as Tool["inputSchema"],
+  };
+}
+
+function toMcpResult(result: ToolResult): CallToolResult {
+  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: unknown): CallToolResult {
+  return { content: [{ type: "text", text: JSON.stringify(value) }] };
+}
+
+function failure(text: string): CallToolResult {
+  return { content: [{ type: "text", text }], isError: true };
+}
+
+function newCallId(): string {
+  return `call_${Bun.randomUUIDv7()}`;
+}

package/src/session.ts

@@ -0,0 +1,26 @@
+import type { WorkId } from "@openshain/core";
+
+/** What one connection remembers: the work the agent is on, and the order of its calls. */
+export class Session {
+  private currentId: WorkId | undefined;
+  private queue: Promise<unknown> = Promise.resolve();
+
+  get current(): WorkId | undefined {
+    return this.currentId;
+  }
+
+  select(id: WorkId): void {
+    this.currentId = id;
+  }
+
+  clear(): void {
+    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<T>(fn: () => Promise<T>): Promise<T> {
+    const next = this.queue.then(fn, fn);
+    this.queue = next.catch(() => undefined);
+    return next;
+  }
+}