@nightowlsdev/mcp-server 0.1.0 → 2.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

@@ -20,7 +20,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  createMcpServer: () => createMcpServer,
   createSwarmMcpServer: () => createSwarmMcpServer,
+  defineMcpTool: () => defineMcpTool,
   runSwarmMcpStdio: () => runSwarmMcpStdio
 });
 module.exports = __toCommonJS(index_exports);
@@ -92,11 +94,112 @@ 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;
 }
+
+// src/host-tools.ts
+var import_mcp2 = require("@modelcontextprotocol/sdk/server/mcp.js");
+var import_stdio2 = require("@modelcontextprotocol/sdk/server/stdio.js");
+var import_zod2 = require("zod");
+var PROTOCOL_VERSION = "2025-06-18";
+function bearerOf(req) {
+  return req.headers.get("authorization")?.replace(/^Bearer\s+/i, "") || void 0;
+}
+var jsonRpc = (id, result) => ({ jsonrpc: "2.0", id, result });
+var jsonRpcError = (id, code, message) => ({ jsonrpc: "2.0", id, error: { code, message } });
+function createMcpServer(opts) {
+  const byName = new Map(opts.tools.map((t) => [t.name, t]));
+  const server = new import_mcp2.McpServer({ name: opts.name ?? "nightowls-host", version: opts.version ?? "0.1.0" });
+  for (const t of opts.tools) {
+    server.registerTool(
+      t.name,
+      { title: t.name, description: t.description ?? t.name, inputSchema: t.inputSchema.shape },
+      async (args) => {
+        const out = await t.handler(args, opts.localContext ?? {});
+        return { content: [{ type: "text", text: JSON.stringify(out) }] };
+      }
+    );
+  }
+  const authorize = async (req) => {
+    if (!opts.auth?.verifyBearer) return { ctx: {} };
+    const resolved = await opts.auth.verifyBearer(bearerOf(req), { req });
+    return resolved ? { ctx: resolved } : { unauthorized: true };
+  };
+  const handleRpc = async (req, msg) => {
+    const { id, method } = msg;
+    switch (method) {
+      case "initialize":
+        return jsonRpc(id, { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: { name: opts.name ?? "nightowls-host", version: opts.version ?? "0.1.0" } });
+      case "notifications/initialized":
+        return null;
+      // a notification — no response
+      case "ping":
+        return jsonRpc(id, {});
+      case "tools/list": {
+        if ((await authorize(req)).unauthorized) return jsonRpcError(id, -32001, "unauthorized");
+        const tools = opts.tools.map((t) => ({ name: t.name, description: t.description ?? t.name, inputSchema: import_zod2.z.toJSONSchema(t.inputSchema) }));
+        return jsonRpc(id, { tools });
+      }
+      case "tools/call": {
+        const authed = await authorize(req);
+        if (authed.unauthorized) return jsonRpcError(id, -32001, "unauthorized");
+        const ctx = authed.ctx;
+        const name = msg.params?.name;
+        const tool = name ? byName.get(name) : void 0;
+        if (!tool) return jsonRpcError(id, -32602, `unknown tool: ${name ?? "(none)"}`);
+        const parsed = tool.inputSchema.safeParse(msg.params?.arguments ?? {});
+        if (!parsed.success) return jsonRpc(id, { content: [{ type: "text", text: JSON.stringify({ error: "invalid arguments", issues: parsed.error.issues }) }], isError: true });
+        try {
+          const out = await tool.handler(parsed.data, ctx);
+          return jsonRpc(id, { content: [{ type: "text", text: JSON.stringify(out) }] });
+        } catch (e) {
+          return jsonRpc(id, { content: [{ type: "text", text: JSON.stringify({ error: e instanceof Error ? e.message : String(e) }) }], isError: true });
+        }
+      }
+      default:
+        return jsonRpcError(id, -32601, `method not found: ${method ?? "(none)"}`);
+    }
+  };
+  const POST = async (req) => {
+    let body;
+    try {
+      body = await req.json();
+    } catch {
+      return Response.json(jsonRpcError(null, -32700, "parse error"), { status: 400 });
+    }
+    const reqs = Array.isArray(body) ? body : [body];
+    const out = [];
+    for (const m of reqs) {
+      const res = await handleRpc(req, m ?? {});
+      if (res !== null) out.push(res);
+    }
+    if (out.length === 0) return new Response(null, { status: 202 });
+    return Response.json(Array.isArray(body) ? out : out[0], { headers: { "cache-control": "no-store" } });
+  };
+  const GET = async () => new Response(JSON.stringify({ error: "GET not supported (stateless server \u2014 POST JSON-RPC)" }), { status: 405, headers: { "content-type": "application/json", allow: "POST" } });
+  const wellKnownGET = async () => opts.auth?.metadata ? Response.json(opts.auth.metadata, { headers: { "cache-control": "no-store" } }) : new Response(JSON.stringify({ error: "no discovery metadata configured" }), { status: 404, headers: { "content-type": "application/json" } });
+  return {
+    server,
+    httpRoute: () => {
+      if (!opts.auth?.verifyBearer) console.warn("[@nightowlsdev/mcp-server] createMcpServer.httpRoute() has no auth.verifyBearer \u2014 the HTTP endpoint is UNAUTHENTICATED (all tools open). Configure `auth` for any non-trusted deployment.");
+      return { GET, POST };
+    },
+    wellKnownRoute: () => ({ GET: wellKnownGET }),
+    stdio: async () => {
+      await server.connect(new import_stdio2.StdioServerTransport());
+      console.error(`[@nightowlsdev/mcp-server] host MCP server ready on stdio (${opts.tools.length} tools)`);
+      return server;
+    }
+  };
+}
+function defineMcpTool(def) {
+  return def;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  createMcpServer,
   createSwarmMcpServer,
+  defineMcpTool,
   runSwarmMcpStdio
 });

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { SwarmEngine, StorageAdapter } from '@nightowlsdev/core';
+import { z } from 'zod';
 
 /** The caller identity resolved from an MCP request — the ONLY source of tenancy (never tool args). */
 interface SwarmMcpContext {
@@ -43,4 +44,51 @@ declare function createSwarmMcpServer(opts: SwarmMcpServerOpts): McpServer;
  *  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 };
