@telorun/mcp-server 0.2.0

package/src/registry.ts

@@ -0,0 +1,146 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { isInvokeError, type ResourceContext, RuntimeError } from "@telorun/sdk";
+
+import { matchCatch, type ModuleLikeContext, type ResolvedToolEntry } from "./outcome.js";
+import type { McpToolsBundle } from "./tools-controller.js";
+
+export interface ServerInfo {
+  name: string;
+  version: string;
+}
+
+export interface BuildOptions {
+  serverInfo: ServerInfo;
+  toolsBundles: McpToolsBundle[];
+  /** Per-session metadata exposed to CEL inputs as `request.session`. */
+  sessionResolver: () => SessionContext;
+  ctx: ResourceContext;
+  moduleContext: ModuleLikeContext;
+}
+
+export interface SessionContext {
+  id: string;
+  clientInfo: { name?: string; version?: string } | Record<string, unknown>;
+  capabilities: Record<string, unknown>;
+}
+
+/** Merge entries from every bundle, throwing if two bundles register the same
+ *  tool name. The plan calls for the analyzer to also catch this at compile
+ *  time (§5.1 item 2) — this runtime guard backstops it until that lands. */
+function mergeToolEntries(bundles: McpToolsBundle[]): Map<string, ResolvedToolEntry> {
+  const byName = new Map<string, ResolvedToolEntry>();
+  const owners = new Map<string, string>();
+  for (const bundle of bundles) {
+    for (const entry of bundle.resolveEntries()) {
+      const priorOwner = owners.get(entry.name);
+      if (priorOwner) {
+        throw new RuntimeError(
+          "ERR_MCP_TOOLS_DUPLICATE",
+          `Mcp: duplicate tool name '${entry.name}' across bundles '${priorOwner}' and '${bundle.bundleName}'`,
+        );
+      }
+      owners.set(entry.name, bundle.bundleName);
+      byName.set(entry.name, entry);
+    }
+  }
+  return byName;
+}
+
+/** Build a fully-wired SDK Server. For stdio the caller connects this once;
+ *  for streamable HTTP a fresh Server is built per session, so this is called
+ *  every time a new Mcp-Session-Id is minted. */
+export function buildServer(opts: BuildOptions): Server {
+  const tools = mergeToolEntries(opts.toolsBundles);
+
+  const server = new Server(
+    { name: opts.serverInfo.name, version: opts.serverInfo.version },
+    { capabilities: { tools: {} } },
+  );
+
+  const advertised = Array.from(tools.values()).map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: t.argumentsSchema as Record<string, unknown>,
+  }));
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: advertised }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const tool = tools.get(request.params.name);
+    if (!tool) {
+      throw new RuntimeError(
+        "ERR_MCP_UNKNOWN_TOOL",
+        `Mcp: unknown tool '${request.params.name}'`,
+      );
+    }
+
+    const session = opts.sessionResolver();
+    const requestCtx: Record<string, unknown> = {
+      request: {
+        name: tool.name,
+        arguments: request.params.arguments ?? {},
+        meta: (request.params as { _meta?: unknown })._meta ?? {},
+        session: {
+          id: session.id,
+          clientInfo: session.clientInfo,
+          capabilities: session.capabilities,
+        },
+      },
+    };
+
+    const inputs = opts.moduleContext.expandWith(tool.inputs, requestCtx) as Record<
+      string,
+      unknown
+    >;
+
+    let handlerResult: unknown;
+    try {
+      handlerResult = await opts.ctx.invokeResolved(
+        tool.handlerKind,
+        tool.handlerName,
+        tool.handler,
+        { ...inputs, inputs },
+      );
+    } catch (err) {
+      if (!isInvokeError(err)) throw err;
+      const errPayload = { code: err.code, message: err.message, data: err.data };
+      const celCtx = { error: errPayload, request: requestCtx.request };
+      const matched = matchCatch(tool.catches, errPayload, celCtx, opts.moduleContext);
+      if (!matched) {
+        throw err;
+      }
+      const expanded = opts.moduleContext.expandWith(matched.error, celCtx) as {
+        code: number;
+        message: string;
+        data?: unknown;
+      };
+      const ipcError: Error & { code?: number; data?: unknown } = new Error(expanded.message);
+      ipcError.code = expanded.code;
+      ipcError.data = expanded.data;
+      throw ipcError;
+    }
+
+    const resultCtx = { result: handlerResult, request: requestCtx.request };
+    const rendered = opts.moduleContext.expandWith(tool.result, resultCtx) as Record<
+      string,
+      unknown
+    >;
+
+    // Schema requires `content` to be present, but the value comes from CEL
+    // expansion at runtime so its type can't be enforced statically. Verify
+    // the expanded shape here.
+    if (!Array.isArray((rendered as { content?: unknown }).content)) {
+      throw new RuntimeError(
+        "ERR_MCP_RESULT_INVALID",
+        `Mcp: tool '${tool.name}' result.content is not an array of content blocks`,
+      );
+    }
+    return rendered as { content: unknown[] };
+  });
+
+  return server;
+}

