mcp-client-general 0.0.1 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Antal Mátyás Nagy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,215 @@
+# mcp-client-general
+
+General, streaming-friendly MCP (Model Context Protocol) client for Node.js.
+
+[![npm version](https://img.shields.io/npm/v/mcp-client-general.svg)](https://npmjs.com/package/mcp-client-general)
+![npm downloads](https://img.shields.io/npm/dm/mcp-client-general.svg)
+![license](https://img.shields.io/badge/license-MIT-blue.svg)
+![node version](https://img.shields.io/node/v/mcp-client-general.svg)
+
+- 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
+
+### Run an MCP server
+```bash
+mcp run "node dist/server.js"
+```
+
+### Send a single JSON-RPC request
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"providers.list"}' \
+  | mcp run "node ../mcp-server-general/dist/server.js"
+```
+
+### Example output
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "providers": [
+      {
+        "provider": "openai",
+        "model": "gpt-4o-mini"
+      }
+    ]
+  }
+}
+```
+
+---
+
+### Multiple requests in a single run
+```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"
+```
+
+### Example output
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": { "providers": [ /* ... */ ] }
+}
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "result": { "steps": [ /* ... */ ] }
+}
+```
+
+---
+
+### Error handling (JSON-RPC native)
+
+```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
+
+### Handshake detection
+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.
+
+### Framing strategy
+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.
+
+### Pending RPC requests
+- Requests stored in `Map<id, PendingEntry>`
+- 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.

package/dist/execution/planner.js

@@ -0,0 +1,31 @@
+import fs from "node:fs";
+import path from "node:path";
+function hasLocalBin(command) {
+    const binPath = path.join(process.cwd(), "node_modules", ".bin", command);
+    return fs.existsSync(binPath);
+}
+export async function planExecution(profile) {
+    const { command, autoInstall } = profile.server;
+    // 1) local node_modules/.bin
+    if (hasLocalBin(command)) {
+        return {
+            command,
+            args: [],
+            source: "local-bin",
+        };
+    }
+    // 2) npm exec (preferred auto-install path)
+    if (autoInstall) {
+        return {
+            command: "npm",
+            args: ["exec", command],
+            source: "npm-exec",
+        };
+    }
+    // 3) fallback npx
+    return {
+        command: "npx",
+        args: [command],
+        source: "npx",
+    };
+}

package/dist/index.js

@@ -0,0 +1,393 @@
+#!/usr/bin/env node
+// src/index.ts
+import { MCPProcess } from "./runner.js";
+import { createRequest } from "./jsonrpc.js";
+import { getProfile, listProfiles } from "./profiles/index.js";
+import { planExecution } from "./execution/planner.js";
+function printUsage() {
+    console.error(`
+General MCP Client
+------------------
+
+Usage:
+  mcp run "<serverCommand>"
+  mcp run --profile web-dev
+  mcp run --profile <profile>
+  mcp list profiles
+  mcp list profiles --json
+  mcp describe profile web-dev
+  mcp describe profile <profile>
+
+Examples:
+  # Run against any MCP-compliant server
+  echo '{"jsonrpc":"2.0","id":1,"method":"providers.list"}' |
+    mcp run "node dist/server.js"
+
+  # Run with a built-in profile
+  echo '{"jsonrpc":"2.0","id":1,"method":"providers.list"}' |
+    mcp run --profile web-dev
+
+Environment Variables:
+  MCP_DEBUG=1    Enables verbose debug output (framing, handshake, events)
+  MCP_PROFILE_SERVER      Override profile server command (advanced)
+
+Debug example:
+  MCP_DEBUG=1 mcp run "node dist/server.js"
+
+Compatible with:
+  - Any MCP-compliant server
+  - The General MCP Server (reference implementation)
+
+More documentation:
+  https://dapo.run/mcp
+`);
+}
+async function readStdin() {
+    return new Promise((resolve) => {
+        let data = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on("end", () => resolve(data));
+    });
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+        printUsage();
+        return;
+    }
+    let profileId;
+    // very simple flag parsing (no dependency)
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--profile") {
+            if (!args[i + 1]) {
+                console.error("--profile requires a value");
+                process.exitCode = 1;
+                return;
+            }
+            profileId = args[i + 1];
+            args.splice(i, 2);
+            break;
+        }
+    }
+    let dryRun = false;
+    let jsonOutput = false;
+    let explain = false;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--dry-run") {
+            dryRun = true;
+            args.splice(i, 1);
+            i--;
+            continue;
+        }
+        if (args[i] === "--json") {
+            jsonOutput = true;
+            args.splice(i, 1);
+            i--;
+            continue;
+        }
+        if (args[i] === "--explain") {
+            explain = true;
+            args.splice(i, 1);
+            i--;
+            continue;
+        }
+    }
+    const explainLines = [];
+    // ---------------------------------------
+    // COMMAND: list profiles
+    // ---------------------------------------
+    if (args[0] === "list") {
+        if (args[1] === "profiles") {
+            const profiles = listProfiles();
+            if (jsonOutput) {
+                console.log(JSON.stringify(profiles, null, 2));
+                return;
+            }
+            if (profiles.length === 0) {
+                console.log("No profiles available.");
+                return;
+            }
+            console.log("Available profiles:\n");
+            for (const p of profiles) {
+                console.log(`  ${p.id.padEnd(8)} ${p.description}`);
+            }
+            return;
+        }
+        console.error(`Unknown list target: ${args[1] ?? ""}
+
+  Usage:
+    mcp list profiles
+    mcp list profiles --json
+  `);
+        process.exitCode = 1;
+        return;
+    }
+    // ---------------------------------------
+    // COMMAND: describe profile
+    // ---------------------------------------
+    if (args[0] === "describe") {
+        if (args[1] === "profile") {
+            const profileId = args[2];
+            if (!profileId) {
+                console.error(`Missing profile id.
+
+  Usage:
+    mcp describe profile <profile>
+  `);
+                process.exitCode = 1;
+                return;
+            }
+            const profile = getProfile(profileId);
+            if (!profile) {
+                console.error(`Unknown profile: ${profileId}`);
+                process.exitCode = 1;
+                return;
+            }
+            if (jsonOutput) {
+                console.log(JSON.stringify(profile, null, 2));
+                return;
+            }
+            console.log(`Profile: ${profile.id}\n`);
+            console.log("Description:");
+            console.log(`  ${profile.description}\n`);
+            console.log("Server:");
+            console.log(`  command: ${profile.server.command}`);
+            console.log(`  kind: ${profile.server.kind}`);
+            if (profile.server.autoInstall) {
+                console.log(`  auto-install: yes`);
+            }
+            if (profile.server.package) {
+                console.log(`  package: ${profile.server.package}`);
+            }
+            console.log("");
+            if (profile.ui?.enabled) {
+                console.log("UI:");
+                console.log("  enabled: yes");
+                if (profile.ui.hint) {
+                    console.log(`  hint: ${profile.ui.hint}`);
+                }
+                console.log("");
+            }
+            if (profile.plugins.length > 0) {
+                console.log("Plugins:");
+                for (const p of profile.plugins) {
+                    console.log(`  - ${p.name} (${p.entry})`);
+                }
+            }
+            else {
+                console.log("Plugins:");
+                console.log("  (none)");
+            }
+            if (profile.notes && profile.notes.length > 0) {
+                console.log("\nNotes:");
+                for (const note of profile.notes) {
+                    console.log(`  - ${note}`);
+                }
+            }
+            return;
+        }
+        console.error(`Unknown describe target: ${args[1] ?? ""}
+
+  Usage:
+    mcp describe profile <profile>
+  `);
+        process.exitCode = 1;
+        return;
+    }
+    if (args[0] !== "run") {
+        console.error(`Unknown command: ${args[0]}
+
+  Usage:
+    mcp run "node dist/server.js"
+    mcp run --profile web-dev
+    mcp run --profile <profile>
+    mcp list profiles
+
+  More documentation:
+    https://dapo.run/mcp
+  `);
+        process.exitCode = 1;
+        return;
+    }
+    let execution;
+    // 1) If a profile was provided, ALWAYS prefer profile execution.
+    if (profileId) {
+        const profile = getProfile(profileId);
+        explainLines.push(`Mode: profile (${profileId})`);
+        if (!profile) {
+            console.error(`Unknown profile: ${profileId}`);
+            process.exitCode = 1;
+            return;
+        }
+        execution = {
+            kind: "profile",
+            profile,
+            command: process.env.MCP_PROFILE_SERVER ?? profile.server.command,
+        };
+    }
+    else {
+        explainLines.push(`Mode: explicit`);
+        // 2) Otherwise try to treat the first non-flag token after "run" as explicit command.
+        const maybeCmd = args
+            .slice(1) // tokens after "run"
+            .find((t) => !t.startsWith("-"));
+        if (maybeCmd) {
+            execution = {
+                kind: "explicit",
+                command: maybeCmd,
+            };
+        }
+        else {
+            console.error(`Missing server command.
+
+    Examples:
+      mcp run "node dist/server.js"
+      mcp run --profile web-dev
+      mcp run --profile <profile>
+
+    More documentation:
+      https://dapo.run/mcp    
+    `);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    const hasProfileServerOverride = execution.kind === "profile" &&
+        process.env.MCP_PROFILE_SERVER !== undefined;
+    let command;
+    let cmdArgs;
+    let executionSource;
+    if (execution.kind === "profile" &&
+        execution.profile.server.kind === "builtin" &&
+        !hasProfileServerOverride) {
+        explainLines.push("Server kind: builtin");
+        explainLines.push("Execution planner: enabled");
+        const plan = await planExecution(execution.profile);
+        if (plan.source === "local-bin") {
+            explainLines.push("Local binary: found");
+        }
+        else {
+            explainLines.push("Local binary: not found");
+            explainLines.push("Auto-install: enabled");
+        }
+        explainLines.push(`Selected execution: ${plan.source} (${[plan.command, ...plan.args].join(" ")})`);
+        command = plan.command;
+        cmdArgs = plan.args;
+        executionSource = plan.source;
+        if (process.env.MCP_DEBUG) {
+            process.stderr.write(`[CLIENT] Using ${plan.source} execution\n`);
+        }
+    }
+    else {
+        explainLines.push("Execution planner: skipped");
+        explainLines.push(`Selected execution: explicit (${execution.command})`);
+        const cmd = execution.command.split(" ");
+        command = cmd[0];
+        cmdArgs = cmd.slice(1);
+        executionSource = "explicit";
+    }
+    if (dryRun) {
+        if (jsonOutput) {
+            console.log(JSON.stringify({
+                mode: execution.kind,
+                profile: execution.kind === "profile"
+                    ? execution.profile.id
+                    : undefined,
+                explain: explain ? explainLines : undefined,
+                plan: {
+                    command,
+                    args: cmdArgs,
+                    source: executionSource,
+                },
+            }, null, 2));
+        }
+        else {
+            if (explain && !jsonOutput) {
+                console.log("Execution explanation:");
+                for (const line of explainLines) {
+                    console.log(`- ${line}`);
+                }
+                console.log("");
+            }
+            console.log("Execution plan:");
+            console.log(`  resolver: ${executionSource}`);
+            console.log(`  command: ${[command, ...cmdArgs].join(" ")}`);
+        }
+        return;
+    }
+    const proc = new MCPProcess({
+        command,
+        args: cmdArgs
+    });
+    // optional debug logs
+    proc.on("stderr", (msg) => process.stderr.write(String(msg)));
+    if (process.env.MCP_DEBUG) {
+        proc.on("exit", ({ code, signal }) => {
+            process.stderr.write(`[CLIENT] Child process exit code=${code} signal=${String(signal)}\n`);
+        });
+        proc.on("error", (err) => {
+            process.stderr.write(`[CLIENT] Child process error: ${String(err)}\n`);
+        });
+    }
+    // staring server + handshake
+    await proc.start();
+    if (process.stdin.isTTY) {
+        if (process.env.MCP_DEBUG) {
+            process.stderr.write("[CLIENT] No stdin detected (TTY). Server started successfully.\n");
+        }
+        await proc.close();
+        return;
+    }
+    const stdinData = await readStdin();
+    if (!stdinData.trim()) {
+        if (process.env.MCP_DEBUG) {
+            process.stderr.write("[CLIENT] No stdin data, nothing to send.\n");
+        }
+        await proc.close();
+        return;
+    }
+    let payloads;
+    // 1) trying by whole JSON
+    try {
+        const parsed = JSON.parse(stdinData);
+        payloads = Array.isArray(parsed) ? parsed : [parsed];
+    }
+    catch {
+        // 2) trying by lines
+        const lines = stdinData
+            .split("\n")
+            .map((x) => x.trim())
+            .filter((x) => x.length > 0);
+        payloads = lines.map((line) => JSON.parse(line));
+    }
+    try {
+        for (const payload of payloads) {
+            const base = payload;
+            const isFullJsonRpc = base.id !== undefined &&
+                typeof base.jsonrpc === "string" &&
+                base.jsonrpc.length > 0;
+            const req = isFullJsonRpc
+                ? base // JSONRPCRequest match
+                : createRequest(base.method ?? "", base.params);
+            const response = await proc.send(req);
+            process.stdout.write(JSON.stringify(response, null, 2) + "\n");
+        }
+    }
+    finally {
+        await proc.close();
+    }
+}
+main()
+    .then(() => {
+    // success here
+    if (process.exitCode === undefined) {
+        process.exitCode = 0;
+    }
+})
+    .catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+});

