tiny-stdio-mcp-server 0.1.15 → 0.1.16

package/README.md

@@ -58,7 +58,7 @@ server.tool("search", "Search for things", schema, async ({ query, limit }) => {
 });
 ```
 
-For structured-data tools, pass a root-object output schema. The server advertises it as MCP `Tool.outputSchema`, validates the handler result, returns it as `CallToolResult.structuredContent`, and also includes a JSON text backstop in `content[]` for older clients.
+For structured-data tools, pass a root-object output schema. The server advertises it as MCP `Tool.outputSchema`, validates successful handler results, and returns them as `CallToolResult.structuredContent`. Plain object returns receive a JSON text backstop in `content[]` for older clients. Explicit `CallToolResult` values keep their handler-supplied content blocks; the JSON text backstop is added only when `content` is empty.
 
 ```ts
 const input = defineSchema({
@@ -89,7 +89,11 @@ server.tool(
 );
 ```
 
-Output schemas must have `type: "object"` at the root. Tools whose natural result is prose, images, audio, files, or other content blocks should omit `outputSchema` and keep returning content.
+Output schemas must have `type: "object"` at the root because MCP structured content is an object. Otherwise, any schema accepted by Ajv is supported, including composition keywords, nullable type unions, and local `$defs`/`$ref` references. Input and output schemas compile synchronously during `.tool()` or `.registerTool()` registration, so malformed schemas throw immediately instead of failing on the first tool call.
+
+Successful structured results must satisfy `outputSchema`. Validation failures use JSON-RPC `-32602` for inputs and `-32603` for outputs, with Ajv's formatted error text in the message and the raw Ajv error array in `error.data`. Explicit handler results with `isError: true` are passed through unchanged and are exempt from structured-content and output-schema validation.
+
+Tools whose natural result is prose, images, audio, files, or other content blocks should omit `outputSchema` and keep returning content.
 
 ### `.listen()`
 

package/dist/server.js

@@ -47,7 +47,8 @@ export function createServer(options) {
                 ? 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: {
@@ -95,6 +96,9 @@ export function createServer(options) {
             for (const tool of tools.values()) {
                 const descriptor = { ...tool };
                 delete descriptor.handler;
+                delete descriptor.inputValidator;
+                delete descriptor
+                    .outputValidator;
                 toolList.push({
                     ...descriptor,
                 });
@@ -121,19 +125,25 @@ export function createServer(options) {
                 };
             }
             const toolArgs = (params?.arguments ?? {});
-            if (options.validateToolArguments !== false && !jsonSchemaValidator.validate(tool.inputSchema, 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",
+                        message: `Invalid tool arguments: ${jsonSchemaValidator.errorsText(errors)}`,
+                        data: errors,
                     },
                 };
             }
             try {
                 const handlerResult = await tool.handler(toolArgs);
                 const result = normalizeToolResult(handlerResult, tool.outputSchema);
-                if (tool.outputSchema !== undefined && !jsonSchemaValidator.validate(tool.outputSchema, result.structuredContent)) {
-                    throw new ToolError(JSON_RPC_ERROR_CODES.INTERNAL_ERROR, "Invalid structured tool result");
+                if (result.isError !== true &&
+                    tool.outputValidator !== undefined &&
+                    !tool.outputValidator(result.structuredContent)) {
+                    const errors = tool.outputValidator.errors ?? [];
+                    throw new ToolError(JSON_RPC_ERROR_CODES.INTERNAL_ERROR, `Invalid structured tool result: ${jsonSchemaValidator.errorsText(errors)}`, errors);
                 }
                 return { result };
             }
@@ -220,7 +230,8 @@ 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: {
@@ -233,8 +244,8 @@ export function createServer(options) {
             if (uri === undefined || !isValidUri(uri)) {
                 return invalidParams("Resource URI required");
             }
-            if (method === "resources/subscribe"
-                && findReadableResource(uri, resources, resourceTemplates) === undefined) {
+            if (method === "resources/subscribe" &&
+                findReadableResource(uri, resources, resourceTemplates) === undefined) {
                 return resourceNotFound(uri);
             }
             if (method === "resources/subscribe") {
@@ -336,26 +347,38 @@ export function createServer(options) {
     const server = {
         tool(name, description, inputSchema, handler, outputSchema) {
             assertNonEmptyName(name, "Tool name required");
+            const inputValidator = jsonSchemaValidator.compile(inputSchema);
+            let outputValidator;
             if (outputSchema !== undefined) {
-                assertSupportedOutputSchema(outputSchema);
+                assertObjectRootSchema(outputSchema, "outputSchema");
+                outputValidator = jsonSchemaValidator.compile(outputSchema);
             }
             tools.set(name, {
                 name,
                 description,
                 inputSchema: inputSchema,
-                ...(outputSchema === undefined ? {} : { outputSchema: outputSchema }),
+                ...(outputSchema === undefined
+                    ? {}
+                    : { outputSchema: outputSchema }),
                 handler: handler,
+                inputValidator,
+                ...(outputValidator === undefined ? {} : { outputValidator }),
             });
             return server;
         },
         registerTool(definition, handler) {
             assertNonEmptyName(definition.name, "Tool name required");
+            const inputValidator = jsonSchemaValidator.compile(definition.inputSchema);
+            let outputValidator;
             if (definition.outputSchema !== undefined) {
-                assertSupportedOutputSchema(definition.outputSchema);
+                assertObjectRootSchema(definition.outputSchema, "outputSchema");
+                outputValidator = jsonSchemaValidator.compile(definition.outputSchema);
             }
             tools.set(definition.name, {
                 ...definition,
                 handler: handler,
+                inputValidator,
+                ...(outputValidator === undefined ? {} : { outputValidator }),
             });
             return server;
         },
@@ -396,17 +419,20 @@ export function createServer(options) {
             return resourceTemplates.delete(uriTemplate);
         },
         async notifyToolsChanged() {
-            if (supportNotifications && [...messageLifecycles].some((lifecycle) => lifecycle.notificationReady)) {
+            if (supportNotifications &&
+                [...messageLifecycles].some((lifecycle) => lifecycle.notificationReady)) {
                 await broadcastNotification("notifications/tools/list_changed");
             }
         },
         async notifyPromptsChanged() {
-            if (supportNotifications && [...messageLifecycles].some((lifecycle) => lifecycle.notificationReady)) {
+            if (supportNotifications &&
+                [...messageLifecycles].some((lifecycle) => lifecycle.notificationReady)) {
                 await broadcastNotification("notifications/prompts/list_changed");
             }
         },
         async notifyResourcesChanged() {
-            if (supportNotifications && [...messageLifecycles].some((lifecycle) => lifecycle.notificationReady)) {
+            if (supportNotifications &&
+                [...messageLifecycles].some((lifecycle) => lifecycle.notificationReady)) {
                 await broadcastNotification("notifications/resources/list_changed");
             }
         },
@@ -617,14 +643,14 @@ function isCallToolResult(value) {
     if (!hasContentArray(value) || !value.content.every(isContentItem)) {
         return false;
     }
-    if (hasOwnProperty(value, "structuredContent")
-        && value.structuredContent !== undefined
-        && !isJsonObject(value.structuredContent)) {
+    if (hasOwnProperty(value, "structuredContent") &&
+        value.structuredContent !== undefined &&
+        !isJsonObject(value.structuredContent)) {
         return false;
     }
-    return !(hasOwnProperty(value, "isError")
-        && value.isError !== undefined
-        && typeof value.isError !== "boolean");
+    return !(hasOwnProperty(value, "isError") &&
+        value.isError !== undefined &&
+        typeof value.isError !== "boolean");
 }
 function normalizeToolResult(handlerResult, outputSchema) {
     if (hasContentArray(handlerResult) && !isCallToolResult(handlerResult)) {
@@ -639,131 +665,71 @@ function normalizeToolResult(handlerResult, outputSchema) {
         }
         return result;
     }
-    const structuredContent = isCallToolResult(handlerResult)
-        ? handlerResult.structuredContent
+    if (isCallToolResult(handlerResult) && handlerResult.isError === true) {
+        return 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");
     }
     return {
-        content: [{ type: "text", text: JSON.stringify(structuredContent) }],
-        ...(isCallToolResult(handlerResult) && handlerResult.isError !== undefined
-            ? { isError: handlerResult.isError }
+        content: callToolResult !== undefined && callToolResult.content.length > 0
+            ? callToolResult.content
+            : [{ type: "text", text: JSON.stringify(structuredContent) }],
+        ...(callToolResult?.isError !== undefined
+            ? { isError: callToolResult.isError }
             : {}),
         structuredContent,
     };
 }
-function assertSupportedOutputSchema(schema) {
-    assertObjectRootSchema(schema, "outputSchema");
-    assertSupportedJsonSchema(schema, "outputSchema");
-}
 function assertObjectRootSchema(schema, path) {
     if (schema.type !== "object") {
         throw new Error(`${path} root type must be "object"`);
     }
 }
-function assertSupportedJsonSchema(schema, path) {
-    for (const keyword of ["anyOf", "allOf", "not", "if", "then", "else", "contains", "prefixItems"]) {
-        if (schema[keyword] !== undefined) {
-            throw new Error(`${path} uses unsupported keyword "${keyword}"`);
-        }
-    }
-    const type = schema.type;
-    if (Array.isArray(type)) {
-        const supported = new Set(["string", "number", "integer", "boolean", "object", "array", "null"]);
-        for (const item of type) {
-            if (!supported.has(item)) {
-                throw new Error(`${path} uses unsupported type "${item}"`);
-            }
-        }
-    }
-    else if (type !== undefined &&
-        type !== "string" &&
-        type !== "number" &&
-        type !== "integer" &&
-        type !== "boolean" &&
-        type !== "object" &&
-        type !== "array") {
-        throw new Error(`${path} uses unsupported type "${type}"`);
-    }
-    if (isJsonObject(schema.properties)) {
-        for (const [key, child] of Object.entries(schema.properties)) {
-            if (isJsonObject(child)) {
-                assertSupportedJsonSchema(child, `${path}.properties.${key}`);
-            }
-            else {
-                throw new Error(`${path}.properties.${key} must be an object schema`);
-            }
-        }
-    }
-    else if (schema.properties !== undefined) {
-        throw new Error(`${path}.properties must be an object`);
-    }
-    const additionalProperties = schema.additionalProperties;
-    if (typeof additionalProperties === "object" && additionalProperties !== null) {
-        if (Array.isArray(additionalProperties)) {
-            throw new Error(`${path}.additionalProperties must be an object schema or boolean`);
-        }
-        assertSupportedJsonSchema(additionalProperties, `${path}.additionalProperties`);
-    }
-    else if (additionalProperties !== undefined
-        && typeof additionalProperties !== "boolean") {
-        throw new Error(`${path}.additionalProperties must be an object schema or boolean`);
-    }
-    const items = schema.items;
-    if (Array.isArray(items)) {
-        throw new Error(`${path}.items uses unsupported tuple array schemas`);
-    }
-    if (typeof items === "object" && items !== null && !Array.isArray(items)) {
-        assertSupportedJsonSchema(items, `${path}.items`);
-    }
-    else if (items !== undefined && typeof items !== "boolean") {
-        throw new Error(`${path}.items must be an object schema or boolean`);
-    }
-    const oneOf = schema.oneOf;
-    if (Array.isArray(oneOf)) {
-        for (const [index, child] of oneOf.entries()) {
-            if (typeof child === "object" && child !== null && !Array.isArray(child)) {
-                assertSupportedJsonSchema(child, `${path}.oneOf[${index}]`);
-            }
-            else {
-                throw new Error(`${path}.oneOf[${index}] must be an object schema`);
-            }
-        }
-    }
-    else if (oneOf !== undefined) {
-        throw new Error(`${path}.oneOf must be an array`);
-    }
-}
 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") || value.description === undefined || typeof value.description === "string")
-        && Array.isArray(value.messages)
-        && value.messages.every((message) => typeof message === "object"
-            && message !== null
-            && hasOwnProperty(message, "role")
-            && (message.role === "user" || message.role === "assistant")
-            && hasOwnProperty(message, "content")
-            && isPromptContentItem(message.content));
+    return ((!hasOwnProperty(value, "description") ||
+        value.description === undefined ||
+        typeof value.description === "string") &&
+        Array.isArray(value.messages) &&
+        value.messages.every((message) => typeof message === "object" &&
+            message !== null &&
+            hasOwnProperty(message, "role") &&
+            (message.role === "user" || message.role === "assistant") &&
+            hasOwnProperty(message, "content") &&
+            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" && value !== null && hasOwnProperty(value, "content")
-        && Array.isArray(value.content);
+    return (typeof value === "object" &&
+        value !== null &&
+        hasOwnProperty(value, "content") &&
+        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;
@@ -774,56 +740,71 @@ function isContentItem(value) {
         return hasOwnProperty(block, "text") && typeof block.text === "string";
     }
     if (block.type === "image" || block.type === "audio") {
-        return hasOwnProperty(block, "data")
-            && typeof block.data === "string"
-            && isBase64(block.data)
-            && hasOwnProperty(block, "mimeType")
-            && typeof block.mimeType === "string";
+        return (hasOwnProperty(block, "data") &&
+            typeof block.data === "string" &&
+            isBase64(block.data) &&
+            hasOwnProperty(block, "mimeType") &&
+            typeof block.mimeType === "string");
     }
     if (block.type === "resource_link") {
-        return hasOwnProperty(block, "uri")
-            && typeof block.uri === "string"
-            && isValidUri(block.uri)
-            && hasOwnProperty(block, "name")
-            && typeof block.name === "string"
-            && (!hasOwnProperty(block, "title") || block.title === undefined || typeof block.title === "string")
-            && (!hasOwnProperty(block, "description") || block.description === undefined || typeof block.description === "string")
-            && (!hasOwnProperty(block, "mimeType") || block.mimeType === undefined || typeof block.mimeType === "string")
-            && (!hasOwnProperty(block, "size") || block.size === undefined || typeof block.size === "number");
-    }
-    if (block.type !== "resource"
-        || !hasOwnProperty(block, "resource")
-        || typeof block.resource !== "object"
-        || block.resource === null) {
+        return (hasOwnProperty(block, "uri") &&
+            typeof block.uri === "string" &&
+            isValidUri(block.uri) &&
+            hasOwnProperty(block, "name") &&
+            typeof block.name === "string" &&
+            (!hasOwnProperty(block, "title") ||
+                block.title === undefined ||
+                typeof block.title === "string") &&
+            (!hasOwnProperty(block, "description") ||
+                block.description === undefined ||
+                typeof block.description === "string") &&
+            (!hasOwnProperty(block, "mimeType") ||
+                block.mimeType === undefined ||
+                typeof block.mimeType === "string") &&
+            (!hasOwnProperty(block, "size") ||
+                block.size === undefined ||
+                typeof block.size === "number"));
+    }
+    if (block.type !== "resource" ||
+        !hasOwnProperty(block, "resource") ||
+        typeof block.resource !== "object" ||
+        block.resource === null) {
         return false;
     }
     return isResourceContents(block.resource);
 }
 function isResourceContents(value) {
-    if (typeof value !== "object"
-        || value === null
-        || !hasOwnProperty(value, "uri")
-        || typeof value.uri !== "string"
-        || !isValidUri(value.uri)) {
+    if (typeof value !== "object" ||
+        value === null ||
+        !hasOwnProperty(value, "uri") ||
+        typeof value.uri !== "string" ||
+        !isValidUri(value.uri)) {
         return false;
     }
-    if (hasOwnProperty(value, "mimeType") && value.mimeType !== undefined && typeof value.mimeType !== "string") {
+    if (hasOwnProperty(value, "mimeType") &&
+        value.mimeType !== undefined &&
+        typeof value.mimeType !== "string") {
         return false;
     }
-    return (hasOwnProperty(value, "text") && typeof value.text === "string")
-        || (hasOwnProperty(value, "blob") && typeof value.blob === "string" && isBase64(value.blob));
+    return ((hasOwnProperty(value, "text") && typeof value.text === "string") ||
+        (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)) {
         return false;
     }
     const { audience, priority, lastModified } = value.annotations;
-    return (audience === undefined || (Array.isArray(audience) && audience.every((item) => item === "user" || item === "assistant")))
-        && (priority === undefined || typeof priority === "number")
-        && (lastModified === undefined || typeof lastModified === "string");
+    return ((audience === undefined ||
+        (Array.isArray(audience) &&
+            audience.every((item) => item === "user" || item === "assistant"))) &&
+        (priority === undefined || typeof priority === "number") &&
+        (lastModified === undefined || typeof lastModified === "string"));
 }
 function isBase64(value) {
     if (value.length === 0) {
@@ -836,7 +817,8 @@ 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))) {
@@ -848,7 +830,10 @@ function isPromptContentItem(value) {
     if (!isContentItem(value)) {
         return false;
     }
-    return !(typeof value === "object" && value !== null && hasOwnProperty(value, "type") && value.type === "resource_link");
+    return !(typeof value === "object" &&
+        value !== null &&
+        hasOwnProperty(value, "type") &&
+        value.type === "resource_link");
 }
 function hasOwnProperty(value, name) {
     return Object.prototype.hasOwnProperty.call(value, name);

package/dist/types.d.ts

@@ -164,10 +164,7 @@ export interface ResourceTemplateDefinition extends ResourceTemplate {
 }
 export interface HandleResult {
     result?: unknown;
-    error?: {
-        code: number;
-        message: string;
-    };
+    error?: JSONRPCError;
 }
 export type PromptContentItem = {
     type: "text";

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.15",
+  "version": "0.1.16",
   "bugs": {
     "url": "https://github.com/poe-platform/poe-code/issues"
   },