tiny-stdio-mcp-server 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,180 @@
+# tiny-stdio-mcp-server
+
+Minimal [Model Context Protocol](https://modelcontextprotocol.io) server for Node.js. Zero runtime dependencies, type-safe tool definitions, rich content helpers for images/audio/files.
+
+## Install
+
+```sh
+npm install tiny-stdio-mcp-server
+```
+
+## Quick start
+
+```ts
+import { createServer, defineSchema } from "tiny-stdio-mcp-server";
+
+const schema = defineSchema({
+  text: { type: "string", description: "Text to reverse" },
+});
+
+createServer({ name: "my-server", version: "1.0.0" })
+  .tool("reverse", "Reverse a string", schema, ({ text }) => {
+    return text.split("").reverse().join("");
+  })
+  .listen();
+```
+
+Run it:
+
+```sh
+node my-server.js
+```
+
+Any MCP client (Claude Code, Codex, etc.) can connect to it over stdio.
+
+## API
+
+### `createServer(options)`
+
+Creates a new MCP server.
+
+```ts
+const server = createServer({ name: "my-server", version: "1.0.0" });
+```
+
+### `.tool(name, description, schema, handler)`
+
+Register a tool. The handler receives typed args matching the schema and returns a string, content helper, or array of either.
+
+```ts
+const schema = defineSchema({
+  query: { type: "string", description: "Search query" },
+  limit: { type: "number", description: "Max results", optional: true },
+});
+
+server.tool("search", "Search for things", schema, async ({ query, limit }) => {
+  // `query` is string, `limit` is number | undefined
+  return `Found results for: ${query}`;
+});
+```
+
+### `.listen()`
+
+Start listening on stdin/stdout (standard MCP stdio transport).
+
+```ts
+await server.listen();
+```
+
+### `.connect(transport)`
+
+Connect to a custom readable/writable stream pair.
+
+```ts
+await server.connect({ readable: process.stdin, writable: process.stdout });
+```
+
+### `.connectSDK(transport)`
+
+Connect using an SDK-compatible in-memory transport (for testing).
+
+```ts
+await server.connectSDK(sdkTransport);
+```
+
+### `.removeTool(name)` / `.notifyToolsChanged()`
+
+Dynamically add/remove tools at runtime and notify connected clients.
+
+## `defineSchema(definition)`
+
+Type-safe schema builder. Returns a JSON Schema object with inferred TypeScript types.
+
+```ts
+const schema = defineSchema({
+  name: { type: "string", description: "User name" },
+  age: { type: "number", description: "User age", optional: true },
+});
+// Handler receives: { name: string; age?: number }
+```
+
+Supported types: `string`, `number`, `boolean`, `object`, `array`.
+
+## Content helpers
+
+Tool handlers can return rich content beyond plain text.
+
+### Images
+
+```ts
+import { Image } from "tiny-stdio-mcp-server";
+
+server.tool("screenshot", "Take a screenshot", schema, async () => {
+  return Image.fromBase64(base64Data, "image/png");
+  // or: await Image.fromUrl("https://example.com/image.png")
+  // or: Image.fromBytes(uint8Array)
+});
+```
+
+Supported formats: PNG, JPEG, GIF, WebP.
+
+### Audio
+
+```ts
+import { Audio } from "tiny-stdio-mcp-server";
+
+server.tool("speak", "Text to speech", schema, async () => {
+  return Audio.fromBase64(base64Data, "audio/mpeg");
+  // or: await Audio.fromUrl("https://example.com/audio.mp3")
+  // or: Audio.fromBytes(uint8Array, "mp3")
+});
+```
+
+Supported formats: MP3, WAV, OGG, M4A.
+
+### Files
+
+```ts
+import { File } from "tiny-stdio-mcp-server";
+
+server.tool("export", "Export data", schema, async () => {
+  return File.fromText(csvContent, "text/csv");
+  // or: File.fromBytes(uint8Array, "application/pdf")
+  // or: await File.fromUrl("https://example.com/report.pdf")
+});
+```
+
+### Mixed content
+
+Return arrays to send multiple content blocks:
+
+```ts
+server.tool("analyze", "Analyze image", schema, async () => {
+  const image = await Image.fromUrl(url);
+  return [image, "Analysis complete: found 3 objects"];
+});
+```
+
+## Testing
+
+Use `createTestPair` with the official MCP SDK for in-memory testing:
+
+```ts
+import { createTestPair } from "tiny-stdio-mcp-server/testing";
+
+const server = createServer({ name: "test", version: "1.0.0" })
+  .tool("ping", "Ping", defineSchema({}), () => "pong");
+
+const { client, cleanup } = await createTestPair(server);
+
+const result = await client.callTool({ name: "ping", arguments: {} });
+// result.content === [{ type: "text", text: "pong" }]
+
+await cleanup();
+```
+
+Requires `@modelcontextprotocol/sdk` as a dev dependency.
+
+## License
+
+MIT

package/dist/content/convert.d.ts

@@ -6,5 +6,11 @@ export interface TextContent {
     text: string;
 }
 export type ContentBlock = TextContent | ImageContent | AudioContent | EmbeddedResource;
-export type ToolReturn = string | Image | Audio | File | ContentBlock | Array<string | Image | Audio | File | ContentBlock>;
+type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export type ToolReturn = undefined | JsonPrimitive | JsonObject | Image | Audio | File | ContentBlock | Array<undefined | JsonPrimitive | JsonObject | Image | Audio | File | ContentBlock>;
 export declare function toContentBlocks(result: ToolReturn): ContentBlock[];
+export {};

package/dist/content/convert.js

@@ -2,8 +2,11 @@ import { Image } from "./image.js";
 import { Audio } from "./audio.js";
 import { File } from "./file.js";
 function convertSingleValue(value) {
-    if (typeof value === "string") {
-        return { type: "text", text: value };
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+        return { type: "text", text: String(value) };
+    }
+    if (value === null) {
+        return { type: "text", text: "null" };
     }
     if (value instanceof Image) {
         return value.toContentBlock();
@@ -14,12 +17,26 @@ function convertSingleValue(value) {
     if (value instanceof File) {
         return value.toContentBlock();
     }
-    // Already a ContentBlock
-    return value;
+    if (isContentBlock(value)) {
+        return value;
+    }
+    return { type: "text", text: JSON.stringify(value) };
 }
 export function toContentBlocks(result) {
+    if (result === undefined) {
+        return [];
+    }
     if (Array.isArray(result)) {
         return result.flatMap((item) => toContentBlocks(item));
     }
     return [convertSingleValue(result)];
 }
+function isContentBlock(value) {
+    if (!("type" in value) || typeof value.type !== "string") {
+        return false;
+    }
+    return (value.type === "text" ||
+        value.type === "image" ||
+        value.type === "audio" ||
+        value.type === "resource");
+}

package/dist/index.d.ts

@@ -2,10 +2,8 @@ export { createServer } from "./server.js";
 export type { Server } from "./server.js";
 export { defineSchema } from "./schema.js";
 export type { TypedSchema } from "./schema.js";
-export { createTestPair } from "./testing.js";
-export type { TestPair } from "./testing.js";
 export { Image, Audio, File, toContentBlocks, fileTypeFromBuffer, } from "./content/index.js";
 export type { ImageContent, AudioContent, EmbeddedResource, TextResourceContents, BlobResourceContents, ContentBlock, TextContent, FileTypeResult, } from "./content/index.js";
 export type { ToolReturn } from "./content/index.js";
-export type { ServerOptions, ToolHandler, ToolDefinition, Tool, CallToolResult, ContentItem, JSONSchema, JSONSchemaProperty, Transport, SDKTransport, JSONRPCRequest, JSONRPCResponse, JSONRPCError, JSONRPCMessage, JSONRPCNotification, InitializeResult, } from "./types.js";
-export { JSON_RPC_ERROR_CODES } from "./types.js";
+export type { ServerOptions, ToolHandler, ToolDefinition, Tool, CallToolResult, HandleResult, ContentItem, JSONSchema, JSONSchemaProperty, Transport, SDKTransport, JSONRPCRequest, JSONRPCResponse, JSONRPCError, JSONRPCMessage, JSONRPCNotification, InitializeResult, } from "./types.js";
+export { JSON_RPC_ERROR_CODES, ToolError } from "./types.js";

package/dist/index.js

@@ -2,8 +2,6 @@
 export { createServer } from "./server.js";
 // Schema
 export { defineSchema } from "./schema.js";
-// Testing utilities
-export { createTestPair } from "./testing.js";
 // Content helpers
 export { Image, Audio, File, toContentBlocks, fileTypeFromBuffer, } from "./content/index.js";
-export { JSON_RPC_ERROR_CODES } from "./types.js";
+export { JSON_RPC_ERROR_CODES, ToolError } from "./types.js";

package/dist/server.d.ts

@@ -1,9 +1,11 @@
-import type { ServerOptions, ToolHandler, Transport, SDKTransport } from "./types.js";
+import type { ServerOptions, ToolHandler, HandleResult, 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;
+    onNotification(listener: (notification: JSONRPCNotification) => void): () => void;
     removeTool(name: string): boolean;
     notifyToolsChanged(): Promise<void>;
+    handleMessage(method: string, params?: Record<string, unknown>): Promise<HandleResult>;
     listen(): Promise<void>;
     connect(transport: Transport): Promise<void>;
     connectSDK(transport: SDKTransport): Promise<void>;

package/dist/server.js

@@ -1,14 +1,13 @@
 import * as readline from "readline";
-import { JSON_RPC_ERROR_CODES } from "./types.js";
+import { JSON_RPC_ERROR_CODES, ToolError } from "./types.js";
 import { parseMessage, formatSuccessResponse, formatErrorResponse, } from "./jsonrpc.js";
 import { toContentBlocks } from "./content/convert.js";
 const PROTOCOL_VERSION = "2025-11-25";
 export function createServer(options) {
     const tools = new Map();
+    const notificationListeners = new Set();
     let initialized = false;
-    let activeTransport = null;
-    let activeSDKTransport = null;
-    const handleRequest = async (method, params) => {
+    const handleMessage = async (method, params) => {
         // Allow ping and initialize before initialization
         if (method === "ping") {
             return { result: {} };
@@ -77,10 +76,20 @@ export function createServer(options) {
             }
             try {
                 const handlerResult = await tool.handler(toolArgs);
-                const result = { content: toContentBlocks(handlerResult) };
+                const result = isCallToolResult(handlerResult)
+                    ? handlerResult
+                    : { content: toContentBlocks(handlerResult) };
                 return { result };
             }
             catch (err) {
+                if (err instanceof ToolError) {
+                    return {
+                        error: {
+                            code: err.code,
+                            message: err.message,
+                        },
+                    };
+                }
                 const errorMessage = err instanceof Error ? err.message : String(err);
                 const result = {
                     content: [{ type: "text", text: `Error: ${errorMessage}` }],
@@ -103,7 +112,7 @@ export function createServer(options) {
             return;
         }
         const { request, isNotification } = parsed;
-        const { result, error } = await handleRequest(request.method, request.params);
+        const { result, error } = await server.handleMessage(request.method, request.params);
         if (isNotification) {
             return;
         }
@@ -115,16 +124,13 @@ export function createServer(options) {
             write(formatSuccessResponse(requestWithId.id, result) + "\n");
         }
     };
-    const sendNotification = async (method) => {
+    const broadcastNotification = (method) => {
         const notification = {
             jsonrpc: "2.0",
             method,
         };
-        if (activeSDKTransport) {
-            await activeSDKTransport.send(notification);
-        }
-        else if (activeTransport) {
-            activeTransport.writable.write(JSON.stringify(notification) + "\n");
+        for (const listener of notificationListeners) {
+            listener(notification);
         }
     };
     const server = {
@@ -137,14 +143,21 @@ export function createServer(options) {
             });
             return server;
         },
+        onNotification(listener) {
+            notificationListeners.add(listener);
+            return () => {
+                notificationListeners.delete(listener);
+            };
+        },
         removeTool(name) {
             return tools.delete(name);
         },
         async notifyToolsChanged() {
             if (initialized) {
-                await sendNotification("notifications/tools/list_changed");
+                broadcastNotification("notifications/tools/list_changed");
             }
         },
+        handleMessage,
         async listen() {
             return server.connect({
                 readable: process.stdin,
@@ -152,9 +165,10 @@ export function createServer(options) {
             });
         },
         async connect(transport) {
-            activeTransport = transport;
-            activeSDKTransport = null;
             return new Promise((resolve) => {
+                const unsubscribe = server.onNotification((notification) => {
+                    transport.writable.write(`${JSON.stringify(notification)}\n`);
+                });
                 const rl = readline.createInterface({
                     input: transport.readable,
                     crlfDelay: Infinity,
@@ -163,15 +177,16 @@ export function createServer(options) {
                     processLine(line, (data) => transport.writable.write(data));
                 });
                 rl.on("close", () => {
-                    activeTransport = null;
+                    unsubscribe();
                     resolve();
                 });
             });
         },
         async connectSDK(transport) {
-            activeSDKTransport = transport;
-            activeTransport = null;
             return new Promise((resolve) => {
+                const unsubscribe = server.onNotification((notification) => {
+                    void transport.send(notification);
+                });
                 transport.onmessage = async (message) => {
                     // Ignore responses (we only handle requests/notifications)
                     if (!("method" in message)) {
@@ -179,11 +194,11 @@ export function createServer(options) {
                     }
                     // Handle notifications (no id) - don't respond
                     if (!("id" in message) || message.id === undefined) {
-                        await handleRequest(message.method, message.params);
+                        await server.handleMessage(message.method, message.params);
                         return;
                     }
                     const request = message;
-                    const { result, error } = await handleRequest(request.method, request.params);
+                    const { result, error } = await server.handleMessage(request.method, request.params);
                     if (error) {
                         const response = {
                             jsonrpc: "2.0",
@@ -202,7 +217,7 @@ export function createServer(options) {
                     }
                 };
                 transport.onclose = () => {
-                    activeSDKTransport = null;
+                    unsubscribe();
                     resolve();
                 };
                 transport.start();
@@ -211,3 +226,9 @@ export function createServer(options) {
     };
     return server;
 }
+function isCallToolResult(value) {
+    if (typeof value !== "object" || value === null || !("content" in value)) {
+        return false;
+    }
+    return Array.isArray(value.content);
+}

package/dist/types.d.ts

@@ -22,6 +22,10 @@ export declare const JSON_RPC_ERROR_CODES: {
     readonly INVALID_PARAMS: -32602;
     readonly INTERNAL_ERROR: -32603;
 };
+export declare class ToolError extends Error {
+    readonly code: number;
+    constructor(code: number, message: string);
+}
 export interface ToolsCapability {
     listChanged?: boolean;
 }
@@ -44,6 +48,13 @@ export interface CallToolResult {
     content: ContentItem[];
     isError?: boolean;
 }
+export interface HandleResult {
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    };
+}
 export type ContentItem = {
     type: "text";
     text: string;
@@ -80,11 +91,8 @@ export interface ServerOptions {
     name: string;
     version: string;
 }
-import type { Image } from "./content/image.js";
-import type { Audio } from "./content/audio.js";
-import type { File } from "./content/file.js";
-export type ToolReturn = string | Image | Audio | File | ContentItem | Array<string | Image | Audio | File | ContentItem>;
-export type ToolHandler<T = Record<string, unknown>> = (args: T) => Promise<ToolReturn> | ToolReturn;
+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>> {
     name: string;
     description: string;

package/dist/types.js

@@ -4,5 +4,13 @@ export const JSON_RPC_ERROR_CODES = {
     INVALID_REQUEST: -32600,
     METHOD_NOT_FOUND: -32601,
     INVALID_PARAMS: -32602,
-    INTERNAL_ERROR: -32603,
+    INTERNAL_ERROR: -32603
 };
+export class ToolError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ToolError";
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-stdio-mcp-server",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Minimal MCP server over stdio with typed tools and rich content helpers",
   "type": "module",
   "main": "dist/index.js",
@@ -9,6 +9,14 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./jsonrpc": {
+      "types": "./dist/jsonrpc.d.ts",
+      "import": "./dist/jsonrpc.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
     }
   },
   "scripts": {
@@ -16,15 +24,16 @@
     "prepublishOnly": "tsc"
   },
   "files": [
-    "dist"
+    "dist",
+    "!dist/testing.*"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/poe-platform/poe-code.git",
-    "directory": "packages/tiny-mcp-server"
+    "directory": "packages/tiny-stdio-mcp-server"
   },
   "license": "MIT",
   "keywords": [

package/dist/testing.d.ts

@@ -1,7 +0,0 @@
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import type { Server } from "./server.js";
-export interface TestPair {
-    client: Client;
-    cleanup: () => Promise<void>;
-}
-export declare function createTestPair(server: Server): Promise<TestPair>;

package/dist/testing.js

@@ -1,20 +0,0 @@
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
-export async function createTestPair(server) {
-    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
-    const client = new Client({
-        name: "test-client",
-        version: "1.0.0",
-    });
-    // Start server connection (runs in background)
-    const serverPromise = server.connectSDK(serverTransport);
-    // Connect client
-    await client.connect(clientTransport);
-    const cleanup = async () => {
-        await client.close();
-        await clientTransport.close();
-        await serverTransport.close();
-        await serverPromise;
-    };
-    return { client, cleanup };
-}