@nightowlsdev/mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Night Owls contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,102 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createSwarmMcpServer: () => createSwarmMcpServer,
+  runSwarmMcpStdio: () => runSwarmMcpStdio
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/server.ts
+var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
+var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
+var import_zod = require("zod");
+var ok = (payload) => ({ content: [{ type: "text", text: JSON.stringify(payload) }] });
+var err = (message) => ({ content: [{ type: "text", text: JSON.stringify({ status: "error", message }) }], isError: true });
+async function drain(iter, runId) {
+  let answer = "";
+  for await (const e of iter) {
+    if (e.type === "swarm.message" && e.data.role === "assistant") {
+      answer += e.data.text ?? e.data.delta ?? "";
+    } else if (e.type === "swarm.question") {
+      return ok({ status: "needs_input", question: e.data.prompt, followupId: e.data.followupId, partial: answer || void 0, runId });
+    } else if (e.type === "swarm.run_failed") {
+      return ok({ status: "failed", message: e.data.message, stage: e.data.stage, runId });
+    }
+  }
+  return ok({ status: "done", answer, runId });
+}
+async function handleAsk(opts, slug, args, extra) {
+  try {
+    const { engine, storage } = opts;
+    const auth = await opts.resolveContext(extra);
+    if (!auth) return err("unauthorized: resolveContext returned null");
+    const newId = opts.newId ?? (() => crypto.randomUUID());
+    if (args.followupId && args.answer != null) {
+      const found = await storage.runs.findSuspended(auth.tenantId, args.followupId);
+      if (!found) return err(`no suspended run for followup ${args.followupId}`);
+      const row = await storage.runs.get(found.runId);
+      if (!row || row.tenantId !== auth.tenantId) return err("forbidden");
+      const ctx2 = { tenantId: auth.tenantId, userId: auth.userId, agentSlug: row.agentSlug, runId: found.runId, threadId: row.threadId };
+      return await drain(engine.resume({ runId: found.runId, toolCallId: found.toolCallId, followupId: args.followupId, answer: args.answer, context: args.context }, ctx2), found.runId);
+    }
+    if (!args.message) return err("message is required for a new ask (or pass followupId + answer to resume)");
+    const runId = newId();
+    const threadId = args.threadId ?? newId();
+    const ctx = { tenantId: auth.tenantId, userId: auth.userId, agentSlug: slug, runId, threadId };
+    return await drain(engine.run({ message: args.message, context: args.context }, ctx), runId);
+  } catch (e) {
+    return err(e instanceof Error ? e.message : String(e));
+  }
+}
+function createSwarmMcpServer(opts) {
+  const server = new import_mcp.McpServer({ name: opts.name ?? "nightowls-swarm", version: opts.version ?? "0.1.0" });
+  for (const agent of opts.agents) {
+    const label = agent.name ?? agent.slug;
+    server.registerTool(
+      `ask_${agent.slug}`,
+      {
+        title: `Ask ${label}`,
+        description: agent.description ?? `Ask the ${label} agent${agent.role ? ` (${agent.role})` : ""}. Returns its answer, or { status: "needs_input", question, followupId } when it needs more from you \u2014 call this tool again with { followupId, answer } to continue the same conversation.`,
+        inputSchema: {
+          message: import_zod.z.string().optional().describe("what to ask the agent (required for a new ask)"),
+          threadId: import_zod.z.string().optional().describe("continue an existing conversation; omit to start a new one"),
+          context: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional().describe("untrusted/advisory page context"),
+          followupId: import_zod.z.string().optional().describe("from a prior needs_input result \u2014 to answer the agent"),
+          answer: import_zod.z.string().optional().describe("your answer to the agent's question (with followupId)")
+        }
+      },
+      (args, extra) => handleAsk(opts, agent.slug, args, extra)
+    );
+  }
+  return server;
+}
+async function runSwarmMcpStdio(opts) {
+  const server = createSwarmMcpServer(opts);
+  await server.connect(new import_stdio.StdioServerTransport());
+  console.error(`[nightowls] swarm MCP server ready on stdio (${opts.agents.length} ask_<agent> tools)`);
+  return server;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createSwarmMcpServer,
+  runSwarmMcpStdio
+});

package/dist/index.d.cts

