node-stdio-jsonrpc

Clean, developer-friendly JSON-RPC 2.0 client over stdio (child process communication)

Built on top of @gnana997/node-jsonrpc with a stdio transport layer for communicating with child processes using line-delimited JSON.

Perfect for building clients for:

• Model Context Protocol (MCP) servers
• Language servers (LSP)
• Custom stdio-based JSON-RPC services
• CLI tools with JSON-RPC interfaces

Features

✨ Clean API - Simple, intuitive interface for stdio JSON-RPC communication 🚀 TypeScript First - Full type safety with generics 📦 Dual Package - ESM and CommonJS support 🔄 Event-Driven - Built on EventEmitter for notifications and logs 🛡️ Robust - Comprehensive error handling and process lifecycle management 🧪 Well-Tested - 47 tests with 81%+ coverage 📝 Well-Documented - Examples and TypeScript types included

Installation

npm install node-stdio-jsonrpc

Quick Start

import { StdioClient } from 'node-stdio-jsonrpc';

// Create a client that spawns a child process
const client = new StdioClient({
  command: 'node',
  args: ['./your-jsonrpc-server.js'],
  debug: true, // Optional: enable debug logging
});

// Connect to the server
await client.connect();

// Make a request
const result = await client.request('yourMethod', { param: 'value' });
console.log('Result:', result);

// Send a notification (no response expected)
client.notify('log', { level: 'info', message: 'Hello' });

// Listen for server notifications
client.on('notification', (method, params) => {
  console.log(`Server notification: ${method}`, params);
});

// Disconnect when done
await client.disconnect();

API Reference

StdioClient

The main class for creating JSON-RPC clients over stdio.

Constructor

new StdioClient(config: StdioClientConfig)

Config Options:

Option	Type	Default	Description
command	string	required	Command to spawn (e.g., 'node', 'python')
args	string[]	[]	Arguments to pass to the command
cwd	string	process.cwd()	Working directory for the child process
env	NodeJS.ProcessEnv	process.env	Environment variables
connectionTimeout	number	10000	Connection timeout in milliseconds
requestTimeout	number	30000	Request timeout in milliseconds
debug	boolean	false	Enable debug logging

Methods

connect(): Promise<void>

Spawns the child process and establishes the connection.

await client.connect();

disconnect(): Promise<void>

Terminates the child process and cleans up resources.

await client.disconnect();

request<TResult>(method: string, params?: unknown): Promise<TResult>

Sends a JSON-RPC request and waits for the response.

interface CalculateResult {
  sum: number;
}

const result = await client.request<CalculateResult>('calculate', {
  operation: 'add',
  a: 5,
  b: 3,
});

console.log(result.sum); // 8

notify(method: string, params?: unknown): void

Sends a JSON-RPC notification (no response expected).

client.notify('log', { level: 'info', message: 'Task completed' });

isConnected(): boolean

Checks if the client is currently connected.

if (client.isConnected()) {
  console.log('Connected!');
}

Events

The client extends EventEmitter and emits the following events:

Event	Parameters	Description
connected	()	Emitted when connection is established
disconnected	()	Emitted when disconnected from server
notification	(method: string, params?: unknown)	Server sent a notification
error	(error: Error)	An error occurred
log	(message: string)	Server wrote to stderr

client.on('connected', () => {
  console.log('Connected to server!');
});

client.on('disconnected', () => {
  console.log('Disconnected from server');
});

client.on('notification', (method, params) => {
  console.log(`Notification: ${method}`, params);
});

client.on('error', (error) => {
  console.error('Error:', error);
});

client.on('log', (message) => {
  console.log(`Server log: ${message}`);
});

StdioTransport

Lower-level transport implementation. Usually you'll use StdioClient, but StdioTransport is available if you need direct control.

import { StdioTransport } from 'node-stdio-jsonrpc/transport';
import { JSONRPCClient } from '@gnana997/node-jsonrpc';

const transport = new StdioTransport({
  command: 'node',
  args: ['./server.js'],
});

const client = new JSONRPCClient({ transport });
await client.connect();

Examples

Basic Example

import { StdioClient } from 'node-stdio-jsonrpc';

const client = new StdioClient({
  command: 'node',
  args: ['./echo-server.js'],
});

await client.connect();

const response = await client.request('echo', { message: 'Hello, World!' });
console.log(response); // { message: 'Hello, World!' }

await client.disconnect();

MCP Client Example

Perfect for connecting to Model Context Protocol servers:

import { StdioClient } from 'node-stdio-jsonrpc';

const client = new StdioClient({
  command: 'npx',
  args: ['@modelcontextprotocol/server-filesystem', '~/Documents'],
  debug: true,
});

await client.connect();

// Initialize MCP session
const initResult = await client.request('initialize', {
  protocolVersion: '2024-11-05',
  capabilities: { roots: { listChanged: true } },
  clientInfo: { name: 'my-client', version: '1.0.0' },
});

client.notify('notifications/initialized');

// List available tools
const { tools } = await client.request('tools/list');
console.log('Available tools:', tools);

await client.disconnect();

See the MCP client example for a complete implementation.

Error Handling

import { StdioClient, JSONRPCError } from 'node-stdio-jsonrpc';

const client = new StdioClient({
  command: 'node',
  args: ['./server.js'],
});

try {
  await client.connect();

  const result = await client.request('someMethod', { param: 'value' });
  console.log('Success:', result);

} catch (error) {
  if (error instanceof JSONRPCError) {
    console.error('JSON-RPC Error:', error.code, error.message);
  } else {
    console.error('Connection/Transport Error:', error);
  }
} finally {
  if (client.isConnected()) {
    await client.disconnect();
  }
}

Using with TypeScript

import { StdioClient } from 'node-stdio-jsonrpc';

// Define your request/response types
interface CalculateParams {
  operation: 'add' | 'subtract' | 'multiply' | 'divide';
  a: number;
  b: number;
}

interface CalculateResult {
  result: number;
}

const client = new StdioClient({
  command: 'node',
  args: ['./calculator-server.js'],
});

await client.connect();

// Type-safe requests
const result = await client.request<CalculateResult>('calculate', {
  operation: 'add',
  a: 10,
  b: 5,
} satisfies CalculateParams);

console.log(result.result); // TypeScript knows this is a number

await client.disconnect();

Protocol

This library implements JSON-RPC 2.0 over stdio (standard input/output) using line-delimited JSON framing:

• Each JSON message is on its own line
• Messages are terminated with \n
• stdin: Client → Server
• stdout: Server → Client (JSON-RPC messages)
• stderr: Server logs (not JSON-RPC)

Message Format

Request:

{"jsonrpc":"2.0","id":1,"method":"methodName","params":{"key":"value"}}

Success Response:

{"jsonrpc":"2.0","id":1,"result":{"data":"value"}}

Error Response:

{"jsonrpc":"2.0","id":1,"error":{"code":-32000,"message":"Error message"}}

Notification (no id):

{"jsonrpc":"2.0","method":"notifyMethod","params":{"key":"value"}}

Requirements

• Node.js 18 or higher
• TypeScript 5.x (if using TypeScript)

Related Packages

• @gnana997/node-jsonrpc - Core JSON-RPC 2.0 implementation
• node-ipc-jsonrpc - JSON-RPC over IPC (Unix sockets / Windows named pipes)

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT © gnana997

Changelog

See CHANGELOG.md for version history.

---

Built with ❤️ using TypeScript and @gnana997/node-jsonrpc