tiny-stdio-mcp-server 0.1.16 → 0.1.18

package/README.md

@@ -125,7 +125,7 @@ Dynamically add/remove tools at runtime and notify connected clients.
 
 ## Configuration Options
 
-- `createServer({ name, version })`: server identity sent during MCP initialization.
+- `createServer({ name, version, toolCallTimeoutMs? })`: server identity plus an optional positive-integer tool timeout in milliseconds. Timed-out calls return JSON-RPC error `-32603`; handlers continue running in the background.
 - `.tool(name, description, schema, handler, outputSchema?)`: tool metadata, input schema, handler, and optional structured output schema.
 - `.connect({ readable, writable })`: custom stream transport for tests or embedded hosts.
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { createServer } from "./server.js";
-export type { MessageHandler, MessageSession, Server } from "./server.js";
+export type { CustomMethodHandler, MessageHandler, MessageSession, MessageSessionContext, Server } from "./server.js";
 export { defineSchema } from "./schema.js";
 export type { TypedSchema } from "./schema.js";
 export { Image, Audio, File, toContentBlocks, fileTypeFromBuffer, DEFAULT_FROM_URL_MAX_BYTES, } from "./content/index.js";

package/dist/server.d.ts

@@ -6,6 +6,7 @@ export interface Server {
     prompt(definition: Prompt, handler: PromptHandler): Server;
     resource(definition: Resource, handler: ResourceHandler): Server;
     resourceTemplate(definition: ResourceTemplate, handler: ResourceHandler): Server;
+    method(name: string, handler: CustomMethodHandler): Server;
     onNotification(listener: (notification: JSONRPCNotification) => void): () => void;
     removeTool(name: string): boolean;
     removePrompt(name: string): boolean;
@@ -21,6 +22,11 @@ export interface Server {
     connect(transport: Transport): Promise<void>;
     connectSDK(transport: SDKTransport): Promise<void>;
 }
+export interface MessageSessionContext {
+    readonly signal: AbortSignal;
+    notify(method: string, params?: Record<string, unknown>): Promise<void>;
+}
+export type CustomMethodHandler = (params: Record<string, unknown> | undefined, session: MessageSessionContext) => unknown | Promise<unknown>;
 export type MessageHandler = (method: string, params?: Record<string, unknown>) => Promise<HandleResult>;
 export interface MessageSession {
     handleMessage: MessageHandler;

package/dist/server.js

@@ -3,15 +3,15 @@ import AjvModule from "ajv";
 import uriTemplateParser from "uri-template";
 import UriTemplate from "uri-template-lite";
 import { JSON_RPC_ERROR_CODES, ToolError } from "./types.js";
-import { parseMessage, formatSuccessResponse, formatErrorResponse, } from "./jsonrpc.js";
+import { parseMessage, formatSuccessResponse, formatErrorResponse } from "./jsonrpc.js";
 import { toContentBlocks } from "./content/convert.js";
 const PROTOCOL_VERSION = "2025-11-25";
-const SUPPORTED_PROTOCOL_VERSIONS = new Set([
-    "2025-03-26",
-    "2025-06-18",
-    PROTOCOL_VERSION,
-]);
+const SUPPORTED_PROTOCOL_VERSIONS = new Set(["2025-03-26", "2025-06-18", PROTOCOL_VERSION]);
 export function createServer(options) {
+    if (options.toolCallTimeoutMs !== undefined &&
+        (!Number.isInteger(options.toolCallTimeoutMs) || options.toolCallTimeoutMs <= 0)) {
+        throw new Error("toolCallTimeoutMs must be a positive integer.");
+    }
     const Ajv = "default" in AjvModule ? AjvModule.default : AjvModule;
     const jsonSchemaValidator = new Ajv({ strict: false });
     const supportNotifications = options.supportNotifications !== false;
@@ -20,6 +20,7 @@ export function createServer(options) {
     const prompts = new Map();
     const resources = new Map();
     const resourceTemplates = new Map();
+    const methods = new Map();
     const notificationListeners = new Set();
     const connectionNotificationListeners = new Map();
     const defaultLifecycle = {
@@ -27,6 +28,7 @@ export function createServer(options) {
         initializeAccepted: false,
         notificationReady: false,
         resourceSubscriptions: new Set(),
+        abortController: new AbortController()
     };
     const messageLifecycles = new Set([defaultLifecycle]);
     const handleMessageWithLifecycle = async (method, lifecycle, params) => {
@@ -43,30 +45,27 @@ export function createServer(options) {
             lifecycle.initializeAccepted = true;
             lifecycle.initialized = true;
             lifecycle.notificationReady = false;
-            const requestedProtocol = typeof params?.protocolVersion === "string"
-                ? params.protocolVersion
-                : undefined;
+            const requestedProtocol = typeof params?.protocolVersion === "string" ? params.protocolVersion : undefined;
             const result = {
-                protocolVersion: requestedProtocol !== undefined &&
-                    SUPPORTED_PROTOCOL_VERSIONS.has(requestedProtocol)
+                protocolVersion: requestedProtocol !== undefined && SUPPORTED_PROTOCOL_VERSIONS.has(requestedProtocol)
                     ? requestedProtocol
                     : PROTOCOL_VERSION,
                 capabilities: {
                     tools: {
-                        ...(supportNotifications ? { listChanged: true } : {}),
+                        ...(supportNotifications ? { listChanged: true } : {})
                     },
                     prompts: {
-                        ...(supportNotifications ? { listChanged: true } : {}),
+                        ...(supportNotifications ? { listChanged: true } : {})
                     },
                     resources: {
                         ...(supportNotifications ? { listChanged: true } : {}),
-                        ...(supportResourceSubscriptions ? { subscribe: true } : {}),
-                    },
+                        ...(supportResourceSubscriptions ? { subscribe: true } : {})
+                    }
                 },
                 serverInfo: {
                     name: options.name,
-                    version: options.version,
-                },
+                    version: options.version
+                }
             };
             return { result };
         }
@@ -75,8 +74,8 @@ export function createServer(options) {
                 return {
                     error: {
                         code: JSON_RPC_ERROR_CODES.INVALID_REQUEST,
-                        message: "Server not initialized",
-                    },
+                        message: "Server not initialized"
+                    }
                 };
             }
             lifecycle.notificationReady = true;
@@ -87,8 +86,8 @@ export function createServer(options) {
             return {
                 error: {
                     code: JSON_RPC_ERROR_CODES.INVALID_REQUEST,
-                    message: "Server not initialized",
-                },
+                    message: "Server not initialized"
+                }
             };
         }
         if (method === "tools/list") {
@@ -97,10 +96,9 @@ export function createServer(options) {
                 const descriptor = { ...tool };
                 delete descriptor.handler;
                 delete descriptor.inputValidator;
-                delete descriptor
-                    .outputValidator;
+                delete descriptor.outputValidator;
                 toolList.push({
-                    ...descriptor,
+                    ...descriptor
                 });
             }
             return { result: { tools: toolList } };
@@ -111,8 +109,8 @@ export function createServer(options) {
                 return {
                     error: {
                         code: JSON_RPC_ERROR_CODES.INVALID_PARAMS,
-                        message: "Tool name required",
-                    },
+                        message: "Tool name required"
+                    }
                 };
             }
             const tool = tools.get(toolName);
@@ -120,24 +118,42 @@ export function createServer(options) {
                 return {
                     error: {
                         code: JSON_RPC_ERROR_CODES.INVALID_PARAMS,
-                        message: `Tool not found: ${toolName}`,
-                    },
+                        message: `Tool not found: ${toolName}`
+                    }
                 };
             }
             const toolArgs = (params?.arguments ?? {});
-            if (options.validateToolArguments !== false &&
-                !tool.inputValidator(toolArgs)) {
+            if (options.validateToolArguments !== false && !tool.inputValidator(toolArgs)) {
                 const errors = tool.inputValidator.errors ?? [];
                 return {
                     error: {
                         code: JSON_RPC_ERROR_CODES.INVALID_PARAMS,
                         message: `Invalid tool arguments: ${jsonSchemaValidator.errorsText(errors)}`,
-                        data: errors,
-                    },
+                        data: errors
+                    }
                 };
             }
             try {
-                const handlerResult = await tool.handler(toolArgs);
+                let handlerResult;
+                if (options.toolCallTimeoutMs === undefined) {
+                    handlerResult = await tool.handler(toolArgs);
+                }
+                else {
+                    let timeout;
+                    const handlerPromise = Promise.resolve().then(() => tool.handler(toolArgs));
+                    handlerResult = await Promise.race([
+                        handlerPromise,
+                        new Promise((_resolve, reject) => {
+                            timeout = setTimeout(() => {
+                                reject(new ToolError(JSON_RPC_ERROR_CODES.INTERNAL_ERROR, `Tool call timed out: ${toolName}`));
+                            }, options.toolCallTimeoutMs);
+                        })
+                    ]).finally(() => {
+                        if (timeout !== undefined) {
+                            clearTimeout(timeout);
+                        }
+                    });
+                }
                 const result = normalizeToolResult(handlerResult, tool.outputSchema);
                 if (result.isError !== true &&
                     tool.outputValidator !== undefined &&
@@ -153,14 +169,14 @@ export function createServer(options) {
                         error: {
                             code: err.code,
                             message: err.message,
-                            ...(err.data === undefined ? {} : { data: err.data }),
-                        },
+                            ...(err.data === undefined ? {} : { data: err.data })
+                        }
                     };
                 }
                 const errorMessage = err instanceof Error ? err.message : String(err);
                 const result = {
                     content: [{ type: "text", text: `Error: ${errorMessage}` }],
-                    isError: true,
+                    isError: true
                 };
                 return { result };
             }