@@ -0,0 +1,46 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { SwarmEngine, StorageAdapter } from '@nightowlsdev/core';
+
+/** The caller identity resolved from an MCP request — the ONLY source of tenancy (never tool args). */
+interface SwarmMcpContext {
+    tenantId: string;
+    userId: string;
+}
+/** One agent to expose as an `ask_<slug>` tool. Pass `await engine.listAgents(ctx)` (AgentSummary[]) directly,
+ *  or a hand-built list. `name`/`role`/`description` only shape the tool's model-facing description. */
+interface SwarmMcpAgent {
+    slug: string;
+    name?: string;
+    role?: string;
+    description?: string;
+}
+interface SwarmMcpServerOpts {
+    engine: SwarmEngine;
+    storage: StorageAdapter;
+    /** The agents to expose (their slugs become `ask_<slug>` tools). Tool names are tenant-independent; the
+     *  per-request tenant (from `resolveContext`) selects each tenant's actual agent version at run time. */
+    agents: SwarmMcpAgent[];
+    /**
+     * Resolve the caller's identity from the MCP request's per-handler `extra` (transport/auth info). Return
+     * `null` to reject the call as unauthorized. Identity is taken ONLY from here — never from tool arguments,
+     * which are attacker-controllable. stdio/local: a fixed context; HTTP: read `extra.authInfo`/headers.
+     */
+    resolveContext: (extra: unknown) => Promise<SwarmMcpContext | null> | SwarmMcpContext | null;
+    /** Id generator for runId/threadId — injectable for deterministic tests. Default `crypto.randomUUID`. */
+    newId?: () => string;
+    name?: string;
+    version?: string;
+}
+/**
+ * Build an MCP server that exposes a Night Owls swarm as `ask_<agent>` tools (R15). Multi-turn HITL: an agent that
+ * asks the human mid-run returns `{ status: "needs_input", question, followupId }`; the caller answers by
+ * calling the same tool again with `{ followupId, answer }`. Serves machine callers, human MCP-client UIs, and
+ * services uniformly. Engine-wall-safe: raw MCP SDK + core types only, no engine-vendor imports; exposes ONLY
+ * `ask_<agent>` (never `run_<workflow>`).
+ */
+declare function createSwarmMcpServer(opts: SwarmMcpServerOpts): McpServer;
+/** Convenience: build the server and serve it over stdio. All logs go to stderr (stdout is the JSON-RPC
+ *  channel). Resolves with the connected server (await its transport close to keep the process alive). */
+declare function runSwarmMcpStdio(opts: SwarmMcpServerOpts): Promise<McpServer>;
+
+export { type SwarmMcpAgent, type SwarmMcpContext, type SwarmMcpServerOpts, createSwarmMcpServer, runSwarmMcpStdio };

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { SwarmEngine, StorageAdapter } from '@nightowlsdev/core';
+
+/** The caller identity resolved from an MCP request — the ONLY source of tenancy (never tool args). */
+interface SwarmMcpContext {
+    tenantId: string;
+    userId: string;
+}
+/** One agent to expose as an `ask_<slug>` tool. Pass `await engine.listAgents(ctx)` (AgentSummary[]) directly,
+ *  or a hand-built list. `name`/`role`/`description` only shape the tool's model-facing description. */
+interface SwarmMcpAgent {
+    slug: string;
+    name?: string;
+    role?: string;
+    description?: string;
+}
+interface SwarmMcpServerOpts {
+    engine: SwarmEngine;
+    storage: StorageAdapter;
+    /** The agents to expose (their slugs become `ask_<slug>` tools). Tool names are tenant-independent; the
+     *  per-request tenant (from `resolveContext`) selects each tenant's actual agent version at run time. */
+    agents: SwarmMcpAgent[];
+    /**
+     * Resolve the caller's identity from the MCP request's per-handler `extra` (transport/auth info). Return
+     * `null` to reject the call as unauthorized. Identity is taken ONLY from here — never from tool arguments,
+     * which are attacker-controllable. stdio/local: a fixed context; HTTP: read `extra.authInfo`/headers.
+     */
+    resolveContext: (extra: unknown) => Promise<SwarmMcpContext | null> | SwarmMcpContext | null;
+    /** Id generator for runId/threadId — injectable for deterministic tests. Default `crypto.randomUUID`. */
+    newId?: () => string;
+    name?: string;
+    version?: string;
+}
+/**
+ * Build an MCP server that exposes a Night Owls swarm as `ask_<agent>` tools (R15). Multi-turn HITL: an agent that
+ * asks the human mid-run returns `{ status: "needs_input", question, followupId }`; the caller answers by
+ * calling the same tool again with `{ followupId, answer }`. Serves machine callers, human MCP-client UIs, and
+ * services uniformly. Engine-wall-safe: raw MCP SDK + core types only, no engine-vendor imports; exposes ONLY
+ * `ask_<agent>` (never `run_<workflow>`).
+ */
+declare function createSwarmMcpServer(opts: SwarmMcpServerOpts): McpServer;
+/** Convenience: build the server and serve it over stdio. All logs go to stderr (stdout is the JSON-RPC
+ *  channel). Resolves with the connected server (await its transport close to keep the process alive). */
+declare function runSwarmMcpStdio(opts: SwarmMcpServerOpts): Promise<McpServer>;
+
+export { type SwarmMcpAgent, type SwarmMcpContext, type SwarmMcpServerOpts, createSwarmMcpServer, runSwarmMcpStdio };