package/src/resources-controller.ts

@@ -0,0 +1,40 @@
+import { type ControllerContext, type ResourceContext, RuntimeError } from "@telorun/sdk";
+
+interface ResourcesManifest {
+  metadata?: { name?: string };
+  entries?: unknown[];
+}
+
+export async function register(_ctx: ControllerContext): Promise<void> {}
+
+/** v2 runtime — schema-only in v1. The bundle is created so transport refs
+ *  resolve cleanly, but transports refuse to wire it up: `Mcp.StdioServer` /
+ *  `Mcp.HttpEndpoint` throw at init() if `resources:` is non-empty, and
+ *  `resolveEntries()` throws if anyone calls it directly. */
+export class McpResourcesBundle {
+  constructor(
+    public readonly bundleName: string,
+    public readonly entries: unknown[],
+  ) {}
+
+  resolveEntries(): never {
+    throw new RuntimeError(
+      "ERR_MCP_V2_NOT_IMPLEMENTED",
+      `Mcp.Resources[${this.bundleName}]: runtime dispatch is v2 work`,
+    );
+  }
+}
+
+export async function create(
+  resource: ResourcesManifest,
+  _ctx: ResourceContext,
+): Promise<McpResourcesBundle> {
+  const bundleName = resource.metadata?.name;
+  if (!bundleName) {
+    throw new RuntimeError(
+      "ERR_MCP_RESOURCES_INVALID",
+      "Mcp.Resources: metadata.name is required",
+    );
+  }
+  return new McpResourcesBundle(bundleName, resource.entries ?? []);
+}

package/src/stdio-server-controller.ts

@@ -0,0 +1,125 @@
+import { randomUUID } from "node:crypto";
+import type { Readable, Writable } from "node:stream";
+
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { type ControllerContext, type ResourceContext, RuntimeError } from "@telorun/sdk";
+
+import { buildServer, type SessionContext, type ServerInfo } from "./registry.js";
+import type { McpToolsBundle } from "./tools-controller.js";
+
+interface StdioServerManifest {
+  metadata: { name: string };
+  serverInfo: ServerInfo;
+  tools?: string[];
+  resources?: string[];
+  prompts?: string[];
+}
+
+export async function register(_ctx: ControllerContext): Promise<void> {}
+
+export class McpStdioServer {
+  private server: Server | null = null;
+  private transport: StdioServerTransport | null = null;
+  private releaseHold: (() => void) | null = null;
+  private session: SessionContext;
+
+  constructor(
+    private readonly resource: StdioServerManifest,
+    private readonly ctx: ResourceContext,
+  ) {
+    // stdio has no transport-level session id; mint a stable synthetic UUID at
+    // construction so request.session.id is always defined for CEL inputs.
+    this.session = { id: randomUUID(), clientInfo: {}, capabilities: {} };
+  }
+
+  async init() {
+    if ((this.resource.resources ?? []).length > 0 || (this.resource.prompts ?? []).length > 0) {
+      throw new RuntimeError(
+        "ERR_MCP_V2_NOT_IMPLEMENTED",
+        `Mcp.StdioServer[${this.resource.metadata.name}]: resources/prompts are schema-only in v1; runtime dispatch is v2 work`,
+      );
+    }
+
+    const toolsBundles = (this.resource.tools ?? []).map((bundleName) => {
+      const inst = this.ctx.moduleContext.getInstance(bundleName) as McpToolsBundle | undefined;
+      if (!inst) {
+        throw new RuntimeError(
+          "ERR_MCP_BUNDLE_NOT_FOUND",
+          `Mcp.StdioServer[${this.resource.metadata.name}]: tools bundle '${bundleName}' not found in module scope`,
+        );
+      }
+      return inst;
+    });
+
+    this.server = buildServer({
+      serverInfo: this.resource.serverInfo,
+      toolsBundles,
+      sessionResolver: () => this.session,
+      ctx: this.ctx,
+      moduleContext: this.ctx.moduleContext,
+    });
+  }
+
+  async run(): Promise<void> {
+    if (!this.server) {
+      throw new Error("Mcp.StdioServer.run() called before init()");
+    }
+
+    this.releaseHold = this.ctx.acquireHold();
+    try {
+      // ResourceContext types stdin/stdout as the structural NodeJS.ReadableStream
+      // / NodeJS.WritableStream interfaces, while the MCP SDK accepts the
+      // concrete node:stream `Readable` / `Writable` classes. process.stdin
+      // and process.stdout satisfy both shapes; a single cast is enough here.
+      this.transport = new StdioServerTransport(
+        this.ctx.stdin as unknown as Readable,
+        this.ctx.stdout as unknown as Writable,
+      );
+
+      // The transport's `onclose` fires when stdin reaches EOF (the parent
+      // closed the pipe). Releasing the hold then lets the kernel exit.
+      this.transport.onclose = () => {
+        if (this.releaseHold) {
+          this.releaseHold();
+          this.releaseHold = null;
+        }
+      };
+
+      await this.server.connect(this.transport);
+
+      await this.ctx.emitEvent(`${this.resource.metadata.name}.Listening`, {
+        transport: "stdio",
+        sessionId: this.session.id,
+      });
+    } catch (error) {
+      if (this.releaseHold) {
+        this.releaseHold();
+        this.releaseHold = null;
+      }
+      throw error;
+    }
+  }
+
+  async teardown(): Promise<void> {
+    if (this.transport) {
+      await this.transport.close();
+      this.transport = null;
+    }
+    if (this.server) {
+      await this.server.close();
+      this.server = null;
+    }
+    if (this.releaseHold) {
+      this.releaseHold();
+      this.releaseHold = null;
+    }
+  }
+}
+
+export async function create(
+  resource: StdioServerManifest,
+  ctx: ResourceContext,
+): Promise<McpStdioServer> {
+  return new McpStdioServer(resource, ctx);
+}

