@telorun/mcp-server 0.2.0

package/dist/stdio-server-controller.js

@@ -0,0 +1,89 @@
+import { randomUUID } from "node:crypto";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { RuntimeError } from "@telorun/sdk";
+import { buildServer } from "./registry.js";
+export async function register(_ctx) { }
+export class McpStdioServer {
+    resource;
+    ctx;
+    server = null;
+    transport = null;
+    releaseHold = null;
+    session;
+    constructor(resource, ctx) {
+        this.resource = resource;
+        this.ctx = ctx;
+        // 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);
+            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() {
+        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, this.ctx.stdout);
+            // 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() {
+        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, ctx) {
+    return new McpStdioServer(resource, ctx);
+}

package/dist/tools-controller.d.ts

@@ -0,0 +1,43 @@
+import type { ControllerContext, ResourceContext } 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 declare 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 declare class McpToolsBundle {
+    readonly bundleName: string;
+    private readonly raw;
+    private readonly captured;
+    private readonly ctx;
+    constructor(bundleName: string, raw: RawToolEntry[], captured: Map<RawToolEntry, CapturedRef>, 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[];
+}
+export declare function create(resource: ToolsManifest, ctx: ResourceContext): Promise<McpToolsBundle>;
+export {};

package/dist/tools-controller.js

@@ -0,0 +1,99 @@
+import { RuntimeError } from "@telorun/sdk";
+export async function register(_ctx) { }
+/** 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 {
+    bundleName;
+    raw;
+    captured;
+    ctx;
+    constructor(bundleName, raw, captured, ctx) {
+        this.bundleName = bundleName;
+        this.raw = raw;
+        this.captured = captured;
+        this.ctx = ctx;
+    }
+    /** 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() {
+        const seen = new Set();
+        const resolved = [];
+        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;
+            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);
+                }
+                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;
+            }
+            if (!handlerInstance || typeof handlerInstance.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 ?? {}),
+                inputs: (raw.inputs ?? {}),
+                result: (raw.result ?? {}),
+                catches: raw.catches,
+                handlerKind: ref.kind,
+                handlerName: ref.name,
+                handler: handlerInstance,
+            });
+        }
+        return resolved;
+    }
+}
+export async function create(resource, ctx) {
+    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();
+    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/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@telorun/mcp-server",
+  "version": "0.2.0",
+  "description": "Telo MCP Server module — Model Context Protocol server resource kinds for Telo manifests.",
+  "keywords": [
+    "telo",
+    "mcp",
+    "model-context-protocol",
+    "server",
+    "tools",
+    "stdio"
+  ],
+  "author": "Bartosz Pasiński <bartosz.pasinski@codenet.pl>",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/telorun/telo.git",
+    "directory": "modules/mcp-server/nodejs"
+  },
+  "homepage": "https://github.com/telorun/telo#readme",
+  "bugs": {
+    "url": "https://github.com/telorun/telo/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "exports": {
+    "./stdio-server": {
+      "types": "./dist/stdio-server-controller.d.ts",
+      "bun": "./src/stdio-server-controller.ts",
+      "import": "./dist/stdio-server-controller.js"
+    },
+    "./http-endpoint": {
+      "types": "./dist/http-endpoint-controller.d.ts",
+      "bun": "./src/http-endpoint-controller.ts",
+      "import": "./dist/http-endpoint-controller.js"
+    },
+    "./tools": {
+      "types": "./dist/tools-controller.d.ts",
+      "bun": "./src/tools-controller.ts",
+      "import": "./dist/tools-controller.js"
+    },
+    "./resources": {
+      "types": "./dist/resources-controller.d.ts",
+      "bun": "./src/resources-controller.ts",
+      "import": "./dist/resources-controller.js"
+    },
+    "./prompts": {
+      "types": "./dist/prompts-controller.d.ts",
+      "bun": "./src/prompts-controller.ts",
+      "import": "./dist/prompts-controller.js"
+    }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@telorun/sdk": "0.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "fastify": "^5.7.2",
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.lib.json"
+  }
+}

package/src/http-endpoint-controller.ts

@@ -0,0 +1,204 @@
+import { randomUUID } from "node:crypto";
+
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { type ControllerContext, type ResourceContext, RuntimeError } from "@telorun/sdk";
+import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+
+import { buildServer, type SessionContext, type ServerInfo } from "./registry.js";
+import type { McpToolsBundle } from "./tools-controller.js";
+
+interface HttpEndpointManifest {
+  metadata: { name: string };
+  serverInfo: ServerInfo;
+  tools?: string[];
+  resources?: string[];
+  prompts?: string[];
+}
+
+interface SessionRecord {
+  server: Server;
+  transport: StreamableHTTPServerTransport;
+  context: SessionContext;
+}
+
+export async function register(_ctx: ControllerContext): Promise<void> {}
+
+export class McpHttpEndpoint {
+  private readonly sessions = new Map<string, SessionRecord>();
+  private toolsBundles: McpToolsBundle[] = [];
+
+  constructor(
+    private readonly resource: HttpEndpointManifest,
+    private readonly ctx: ResourceContext,
+  ) {}
+
+  async init() {
+    if ((this.resource.resources ?? []).length > 0 || (this.resource.prompts ?? []).length > 0) {
+      throw new RuntimeError(
+        "ERR_MCP_V2_NOT_IMPLEMENTED",
+        `Mcp.HttpEndpoint[${this.resource.metadata.name}]: resources/prompts are schema-only in v1; runtime dispatch is v2 work`,
+      );
+    }
+    this.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.HttpEndpoint[${this.resource.metadata.name}]: tools bundle '${bundleName}' not found in module scope`,
+        );
+      }
+      return inst;
+    });
+  }
+
+  /** Mount contract — duck-typed against Http.Server's mount loop. The
+   *  signature matches Http.Api.register(); see plan §3 mount contract.
+   *
+   *  Routes are declared with `app.route(...)` directly rather than via
+   *  `app.register(plugin, { prefix })`. The latter is async (the plugin
+   *  loads inside `app.ready()`); declaring the route synchronously removes
+   *  any ordering coupling with the host's `app.listen()` call. Both
+   *  `<prefix>` and `<prefix>/` are registered so trailing-slash variants
+   *  both reach the handler. */
+  register(app: FastifyInstance, prefix = "") {
+    const handler = async (request: FastifyRequest, reply: FastifyReply) => {
+      await this.handleRequest(request, reply);
+    };
+    const methods = ["POST", "GET", "DELETE"];
+
+    // Normalize prefix: strip a trailing slash unless the prefix is exactly
+    // "/", so a configured `/mcp/` doesn't expand to `/mcp//`.
+    const base =
+      prefix && prefix !== "/" && prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+
+    if (base && base !== "/") {
+      app.route({ method: methods, url: base, handler });
+      app.route({ method: methods, url: `${base}/`, handler });
+    } else {
+      app.route({ method: methods, url: "/", handler });
+    }
+
+    app.addHook("onClose", async () => {
+      await this.closeAllSessions();
+    });
+  }
+
+  private async handleRequest(request: FastifyRequest, reply: FastifyReply) {
+    const sessionHeader = (request.headers["mcp-session-id"] ?? "") as string;
+    const body = request.body as Record<string, unknown> | undefined;
+
+    let record: SessionRecord | undefined;
+    if (sessionHeader) {
+      record = this.sessions.get(sessionHeader);
+      if (!record) {
+        reply.code(404);
+        reply.header("Content-Type", "application/json");
+        reply.send({
+          jsonrpc: "2.0",
+          error: { code: -32001, message: "Mcp: unknown session" },
+          id: null,
+        });
+        return;
+      }
+    } else if (request.method === "POST" && body && isInitializeRequest(body)) {
+      record = await this.createSession();
+    } else {
+      reply.code(400);
+      reply.header("Content-Type", "application/json");
+      reply.send({
+        jsonrpc: "2.0",
+        error: {
+          code: -32000,
+          message: "Mcp: missing Mcp-Session-Id header (or initialize request body)",
+        },
+        id: null,
+      });
+      return;
+    }
+
+    // Hand the raw request/response off to the SDK transport. Fastify has
+    // already parsed the body, so we pass it explicitly — the transport will
+    // not re-read the stream.
+    reply.hijack();
+    await record.transport.handleRequest(request.raw, reply.raw, body);
+  }
+
+  private async createSession(): Promise<SessionRecord> {
+    const sessionContext: SessionContext = { id: "", clientInfo: {}, capabilities: {} };
+
+    // Pre-allocate the SessionRecord shell so the onsessioninitialized
+    // closure can capture a stable object reference and register the session
+    // synchronously, before the transport writes the initialize response.
+    // Registering after `await transport.handleRequest()` would open a race
+    // where the client's follow-up request races with the registration.
+    const record = { context: sessionContext } as SessionRecord;
+
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => randomUUID(),
+      onsessioninitialized: (id: string) => {
+        sessionContext.id = id;
+        this.sessions.set(id, record);
+      },
+    });
+    record.transport = transport;
+
+    record.server = buildServer({
+      serverInfo: this.resource.serverInfo,
+      toolsBundles: this.toolsBundles,
+      sessionResolver: () => sessionContext,
+      ctx: this.ctx,
+      moduleContext: this.ctx.moduleContext,
+    });
+
+    transport.onclose = () => {
+      if (sessionContext.id) {
+        this.sessions.delete(sessionContext.id);
+      }
+    };
+
+    await record.server.connect(transport);
+    return record;
+  }
+
+  private async closeAllSessions(): Promise<void> {
+    const records = Array.from(this.sessions.values());
+    this.sessions.clear();
+    for (const record of records) {
+      const sessionId = record.context.id || "<unbound>";
+      try {
+        await record.transport.close();
+      } catch (err) {
+        await this.ctx.emitEvent(`${this.resource.metadata.name}.SessionCloseFailed`, {
+          sessionId,
+          stage: "transport",
+          error: errorPayload(err),
+        });
+      }
+      try {
+        await record.server.close();
+      } catch (err) {
+        await this.ctx.emitEvent(`${this.resource.metadata.name}.SessionCloseFailed`, {
+          sessionId,
+          stage: "server",
+          error: errorPayload(err),
+        });
+      }
+    }
+  }
+}
+
+function errorPayload(err: unknown): { message: string; stack?: string; code?: string } {
+  if (err instanceof Error) {
+    return { message: err.message, stack: err.stack, code: (err as { code?: string }).code };
+  }
+  return { message: String(err) };
+}
+
+export async function create(
+  resource: HttpEndpointManifest,
+  ctx: ResourceContext,
+): Promise<McpHttpEndpoint> {
+  return new McpHttpEndpoint(resource, ctx);
+}

