tiny-stdio-mcp-server 0.1.6 → 0.1.8

package/README.md

@@ -42,9 +42,9 @@ Creates a new MCP server.
 const server = createServer({ name: "my-server", version: "1.0.0" });
 ```
 
-### `.tool(name, description, schema, handler)`
+### `.tool(name, description, schema, handler, outputSchema?)`
 
-Register a tool. The handler receives typed args matching the schema and returns a string, content helper, or array of either.
+Register a tool. The handler receives typed args matching the schema and returns a string, content helper, array of content, or a typed object when `outputSchema` is supplied.
 
 ```ts
 const schema = defineSchema({
@@ -58,6 +58,33 @@ 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.
+
+```ts
+const input = defineSchema({
+  query: { type: "string" },
+});
+const output = defineSchema({
+  items: {
+    type: "array",
+    items: {
+      type: "object",
+      properties: {
+        title: { type: "string" },
+        score: { type: "number" },
+      },
+      required: ["title", "score"],
+    },
+  },
+});
+
+server.tool("search", "Search", input, async ({ query }) => ({
+  items: [{ title: query, score: 1 }],
+}), output);
+```
+
+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.
+
 ### `.listen()`
 
 Start listening on stdin/stdout (standard MCP stdio transport).

package/dist/schema.d.ts

@@ -4,6 +4,7 @@ interface SchemaPropertyDef {
     type: SchemaPropertyType;
     description?: string;
     optional?: boolean;
+    [keyword: string]: unknown;
 }
 type SchemaDefinition = Record<string, SchemaPropertyDef>;
 type InferType<T extends SchemaPropertyType> = T extends "string" ? string : T extends "number" ? number : T extends "boolean" ? boolean : T extends "object" ? Record<string, unknown> : T extends "array" ? unknown[] : never;

package/dist/schema.js

@@ -2,14 +2,17 @@ export function defineSchema(definition) {
     const properties = {};
     const required = [];
     for (const [key, prop] of Object.entries(definition)) {
+        const jsonSchemaProperty = {};
+        for (const [propertyKey, propertyValue] of Object.entries(prop)) {
+            if (propertyKey !== "optional") {
+                jsonSchemaProperty[propertyKey] = propertyValue;
+            }
+        }
         Object.defineProperty(properties, key, {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: {
-                type: prop.type,
-                ...(prop.description !== undefined && { description: prop.description }),
-            },
+            value: jsonSchemaProperty,
         });
         if (!prop.optional) {
             required.push(key);

package/dist/server.d.ts

@@ -1,8 +1,8 @@
 import type { ServerOptions, ToolDefinition, ToolHandler, HandleResult, Prompt, PromptHandler, Resource, ResourceHandler, ResourceTemplate, Transport, SDKTransport, JSONRPCNotification } from "./types.js";
 import type { TypedSchema } from "./schema.js";
 export interface Server {
-    tool<T>(name: string, description: string, inputSchema: TypedSchema<T>, handler: ToolHandler<T>): Server;
-    registerTool<T>(definition: Omit<ToolDefinition<T>, "handler">, handler: ToolHandler<T>): Server;
+    tool<TIn, TOut = never>(name: string, description: string, inputSchema: TypedSchema<TIn>, handler: ToolHandler<TIn, TOut>, outputSchema?: TypedSchema<TOut>): Server;
+    registerTool<TIn, TOut = never>(definition: Omit<ToolDefinition<TIn, TOut>, "handler">, handler: ToolHandler<TIn, TOut>): Server;
     prompt(definition: Prompt, handler: PromptHandler): Server;
     resource(definition: Resource, handler: ResourceHandler): Server;
     resourceTemplate(definition: ResourceTemplate, handler: ResourceHandler): Server;

package/dist/server.js

@@ -131,16 +131,9 @@ export function createServer(options) {
             }
             try {
                 const handlerResult = await tool.handler(toolArgs);
-                if (hasContentArray(handlerResult) && !isCallToolResult(handlerResult)) {
-                    throw new Error("Invalid tool result");
-                }
-                const result = isCallToolResult(handlerResult)
-                    ? handlerResult
-                    : { content: toContentBlocks(handlerResult) };
-                if (tool.outputSchema !== undefined
-                    && (result.structuredContent === undefined
-                        || !jsonSchemaValidator.validate(tool.outputSchema, result.structuredContent))) {
-                    throw new Error("Invalid structured tool result");
+                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");
                 }
                 return { result };
             }
@@ -326,16 +319,25 @@ export function createServer(options) {
         }));
     };
     const server = {
-        tool(name, description, inputSchema, handler) {
+        tool(name, description, inputSchema, handler, outputSchema) {
+            assertNonEmptyName(name, "Tool name required");
+            if (outputSchema !== undefined) {
+                assertSupportedOutputSchema(outputSchema);
+            }
             tools.set(name, {
                 name,
                 description,
                 inputSchema: inputSchema,
+                ...(outputSchema === undefined ? {} : { outputSchema: outputSchema }),
                 handler: handler,
             });
             return server;
         },
         registerTool(definition, handler) {
+            assertNonEmptyName(definition.name, "Tool name required");
+            if (definition.outputSchema !== undefined) {
+                assertSupportedOutputSchema(definition.outputSchema);
+            }
             tools.set(definition.name, {
                 ...definition,
                 handler: handler,
@@ -343,6 +345,7 @@ export function createServer(options) {
             return server;
         },
         prompt(definition, handler) {
+            assertNonEmptyName(definition.name, "Prompt name required");
             prompts.set(definition.name, { ...definition, handler });
             return server;
         },
@@ -354,7 +357,7 @@ export function createServer(options) {
             return server;
         },
         resourceTemplate(definition, handler) {
-            uriTemplateParser.parse(definition.uriTemplate);
+            assertReadableUriTemplate(definition.uriTemplate);
             new UriTemplate(definition.uriTemplate);
             resourceTemplates.set(definition.uriTemplate, { ...definition, handler });
             return server;
@@ -536,6 +539,20 @@ function isValidUri(uri) {
         return false;
     }
 }
+function assertNonEmptyName(name, message) {
+    if (name.length === 0) {
+        throw new Error(message);
+    }
+}
+function assertReadableUriTemplate(uriTemplate) {
+    const parsed = uriTemplateParser.parse(uriTemplate);
+    const expanded = parsed.expand(new Proxy({}, {
+        get: (_target, property) => typeof property === "string" ? "value" : undefined,
+    }));
+    if (typeof expanded !== "string" || !isValidUri(expanded)) {
+        throw new Error(`Invalid resource URI template: ${uriTemplate}`);
+    }
+}
 function toStringArguments(value) {
     if (value === undefined) {
         return {};
@@ -571,13 +588,136 @@ function matchesUriTemplate(template, uri) {
     }
 }
 function isCallToolResult(value) {
-    return hasContentArray(value) && value.content.every(isContentItem);
+    if (!hasContentArray(value) || !value.content.every(isContentItem)) {
+        return false;
+    }
+    if (hasOwnProperty(value, "structuredContent")
+        && value.structuredContent !== undefined
+        && !isJsonObject(value.structuredContent)) {
+        return false;
+    }
+    return !(hasOwnProperty(value, "isError")
+        && value.isError !== undefined
+        && typeof value.isError !== "boolean");
+}
+function normalizeToolResult(handlerResult, outputSchema) {
+    if (hasContentArray(handlerResult) && !isCallToolResult(handlerResult)) {
+        throw new Error("Invalid tool result");
+    }
+    if (outputSchema === undefined) {
+        const result = isCallToolResult(handlerResult)
+            ? handlerResult
+            : { content: toContentBlocks(handlerResult) };
+        if (!isCallToolResult(result)) {
+            throw new Error("Invalid tool result");
+        }
+        return result;
+    }
+    const structuredContent = isCallToolResult(handlerResult)
+        ? handlerResult.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 }
+            : {}),
+        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")) {
         return false;
     }
-    return Array.isArray(value.messages)
+    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")
@@ -590,13 +730,7 @@ function isReadResourceResult(value) {
         return false;
     }
     return Array.isArray(value.contents)
-        && value.contents.every((content) => typeof content === "object"
-            && content !== null
-            && hasOwnProperty(content, "uri")
-            && typeof content.uri === "string"
-            && isValidUri(content.uri)
-            && ((hasOwnProperty(content, "text") && typeof content.text === "string")
-                || (hasOwnProperty(content, "blob") && typeof content.blob === "string" && isBase64(content.blob))));
+        && value.contents.every(isResourceContents);
 }
 function hasContentArray(value) {
     return typeof value === "object" && value !== null && hasOwnProperty(value, "content")
@@ -607,6 +741,9 @@ function isContentItem(value) {
         return false;
     }
     const block = value;
+    if (!hasValidContentAnnotations(block)) {
+        return false;
+    }
     if (block.type === "text") {
         return hasOwnProperty(block, "text") && typeof block.text === "string";
     }
@@ -620,8 +757,13 @@ function isContentItem(value) {
     if (block.type === "resource_link") {
         return hasOwnProperty(block, "uri")
             && typeof block.uri === "string"
+            && isValidUri(block.uri)
             && hasOwnProperty(block, "name")
-            && typeof block.name === "string";
+            && 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")
@@ -629,12 +771,33 @@ function isContentItem(value) {
         || block.resource === null) {
         return false;
     }
-    const resource = block.resource;
-    return hasOwnProperty(resource, "uri")
-        && typeof resource.uri === "string"
-        && (!hasOwnProperty(resource, "mimeType") || typeof resource.mimeType === "string")
-        && ((hasOwnProperty(resource, "text") && typeof resource.text === "string")
-            || (hasOwnProperty(resource, "blob") && typeof resource.blob === "string" && isBase64(resource.blob)));
+    return isResourceContents(block.resource);
+}
+function isResourceContents(value) {
+    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") {
+        return false;
+    }
+    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) {
+        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");
 }
 function isBase64(value) {
     if (value.length === 0) {

package/dist/types.d.ts

@@ -215,8 +215,8 @@ export interface ServerOptions {
     supportResourceSubscriptions?: boolean;
 }
 import type { ToolReturn } from "./content/index.js";
-export type ToolHandler<T = Record<string, unknown>> = (args: T) => Promise<ToolReturn | CallToolResult> | ToolReturn | CallToolResult;
-export interface ToolDefinition<T = Record<string, unknown>> {
+export type ToolHandler<T = Record<string, unknown>, TOut = ToolReturn> = (args: T) => Promise<TOut | CallToolResult> | TOut | CallToolResult;
+export interface ToolDefinition<T = Record<string, unknown>, TOut = ToolReturn> {
     name: string;
     title?: string;
     description?: string;
@@ -226,7 +226,7 @@ export interface ToolDefinition<T = Record<string, unknown>> {
     execution?: ToolExecution;
     icons?: Icon[];
     _meta?: Record<string, unknown>;
-    handler: ToolHandler<T>;
+    handler: ToolHandler<T, TOut>;
 }
 export interface Transport {
     readable: NodeJS.ReadableStream;

package/package.json

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