@@ -168,8 +184,8 @@ export function createServer(options) {
         if (method === "prompts/list") {
             return {
                 result: {
-                    prompts: [...prompts.values()].map(({ handler: _handler, ...prompt }) => prompt),
-                },
+                    prompts: [...prompts.values()].map(({ handler: _handler, ...prompt }) => prompt)
+                }
             };
         }
         if (method === "prompts/get") {
@@ -199,15 +215,15 @@ export function createServer(options) {
         if (method === "resources/list") {
             return {
                 result: {
-                    resources: [...resources.values()].map(({ handler: _handler, ...resource }) => resource),
-                },
+                    resources: [...resources.values()].map(({ handler: _handler, ...resource }) => resource)
+                }
             };
         }
         if (method === "resources/templates/list") {
             return {
                 result: {
-                    resourceTemplates: [...resourceTemplates.values()].map(({ handler: _handler, ...resourceTemplate }) => resourceTemplate),
-                },
+                    resourceTemplates: [...resourceTemplates.values()].map(({ handler: _handler, ...resourceTemplate }) => resourceTemplate)
+                }
             };
         }
         if (method === "resources/read") {
@@ -230,14 +246,13 @@ export function createServer(options) {
                 return internalError(toErrorMessage(error));
             }
         }
-        if (method === "resources/subscribe" ||
-            method === "resources/unsubscribe") {
+        if (method === "resources/subscribe" || method === "resources/unsubscribe") {
             if (!supportResourceSubscriptions) {
                 return {
                     error: {
                         code: JSON_RPC_ERROR_CODES.METHOD_NOT_FOUND,
-                        message: "Method not found",
-                    },
+                        message: "Method not found"
+                    }
                 };
             }
             const uri = typeof params?.uri === "string" ? params.uri : undefined;
@@ -256,11 +271,33 @@ export function createServer(options) {
             }
             return { result: {} };
         }