+/** The per-call identity a host tool sees — whatever `verifyBearer` returns (e.g. `{ userId }`). For stdio (local)
+ *  it is `{}` unless a `localContext` is supplied. Tools take identity ONLY from here, never from their args. */
+type McpToolContext = Record<string, unknown>;
+/** One host tool: a zod object input + a handler that receives the validated args and the resolved identity ctx. */
+interface McpToolDef<I extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>> {
+    name: string;
+    description?: string;
+    inputSchema: I;
+    handler: (args: z.infer<I>, ctx: McpToolContext) => Promise<unknown> | unknown;
+}
+/** Pluggable auth seam. `verifyBearer` validates the request's bearer token and returns the per-call identity ctx
+ *  (or null to reject 401). Omit for an unauthenticated server (local/stdio, or a host gating elsewhere).
+ *  `metadata` (optional) is served verbatim at `/.well-known/oauth-protected-resource` for discovery — a host that
+ *  runs its own OAuth AS points clients at it here; this package does not implement the AS. */
+interface McpAuth {
+    verifyBearer?: (token: string | undefined, extra: {
+        req: Request;
+    }) => Promise<McpToolContext | null> | McpToolContext | null;
+    metadata?: Record<string, unknown>;
+}
+interface CreateMcpServerOpts {
+    tools: McpToolDef[];
+    auth?: McpAuth;
+    name?: string;
+    version?: string;
+    /** Identity ctx for the stdio transport (no HTTP bearer there). Default `{}`. */
+    localContext?: McpToolContext;
+}
+type RouteHandler = (req: Request) => Promise<Response>;
+/** The generic host-tool MCP server. `httpRoute()` → a stateless `{ GET, POST }` for a Next.js App Router route;
+ *  `stdio()` serves the same tools over stdio; `wellKnownRoute()` serves the optional discovery metadata. */
+interface HostMcpServer {
+    /** The underlying SDK server (host tools registered) — for stdio + advanced wiring. */
+    readonly server: McpServer;
+    httpRoute(): {
+        GET: RouteHandler;
+        POST: RouteHandler;
+    };
+    wellKnownRoute(): {
+        GET: RouteHandler;
+    };
+    stdio(): Promise<McpServer>;
+}
+declare function createMcpServer(opts: CreateMcpServerOpts): HostMcpServer;
+/** Define a host tool with inferred arg typing — a small ergonomic wrapper over the `McpToolDef` shape. */
+declare function defineMcpTool<I extends z.ZodObject<z.ZodRawShape>>(def: McpToolDef<I>): McpToolDef<I>;
+
+export { type CreateMcpServerOpts, type HostMcpServer, type McpAuth, type McpToolContext, type McpToolDef, type SwarmMcpAgent, type SwarmMcpContext, type SwarmMcpServerOpts, createMcpServer, createSwarmMcpServer, defineMcpTool, runSwarmMcpStdio };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { SwarmEngine, StorageAdapter } from '@nightowlsdev/core';
+import { z } from 'zod';
 
 /** The caller identity resolved from an MCP request — the ONLY source of tenancy (never tool args). */
 interface SwarmMcpContext {
@@ -43,4 +44,51 @@ declare function createSwarmMcpServer(opts: SwarmMcpServerOpts): McpServer;
  *  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 };