package/dist/index.js

@@ -0,0 +1,74 @@
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+var ok = (payload) => ({ content: [{ type: "text", text: JSON.stringify(payload) }] });
+var err = (message) => ({ content: [{ type: "text", text: JSON.stringify({ status: "error", message }) }], isError: true });
+async function drain(iter, runId) {
+  let answer = "";
+  for await (const e of iter) {
+    if (e.type === "swarm.message" && e.data.role === "assistant") {
+      answer += e.data.text ?? e.data.delta ?? "";
+    } else if (e.type === "swarm.question") {
+      return ok({ status: "needs_input", question: e.data.prompt, followupId: e.data.followupId, partial: answer || void 0, runId });
+    } else if (e.type === "swarm.run_failed") {
+      return ok({ status: "failed", message: e.data.message, stage: e.data.stage, runId });
+    }
+  }
+  return ok({ status: "done", answer, runId });
+}
+async function handleAsk(opts, slug, args, extra) {
+  try {
+    const { engine, storage } = opts;
+    const auth = await opts.resolveContext(extra);
+    if (!auth) return err("unauthorized: resolveContext returned null");
+    const newId = opts.newId ?? (() => crypto.randomUUID());
+    if (args.followupId && args.answer != null) {
+      const found = await storage.runs.findSuspended(auth.tenantId, args.followupId);
+      if (!found) return err(`no suspended run for followup ${args.followupId}`);
+      const row = await storage.runs.get(found.runId);
+      if (!row || row.tenantId !== auth.tenantId) return err("forbidden");
+      const ctx2 = { tenantId: auth.tenantId, userId: auth.userId, agentSlug: row.agentSlug, runId: found.runId, threadId: row.threadId };
+      return await drain(engine.resume({ runId: found.runId, toolCallId: found.toolCallId, followupId: args.followupId, answer: args.answer, context: args.context }, ctx2), found.runId);
+    }
+    if (!args.message) return err("message is required for a new ask (or pass followupId + answer to resume)");
+    const runId = newId();
+    const threadId = args.threadId ?? newId();
+    const ctx = { tenantId: auth.tenantId, userId: auth.userId, agentSlug: slug, runId, threadId };
+    return await drain(engine.run({ message: args.message, context: args.context }, ctx), runId);
+  } catch (e) {
+    return err(e instanceof Error ? e.message : String(e));
+  }
+}
+function createSwarmMcpServer(opts) {
+  const server = new McpServer({ name: opts.name ?? "nightowls-swarm", version: opts.version ?? "0.1.0" });
+  for (const agent of opts.agents) {
+    const label = agent.name ?? agent.slug;
+    server.registerTool(
+      `ask_${agent.slug}`,
+      {
+        title: `Ask ${label}`,
+        description: agent.description ?? `Ask the ${label} agent${agent.role ? ` (${agent.role})` : ""}. Returns its answer, or { status: "needs_input", question, followupId } when it needs more from you \u2014 call this tool again with { followupId, answer } to continue the same conversation.`,
+        inputSchema: {
+          message: z.string().optional().describe("what to ask the agent (required for a new ask)"),
+          threadId: z.string().optional().describe("continue an existing conversation; omit to start a new one"),
+          context: z.record(z.string(), z.unknown()).optional().describe("untrusted/advisory page context"),
+          followupId: z.string().optional().describe("from a prior needs_input result \u2014 to answer the agent"),
+          answer: z.string().optional().describe("your answer to the agent's question (with followupId)")
+        }
+      },
+      (args, extra) => handleAsk(opts, agent.slug, args, extra)
+    );
+  }
+  return server;
+}
+async function runSwarmMcpStdio(opts) {
+  const server = createSwarmMcpServer(opts);
+  await server.connect(new StdioServerTransport());
+  console.error(`[nightowls] swarm MCP server ready on stdio (${opts.agents.length} ask_<agent> tools)`);
+  return server;
+}
+export {
+  createSwarmMcpServer,
+  runSwarmMcpStdio
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@nightowlsdev/mcp-server",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cueplusplus/corale.git",
+    "directory": "packages/mcp-server"
+  },
+  "homepage": "https://github.com/cueplusplus/corale#readme",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.0.0"
+  },
+  "peerDependencies": {
+    "@nightowlsdev/core": "0.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.4",
+    "ai": "^6.0.0",
+    "tsup": "8.5.1",
+    "typescript": "6.0.3",
+    "vitest": "^3.2.0",
+    "@nightowlsdev/core": "0.3.0",
+    "@nightowlsdev/eslint-config": "0.0.0",
+    "@nightowlsdev/tsconfig": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src"
+  }
+}