tiny-stdio-mcp-server 0.1.5 → 0.1.7

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/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,23 @@ export function createServer(options) {
         }));
     };
     const server = {
-        tool(name, description, inputSchema, handler) {
+        tool(name, description, inputSchema, handler, outputSchema) {
+            if (outputSchema !== undefined) {
+                assertSupportedOutputSchema(outputSchema);
+            }
             tools.set(name, {
                 name,
                 description,
                 inputSchema: inputSchema,
+                ...(outputSchema === undefined ? {} : { outputSchema: outputSchema }),
                 handler: handler,
             });
             return server;
         },
         registerTool(definition, handler) {
+            if (definition.outputSchema !== undefined) {
+                assertSupportedOutputSchema(definition.outputSchema);
+            }
             tools.set(definition.name, {
                 ...definition,
                 handler: handler,
@@ -571,7 +571,125 @@ 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) {
+        return isCallToolResult(handlerResult)
+            ? handlerResult
+            : { content: toContentBlocks(handlerResult) };
+    }
+    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")) {

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,9 @@
 {
   "name": "tiny-stdio-mcp-server",
-  "version": "0.1.5",
+  "version": "0.1.7",
+  "bugs": {
+    "url": "https://github.com/poe-platform/poe-code/issues"
+  },
   "description": "Minimal MCP server over stdio with typed tools and rich content helpers",
   "type": "module",
   "main": "dist/index.js",