package/src/outcome.ts

@@ -0,0 +1,69 @@
+import type { ResourceInstance } from "@telorun/sdk";
+
+/** Single catches: entry on a tool/resource/prompt entry. `when` is typed
+ *  loosely because the manifest schema says `type: boolean` but the value at
+ *  this point is a `CompiledValue` (when the user wrote `${{ ... }}`) or a
+ *  bare boolean literal (when the user wrote `when: true`/`when: false`).
+ *  Truthiness checks would mis-classify the literal `false` case as "no
+ *  when field" — see matchCatch below. */
+export interface CatchEntry {
+  code?: string;
+  when?: unknown;
+  error: {
+    code: number;
+    message: string;
+    data?: unknown;
+  };
+}
+
+/** Resolved entry handed to the registry — handler ref is captured before
+ *  Phase 5 injection (kind/name) and the live instance is read after. */
+export interface ResolvedToolEntry {
+  name: string;
+  description?: string;
+  argumentsSchema: Record<string, unknown>;
+  inputs: Record<string, unknown>;
+  result: Record<string, unknown>;
+  catches?: CatchEntry[];
+  handlerKind: string;
+  handlerName: string;
+  handler: ResourceInstance;
+}
+
+/** Module-context-shaped surface used by registry dispatch — matches the
+ *  shape consumed by http-api-controller's dispatchReturns/dispatchCatches. */
+export interface ModuleLikeContext {
+  expandWith: (v: unknown, ctx: Record<string, unknown>) => unknown;
+}
+
+interface InvokeError {
+  code: string;
+  message: string;
+  data?: unknown;
+}
+
+/** Pick the first `catches:` entry that matches the thrown InvokeError. An
+ *  entry matches when *every* declared predicate passes: `code:` (if present)
+ *  must equal the error's code AND `when:` (if present) must evaluate truthy.
+ *  An entry with neither field is the catch-all and matches last. */
+export function matchCatch(
+  catches: CatchEntry[] | undefined,
+  err: InvokeError,
+  celCtx: Record<string, unknown>,
+  moduleContext: ModuleLikeContext,
+): CatchEntry | undefined {
+  if (!catches || catches.length === 0) return undefined;
+  let fallback: CatchEntry | undefined;
+  for (const entry of catches) {
+    if (entry.when === undefined && entry.code === undefined) {
+      fallback ??= entry;
+      continue;
+    }
+    if (entry.code !== undefined && entry.code !== err.code) continue;
+    if (entry.when !== undefined && moduleContext.expandWith(entry.when, celCtx) !== true) {
+      continue;
+    }
+    return entry;
+  }
+  return fallback;
+}