package/src/tools-controller.ts

@@ -0,0 +1,151 @@
+import type { ControllerContext, ResourceContext, ResourceInstance } from "@telorun/sdk";
+import { RuntimeError } from "@telorun/sdk";
+
+import type { CatchEntry, ResolvedToolEntry } from "./outcome.js";
+
+/** Manifest shape pre-Phase-5. The handler field is still {kind, name} (or a
+ *  bare name string) at create() time; Phase 5 swaps it for a live
+ *  ResourceInstance before consumers (transports) read .entries. */
+interface RawToolEntry {
+  name?: string;
+  description?: string;
+  argumentsSchema?: Record<string, unknown>;
+  handler?: unknown;
+  inputs?: Record<string, unknown>;
+  result?: Record<string, unknown>;
+  catches?: CatchEntry[];
+}
+
+interface ToolsManifest {
+  metadata?: { name?: string; module?: string };
+  entries?: RawToolEntry[];
+}
+
+interface CapturedRef {
+  kind: string;
+  name: string;
+}
+
+export async function register(_ctx: ControllerContext): Promise<void> {}
+
+/** Passive bundle exposed via ctx.moduleContext.getInstance(name). The
+ *  transport (StdioServer / HttpEndpoint) reads `.entries` after Phase 5
+ *  injection — handler refs in each entry are then live ResourceInstances. */
+export class McpToolsBundle {
+  constructor(
+    public readonly bundleName: string,
+    private readonly raw: RawToolEntry[],
+    private readonly captured: Map<RawToolEntry, CapturedRef>,
+    private readonly ctx: ResourceContext,
+  ) {}
+
+  /** Resolve the raw entries into ResolvedToolEntry records suitable for
+   *  registry consumption. Called from a transport's init() — at that point
+   *  Phase 5 has injected live handler instances over the captured object refs.
+   *  String-form refs are resolved here via moduleContext.getInstance(). */
+  resolveEntries(): ResolvedToolEntry[] {
+    const seen = new Set<string>();
+    const resolved: ResolvedToolEntry[] = [];
+    for (const raw of this.raw) {
+      const name = raw.name;
+      if (!name) {
+        throw new RuntimeError(
+          "ERR_MCP_TOOLS_INVALID",
+          `Mcp.Tools[${this.bundleName}]: entry is missing 'name'`,
+        );
+      }
+      if (seen.has(name)) {
+        throw new RuntimeError(
+          "ERR_MCP_TOOLS_DUPLICATE",
+          `Mcp.Tools[${this.bundleName}]: duplicate tool name '${name}' within the same bundle`,
+        );
+      }
+      seen.add(name);
+
+      const ref = this.captured.get(raw);
+      if (!ref) {
+        throw new RuntimeError(
+          "ERR_MCP_TOOLS_NO_HANDLER",
+          `Mcp.Tools[${this.bundleName}]: tool '${name}' has no handler reference`,
+        );
+      }
+
+      let handlerInstance: ResourceInstance | undefined;
+      if (typeof raw.handler === "string") {
+        // moduleContext.getInstance(name) throws a plain Error when the
+        // resource is missing. Wrap it so misconfigured string refs surface
+        // as the MCP-specific ERR_MCP_TOOLS_HANDLER_UNRESOLVED with the
+        // bundle/tool location included.
+        try {
+          handlerInstance = this.ctx.moduleContext.getInstance(ref.name) as ResourceInstance;
+        } catch (err) {
+          throw new RuntimeError(
+            "ERR_MCP_TOOLS_HANDLER_UNRESOLVED",
+            `Mcp.Tools[${this.bundleName}]: tool '${name}' handler '${ref.name}' not found: ${err instanceof Error ? err.message : String(err)}`,
+          );
+        }
+      } else if (raw.handler && typeof raw.handler === "object") {
+        // Phase 5 injection has replaced the {kind, name} ref with the live
+        // ResourceInstance — unless the referenced resource was missing, in
+        // which case Phase 5 leaves the {kind, name} object in place. Detect
+        // that case via the absence of `invoke` below.
+        handlerInstance = raw.handler as ResourceInstance;
+      }
+      if (!handlerInstance || typeof (handlerInstance as { invoke?: unknown }).invoke !== "function") {
+        throw new RuntimeError(
+          "ERR_MCP_TOOLS_HANDLER_UNRESOLVED",
+          `Mcp.Tools[${this.bundleName}]: tool '${name}' handler '${ref.kind || "?"}.${ref.name}' did not resolve to a live Invocable — Phase 5 injection may have failed`,
+        );
+      }
+
+      resolved.push({
+        name,
+        description: raw.description,
+        argumentsSchema: (raw.argumentsSchema ?? {}) as Record<string, unknown>,
+        inputs: (raw.inputs ?? {}) as Record<string, unknown>,
+        result: (raw.result ?? {}) as Record<string, unknown>,
+        catches: raw.catches,
+        handlerKind: ref.kind,
+        handlerName: ref.name,
+        handler: handlerInstance,
+      });
+    }
+    return resolved;
+  }
+}
+
+export async function create(
+  resource: ToolsManifest,
+  ctx: ResourceContext,
+): Promise<McpToolsBundle> {
+  const bundleName = resource.metadata?.name;
+  if (!bundleName) {
+    throw new RuntimeError(
+      "ERR_MCP_TOOLS_INVALID",
+      "Mcp.Tools: metadata.name is required",
+    );
+  }
+  const entries = resource.entries ?? [];
+
+  const captured = new Map<RawToolEntry, CapturedRef>();
+  for (const entry of entries) {
+    const handler = entry.handler;
+    if (!handler) {
+      throw new RuntimeError(
+        "ERR_MCP_TOOLS_INVALID",
+        `Mcp.Tools[${bundleName}]: tool '${entry.name ?? "<unnamed>"}' missing handler`,
+      );
+    }
+    if (typeof handler === "object") {
+      captured.set(entry, ctx.resolveChildren(handler));
+    } else if (typeof handler === "string") {
+      // Bare name reference (oneOf: string). Phase 5 injection only replaces
+      // {kind, name} object refs — string refs survive as the resource name.
+      // We capture the name here so the dispatcher can still look up the
+      // instance via moduleContext.getInstance() at invoke time.
+      captured.set(entry, { kind: "", name: handler });
+    }
+  }
+
+  return new McpToolsBundle(bundleName, entries, captured, ctx);
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "files": [],
+  "include": ["src/**/*.ts"],
+  "compilerOptions": {
+    "strict": true,
+    "esModuleInterop": true
+  },
+  "references": [
+    {
+      "path": "tsconfig.lib.json"
+    }
+  ]
+}

package/tsconfig.lib.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "exclude": ["node_modules", "dist", "**/*spec.ts"],
+  "include": ["src/**/*.ts"]
+}