+/** The per-call identity a host tool sees — whatever `verifyBearer` returns (e.g. `{ userId }`). For stdio (local)
+ *  it is `{}` unless a `localContext` is supplied. Tools take identity ONLY from here, never from their args. */
+type McpToolContext = Record<string, unknown>;
+/** One host tool: a zod object input + a handler that receives the validated args and the resolved identity ctx. */
+interface McpToolDef<I extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>> {
+    name: string;
+    description?: string;
+    inputSchema: I;
+    handler: (args: z.infer<I>, ctx: McpToolContext) => Promise<unknown> | unknown;
+}
+/** Pluggable auth seam. `verifyBearer` validates the request's bearer token and returns the per-call identity ctx
+ *  (or null to reject 401). Omit for an unauthenticated server (local/stdio, or a host gating elsewhere).
+ *  `metadata` (optional) is served verbatim at `/.well-known/oauth-protected-resource` for discovery — a host that
+ *  runs its own OAuth AS points clients at it here; this package does not implement the AS. */
+interface McpAuth {
+    verifyBearer?: (token: string | undefined, extra: {
+        req: Request;
+    }) => Promise<McpToolContext | null> | McpToolContext | null;
+    metadata?: Record<string, unknown>;
+}
+interface CreateMcpServerOpts {
+    tools: McpToolDef[];
+    auth?: McpAuth;
+    name?: string;
+    version?: string;
+    /** Identity ctx for the stdio transport (no HTTP bearer there). Default `{}`. */
+    localContext?: McpToolContext;
+}
+type RouteHandler = (req: Request) => Promise<Response>;
+/** The generic host-tool MCP server. `httpRoute()` → a stateless `{ GET, POST }` for a Next.js App Router route;
+ *  `stdio()` serves the same tools over stdio; `wellKnownRoute()` serves the optional discovery metadata. */
+interface HostMcpServer {
+    /** The underlying SDK server (host tools registered) — for stdio + advanced wiring. */
+    readonly server: McpServer;
+    httpRoute(): {
+        GET: RouteHandler;
+        POST: RouteHandler;
+    };
+    wellKnownRoute(): {
+        GET: RouteHandler;
+    };
+    stdio(): Promise<McpServer>;
+}
+declare function createMcpServer(opts: CreateMcpServerOpts): HostMcpServer;
+/** Define a host tool with inferred arg typing — a small ergonomic wrapper over the `McpToolDef` shape. */
+declare function defineMcpTool<I extends z.ZodObject<z.ZodRawShape>>(def: McpToolDef<I>): McpToolDef<I>;
+
+export { type CreateMcpServerOpts, type HostMcpServer, type McpAuth, type McpToolContext, type McpToolDef, type SwarmMcpAgent, type SwarmMcpContext, type SwarmMcpServerOpts, createMcpServer, createSwarmMcpServer, defineMcpTool, runSwarmMcpStdio };

package/dist/index.js

@@ -65,10 +65,111 @@ 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;
 }
