@hazeljs/mcp 0.7.9 → 0.8.0

package/dist/server/stdioTransport.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * STDIO Transport
+ *
+ * Reads newline-delimited JSON from process.stdin, passes each message to the
+ * supplied RequestHandler, and writes the JSON-RPC response back to
+ * process.stdout followed by a newline.
+ *
+ * Design decisions:
+ *   - Each incoming line is handled in its own promise chain (no await in the
+ *     readline handler) so slow tool calls don't block subsequent requests.
+ *   - JSON parse errors are returned as -32700 responses instead of crashing.
+ *   - Unexpected handler exceptions are caught and returned as -32603 so the
+ *     server never exits due to user input.
+ *   - process.stdin 'close' triggers a clean process.exit(0) — MCP clients
+ *     that close stdin expect the server to terminate.
+ *
+ * Extension note:
+ *   To add HTTP/SSE transport, implement the same RequestHandler signature
+ *   and wire it to incoming HTTP requests (e.g. via Express or Fastify).
+ *   The handler itself, the adapter, and all protocol types stay unchanged.
+ *
+ *   Example HTTP skeleton:
+ *     app.post('/rpc', async (req, res) => {
+ *       const response = await handler(req.body as McpRequest);
+ *       res.json(response);
+ *     });
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStdioTransport = createStdioTransport;
+const readline = __importStar(require("readline"));
+const errors_1 = require("./errors");
+/**
+ * Attach the STDIO transport to the current process.
+ *
+ * After this call, the process reads from stdin and writes to stdout until
+ * stdin is closed. Call this once at server startup.
+ */
+function createStdioTransport(handler) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        // terminal: false disables readline's default SIGINT / line-echoing
+        terminal: false,
+    });
+    rl.on('line', (line) => {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        // Fire-and-forget: concurrent tool calls are handled independently
+        void handleLine(trimmed, handler);
+    });
+    rl.on('close', () => {
+        // Client closed stdin — exit cleanly rather than hanging
+        process.exit(0);
+    });
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+async function handleLine(line, handler) {
+    let request;
+    try {
+        request = JSON.parse(line);
+    }
+    catch {
+        writeResponse((0, errors_1.parseError)(null));
+        return;
+    }
+    const id = request.id ?? null;
+    try {
+        const response = await handler(request);
+        writeResponse(response);
+    }
+    catch (err) {
+        // The handler should never throw, but guard here as a last resort
+        writeResponse((0, errors_1.internalError)(id, err));
+    }
+}
+function writeResponse(response) {
+    process.stdout.write(JSON.stringify(response) + '\n');
+}
+//# sourceMappingURL=stdioTransport.js.map

package/dist/server/stdioTransport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdioTransport.js","sourceRoot":"","sources":["../../src/server/stdioTransport.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAcH,oDAmBC;AA/BD,mDAAqC;AAErC,qCAAqD;AAIrD;;;;;GAKG;AACH,SAAgB,oBAAoB,CAAC,OAAuB;IAC1D,MAAM,EAAE,GAAG,QAAQ,CAAC,eAAe,CAAC;QAClC,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,oEAAoE;QACpE,QAAQ,EAAE,KAAK;KAChB,CAAC,CAAC;IAEH,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE;QAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,CAAC,OAAO;YAAE,OAAO;QAErB,mEAAmE;QACnE,KAAK,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;QAClB,yDAAyD;QACzD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E,KAAK,UAAU,UAAU,CAAC,IAAY,EAAE,OAAuB;IAC7D,IAAI,OAAmB,CAAC;IAExB,IAAI,CAAC;QACH,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAe,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,aAAa,CAAC,IAAA,mBAAU,EAAC,IAAI,CAAC,CAAC,CAAC;QAChC,OAAO;IACT,CAAC;IAED,MAAM,EAAE,GAAG,OAAO,CAAC,EAAE,IAAI,IAAI,CAAC;IAE9B,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;QACxC,aAAa,CAAC,QAAQ,CAAC,CAAC;IAC1B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,kEAAkE;QAClE,aAAa,CAAC,IAAA,sBAAa,EAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IACxC,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,QAAwC;IAC7D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,CAAC;AACxD,CAAC"}

package/dist/server/types.d.ts

