@nightowlsdev/mcp-server 0.1.0 → 1.0.0

package/README.md

@@ -0,0 +1,195 @@
+# @nightowlsdev/mcp-server
+
+> Expose a Night Owls swarm as `ask_<agent>` MCP tools — serving machine callers, human MCP-client UIs, and services uniformly.
+
+This package turns any Night Owls `SwarmEngine` into an MCP server. Each agent you register becomes an `ask_<slug>` tool that handles both fresh conversations and multi-turn human-in-the-loop (HITL) resume. The engine-wall contract is enforced: only `@nightowlsdev/core` types and the raw `@modelcontextprotocol/sdk` are imported — no engine-vendor (`@mastra/*`) symbols leak into the public API.
+
+## Install
+
+```sh
+pnpm add @nightowlsdev/mcp-server
+```
+
+**Peer dependencies** (install separately):
+
+```sh
+pnpm add @nightowlsdev/core
+```
+
+## Usage
+
+### stdio server (local / CLI integration)
+
+```ts
+import { runSwarmMcpStdio } from "@nightowlsdev/mcp-server";
+import { SwarmEngine, InMemoryStorage } from "@nightowlsdev/core";
+import type { SwarmMcpContext } from "@nightowlsdev/mcp-server";
+
+const storage = new InMemoryStorage();
+const engine = new SwarmEngine({ storage, model, modelFactory, cost });
+
+// All logs go to stderr; stdout is the JSON-RPC channel.
+await runSwarmMcpStdio({
+  engine,
+  storage,
+  agents: [
+    { slug: "biller", name: "Billing agent", role: "handles refunds and invoices" },
+    { slug: "support" },
+  ],
+  // stdio/local: return a fixed context.
+  // HTTP: read extra.authInfo or request headers — never tool args.
+  resolveContext: (): SwarmMcpContext => ({ tenantId: "acme", userId: "u-123" }),
+});
+// Process stays alive; connect your MCP client to its stdin/stdout.
+```
+
+### HTTP / programmatic server
+
+```ts
+import { createSwarmMcpServer } from "@nightowlsdev/mcp-server";
+
+const server = createSwarmMcpServer({
+  engine,
+  storage,
+  agents: await engine.listAgents(ctx), // AgentSummary[] — pass directly
+  resolveContext: async (extra) => {
+    // extra = transport/auth info from the MCP SDK; shape depends on your transport.
+    // Return null to reject as unauthorized.
+    const token = (extra as { authInfo?: { token: string } }).authInfo?.token;
+    if (!token) return null;
+    return { tenantId: "acme", userId: await verifyToken(token) };
+  },
+});
+
+// Wire to your chosen transport (e.g. StreamableHTTPServerTransport).
+await server.connect(transport);
+```
+
+## API
+
+### `createSwarmMcpServer(opts: SwarmMcpServerOpts): McpServer`
+
+Builds and returns an MCP `McpServer` (from `@modelcontextprotocol/sdk`) pre-loaded with one `ask_<slug>` tool per agent in `opts.agents`. The server is not yet connected — call `server.connect(transport)` yourself.
+
+### `runSwarmMcpStdio(opts: SwarmMcpServerOpts): Promise<McpServer>`
+
+Convenience wrapper: builds the server and immediately connects it to a `StdioServerTransport`. All diagnostic logs go to stderr; stdout carries the JSON-RPC channel. Resolves with the connected server; await it or attach a `close` handler to keep the process alive.
+
+### `SwarmMcpServerOpts`
+
+```ts
+interface SwarmMcpServerOpts {
+  /** The running Night Owls engine. */
+  engine: SwarmEngine;
+  /** The storage adapter (used to look up suspended runs on resume). */
+  storage: StorageAdapter;
+  /**
+   * Agents to expose. Each slug becomes an ask_<slug> MCP tool.
+   * Pass `await engine.listAgents(ctx)` (AgentSummary[]) directly, or a hand-built list.
+   * name/role/description only shape the tool's model-facing description.
+   */
+  agents: SwarmMcpAgent[];
+  /**
+   * Resolve caller 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.
+   */
+  resolveContext: (extra: unknown) => Promise<SwarmMcpContext | null> | SwarmMcpContext | null;
+  /** Id generator for runId and threadId. Injectable for deterministic tests. Default: crypto.randomUUID. */
+  newId?: () => string;
+  /** MCP server name advertised in the handshake. Default: "nightowls-swarm". */
+  name?: string;
+  /** MCP server version advertised in the handshake. Default: "0.1.0". */
+  version?: string;
+}
+```
+
+### `SwarmMcpAgent`
+
+```ts
+interface SwarmMcpAgent {
+  slug: string;       // Becomes the ask_<slug> tool name.
+  name?: string;      // Human label used in the tool title.
+  role?: string;      // Inserted into the auto-generated tool description.
+  description?: string; // Overrides the auto-generated tool description entirely.
+}
+```
+
+### `SwarmMcpContext`
+
+```ts
+interface SwarmMcpContext {
+  /** Tenant that owns this call — the ONLY source of tenancy; never read from tool args. */
+  tenantId: string;
+  /** The end-user making the request. */
+  userId: string;
+}
+```
+
+## `ask_<slug>` tool — input/output contract
+
+Every registered agent is exposed as an MCP tool named `ask_<slug>`. The tool handles both fresh asks and multi-turn HITL resume within the same signature.
+
+### Tool input
+
+| Field | Type | Required | Purpose |
+|---|---|---|---|
+| `message` | `string` | Required for a **new** ask | What to ask the agent. |
+| `threadId` | `string` | Optional | Continue an existing conversation. Omit to start a new thread. |
+| `context` | `Record<string, unknown>` | Optional | Untrusted/advisory page context forwarded to the agent. |
+| `followupId` | `string` | Required for **resume** | Taken from a prior `needs_input` result. |
+| `answer` | `string` | Required for **resume** | Your answer to the agent's suspended question. Pass with `followupId`. |
+
+For a fresh call, supply `message` (and optionally `threadId`/`context`). For a resume call, supply `followupId` + `answer` (message is ignored).
+
+### Tool output
+
+All results are returned as a JSON object in `content[0].text`. The `status` field selects the variant:
+
+**`done`** — the agent finished and returned its answer.
+
+```json
+{ "status": "done", "answer": "Refund of $42 processed.", "runId": "<uuid>" }
+```
+
+**`needs_input`** — the agent asked a question and is durably suspended. The run remains open; the caller must answer by calling the same tool again with `followupId` + `answer`.
+
+```json
+{
+  "status": "needs_input",
+  "question": "Which order number should I refund?",
+  "followupId": "<durable-token>",
+  "runId": "<uuid>",
+  "partial": "I can help with your refund."
+}
+```
+
+- `followupId` is the durable suspend token. **Do not discard it.** Without it the run cannot be resumed and will be orphaned.
+- `partial` carries any assistant text streamed before the question was asked; may be absent.
+- The `to` field on a swarm question is advisory metadata — the MCP caller (the host) is always the sole resumer, regardless of what `to` says.
+
+**`failed`** — the engine reported a run failure.
+
+```json
+{ "status": "failed", "message": "Tool call limit exceeded.", "stage": "run", "runId": "<uuid>" }
+```
+
+- `stage` echoes the engine's failure stage (e.g. `"run"`, `"resume"`).
+
+**`error`** — a pre-run error (unauthorized, missing argument, unknown agent, storage failure). `isError: true` is set on the MCP result envelope.
+
+```json
+{ "status": "error", "message": "unauthorized: resolveContext returned null" }
+```
+
+Every failure path — including engine throws that occur before the first event is yielded — returns this structured JSON shape rather than a raw exception, so callers can always parse `content[0].text` safely.
+
+## Configuration / Environment
+
+This package reads **no environment variables directly**. Configuration is passed entirely through `SwarmMcpServerOpts` at construction time. The underlying `@nightowlsdev/core` engine reads its own env vars (model keys, cost limits, etc.) — see the `@nightowlsdev/core` README.
+
+## Engine-wall contract
+
+`@nightowlsdev/mcp-server` imports only `@nightowlsdev/core` **types** and the raw `@modelcontextprotocol/sdk`. It never imports `@mastra/*` symbols. The wall is verified at build time: the compiled `dist/index.d.ts` must not reference `@mastra`. This means the package is safe to bundle in edge or non-Node runtimes that cannot load native Mastra dependencies.
+
+The package exposes **only** `ask_<agent>` tools — never `run_<workflow>` — as specified in the engine-wall contract (CONTRACTS §1).

package/dist/index.cjs

@@ -92,7 +92,7 @@ function createSwarmMcpServer(opts) {
 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)`);
+  console.error(`[@nightowlsdev/mcp-server] swarm MCP server ready on stdio (${opts.agents.length} ask_<agent> tools)`);
   return server;
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.js

@@ -65,7 +65,7 @@ function createSwarmMcpServer(opts) {
 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)`);
+  console.error(`[@nightowlsdev/mcp-server] swarm MCP server ready on stdio (${opts.agents.length} ask_<agent> tools)`);
   return server;
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nightowlsdev/mcp-server",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
@@ -31,7 +31,7 @@
     "zod": "^4.0.0"
   },
   "peerDependencies": {
-    "@nightowlsdev/core": "0.3.0"
+    "@nightowlsdev/core": "0.4.0"
   },
   "devDependencies": {
     "@types/node": "^24.12.4",
@@ -39,9 +39,9 @@
     "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"
+    "@nightowlsdev/core": "0.4.0",
+    "@nightowlsdev/tsconfig": "0.0.0",
+    "@nightowlsdev/eslint-config": "0.0.0"
   },
   "scripts": {
     "build": "tsup",