tiny-stdio-mcp-server 0.1.0

package/dist/content/audio.d.ts

@@ -0,0 +1,14 @@
+export interface AudioContent {
+    type: "audio";
+    data: string;
+    mimeType: string;
+}
+export declare class Audio {
+    private readonly base64Data;
+    private readonly mimeType;
+    private constructor();
+    static fromUrl(url: string): Promise<Audio>;
+    static fromBytes(data: Uint8Array, format?: string): Audio;
+    static fromBase64(base64: string, mimeType: string): Audio;
+    toContentBlock(): AudioContent;
+}

package/dist/content/audio.js

@@ -0,0 +1,76 @@
+import { fileTypeFromBuffer } from "./mime.js";
+const SUPPORTED_AUDIO_MIMES = new Set([
+    "audio/mpeg",
+    "audio/wav",
+    "audio/ogg",
+    "audio/mp4",
+]);
+const AUDIO_FORMAT_MAP = {
+    mp3: "audio/mpeg",
+    wav: "audio/wav",
+    ogg: "audio/ogg",
+    m4a: "audio/mp4",
+    mpeg: "audio/mpeg",
+};
+export class Audio {
+    base64Data;
+    mimeType;
+    constructor(base64Data, mimeType) {
+        this.base64Data = base64Data;
+        this.mimeType = mimeType;
+    }
+    static async fromUrl(url) {
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch audio from ${url}: ${response.status} ${response.statusText}`);
+        }
+        const arrayBuffer = await response.arrayBuffer();
+        const data = new Uint8Array(arrayBuffer);
+        const detected = fileTypeFromBuffer(data);
+        let mimeType;
+        if (detected && SUPPORTED_AUDIO_MIMES.has(detected.mime)) {
+            mimeType = detected.mime;
+        }
+        else {
+            const contentType = response.headers.get("content-type")?.split(";")[0];
+            if (contentType && SUPPORTED_AUDIO_MIMES.has(contentType)) {
+                mimeType = contentType;
+            }
+            else {
+                throw new Error(`Unable to detect audio MIME type from ${url}`);
+            }
+        }
+        const base64 = Buffer.from(data).toString("base64");
+        return new Audio(base64, mimeType);
+    }
+    static fromBytes(data, format) {
+        let mimeType;
+        if (format) {
+            if (format.includes("/")) {
+                mimeType = format;
+            }
+            else {
+                mimeType = AUDIO_FORMAT_MAP[format.toLowerCase()] || `audio/${format}`;
+            }
+        }
+        else {
+            const detected = fileTypeFromBuffer(data);
+            if (!detected || !SUPPORTED_AUDIO_MIMES.has(detected.mime)) {
+                throw new Error("Unable to detect audio MIME type from bytes");
+            }
+            mimeType = detected.mime;
+        }
+        const base64 = Buffer.from(data).toString("base64");
+        return new Audio(base64, mimeType);
+    }
+    static fromBase64(base64, mimeType) {
+        return new Audio(base64, mimeType);
+    }
+    toContentBlock() {
+        return {
+            type: "audio",
+            data: this.base64Data,
+            mimeType: this.mimeType,
+        };
+    }
+}

package/dist/content/convert.d.ts

@@ -0,0 +1,10 @@
+import { Image, type ImageContent } from "./image.js";
+import { Audio, type AudioContent } from "./audio.js";
+import { File, type EmbeddedResource } from "./file.js";
+export interface TextContent {
+    type: "text";
+    text: string;
+}
+export type ContentBlock = TextContent | ImageContent | AudioContent | EmbeddedResource;
+export type ToolReturn = string | Image | Audio | File | ContentBlock | Array<string | Image | Audio | File | ContentBlock>;
+export declare function toContentBlocks(result: ToolReturn): ContentBlock[];

package/dist/content/convert.js

@@ -0,0 +1,25 @@
+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 (value instanceof Image) {
+        return value.toContentBlock();
+    }
+    if (value instanceof Audio) {
+        return value.toContentBlock();
+    }
+    if (value instanceof File) {
+        return value.toContentBlock();
+    }
+    // Already a ContentBlock
+    return value;
+}
+export function toContentBlocks(result) {
+    if (Array.isArray(result)) {
+        return result.flatMap((item) => toContentBlocks(item));
+    }
+    return [convertSingleValue(result)];
+}

package/dist/content/file-type.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Minimal magic bytes detection for common media types.
+ * This can be replaced with `file-type` package (https://npm.im/file-type)
+ * if more comprehensive detection is needed. The API is designed to be
+ * compatible: fileTypeFromBuffer(data) returns { mime: string, ext: string } | undefined
+ */
+export interface FileTypeResult {
+    mime: string;
+    ext: string;
+}
+export declare function fileTypeFromBuffer(data: Uint8Array): FileTypeResult | undefined;

package/dist/content/file-type.js

@@ -0,0 +1,93 @@
+/**
+ * Minimal magic bytes detection for common media types.
+ * This can be replaced with `file-type` package (https://npm.im/file-type)
+ * if more comprehensive detection is needed. The API is designed to be
+ * compatible: fileTypeFromBuffer(data) returns { mime: string, ext: string } | undefined
+ */
+export function fileTypeFromBuffer(data) {
+    if (data.length < 12) {
+        return undefined;
+    }
+    // PNG: 89 50 4E 47 0D 0A 1A 0A
+    if (data[0] === 0x89 &&
+        data[1] === 0x50 &&
+        data[2] === 0x4e &&
+        data[3] === 0x47 &&
+        data[4] === 0x0d &&
+        data[5] === 0x0a &&
+        data[6] === 0x1a &&
+        data[7] === 0x0a) {
+        return { mime: "image/png", ext: "png" };
+    }
+    // JPEG: FF D8 FF
+    if (data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff) {
+        return { mime: "image/jpeg", ext: "jpg" };
+    }
+    // GIF: 47 49 46 38 (GIF8)
+    if (data[0] === 0x47 &&
+        data[1] === 0x49 &&
+        data[2] === 0x46 &&
+        data[3] === 0x38) {
+        return { mime: "image/gif", ext: "gif" };
+    }
+    // WEBP: 52 49 46 46 ... 57 45 42 50 (RIFF...WEBP)
+    if (data[0] === 0x52 &&
+        data[1] === 0x49 &&
+        data[2] === 0x46 &&
+        data[3] === 0x46 &&
+        data[8] === 0x57 &&
+        data[9] === 0x45 &&
+        data[10] === 0x42 &&
+        data[11] === 0x50) {
+        return { mime: "image/webp", ext: "webp" };
+    }
+    // MP3: FF FB or FF FA (MPEG audio) or 49 44 33 (ID3 tag)
+    if ((data[0] === 0xff && (data[1] === 0xfb || data[1] === 0xfa)) ||
+        (data[0] === 0x49 && data[1] === 0x44 && data[2] === 0x33)) {
+        return { mime: "audio/mpeg", ext: "mp3" };
+    }
+    // WAV: 52 49 46 46 ... 57 41 56 45 (RIFF...WAVE)
+    if (data[0] === 0x52 &&
+        data[1] === 0x49 &&
+        data[2] === 0x46 &&
+        data[3] === 0x46 &&
+        data[8] === 0x57 &&
+        data[9] === 0x41 &&
+        data[10] === 0x56 &&
+        data[11] === 0x45) {
+        return { mime: "audio/wav", ext: "wav" };
+    }
+    // OGG: 4F 67 67 53 (OggS)
+    if (data[0] === 0x4f &&
+        data[1] === 0x67 &&
+        data[2] === 0x67 &&
+        data[3] === 0x53) {
+        return { mime: "audio/ogg", ext: "ogg" };
+    }
+    // M4A: MP4 container with audio - check for M4A brand at offset 8
+    // ftyp followed by M4A brand
+    if (data[4] === 0x66 &&
+        data[5] === 0x74 &&
+        data[6] === 0x79 &&
+        data[7] === 0x70 &&
+        data[8] === 0x4d &&
+        data[9] === 0x34 &&
+        data[10] === 0x41) {
+        return { mime: "audio/mp4", ext: "m4a" };
+    }
+    // MP4: ... 66 74 79 70 (ftyp box, offset 4)
+    if (data[4] === 0x66 &&
+        data[5] === 0x74 &&
+        data[6] === 0x79 &&
+        data[7] === 0x70) {
+        return { mime: "video/mp4", ext: "mp4" };
+    }
+    // WEBM: 1A 45 DF A3 (EBML header)
+    if (data[0] === 0x1a &&
+        data[1] === 0x45 &&
+        data[2] === 0xdf &&
+        data[3] === 0xa3) {
+        return { mime: "video/webm", ext: "webm" };
+    }
+    return undefined;
+}

package/dist/content/file.d.ts

@@ -0,0 +1,26 @@
+export interface TextResourceContents {
+    uri: string;
+    mimeType: string;
+    text: string;
+}
+export interface BlobResourceContents {
+    uri: string;
+    mimeType: string;
+    blob: string;
+}
+export interface EmbeddedResource {
+    type: "resource";
+    resource: TextResourceContents | BlobResourceContents;
+}
+export declare class File {
+    private readonly data;
+    private readonly mimeType;
+    private readonly isText;
+    private readonly name?;
+    private constructor();
+    static fromUrl(url: string): Promise<File>;
+    static fromBytes(data: Uint8Array, mimeType: string): File;
+    static fromText(text: string, mimeType?: string): File;
+    static fromBase64(base64: string, mimeType: string): File;
+    toContentBlock(): EmbeddedResource;
+}

package/dist/content/file.js

@@ -0,0 +1,94 @@
+import { fileTypeFromBuffer } from "./mime.js";
+function isTextMimeType(mimeType) {
+    return (mimeType.startsWith("text/") ||
+        mimeType === "application/json" ||
+        mimeType === "application/xml" ||
+        mimeType === "application/javascript" ||
+        mimeType === "application/typescript");
+}
+export class File {
+    data;
+    mimeType;
+    isText;
+    name;
+    constructor(data, mimeType, isText, name) {
+        this.data = data;
+        this.mimeType = mimeType;
+        this.isText = isText;
+        this.name = name;
+    }
+    static async fromUrl(url) {
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch file from ${url}: ${response.status} ${response.statusText}`);
+        }
+        const arrayBuffer = await response.arrayBuffer();
+        const data = new Uint8Array(arrayBuffer);
+        const detected = fileTypeFromBuffer(data);
+        let mimeType;
+        if (detected) {
+            mimeType = detected.mime;
+        }
+        else {
+            const contentType = response.headers.get("content-type")?.split(";")[0];
+            if (contentType) {
+                mimeType = contentType;
+            }
+            else {
+                throw new Error(`Unable to detect MIME type from ${url}`);
+            }
+        }
+        const isText = isTextMimeType(mimeType);
+        const name = url.split("/").pop() || "file";
+        return new File(data, mimeType, isText, name);
+    }
+    static fromBytes(data, mimeType) {
+        const isText = isTextMimeType(mimeType);
+        return new File(data, mimeType, isText);
+    }
+    static fromText(text, mimeType = "text/plain") {
+        return new File(text, mimeType, true);
+    }
+    static fromBase64(base64, mimeType) {
+        const data = Buffer.from(base64, "base64");
+        const isText = isTextMimeType(mimeType);
+        return new File(new Uint8Array(data), mimeType, isText);
+    }
+    toContentBlock() {
+        const uri = this.name ? `file:///${this.name}` : "file:///data";
+        if (this.isText) {
+            let text;
+            if (typeof this.data === "string") {
+                text = this.data;
+            }
+            else {
+                text = new TextDecoder("utf-8").decode(this.data);
+            }
+            return {
+                type: "resource",
+                resource: {
+                    uri,
+                    mimeType: this.mimeType,
+                    text,
+                },
+            };
+        }
+        else {
+            let blob;
+            if (typeof this.data === "string") {
+                blob = Buffer.from(this.data).toString("base64");
+            }
+            else {
+                blob = Buffer.from(this.data).toString("base64");
+            }
+            return {
+                type: "resource",
+                resource: {
+                    uri,
+                    mimeType: this.mimeType,
+                    blob,
+                },
+            };
+        }
+    }
+}

