mcp-client-general

General, streaming-friendly MCP (Model Context Protocol) client for Node.js.

!npm downloads
!license
!node version

- Spawns an MCP-compatible server as a child process
- Speaks JSON-RPC 2.0 over stdin / stdout
- Ignores fragile Content-Length headers and uses a robust JSON object scanner
- Supports multiple requests per process (piped line-by-line)
- CLI + programmatic TypeScript API

> This package is designed to be a generic, open-source MCP client. It works with any MCP-compliant server implementation, including the reference mcp-server-general package.

---

Features

- Zero-config profiles – run built-in MCP stacks without manual wiring
- Child process orchestration – monitors stderr, exit, error
- Handshake detection – first valid JSON object = handshake
- Framing-agnostic parsing – safely ignores Content-Length
- JSON-RPC 2.0 support – id-based pending map, timeouts
- CLI & Library – usable from terminal or TypeScript

---

Installation

``bash
npm install -g mcp-client-general


or


npm install mcp-client-general --save-dev
`

---

CLI Usage

$3

`bash
mcp run "node dist/server.js"
`

$3

`bash
echo '{"jsonrpc":"2.0","id":1,"method":"providers.list"}' \
| mcp run "node ../mcp-server-general/dist/server.js"
`

$3

`json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"providers": [
{
"provider": "openai",
"model": "gpt-4o-mini"
}
]
}
}
`

---

$3

`bash
printf '%s\n%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"providers.list"}' \
'{"jsonrpc":"2.0","id":2,"method":"steps.list"}' \
| mcp run "node ../mcp-server-general/dist/server.js"
`

$3

`json
{
"jsonrpc": "2.0",
"id": 1,
"result": { "providers": [ / ... / ] }
}
{
"jsonrpc": "2.0",
"id": 2,
"result": { "steps": [ / ... / ] }
}
`

---

$3

`bash
echo '{"jsonrpc":"2.0","id":3,"method":"scoring.schema"}' \
| mcp run "node ../mcp-server-general/dist/server.js"
`

`json
{
"jsonrpc": "2.0",
"id": 3,
"error": {
"code": -32601,
"message": "Method not found: scoring.schema"
}
}
`

---

Programmatic Usage (TypeScript)

`ts
import { MCPProcess } from "mcp-client-general";
import type { JSONRPCRequest } from "mcp-client-general/jsonrpc";

async function main() {
const proc = new MCPProcess({
command: "node",
args: ["../mcp-server-general/dist/server.js"],
startupTimeoutMs: 4000,
shutdownTimeoutMs: 3000
});

proc.on("stderr", (msg) => process.stderr.write(String(msg)));

await proc.start();

const req: JSONRPCRequest = {
jsonrpc: "2.0",
id: 1,
method: "providers.list",
params: {}
};

const response = await proc.send(req);
console.log(JSON.stringify(response, null, 2));

await proc.close();
}

main().catch((err) => {
console.error(err);
process.exit(1);
});
`

---

Design Notes

$3

The first valid JSON object received from stdout is treated as the handshake.
If the server delays or prints logs first, the client still proceeds safely.

$3

Many servers emit:

`
Content-Length: 2888\r\n\r\n{ ... JSON ... }
`

But Content-Length is often wrong or mixed with logs.

This client instead:

- ignores Content-Length
- uses a streaming JSON scanner:
- finds {
- tracks nested { / }
- handles JSON strings & escapes
- extracts full JSON frames

Works even with imperfect/experimental MCP servers.

$3


- Requests stored in Map
- Responses resolve Promises
- Timeouts reject automatically

---

Environment Variables

Enable verbose debugging:

`bash
MCP_DEBUG=1 mcp run "node dist/server.js"
``

Shows:
- handshake detection
- scan events
- JSON parse errors
- child process exits
- forwarded stderr

---

Limitations

- Server must output valid JSON frames
- First JSON object is always treated as handshake
- JSON-like logs printed before handshake may be misinterpreted

---

License

MIT – see LICENSE.