package/dist/jsonrpc.js

@@ -0,0 +1,10 @@
+// src/jsonrpc.ts
+let idCounter = 1;
+export function createRequest(method, params) {
+    return {
+        jsonrpc: "2.0",
+        id: idCounter++,
+        method,
+        params
+    };
+}

package/dist/profiles/index.js

@@ -0,0 +1,10 @@
+import { webDevProfile } from "./web-dev.profile.js";
+const profiles = new Map([
+    [webDevProfile.id, webDevProfile],
+]);
+export function getProfile(id) {
+    return profiles.get(id);
+}
+export function listProfiles() {
+    return [...profiles.values()];
+}

package/dist/profiles/types.js

@@ -0,0 +1 @@
+export {};

package/dist/profiles/web-dev.profile.js

@@ -0,0 +1,24 @@
+export const webDevProfile = {
+    id: "web-dev",
+    description: "Zero-config web development MCP stack",
+    server: {
+        kind: "builtin",
+        command: "mcp-server-general",
+        autoInstall: true,
+        package: "mcp-server-general",
+    },
+    plugins: [
+        {
+            name: "web-tools",
+            entry: "@mcp/plugin-web-tools",
+        },
+    ],
+    ui: {
+        enabled: true,
+        hint: "Launches browser-based MCP UI for web development",
+    },
+    notes: [
+        "Automatically installs and runs the reference MCP server",
+        "Designed for zero-config onboarding",
+    ],
+};