+        const customMethod = methods.get(method);
+        if (customMethod !== undefined) {
+            try {
+                const result = await customMethod(params, {
+                    signal: lifecycle.abortController.signal,
+                    async notify(notificationMethod, notificationParams) {
+                        if (!lifecycle.notificationReady || lifecycle.listener === undefined) {
+                            return;
+                        }
+                        await lifecycle.listener({
+                            jsonrpc: "2.0",
+                            method: notificationMethod,
+                            ...(notificationParams === undefined ? {} : { params: notificationParams })
+                        });
+                    }
+                });
+                return { result };
+            }
+            catch (error) {
+                return internalError(toErrorMessage(error));
+            }
+        }
         return {
             error: {
                 code: JSON_RPC_ERROR_CODES.METHOD_NOT_FOUND,
-                message: "Method not found",
-            },
+                message: "Method not found"
+            }
         };
     };
     const createMessageSession = (listener) => {
@@ -269,6 +306,8 @@ export function createServer(options) {
             initializeAccepted: false,
             notificationReady: false,
             resourceSubscriptions: new Set(),
+            abortController: new AbortController(),
+            listener
         };
         messageLifecycles.add(lifecycle);
         if (listener !== undefined) {
@@ -277,11 +316,12 @@ export function createServer(options) {
         return {
             handleMessage: (method, params) => handleMessageWithLifecycle(method, lifecycle, params),
             close: () => {
+                lifecycle.abortController.abort();
                 if (listener !== undefined) {
                     connectionNotificationListeners.delete(listener);
                 }
                 messageLifecycles.delete(lifecycle);
-            },
+            }
         };
     };
     const handleMessage = (method, params) => handleMessageWithLifecycle(method, defaultLifecycle, params);
@@ -299,7 +339,7 @@ export function createServer(options) {
             const requestWithId = request;
             write(formatErrorResponse(requestWithId.id, {
                 code: JSON_RPC_ERROR_CODES.INVALID_REQUEST,
-                message: "Invalid Request",
+                message: "Invalid Request"
             }) + "\n");
             return;
         }
@@ -312,7 +352,7 @@ export function createServer(options) {
                 const requestWithId = request;
                 write(formatErrorResponse(requestWithId.id, {
                     code: JSON_RPC_ERROR_CODES.INTERNAL_ERROR,
-                    message: "Internal error",
+                    message: "Internal error"
                 }) + "\n");
             }
             return;
@@ -333,7 +373,7 @@ export function createServer(options) {
         const notification = {
             jsonrpc: "2.0",
             method,
-            ...(params === undefined ? {} : { params }),
+            ...(params === undefined ? {} : { params })
         };
         for (const listener of notificationListeners) {
             listener(notification);
@@ -357,12 +397,10 @@ export function createServer(options) {
                 name,
                 description,
                 inputSchema: inputSchema,
-                ...(outputSchema === undefined
-                    ? {}
-                    : { outputSchema: outputSchema }),
+                ...(outputSchema === undefined ? {} : { outputSchema: outputSchema }),
                 handler: handler,
                 inputValidator,
-                ...(outputValidator === undefined ? {} : { outputValidator }),
+                ...(outputValidator === undefined ? {} : { outputValidator })
             });
             return server;
         },
@@ -378,7 +416,7 @@ export function createServer(options) {
                 ...definition,
                 handler: handler,
                 inputValidator,
-                ...(outputValidator === undefined ? {} : { outputValidator }),
+                ...(outputValidator === undefined ? {} : { outputValidator })
             });
             return server;
         },