package/src/prompts-controller.ts

@@ -0,0 +1,38 @@
+import { type ControllerContext, type ResourceContext, RuntimeError } from "@telorun/sdk";
+
+interface PromptsManifest {
+  metadata?: { name?: string };
+  entries?: unknown[];
+}
+
+export async function register(_ctx: ControllerContext): Promise<void> {}
+
+/** v2 runtime — schema-only in v1. See resources-controller.ts for the same
+ *  pattern. */
+export class McpPromptsBundle {
+  constructor(
+    public readonly bundleName: string,
+    public readonly entries: unknown[],
+  ) {}
+
+  resolveEntries(): never {
+    throw new RuntimeError(
+      "ERR_MCP_V2_NOT_IMPLEMENTED",
+      `Mcp.Prompts[${this.bundleName}]: runtime dispatch is v2 work`,
+    );
+  }
+}
+
+export async function create(
+  resource: PromptsManifest,
+  _ctx: ResourceContext,
+): Promise<McpPromptsBundle> {
+  const bundleName = resource.metadata?.name;
+  if (!bundleName) {
+    throw new RuntimeError(
+      "ERR_MCP_PROMPTS_INVALID",
+      "Mcp.Prompts: metadata.name is required",
+    );
+  }
+  return new McpPromptsBundle(bundleName, resource.entries ?? []);
+}