@nightowlsdev/mcp-server 1.0.0 → 2.0.0

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);
@@ -95,8 +97,109 @@ async function runSwarmMcpStdio(opts) {
   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

@@ -68,7 +68,108 @@ async function runSwarmMcpStdio(opts) {
   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": "1.0.0",
+  "version": "2.0.0",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
@@ -31,7 +31,7 @@
     "zod": "^4.0.0"
   },
   "peerDependencies": {
-    "@nightowlsdev/core": "0.4.0"
+    "@nightowlsdev/core": "0.5.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.4.0",
-    "@nightowlsdev/tsconfig": "0.0.0",
-    "@nightowlsdev/eslint-config": "0.0.0"
+    "@nightowlsdev/eslint-config": "0.0.0",
+    "@nightowlsdev/core": "0.5.0",
+    "@nightowlsdev/tsconfig": "0.0.0"
   },
   "scripts": {
     "build": "tsup",