@@ -400,6 +438,11 @@ export function createServer(options) {
             resourceTemplates.set(definition.uriTemplate, { ...definition, handler });
             return server;
         },
+        method(name, handler) {
+            assertNonEmptyName(name, "Method name required");
+            methods.set(name, handler);
+            return server;
+        },
         onNotification(listener) {
             notificationListeners.add(listener);
             return () => {
@@ -447,7 +490,7 @@ export function createServer(options) {
         async listen() {
             return server.connect({
                 readable: process.stdin,
-                writable: process.stdout,
+                writable: process.stdout
             });
         },
         async connect(transport) {
@@ -458,7 +501,7 @@ export function createServer(options) {
                 const session = server.createMessageSession(listener);
                 const rl = readline.createInterface({
                     input: transport.readable,
-                    crlfDelay: Infinity,
+                    crlfDelay: Infinity
                 });
                 const pendingMessages = new Set();
                 rl.on("line", (line) => {
@@ -503,8 +546,8 @@ export function createServer(options) {
                             id: message.id,
                             error: {
                                 code: JSON_RPC_ERROR_CODES.INVALID_REQUEST,
-                                message: "Invalid Request",
-                            },
+                                message: "Invalid Request"
+                            }
                         });
                         return;
                     }
@@ -519,8 +562,8 @@ export function createServer(options) {
                             id: request.id,
                             error: {
                                 code: JSON_RPC_ERROR_CODES.INTERNAL_ERROR,
-                                message: "Internal error",
-                            },
+                                message: "Internal error"
+                            }
                         });
                         return;
                     }
@@ -529,7 +572,7 @@ export function createServer(options) {
                         const response = {
                             jsonrpc: "2.0",
                             id: request.id,
-                            error,
+                            error
                         };
                         await transport.send(response);
                     }
@@ -537,7 +580,7 @@ export function createServer(options) {
                         const response = {
                             jsonrpc: "2.0",
                             id: request.id,
-                            result,
+                            result
                         };
                         await transport.send(response);
                     }
@@ -551,7 +594,7 @@ export function createServer(options) {
                     reject(error);
                 });
             });