package/dist/content/image.d.ts

@@ -0,0 +1,14 @@
+export interface ImageContent {
+    type: "image";
+    data: string;
+    mimeType: string;
+}
+export declare class Image {
+    private readonly base64Data;
+    private readonly mimeType;
+    private constructor();
+    static fromUrl(url: string): Promise<Image>;
+    static fromBytes(data: Uint8Array, format?: string): Image;
+    static fromBase64(base64: string, mimeType: string): Image;
+    toContentBlock(): ImageContent;
+}

package/dist/content/image.js

@@ -0,0 +1,64 @@
+import { fileTypeFromBuffer } from "./mime.js";
+const SUPPORTED_IMAGE_MIMES = new Set([
+    "image/png",
+    "image/jpeg",
+    "image/gif",
+    "image/webp",
+]);
+export class Image {
+    base64Data;
+    mimeType;
+    constructor(base64Data, mimeType) {
+        this.base64Data = base64Data;
+        this.mimeType = mimeType;
+    }
+    static async fromUrl(url) {
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch image from ${url}: ${response.status} ${response.statusText}`);
+        }
+        const arrayBuffer = await response.arrayBuffer();
+        const data = new Uint8Array(arrayBuffer);
+        const detected = fileTypeFromBuffer(data);
+        let mimeType;
+        if (detected && SUPPORTED_IMAGE_MIMES.has(detected.mime)) {
+            mimeType = detected.mime;
+        }
+        else {
+            const contentType = response.headers.get("content-type")?.split(";")[0];
+            if (contentType && SUPPORTED_IMAGE_MIMES.has(contentType)) {
+                mimeType = contentType;
+            }
+            else {
+                throw new Error(`Unable to detect image MIME type from ${url}`);
+            }
+        }
+        const base64 = Buffer.from(data).toString("base64");
+        return new Image(base64, mimeType);
+    }
+    static fromBytes(data, format) {
+        let mimeType;
+        if (format) {
+            mimeType = format.includes("/") ? format : `image/${format}`;
+        }
+        else {
+            const detected = fileTypeFromBuffer(data);
+            if (!detected || !SUPPORTED_IMAGE_MIMES.has(detected.mime)) {
+                throw new Error("Unable to detect image MIME type from bytes");
+            }
+            mimeType = detected.mime;
+        }
+        const base64 = Buffer.from(data).toString("base64");
+        return new Image(base64, mimeType);
+    }
+    static fromBase64(base64, mimeType) {
+        return new Image(base64, mimeType);
+    }
+    toContentBlock() {
+        return {
+            type: "image",
+            data: this.base64Data,
+            mimeType: this.mimeType,
+        };
+    }
+}

package/dist/content/index.d.ts

@@ -0,0 +1,5 @@
+export { fileTypeFromBuffer, type FileTypeResult } from "./mime.js";
+export { Image, type ImageContent } from "./image.js";
+export { Audio, type AudioContent } from "./audio.js";
+export { File, type EmbeddedResource, type TextResourceContents, type BlobResourceContents, } from "./file.js";
+export { toContentBlocks, type ContentBlock, type TextContent, type ToolReturn, } from "./convert.js";

package/dist/content/index.js

@@ -0,0 +1,8 @@
+// MIME detection
+export { fileTypeFromBuffer } from "./mime.js";
+// Content helpers
+export { Image } from "./image.js";
+export { Audio } from "./audio.js";
+export { File, } from "./file.js";
+// Conversion utility
+export { toContentBlocks, } from "./convert.js";

package/dist/content/mime.d.ts

@@ -0,0 +1 @@
+export { fileTypeFromBuffer, type FileTypeResult } from "./file-type.js";

package/dist/content/mime.js

@@ -0,0 +1 @@
+export { fileTypeFromBuffer } from "./file-type.js";

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+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";

package/dist/index.js

@@ -0,0 +1,9 @@
+// Server
+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";

package/dist/jsonrpc.d.ts

@@ -0,0 +1,14 @@
+import type { JSONRPCRequest, JSONRPCError, JSONRPCNotification } from "./types.js";
+export interface ParseResult {
+    success: true;
+    request: JSONRPCRequest | JSONRPCNotification;
+    isNotification: boolean;
+}
+export interface ParseError {
+    success: false;
+    error: JSONRPCError;
+    id: string | number | null;
+}
+export declare function parseMessage(line: string): ParseResult | ParseError;
+export declare function formatSuccessResponse(id: string | number | null, result: unknown): string;
+export declare function formatErrorResponse(id: string | number | null, error: JSONRPCError): string;

package/dist/jsonrpc.js

@@ -0,0 +1,99 @@
+import { JSON_RPC_ERROR_CODES } from "./types.js";
+export function parseMessage(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return {
+            success: false,
+            error: {
+                code: JSON_RPC_ERROR_CODES.PARSE_ERROR,
+                message: "Parse error",
+            },
+            id: null,
+        };
+    }
+    if (typeof parsed !== "object" ||
+        parsed === null ||
+        Array.isArray(parsed)) {
+        return {
+            success: false,
+            error: {
+                code: JSON_RPC_ERROR_CODES.INVALID_REQUEST,
+                message: "Invalid Request",
+            },
+            id: null,
+        };
+    }
+    const obj = parsed;
+    const hasId = "id" in obj;
+    const id = typeof obj.id === "string" || typeof obj.id === "number" ? obj.id : null;
+    if (obj.jsonrpc !== "2.0") {
+        return {
+            success: false,
+            error: {
+                code: JSON_RPC_ERROR_CODES.INVALID_REQUEST,
+                message: "Invalid Request",
+            },
+            id,
+        };
+    }
+    if (typeof obj.method !== "string") {
+        return {
+            success: false,
+            error: {
+                code: JSON_RPC_ERROR_CODES.INVALID_REQUEST,
+                message: "Invalid Request",
+            },
+            id,
+        };
+    }
+    if (!hasId) {
+        return {
+            success: true,
+            isNotification: true,
+            request: {
+                jsonrpc: "2.0",
+                method: obj.method,
+                params: obj.params,
+            },
+        };
+    }
+    if (id === null) {
+        return {
+            success: false,
+            error: {
+                code: JSON_RPC_ERROR_CODES.INVALID_REQUEST,
+                message: "Invalid Request",
+            },
+            id: null,
+        };
+    }
+    return {
+        success: true,
+        isNotification: false,
+        request: {
+            jsonrpc: "2.0",
+            id,
+            method: obj.method,
+            params: obj.params,
+        },
+    };
+}
+export function formatSuccessResponse(id, result) {
+    const response = {
+        jsonrpc: "2.0",
+        id,
+        result,
+    };
+    return JSON.stringify(response);
+}
+export function formatErrorResponse(id, error) {
+    const response = {
+        jsonrpc: "2.0",
+        id,
+        error,
+    };
+    return JSON.stringify(response);
+}

package/dist/schema.d.ts

@@ -0,0 +1,19 @@
+import type { JSONSchema } from "./types.js";
+type SchemaPropertyType = "string" | "number" | "boolean" | "object" | "array";
+interface SchemaPropertyDef {
+    type: SchemaPropertyType;
+    description?: string;
+    optional?: boolean;
+}
+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;
+type InferSchema<T extends SchemaDefinition> = {
+    [K in keyof T as T[K]["optional"] extends true ? never : K]: InferType<T[K]["type"]>;
+} & {
+    [K in keyof T as T[K]["optional"] extends true ? K : never]?: InferType<T[K]["type"]>;
+};
+export interface TypedSchema<T> extends JSONSchema {
+    __type?: T;
+}
+export declare function defineSchema<T extends SchemaDefinition>(definition: T): TypedSchema<InferSchema<T>>;
+export {};

package/dist/schema.js

@@ -0,0 +1,18 @@
+export function defineSchema(definition) {
+    const properties = {};
+    const required = [];
+    for (const [key, prop] of Object.entries(definition)) {
+        properties[key] = {
+            type: prop.type,
+            ...(prop.description !== undefined && { description: prop.description }),
+        };
+        if (!prop.optional) {
+            required.push(key);
+        }
+    }
+    return {
+        type: "object",
+        properties,
+        required,
+    };
+}

package/dist/server.d.ts

@@ -0,0 +1,11 @@
+import type { ServerOptions, ToolHandler, Transport, SDKTransport } 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;
+    removeTool(name: string): boolean;
+    notifyToolsChanged(): Promise<void>;
+    listen(): Promise<void>;
+    connect(transport: Transport): Promise<void>;
+    connectSDK(transport: SDKTransport): Promise<void>;
+}
+export declare function createServer(options: ServerOptions): Server;

package/dist/server.js

@@ -0,0 +1,213 @@
+import * as readline from "readline";
+import { JSON_RPC_ERROR_CODES } 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();
+    let initialized = false;
+    let activeTransport = null;
+    let activeSDKTransport = null;
+    const handleRequest = async (method, params) => {
+        // Allow ping and initialize before initialization
+        if (method === "ping") {
+            return { result: {} };
+        }
+        if (method === "initialize") {
+            initialized = true;
+            const requestedProtocol = typeof params?.protocolVersion === "string"
+                ? params.protocolVersion
+                : null;
+            const result = {
+                protocolVersion: requestedProtocol ?? PROTOCOL_VERSION,
+                capabilities: {
+                    tools: {
+                        listChanged: true,
+                    },
+                },
+                serverInfo: {
+                    name: options.name,
+                    version: options.version,
+                },
+            };
+            return { result };
+        }
+        if (method === "notifications/initialized") {
+            return { result: undefined };
+        }
+        // All other methods require initialization
+        if (!initialized) {
+            return {
+                error: {
+                    code: JSON_RPC_ERROR_CODES.INVALID_REQUEST,
+                    message: "Server not initialized",
+                },
+            };
+        }
+        if (method === "tools/list") {
+            const toolList = [];
+            for (const tool of tools.values()) {
+                toolList.push({
+                    name: tool.name,
+                    description: tool.description,
+                    inputSchema: tool.inputSchema,
+                });
+            }
+            return { result: { tools: toolList } };
+        }
+        if (method === "tools/call") {
+            const toolName = params?.name;
+            const toolArgs = params?.arguments || {};
+            if (!toolName) {
+                return {
+                    error: {
+                        code: JSON_RPC_ERROR_CODES.INVALID_PARAMS,
+                        message: "Tool name required",
+                    },
+                };
+            }
+            const tool = tools.get(toolName);
+            if (!tool) {
+                return {
+                    error: {
+                        code: JSON_RPC_ERROR_CODES.INVALID_PARAMS,
+                        message: `Tool not found: ${toolName}`,
+                    },
+                };
+            }
+            try {
+                const handlerResult = await tool.handler(toolArgs);
+                const result = { content: toContentBlocks(handlerResult) };
+                return { result };
+            }
+            catch (err) {
+                const errorMessage = err instanceof Error ? err.message : String(err);
+                const result = {
+                    content: [{ type: "text", text: `Error: ${errorMessage}` }],
+                    isError: true,
+                };
+                return { result };
+            }
+        }
+        return {
+            error: {
+                code: JSON_RPC_ERROR_CODES.METHOD_NOT_FOUND,
+                message: "Method not found",
+            },
+        };
+    };
+    const processLine = async (line, write) => {
+        const parsed = parseMessage(line);
+        if (!parsed.success) {
+            write(formatErrorResponse(parsed.id, parsed.error) + "\n");
+            return;
+        }
+        const { request, isNotification } = parsed;
+        const { result, error } = await handleRequest(request.method, request.params);
+        if (isNotification) {
+            return;
+        }
+        const requestWithId = request;
+        if (error) {
+            write(formatErrorResponse(requestWithId.id, error) + "\n");
+        }
+        else if (result !== undefined) {
+            write(formatSuccessResponse(requestWithId.id, result) + "\n");
+        }
+    };
+    const sendNotification = async (method) => {
+        const notification = {
+            jsonrpc: "2.0",
+            method,
+        };
+        if (activeSDKTransport) {
+            await activeSDKTransport.send(notification);
+        }
+        else if (activeTransport) {
+            activeTransport.writable.write(JSON.stringify(notification) + "\n");
+        }
+    };
+    const server = {
+        tool(name, description, inputSchema, handler) {
+            tools.set(name, {
+                name,
+                description,
+                inputSchema: inputSchema,
+                handler: handler,
+            });
+            return server;
+        },
+        removeTool(name) {
+            return tools.delete(name);
+        },
+        async notifyToolsChanged() {
+            if (initialized) {
+                await sendNotification("notifications/tools/list_changed");
+            }
+        },
+        async listen() {
+            return server.connect({
+                readable: process.stdin,
+                writable: process.stdout,
+            });
+        },
+        async connect(transport) {
+            activeTransport = transport;
+            activeSDKTransport = null;
+            return new Promise((resolve) => {
+                const rl = readline.createInterface({
+                    input: transport.readable,
+                    crlfDelay: Infinity,
+                });
+                rl.on("line", (line) => {
+                    processLine(line, (data) => transport.writable.write(data));
+                });
+                rl.on("close", () => {
+                    activeTransport = null;
+                    resolve();
+                });
+            });
+        },
+        async connectSDK(transport) {
+            activeSDKTransport = transport;
+            activeTransport = null;
+            return new Promise((resolve) => {
+                transport.onmessage = async (message) => {
+                    // Ignore responses (we only handle requests/notifications)
+                    if (!("method" in message)) {
+                        return;
+                    }
+                    // Handle notifications (no id) - don't respond
+                    if (!("id" in message) || message.id === undefined) {
+                        await handleRequest(message.method, message.params);
+                        return;
+                    }
+                    const request = message;
+                    const { result, error } = await handleRequest(request.method, request.params);
+                    if (error) {
+                        const response = {
+                            jsonrpc: "2.0",
+                            id: request.id,
+                            error,
+                        };
+                        await transport.send(response);
+                    }
+                    else if (result !== undefined) {
+                        const response = {
+                            jsonrpc: "2.0",
+                            id: request.id,
+                            result,
+                        };
+                        await transport.send(response);
+                    }
+                };
+                transport.onclose = () => {
+                    activeSDKTransport = null;
+                    resolve();
+                };
+                transport.start();
+            });
+        },
+    };
+    return server;
+}

package/dist/testing.d.ts

@@ -0,0 +1,7 @@
+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

@@ -0,0 +1,20 @@
+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 };
+}

package/dist/types.d.ts

@@ -0,0 +1,111 @@
+export interface JSONRPCRequest {
+    jsonrpc: "2.0";
+    id: string | number;
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface JSONRPCResponse {
+    jsonrpc: "2.0";
+    id: string | number | null;
+    result?: unknown;
+    error?: JSONRPCError;
+}
+export interface JSONRPCError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+export declare const JSON_RPC_ERROR_CODES: {
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+};
+export interface ToolsCapability {
+    listChanged?: boolean;
+}
+export interface InitializeResult {
+    protocolVersion: string;
+    capabilities: {
+        tools?: ToolsCapability;
+    };
+    serverInfo: {
+        name: string;
+        version: string;
+    };
+}
+export interface Tool {
+    name: string;
+    description: string;
+    inputSchema: JSONSchema;
+}
+export interface CallToolResult {
+    content: ContentItem[];
+    isError?: boolean;
+}
+export type ContentItem = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+} | {
+    type: "audio";
+    data: string;
+    mimeType: string;
+} | {
+    type: "resource";
+    resource: {
+        uri: string;
+        mimeType: string;
+        text: string;
+    } | {
+        uri: string;
+        mimeType: string;
+        blob: string;
+    };
+};
+export interface JSONSchema {
+    type: "object";
+    properties: Record<string, JSONSchemaProperty>;
+    required?: string[];
+}
+export interface JSONSchemaProperty {
+    type: "string" | "number" | "boolean" | "object" | "array";
+    description?: string;
+}
+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;
+export interface ToolDefinition<T = Record<string, unknown>> {
+    name: string;
+    description: string;
+    inputSchema: JSONSchema;
+    handler: ToolHandler<T>;
+}
+export interface Transport {
+    readable: NodeJS.ReadableStream;
+    writable: NodeJS.WritableStream;
+}
+export interface SDKTransport {
+    onmessage?: (message: JSONRPCMessage) => void;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    start: () => Promise<void>;
+    close: () => Promise<void>;
+    send: (message: JSONRPCMessage) => Promise<void>;
+}
+export type JSONRPCMessage = JSONRPCRequest | JSONRPCResponse | JSONRPCNotification;
+export interface JSONRPCNotification {
+    jsonrpc: "2.0";
+    method: string;
+    params?: Record<string, unknown>;
+}

package/dist/types.js

@@ -0,0 +1,8 @@
+// JSON-RPC error codes
+export const JSON_RPC_ERROR_CODES = {
+    PARSE_ERROR: -32700,
+    INVALID_REQUEST: -32600,
+    METHOD_NOT_FOUND: -32601,
+    INVALID_PARAMS: -32602,
+    INTERNAL_ERROR: -32603,
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "tiny-stdio-mcp-server",
+  "version": "0.1.0",
+  "description": "Minimal MCP server over stdio with typed tools and rich content helpers",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/poe-platform/poe-code.git",
+    "directory": "packages/tiny-mcp-server"
+  },
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "stdio",
+    "server"
+  ],
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.3"
+  }
+}