tiny-stdio-mcp-server weekly downloads statistics

tiny-stdio-mcp-server

Minimal Model Context Protocol server for Node.js. Type-safe tool definitions, rich content helpers for images/audio/files.

Install

Quick start

Run it:

Any MCP client (Claude Code, Codex, etc.) can connect to it over stdio.

API

createServer(options)

Creates a new MCP server.

.tool(name, description, schema, handler, outputSchema?)

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.

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.

Object output schemas work across MCP versions; modern MCP also supports other JSON output types. Otherwise, supported JSON Schema keywords are accepted, 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 formatted validation details in the message and the issue 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.

Handlers can throw ToolError to return a JSON-RPC tool error with a specific code, message, and optional structured data payload. The server forwards that data field in the JSON-RPC error response so clients can inspect machine-readable failure details.

Standard schemas, including Zod

Pass schemas implementing Standard Schema v1 and Standard JSON Schema v1 straight to .tool() or .registerTool(). Toolcraft schemas and Zod 4.5.4 support both interfaces. Existing defineSchema and raw JSON Schema inputs continue to work on the same server.

Tiny MCP has no Zod dependency, peer dependency, imports, or adapter setup. Detection uses the standard interfaces. Older libraries exposing validation without JSON Schema conversion fail clearly during registration.

Discovery uses the schema's input JSON Schema and, when supplied, its output JSON Schema. Runtime parsing uses the original library, preserving defaults, coercions, transforms, refinements, and asynchronous validation. Handler arguments are inferred from parsed output; a handler's return value is checked against the output schema's accepted input. Output parsing runs once before structured content and fallback text are produced. Explicit error results skip output parsing.

Input wire schemas must describe objects. Output schemas may describe any JSON value for modern MCP; older clients receive object structured content or text fallbacks for other values. Conversion failures occur at registration. Custom refinements remain runtime checks and cannot always appear in discovery JSON Schema. Async parsing shares the tool timeout and concurrency limits. validateToolArguments: false disables input parsing, including defaults and transforms; handlers then receive the original arguments.

.listen()

Start listening on stdin/stdout (standard MCP stdio transport).

.connect(transport)

Connect to a custom readable/writable stream pair.

.connectSDK(transport)

Connect using an SDK-compatible in-memory transport (for testing).

.removeTool(name) / .notifyToolsChanged()

Dynamically add/remove tools at runtime and notify connected clients.

Configuration Options

• createServer({ name, version, toolCallTimeoutMs? }): server identity plus an optional positive-integer tool timeout in milliseconds. Timed-out calls return JSON-RPC error -32603; handlers continue running in the background. • .tool(name, description, schema, handler, outputSchema?): tool metadata, input schema, handler, and optional structured output schema. • .connect({ readable, writable }): custom stream transport for tests or embedded hosts.

defineSchema(definition)

Type-safe schema builder. Returns a JSON Schema object with inferred TypeScript types.

Environment Variables

This package does not read public environment variables.

Supported types: string, number, boolean, object, array.

Content helpers

Tool handlers can return rich content beyond plain text.

Images

Supported formats: PNG, JPEG, GIF, WebP.

Audio

Supported formats: MP3, WAV, OGG, M4A.

Remote helpers (Image.fromUrl, Audio.fromUrl, and File.fromUrl) cap downloads at DEFAULT_FROM_URL_MAX_BYTES (5 MiB). Pass { maxBytes } to set a positive integer byte limit per call; responses that exceed the limit are rejected before being converted to content blocks.

Files

Mixed content

Return arrays to send multiple content blocks:

Testing

Use createTestPair with the official MCP SDK for in-memory testing:

Requires @modelcontextprotocol/sdk as a dev dependency.

Environment variables

This package exposes no environment variables. Remote content helpers use the runtime fetch implementation and do not read package-level configuration.

Configuration

There are no package-level config files. Configure each server in code with createServer(options), per-tool schemas, and per-call content helper options such as maxBytes for remote files.

License

MIT

Protocol-only hosts…