+
+// src/host-tools.ts
+import { McpServer as McpServer2 } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport as StdioServerTransport2 } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z as z2 } from "zod";
+var PROTOCOL_VERSION = "2025-06-18";
+function bearerOf(req) {
+  return req.headers.get("authorization")?.replace(/^Bearer\s+/i, "") || void 0;
+}
+var jsonRpc = (id, result) => ({ jsonrpc: "2.0", id, result });
+var jsonRpcError = (id, code, message) => ({ jsonrpc: "2.0", id, error: { code, message } });
+function createMcpServer(opts) {
+  const byName = new Map(opts.tools.map((t) => [t.name, t]));
+  const server = new McpServer2({ name: opts.name ?? "nightowls-host", version: opts.version ?? "0.1.0" });
+  for (const t of opts.tools) {
+    server.registerTool(
+      t.name,
+      { title: t.name, description: t.description ?? t.name, inputSchema: t.inputSchema.shape },
+      async (args) => {
+        const out = await t.handler(args, opts.localContext ?? {});
+        return { content: [{ type: "text", text: JSON.stringify(out) }] };
+      }
+    );
+  }
+  const authorize = async (req) => {
+    if (!opts.auth?.verifyBearer) return { ctx: {} };
+    const resolved = await opts.auth.verifyBearer(bearerOf(req), { req });
+    return resolved ? { ctx: resolved } : { unauthorized: true };
+  };
+  const handleRpc = async (req, msg) => {
+    const { id, method } = msg;
+    switch (method) {
+      case "initialize":
+        return jsonRpc(id, { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: { name: opts.name ?? "nightowls-host", version: opts.version ?? "0.1.0" } });
+      case "notifications/initialized":
+        return null;
+      // a notification — no response
+      case "ping":
+        return jsonRpc(id, {});
+      case "tools/list": {
+        if ((await authorize(req)).unauthorized) return jsonRpcError(id, -32001, "unauthorized");
+        const tools = opts.tools.map((t) => ({ name: t.name, description: t.description ?? t.name, inputSchema: z2.toJSONSchema(t.inputSchema) }));
+        return jsonRpc(id, { tools });
+      }
+      case "tools/call": {
+        const authed = await authorize(req);
+        if (authed.unauthorized) return jsonRpcError(id, -32001, "unauthorized");
+        const ctx = authed.ctx;
+        const name = msg.params?.name;
+        const tool = name ? byName.get(name) : void 0;
+        if (!tool) return jsonRpcError(id, -32602, `unknown tool: ${name ?? "(none)"}`);
+        const parsed = tool.inputSchema.safeParse(msg.params?.arguments ?? {});
+        if (!parsed.success) return jsonRpc(id, { content: [{ type: "text", text: JSON.stringify({ error: "invalid arguments", issues: parsed.error.issues }) }], isError: true });
+        try {
+          const out = await tool.handler(parsed.data, ctx);
+          return jsonRpc(id, { content: [{ type: "text", text: JSON.stringify(out) }] });
+        } catch (e) {
+          return jsonRpc(id, { content: [{ type: "text", text: JSON.stringify({ error: e instanceof Error ? e.message : String(e) }) }], isError: true });
+        }
+      }
+      default:
+        return jsonRpcError(id, -32601, `method not found: ${method ?? "(none)"}`);
+    }
+  };
+  const POST = async (req) => {
+    let body;
+    try {
+      body = await req.json();
+    } catch {
+      return Response.json(jsonRpcError(null, -32700, "parse error"), { status: 400 });
+    }
+    const reqs = Array.isArray(body) ? body : [body];
+    const out = [];
+    for (const m of reqs) {
+      const res = await handleRpc(req, m ?? {});
+      if (res !== null) out.push(res);
+    }
+    if (out.length === 0) return new Response(null, { status: 202 });
+    return Response.json(Array.isArray(body) ? out : out[0], { headers: { "cache-control": "no-store" } });
+  };
+  const GET = async () => new Response(JSON.stringify({ error: "GET not supported (stateless server \u2014 POST JSON-RPC)" }), { status: 405, headers: { "content-type": "application/json", allow: "POST" } });
+  const wellKnownGET = async () => opts.auth?.metadata ? Response.json(opts.auth.metadata, { headers: { "cache-control": "no-store" } }) : new Response(JSON.stringify({ error: "no discovery metadata configured" }), { status: 404, headers: { "content-type": "application/json" } });
+  return {
+    server,
+    httpRoute: () => {
+      if (!opts.auth?.verifyBearer) console.warn("[@nightowlsdev/mcp-server] createMcpServer.httpRoute() has no auth.verifyBearer \u2014 the HTTP endpoint is UNAUTHENTICATED (all tools open). Configure `auth` for any non-trusted deployment.");
+      return { GET, POST };
+    },
+    wellKnownRoute: () => ({ GET: wellKnownGET }),
+    stdio: async () => {
+      await server.connect(new StdioServerTransport2());
+      console.error(`[@nightowlsdev/mcp-server] host MCP server ready on stdio (${opts.tools.length} tools)`);
+      return server;
+    }
+  };
+}
+function defineMcpTool(def) {
+  return def;
+}
 export {
+  createMcpServer,
   createSwarmMcpServer,
+  defineMcpTool,
   runSwarmMcpStdio
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nightowlsdev/mcp-server",
-  "version": "0.1.0",
+  "version": "2.0.0",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
@@ -31,7 +31,7 @@
     "zod": "^4.0.0"
   },
   "peerDependencies": {
-    "@nightowlsdev/core": "0.3.0"
+    "@nightowlsdev/core": "0.5.0"
   },
   "devDependencies": {
     "@types/node": "^24.12.4",
@@ -39,8 +39,8 @@
     "tsup": "8.5.1",
     "typescript": "6.0.3",
     "vitest": "^3.2.0",
-    "@nightowlsdev/core": "0.3.0",
     "@nightowlsdev/eslint-config": "0.0.0",
+    "@nightowlsdev/core": "0.5.0",
     "@nightowlsdev/tsconfig": "0.0.0"
   },
   "scripts": {