package/dist/prompt.js

@@ -0,0 +1,32 @@
+import readline from "node:readline";
+import { createRequest } from "./jsonrpc.js";
+export function startPrompt(proc) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        historySize: 200
+    });
+    console.error("MCP Prompt Ready");
+    proc.on("rpc-response", (msg) => {
+        console.error("RESPONSE:", JSON.stringify(msg, null, 2));
+    });
+    rl.setPrompt("mcp> ");
+    rl.prompt();
+    rl.on("line", (line) => {
+        const trimmed = line.trim();
+        if (trimmed === "exit") {
+            rl.close();
+            proc.close();
+            return;
+        }
+        try {
+            const json = JSON.parse(trimmed);
+            const req = createRequest(json.method, json.params);
+            proc.send(req);
+        }
+        catch {
+            console.error("Invalid JSON input");
+        }
+        rl.prompt();
+    });
+}

package/dist/runner.js

@@ -0,0 +1,234 @@
+// src/runner.ts
+import { spawn } from "node:child_process";
+import { EventEmitter, once } from "node:events";
+/**
+ * MCPProcess
+ * - Spawns the provider server
+ * - Handles Content-Length framed JSON RPC
+ * - Waits for handshake before allowing requests
+ */
+export class MCPProcess extends EventEmitter {
+    proc = null;
+    opts;
+    startupTimeout;
+    shutdownTimeout;
+    closed = false;
+    pending = new Map();
+    handshakeEmitted = false;
+    constructor(opts) {
+        super();
+        this.opts = opts;
+        this.startupTimeout = opts.startupTimeoutMs ?? 4000;
+        this.shutdownTimeout = opts.shutdownTimeoutMs ?? 3000;
+    }
+    // ---------------------------------------------------------------------
+    // START
+    // ---------------------------------------------------------------------
+    async start() {
+        if (this.proc) {
+            throw new Error("Process already running.");
+        }
+        const { command, args = [], cwd, env } = this.opts;
+        this.proc = spawn(command, args, {
+            cwd,
+            env,
+            stdio: ["pipe", "pipe", "pipe"]
+        });
+        const spawned = this.proc;
+        this.closed = false;
+        this.attachRouter();
+        spawned.stderr.on("data", (chunk) => {
+            this.emit("stderr", chunk.toString());
+        });
+        spawned.on("exit", (code, signal) => {
+            this.closed = true;
+            this.emit("exit", { code, signal });
+            for (const [id, entry] of this.pending.entries()) {
+                clearTimeout(entry.timer);
+                entry.reject(new Error(`Process exited before response ${id}`));
+            }
+            this.pending.clear();
+        });
+        spawned.on("error", (err) => this.emit("error", err));
+        // waiting for handshake but handling the timeout
+        try {
+            await Promise.race([
+                this.waitForHandshake(),
+                this.timeout(this.startupTimeout, "Handshake timeout")
+            ]);
+        }
+        catch (err) {
+            if (process.env.MCP_DEBUG) {
+                this.emit("stderr", `[CLIENT] Handshake wait failed (continuing anyway): ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+        }
+        return { pid: spawned.pid };
+    }
+    // ---------------------------------------------------------------------
+    // SEND REQUEST
+    // ---------------------------------------------------------------------
+    send(req, timeoutMs = 5000) {
+        const proc = this.proc;
+        if (!proc || this.closed) {
+            return Promise.reject(new Error("Process not running."));
+        }
+        const id = req.id;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`Request ${id} timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.pending.set(id, { resolve, reject, timer });
+            try {
+                const body = JSON.stringify(req);
+                const header = `Content-Length: ${Buffer.byteLength(body, "utf8")}\r\n\r\n`;
+                proc.stdin.write(header + body, "utf8");
+            }
+            catch (err) {
+                clearTimeout(timer);
+                this.pending.delete(id);
+                reject(new Error(`Failed to write request ${id}: ${err.message}`));
+            }
+        });
+    }
+    // ---------------------------------------------------------------------
+    // CLOSE
+    // ---------------------------------------------------------------------
+    async close() {
+        if (this.closed || !this.proc)
+            return;
+        this.closed = true;
+        // Reject all pending
+        for (const [id, entry] of this.pending.entries()) {
+            clearTimeout(entry.timer);
+            entry.reject(new Error(`Process closed before response ${id}`));
+        }
+        this.pending.clear();
+        const p = this.proc;
+        try {
+            p.kill("SIGTERM");
+        }
+        catch {
+            // ignore
+        }
+        try {
+            await Promise.race([
+                once(p, "exit"),
+                this.timeout(this.shutdownTimeout, "Shutdown timeout")
+            ]);
+        }
+        catch {
+            try {
+                p.kill("SIGKILL");
+            }
+            catch {
+                // ignore
+            }
+            await once(p, "exit");
+        }
+    }
+    // ---------------------------------------------------------------------
+    // ROUTER – streaming JSON object scanner (ignores Content-Length)
+    // ---------------------------------------------------------------------
+    attachRouter() {
+        if (!this.proc)
+            return;
+        let buffer = "";
+        this.proc.stdout.on("data", (chunk) => {
+            buffer += chunk.toString("utf8");
+            parseLoop: while (true) {
+                // Find first '{' – skip logs, headers, etc.
+                const start = buffer.indexOf("{");
+                if (start === -1) {
+                    // no JSON start yet, wait for more data
+                    return;
+                }
+                let depth = 0;
+                let inString = false;
+                let escape = false;
+                let end = -1;
+                // Scan forward and find matching '}' that closes the outermost object
+                for (let i = start; i < buffer.length; i++) {
+                    const ch = buffer[i];
+                    if (escape) {
+                        // current char is escaped, just skip
+                        escape = false;
+                        continue;
+                    }
+                    if (ch === "\\") {
+                        if (inString) {
+                            escape = true;
+                        }
+                        continue;
+                    }
+                    if (ch === "\"") {
+                        inString = !inString;
+                        continue;
+                    }
+                    if (!inString) {
+                        if (ch === "{") {
+                            depth++;
+                        }
+                        else if (ch === "}") {
+                            depth--;
+                            if (depth === 0) {
+                                end = i;
+                                break;
+                            }
+                        }
+                    }
+                }
+                // If depth != 0, JSON is incomplete; wait for more data
+                if (depth !== 0 || end === -1) {
+                    return;
+                }
+                const jsonStr = buffer.slice(start, end + 1);
+                // Drop everything up to the end of this JSON object
+                buffer = buffer.slice(end + 1);
+                let msg;
+                try {
+                    msg = JSON.parse(jsonStr);
+                }
+                catch (err) {
+                    this.emit("stderr", `Invalid JSON from server (scanner): ${err.message}\n`);
+                    // Try to continue from the next possible JSON in the buffer
+                    continue parseLoop;
+                }
+                // First successfully parsed JSON -> treat as handshake
+                if (!this.handshakeEmitted) {
+                    this.handshakeEmitted = true;
+                    if (process.env.MCP_DEBUG) {
+                        this.emit("stderr", "[CLIENT] First JSON object parsed, treating as handshake\n");
+                    }
+                    this.emit("handshake", msg);
+                    // Do not treat this as a normal RPC response
+                    continue parseLoop;
+                }
+                // Normal RPC response from here on
+                this.emit("rpc-response", msg);
+                const maybeId = msg.id;
+                if (maybeId != null && this.pending.has(Number(maybeId))) {
+                    const entry = this.pending.get(Number(maybeId));
+                    clearTimeout(entry.timer);
+                    this.pending.delete(Number(maybeId));
+                    entry.resolve(msg);
+                }
+                // loop to see if another JSON object is already in buffer
+            }
+        });
+    }
+    // ---------------------------------------------------------------------
+    // WAIT FOR HANDSHAKE EVENT
+    // ---------------------------------------------------------------------
+    waitForHandshake() {
+        return new Promise((resolve) => this.once("handshake", () => resolve()));
+    }
+    timeout(ms, message) {
+        return new Promise((_resolve, reject) => {
+            const t = setTimeout(() => {
+                clearTimeout(t);
+                reject(new Error(message));
+            }, ms);
+        });
+    }
+}

package/package.json

@@ -1,8 +1,63 @@
 {
   "name": "mcp-client-general",
-  "version": "0.0.1",
-  "description": "Reserved package name for the General MCP Client.",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "General-purpose MCP Client and cross-platform CLI for the Model Context Protocol (MCP). Supports JSON-RPC over stdio with robust framing, handshake detection, and multi-request workflows.",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "dev": "tsx src/index.ts",
+    "test": "vitest --run",
+    "prepare": "npm run build",
+    "start": "node dist/index.js",
+    "link": "npm link",
+    "unlink": "npm unlink -g mcp-client-general || true",
+    "lint": "eslint . --ext .ts",
+    "lint:fix": "eslint . --ext .ts --fix",
+    "format": "prettier --check ."
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/daporun/mcp-client-general.git"
+  },
+  "keywords": [
+    "mcp client",
+    "mcp",
+    "model-context-protocol",
+    "jsonrpc",
+    "cli",
+    "client",
+    "stdio",
+    "agent",
+    "protocol",
+    "framework"
+  ],
+  "author": "DAPO / daporun <info@dapo.run>",
   "license": "MIT",
-  "main": "index.js",
-  "files": ["index.js"]
+  "bugs": {
+    "url": "https://github.com/daporun/mcp-client-general/issues"
+  },
+  "homepage": "https://github.com/daporun/mcp-client-general#readme",
+  "devDependencies": {
+    "@types/node": "^25.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.49.0",
+    "@typescript-eslint/parser": "^8.49.0",
+    "eslint": "^9.39.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "prettier": "^3.7.4",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.15"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ]
 }

package/index.js

@@ -1 +0,0 @@
-module.exports = {};