@@ -0,0 +1,131 @@
+/**
+ * MCP Protocol Types — JSON-RPC 2.0
+ *
+ * This module defines the minimal set of types needed for the Model Context
+ * Protocol over STDIO. The full spec lives at:
+ * https://spec.modelcontextprotocol.io/
+ *
+ * Extension note: When adding HTTP/SSE transport in the future, only the
+ * transport layer changes. These types remain unchanged because they describe
+ * the protocol messages, not the transport mechanism.
+ */
+/** A single JSON Schema property descriptor used in inputSchema */
+export interface JsonSchemaProperty {
+    type: string;
+    description: string;
+    enum?: unknown[];
+}
+/**
+ * MCP tool definition — what is advertised to clients on tools/list.
+ *
+ * Mapping from Hazel:
+ *   ToolMetadata.name        → name
+ *   ToolMetadata.description → description
+ *   ToolMetadata.parameters  → inputSchema.properties / required
+ */
+export interface McpToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, JsonSchemaProperty>;
+        required: string[];
+    };
+}
+/** JSON-RPC 2.0 inbound request */
+export interface McpRequest {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    method: string;
+    params?: unknown;
+}
+/** JSON-RPC 2.0 successful response */
+export interface McpResponse {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    result: unknown;
+}
+/** JSON-RPC 2.0 error object */
+export interface McpError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+/** JSON-RPC 2.0 error response */
+export interface McpErrorResponse {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    error: McpError;
+}
+/** Params received with the initialize request */
+export interface InitializeParams {
+    protocolVersion: string;
+    capabilities?: Record<string, unknown>;
+    clientInfo?: {
+        name: string;
+        version: string;
+    };
+}
+/** Params received with tools/call */
+export interface CallToolParams {
+    name: string;
+    arguments?: Record<string, unknown>;
+}
+/** Server capabilities advertised during the initialize handshake */
+export interface ServerCapabilities {
+    tools?: {
+        listChanged?: boolean;
+    };
+}
+/**
+ * Minimal representation of a Hazel tool as seen by the MCP adapter.
+ *
+ * @hazeljs/agent's ToolMetadata is a structural superset of this interface,
+ * so a ToolRegistry instance can be passed as IToolRegistry without any cast.
+ *
+ * If you use a custom registry (no decorators), implement this interface
+ * directly — see examples/stdio-server for a reference implementation.
+ */
+export interface HazelTool {
+    name: string;
+    description: string;
+    parameters?: Array<{
+        name: string;
+        type: string;
+        description: string;
+        required?: boolean;
+        enum?: unknown[];
+    }>;
+    /** The object whose context the method should be called with */
+    target: object;
+    /** The callable function — invoked as method.call(target, input) */
+    method: Function;
+}
+/**
+ * The interface a tool registry must satisfy to work with @hazeljs/mcp.
+ *
+ * @hazeljs/agent's ToolRegistry satisfies this interface out of the box.
+ * You can also roll your own for standalone MCP servers — see the example.
+ */
+export interface IToolRegistry {
+    getAllTools(): HazelTool[];
+    getTool(toolName: string): HazelTool | undefined;
+    hasTool(toolName: string): boolean;
+}
+/** Options passed to createMcpServer() */
+export interface McpServerOptions {
+    /** Server name advertised to MCP clients during initialize */
+    name: string;
+    /** Server version advertised to MCP clients during initialize */
+    version: string;
+    /** Hazel tool registry — @hazeljs/agent ToolRegistry or a custom one */
+    toolRegistry: IToolRegistry;
+}
+/** The object returned by createMcpServer() */
+export interface McpServer {
+    /** Attach to process.stdin / process.stdout and start serving */
+    listenStdio(): void;
+    /** Return the current list of MCP tool definitions */
+    listTools(): McpToolDefinition[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/server/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"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"}

package/dist/server/types.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * MCP Protocol Types — JSON-RPC 2.0
+ *
+ * This module defines the minimal set of types needed for the Model Context
+ * Protocol over STDIO. The full spec lives at:
+ * https://spec.modelcontextprotocol.io/
+ *
+ * Extension note: When adding HTTP/SSE transport in the future, only the
+ * transport layer changes. These types remain unchanged because they describe
+ * the protocol messages, not the transport mechanism.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/server/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hazeljs/mcp",
-  "version": "0.7.9",
+  "version": "0.8.0",
   "description": "Expose HazelJS tools as MCP (Model Context Protocol) tools over STDIO",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -54,5 +54,5 @@
       "description": "Required when using @hazeljs/agent ToolRegistry. Not needed for custom IToolRegistry implementations."
     }
   },
-  "gitHead": "28c21c509aeca3bf2d0878fbee737d906b654c67"
+  "gitHead": "e0ed98ca074dd4f7472816d3c32ef576900dcca6"
 }