-        },
+        }
     };
     return server;
 }
@@ -559,24 +602,24 @@ function invalidParams(message) {
     return {
         error: {
             code: JSON_RPC_ERROR_CODES.INVALID_PARAMS,
-            message,
-        },
+            message
+        }
     };
 }
 function internalError(message) {
     return {
         error: {
             code: JSON_RPC_ERROR_CODES.INTERNAL_ERROR,
-            message,
-        },
+            message
+        }
     };
 }
 function resourceNotFound(uri) {
     return {
         error: {
             code: JSON_RPC_ERROR_CODES.RESOURCE_NOT_FOUND,
-            message: `Resource not found: ${uri}`,
-        },
+            message: `Resource not found: ${uri}`
+        }
     };
 }
 function toErrorMessage(error) {
@@ -599,7 +642,7 @@ function assertNonEmptyName(name, message) {
 function assertReadableUriTemplate(uriTemplate) {
     const parsed = uriTemplateParser.parse(uriTemplate);
     const expanded = parsed.expand(new Proxy({}, {
-        get: (_target, property) => typeof property === "string" ? "value" : undefined,
+        get: (_target, property) => (typeof property === "string" ? "value" : undefined)
     }));
     if (typeof expanded !== "string" || !isValidUri(expanded)) {
         throw new Error(`Invalid resource URI template: ${uriTemplate}`);
@@ -668,12 +711,8 @@ function normalizeToolResult(handlerResult, outputSchema) {
     if (isCallToolResult(handlerResult) && handlerResult.isError === true) {
         return handlerResult;
     }
-    const callToolResult = isCallToolResult(handlerResult)
-        ? handlerResult
-        : undefined;
-    const structuredContent = callToolResult
-        ? callToolResult.structuredContent
-        : handlerResult;
+    const callToolResult = isCallToolResult(handlerResult) ? handlerResult : undefined;
+    const structuredContent = callToolResult ? callToolResult.structuredContent : handlerResult;
     if (!isJsonObject(structuredContent)) {
         throw new ToolError(JSON_RPC_ERROR_CODES.INTERNAL_ERROR, "Structured tool result must be an object");
     }
@@ -681,10 +720,8 @@ function normalizeToolResult(handlerResult, outputSchema) {
         content: callToolResult !== undefined && callToolResult.content.length > 0
             ? callToolResult.content
             : [{ type: "text", text: JSON.stringify(structuredContent) }],
-        ...(callToolResult?.isError !== undefined
-            ? { isError: callToolResult.isError }
-            : {}),
-        structuredContent,
+        ...(callToolResult?.isError !== undefined ? { isError: callToolResult.isError } : {}),
+        structuredContent
     };
 }
 function assertObjectRootSchema(schema, path) {
@@ -696,9 +733,7 @@ function isJsonObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isGetPromptResult(value) {
-    if (typeof value !== "object" ||
-        value === null ||
-        !hasOwnProperty(value, "messages")) {
+    if (typeof value !== "object" || value === null || !hasOwnProperty(value, "messages")) {
         return false;
     }
     return ((!hasOwnProperty(value, "description") ||
@@ -713,12 +748,10 @@ function isGetPromptResult(value) {
             isPromptContentItem(message.content)));
 }
 function isReadResourceResult(value) {
-    if (typeof value !== "object" ||
-        value === null ||
-        !hasOwnProperty(value, "contents")) {
+    if (typeof value !== "object" || value === null || !hasOwnProperty(value, "contents")) {
         return false;
     }
-    return (Array.isArray(value.contents) && value.contents.every(isResourceContents));
+    return Array.isArray(value.contents) && value.contents.every(isResourceContents);
 }
 function hasContentArray(value) {
     return (typeof value === "object" &&
@@ -727,9 +760,7 @@ function hasContentArray(value) {
         Array.isArray(value.content));
 }
 function isContentItem(value) {
-    if (typeof value !== "object" ||
-        value === null ||
-        !hasOwnProperty(value, "type")) {
+    if (typeof value !== "object" || value === null || !hasOwnProperty(value, "type")) {
         return false;
     }
     const block = value;
@@ -761,9 +792,7 @@ function isContentItem(value) {
             (!hasOwnProperty(block, "mimeType") ||
                 block.mimeType === undefined ||
                 typeof block.mimeType === "string") &&
-            (!hasOwnProperty(block, "size") ||
-                block.size === undefined ||
-                typeof block.size === "number"));
+            (!hasOwnProperty(block, "size") || block.size === undefined || typeof block.size === "number"));
     }
     if (block.type !== "resource" ||
         !hasOwnProperty(block, "resource") ||
@@ -787,13 +816,10 @@ function isResourceContents(value) {
         return false;
     }
     return ((hasOwnProperty(value, "text") && typeof value.text === "string") ||
-        (hasOwnProperty(value, "blob") &&
-            typeof value.blob === "string" &&
-            isBase64(value.blob)));
+        (hasOwnProperty(value, "blob") && typeof value.blob === "string" && isBase64(value.blob)));
 }
 function hasValidContentAnnotations(value) {
-    if (!hasOwnProperty(value, "annotations") ||
-        value.annotations === undefined) {
+    if (!hasOwnProperty(value, "annotations") || value.annotations === undefined) {
         return true;
     }
     if (!isJsonObject(value.annotations)) {
@@ -817,8 +843,7 @@ function isBase64(value) {
     const paddingStart = value.indexOf("=");
     const encoded = paddingStart === -1 ? value : value.slice(0, paddingStart);
     const padding = paddingStart === -1 ? "" : value.slice(paddingStart);
-    if (padding.length > 2 ||
-        [...padding].some((character) => character !== "=")) {
+    if (padding.length > 2 || [...padding].some((character) => character !== "=")) {
         return false;
     }
     if ([...encoded].some((character) => !alphabet.includes(character))) {

package/dist/types.d.ts

@@ -208,6 +208,7 @@ export interface JSONSchemaProperty extends Record<string, unknown> {
 export interface ServerOptions {
     name: string;
     version: string;
+    toolCallTimeoutMs?: number;
     validateToolArguments?: boolean;
     supportNotifications?: boolean;
     supportResourceSubscriptions?: boolean;

package/dist/types.js

@@ -5,7 +5,7 @@ export const JSON_RPC_ERROR_CODES = Object.freeze({
     METHOD_NOT_FOUND: -32601,
     INVALID_PARAMS: -32602,
     INTERNAL_ERROR: -32603,
-    RESOURCE_NOT_FOUND: -32002,
+    RESOURCE_NOT_FOUND: -32002
 });
 export class ToolError extends Error {
     code;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-stdio-mcp-server",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "bugs": {
     "url": "https://github.com/poe-platform/poe-code/issues"
   },