ilya 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AugmentedMagic
+
+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,166 @@
+# ilya
+
+See exactly what your MCP client sends and your server responds.
+
+A transparent stdio proxy that sits between any MCP client (Cursor, Claude Desktop, Claude Code) and any MCP server, logging every JSON-RPC message so you can actually see what's happening.
+
+```
+Cursor / Claude Desktop / Claude Code
+    │
+    │ ←────────── spawns (thinks this IS the MCP server)
+    ▼
+┌───────────┐
+│  ilya  │  ←─ logs every message
+└───────────┘
+    │
+    │ ←────────── spawns the real server
+    ▼
+┌────────────────────┐
+│  actual MCP server │
+└────────────────────┘
+```
+
+## Why
+
+When Cursor or Claude Desktop spawns an MCP server, it owns the child process. All stdio communication is invisible. There's no terminal, no logs, no way to see what the AI is asking or what the server responds with.
+
+`ilya` fixes that. Zero dependencies, zero config. Just prefix your command.
+
+<!-- TODO: terminal recording gif -->
+
+## Install
+
+```bash
+npm install -g ilya
+```
+
+Or use directly with npx:
+
+```bash
+npx ilya node ./my-server.js
+```
+
+## Usage
+
+Prefix your MCP server command with `ilya`:
+
+```bash
+ilya node ./my-server.js
+ilya python ./server.py
+ilya npx ts-node ./server.ts
+ilya ./my-binary --flag
+```
+
+Logs are written to `~/.ilya/logs/<server>-<pid>.log` by default. The log path is printed to stderr on startup.
+
+### Flags
+
+```
+--log, -l <path>    Write logs to a specific file
+--port, -p <port>   Start an HTTP server to stream logs in real time
+--help, -h          Show help
+--version, -v       Show version
+```
+
+### Integration with MCP clients
+
+In your MCP client config, just wrap the command with `npx ilya`:
+
+**Cursor / Claude Desktop (`mcp.json` or settings):**
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "npx",
+      "args": ["ilya", "node", "./my-server.js"]
+    }
+  }
+}
+```
+
+**Claude Code (`.mcp.json`):**
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "npx",
+      "args": ["ilya", "node", "./my-server.js"]
+    }
+  }
+}
+```
+
+Then tail the log file in a separate terminal:
+
+```bash
+tail -f ~/.ilya/logs/node-*.log
+```
+
+Or use `--port` to stream logs over HTTP:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "npx",
+      "args": ["ilya", "--port", "3456", "node", "./my-server.js"]
+    }
+  }
+}
+```
+
+```bash
+curl http://localhost:3456
+```
+
+## Example output
+
+```
+12:34:56.100 → CLIENT  notification  notifications/initialized
+12:34:56.200 → CLIENT  request  initialize  #1
+    {"protocolVersion":"2024-11-05","capabilities":{}}
+12:34:56.250 ← SERVER  response  initialize  #1  50ms
+    my-server v1.0.0  capabilities: tools, resources
+12:34:56.300 → CLIENT  request  tools/list  #2
+12:34:56.310 ← SERVER  response  tools/list  #2  10ms
+    (5 tools: get_overview, analyze_error, search_logs, get_config, restart)
+12:34:56.500 → CLIENT  request  tools/call  get_overview  #3
+    {
+      "query": "why is my app slow"
+    }
+12:34:57.100 ← SERVER  response  tools/call  #3  600ms
+    [text] Found 3 sessions with performance issues...
+```
+
+Errors are clearly highlighted:
+
+```
+12:34:57.456 ← SERVER  ERROR  (tools/call #3)  12ms
+    [-32601] Method not found
+```
+
+Server stderr is forwarded with a prefix:
+
+```
+[server stderr] Listening on stdio
+[server stderr] Connected to database
+```
+
+## How it works
+
+1. Your MCP client spawns `ilya` instead of the real server
+2. `ilya` spawns the real server as a child process
+3. Every stdin line from the client is logged and forwarded to the server
+4. Every stdout line from the server is logged and forwarded to the client
+5. Messages are never modified, delayed, or buffered — fully transparent
+6. Logs go to a file (and optionally stderr/HTTP) so they never interfere with the stdio protocol
+
+## Works with everything
+
+Any MCP server in any language. If it speaks JSON-RPC over stdio, `ilya` can log it.
+
+## License
+
+MIT

package/bin/mcp-tap.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import("../dist/cli.js");

package/dist/cli.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Run the CLI application.
+ */
+export declare const run: () => void;

package/dist/cli.js

@@ -0,0 +1,85 @@
+import { createColors, PLAIN } from "./colors.js";
+import { Logger } from "./logger.js";
+import { startHttpServer } from "./http-server.js";
+import { startProxy } from "./proxy.js";
+/**
+ * Print the usage information for the CLI.
+ */
+const printUsage = () => {
+    process.stderr.write(`serde — transparent MCP stdio proxy with logging
+
+Usage:
+  serde [options] <command> [args...]
+
+Options:
+  --log, -l <path>    Write logs to a specific file
+  --port, -p <port>   Start an HTTP server to stream logs
+  --help, -h          Show this help
+  --version, -v       Show version
+
+Examples:
+  serde node ./my-server.js
+  serde --log /tmp/tap.log python server.py
+  serde --port 3456 npx ts-node ./server.ts
+`);
+};
+/**
+ * Parse command-line arguments into a structured format.
+ * @param argv The command-line arguments to parse
+ */
+const parseArgs = (argv) => {
+    const args = argv.slice(2);
+    let logFilePath = null;
+    let httpPort = null;
+    let serverCmd = null;
+    let serverArgs = [];
+    for (let i = 0; i < args.length; i++) {
+        if ((args[i] === "--log" || args[i] === "-l") && i + 1 < args.length) {
+            logFilePath = args[++i];
+        }
+        else if ((args[i] === "--port" || args[i] === "-p") &&
+            i + 1 < args.length) {
+            httpPort = parseInt(args[++i], 10);
+        }
+        else if (args[i] === "--help" || args[i] === "-h") {
+            printUsage();
+            process.exit(0);
+        }
+        else if (args[i] === "--version" || args[i] === "-v") {
+            process.stderr.write("serde 0.1.0\n");
+            process.exit(0);
+        }
+        else {
+            serverCmd = args[i];
+            serverArgs = args.slice(i + 1);
+            break;
+        }
+    }
+    return { logFilePath, httpPort, serverCmd, serverArgs };
+};
+/**
+ * Run the CLI application.
+ */
+export const run = () => {
+    const { logFilePath, httpPort, serverCmd, serverArgs } = parseArgs(process.argv);
+    if (!serverCmd) {
+        printUsage();
+        process.exit(1);
+        return; // unreachable, helps TS narrow
+    }
+    const isTTY = !!process.stderr.isTTY;
+    const colors = createColors(isTTY);
+    const logger = new Logger({ logFilePath, isTTY, serverCmd });
+    const pendingRequests = new Map();
+    if (httpPort) {
+        startHttpServer(httpPort, logger, `${serverCmd} ${serverArgs.join(" ")}`);
+    }
+    startProxy({
+        serverCmd,
+        serverArgs,
+        logger,
+        colors,
+        ctx: { logger, colors, plainColors: PLAIN, pendingRequests },
+    });
+};
+run();

package/dist/colors.d.ts

@@ -0,0 +1,28 @@
+export interface Colors {
+    RESET: string;
+    BOLD: string;
+    DIM: string;
+    RED: string;
+    GREEN: string;
+    YELLOW: string;
+    BLUE: string;
+    MAGENTA: string;
+    CYAN: string;
+    WHITE: string;
+}
+/**
+ * Create a Colors object with ANSI escape codes if the terminal supports it.
+ *
+ * @param isTTY Whether the output is a TTY (supports colors)
+ * @returns A Colors object with appropriate escape codes or empty strings
+ */
+export declare const createColors: (isTTY: boolean) => Colors;
+export declare const PLAIN: Colors;
+/**
+ * Get the color for a given method name.
+ *
+ * @param method The method name
+ * @param colors The Colors object to use
+ * @returns The color string for the method
+ */
+export declare const methodColor: (method: string | undefined, colors: Colors) => string;

package/dist/colors.js

@@ -0,0 +1,68 @@
+/**
+ * Create a Colors object with ANSI escape codes if the terminal supports it.
+ *
+ * @param isTTY Whether the output is a TTY (supports colors)
+ * @returns A Colors object with appropriate escape codes or empty strings
+ */
+export const createColors = (isTTY) => {
+    if (isTTY) {
+        return {
+            RESET: "\x1b[0m",
+            BOLD: "\x1b[1m",
+            DIM: "\x1b[2m",
+            RED: "\x1b[31m",
+            GREEN: "\x1b[32m",
+            YELLOW: "\x1b[33m",
+            BLUE: "\x1b[34m",
+            MAGENTA: "\x1b[35m",
+            CYAN: "\x1b[36m",
+            WHITE: "\x1b[37m",
+        };
+    }
+    return {
+        RESET: "",
+        BOLD: "",
+        DIM: "",
+        RED: "",
+        GREEN: "",
+        YELLOW: "",
+        BLUE: "",
+        MAGENTA: "",
+        CYAN: "",
+        WHITE: "",
+    };
+};
+export const PLAIN = {
+    RESET: "",
+    BOLD: "",
+    DIM: "",
+    RED: "",
+    GREEN: "",
+    YELLOW: "",
+    BLUE: "",
+    MAGENTA: "",
+    CYAN: "",
+    WHITE: "",
+};
+/**
+ * Get the color for a given method name.
+ *
+ * @param method The method name
+ * @param colors The Colors object to use
+ * @returns The color string for the method
+ */
+export const methodColor = (method, colors) => {
+    if (!method)
+        return colors.WHITE;
+    if (method.startsWith("initialize"))
+        return colors.MAGENTA;
+    if (method.startsWith("tools/"))
+        return colors.GREEN;
+    if (method.startsWith("resources/"))
+        return colors.CYAN;
+    if (method.startsWith("prompts/"))
+        return colors.YELLOW;
+    if (method.startsWith("notifications/"))
+        return colors.BLUE;
+    return colors.WHITE;
+};

package/dist/colors.test.d.ts

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

package/dist/colors.test.js

@@ -0,0 +1,48 @@
+import { describe, it, expect } from "vitest";
+import { createColors, PLAIN, methodColor } from "./colors.js";
+describe("createColors", () => {
+    it("returns ANSI codes when isTTY is true", () => {
+        const c = createColors(true);
+        expect(c.RESET).toBe("\x1b[0m");
+        expect(c.RED).toBe("\x1b[31m");
+        expect(c.BOLD).toBe("\x1b[1m");
+    });
+    it("returns empty strings when isTTY is false", () => {
+        const c = createColors(false);
+        expect(c.RESET).toBe("");
+        expect(c.RED).toBe("");
+        expect(c.BOLD).toBe("");
+    });
+});
+describe("PLAIN", () => {
+    it("has all empty strings", () => {
+        for (const val of Object.values(PLAIN)) {
+            expect(val).toBe("");
+        }
+    });
+});
+describe("methodColor", () => {
+    const c = createColors(true);
+    it("returns MAGENTA for initialize", () => {
+        expect(methodColor("initialize", c)).toBe(c.MAGENTA);
+    });
+    it("returns GREEN for tools/*", () => {
+        expect(methodColor("tools/list", c)).toBe(c.GREEN);
+        expect(methodColor("tools/call", c)).toBe(c.GREEN);
+    });
+    it("returns CYAN for resources/*", () => {
+        expect(methodColor("resources/list", c)).toBe(c.CYAN);
+    });
+    it("returns YELLOW for prompts/*", () => {
+        expect(methodColor("prompts/list", c)).toBe(c.YELLOW);
+    });
+    it("returns BLUE for notifications/*", () => {
+        expect(methodColor("notifications/initialized", c)).toBe(c.BLUE);
+    });
+    it("returns WHITE for unknown methods", () => {
+        expect(methodColor("something/else", c)).toBe(c.WHITE);
+    });
+    it("returns WHITE for undefined", () => {
+        expect(methodColor(undefined, c)).toBe(c.WHITE);
+    });
+});

package/dist/formatter.d.ts

@@ -0,0 +1,18 @@
+import type { Colors } from "./colors.js";
+import type { Logger } from "./logger.js";
+import type { PendingRequest } from "./result-formatter.js";
+export interface MessageContext {
+    logger: Logger;
+    colors: Colors;
+    plainColors: Colors;
+    pendingRequests: Map<string | number, PendingRequest>;
+}
+/**
+ * Format a JSON-RPC message for logging.
+ *
+ * @param json The JSON-RPC message as a string
+ * @param direction The direction of the message, either "client" or "server"
+ * @param ctx The context for formatting, including logger, colors, and pending requests
+ * @returns void
+ */
+export declare const formatMessage: (json: string, direction: "client" | "server", ctx: MessageContext) => void;

package/dist/formatter.js

@@ -0,0 +1,95 @@
+import { methodColor } from "./colors.js";
+import { formatResult } from "./result-formatter.js";
+import { timestamp, truncate } from "./utils.js";
+/**
+ * Format a JSON-RPC message for logging.
+ *
+ * @param json The JSON-RPC message as a string
+ * @param direction The direction of the message, either "client" or "server"
+ * @param ctx The context for formatting, including logger, colors, and pending requests
+ * @returns void
+ */
+export const formatMessage = (json, direction, ctx) => {
+    const { logger, colors: c, plainColors: pc, pendingRequests } = ctx;
+    const isClient = direction === "client";
+    const arrow = isClient ? "→" : "←";
+    const label = isClient ? "CLIENT" : "SERVER";
+    const dirColor = isClient ? c.CYAN : c.GREEN;
+    const ts = timestamp();
+    try {
+        const msg = JSON.parse(json);
+        const id = msg.id;
+        const method = msg.method;
+        if (method && id === undefined) {
+            const mc = methodColor(method, c);
+            const colored = `${c.DIM}${ts}${c.RESET} ${dirColor}${arrow} ${label}${c.RESET}  ${c.BLUE}notification${c.RESET}  ${mc}${method}${c.RESET}`;
+            const plain = `${ts} ${arrow} ${label}  notification  ${method}`;
+            logger.write(colored, plain);
+            const params = msg.params;
+            if (params && Object.keys(params).length > 0) {
+                const paramStr = truncate(JSON.stringify(params), 200);
+                logger.write(`    ${c.DIM}${paramStr}${c.RESET}`, `    ${paramStr}`);
+            }
+            return;
+        }
+        if (method && id !== undefined) {
+            const mc = methodColor(method, c);
+            let toolName = null;
+            const params = msg.params;
+            if (method === "tools/call" && params?.name) {
+                toolName = params.name;
+            }
+            pendingRequests.set(id, { method, toolName, ts: Date.now() });
+            const extra = toolName ? `  ${c.BOLD}${toolName}${c.RESET}` : "";
+            const extraPlain = toolName ? `  ${toolName}` : "";
+            const colored = `${c.DIM}${ts}${c.RESET} ${dirColor}${arrow} ${label}${c.RESET}  ${c.WHITE}request${c.RESET}  ${mc}${method}${c.RESET}${extra}  ${c.DIM}#${id}${c.RESET}`;
+            const plain = `${ts} ${arrow} ${label}  request  ${method}${extraPlain}  #${id}`;
+            logger.write(colored, plain);
+            if (method === "tools/call" && params?.arguments) {
+                const argStr = JSON.stringify(params.arguments, null, 2);
+                const lines = argStr.split("\n");
+                for (const line of lines) {
+                    logger.write(`    ${c.DIM}${line}${c.RESET}`, `    ${line}`);
+                }
+            }
+            else if (params && Object.keys(params).length > 0) {
+                const paramStr = truncate(JSON.stringify(params), 200);
+                logger.write(`    ${c.DIM}${paramStr}${c.RESET}`, `    ${paramStr}`);
+            }
+            return;
+        }
+        if (id !== undefined && !method) {
+            const pending = pendingRequests.get(id);
+            const reqMethod = pending?.method || "unknown";
+            const mc = methodColor(reqMethod, c);
+            const elapsed = pending ? `${Date.now() - pending.ts}ms` : "";
+            const error = msg.error;
+            if (error) {
+                const code = error.code || "?";
+                const errMsg = error.message || "Unknown error";
+                const colored = `${c.DIM}${ts}${c.RESET} ${dirColor}${arrow} ${label}${c.RESET}  ${c.RED}${c.BOLD}ERROR${c.RESET}  ${mc}(${reqMethod} #${id})${c.RESET}  ${c.DIM}${elapsed}${c.RESET}`;
+                const plain = `${ts} ${arrow} ${label}  ERROR  (${reqMethod} #${id})  ${elapsed}`;
+                logger.write(colored, plain);
+                logger.write(`    ${c.RED}[${code}] ${errMsg}${c.RESET}`, `    [${code}] ${errMsg}`);
+                pendingRequests.delete(id);
+                return;
+            }
+            const colored = `${c.DIM}${ts}${c.RESET} ${dirColor}${arrow} ${label}${c.RESET}  ${c.WHITE}response${c.RESET}  ${mc}${reqMethod}${c.RESET}  ${c.DIM}#${id}  ${elapsed}${c.RESET}`;
+            const plain = `${ts} ${arrow} ${label}  response  ${reqMethod}  #${id}  ${elapsed}`;
+            logger.write(colored, plain);
+            formatResult(reqMethod, msg.result, pending, {
+                logger,
+                colors: c,
+                plainColors: pc,
+            });
+            pendingRequests.delete(id);
+            return;
+        }
+        const raw = truncate(json.trim(), 200);
+        logger.write(`${c.DIM}${ts}${c.RESET} ${dirColor}${arrow} ${label}${c.RESET}  ${c.DIM}${raw}${c.RESET}`, `${ts} ${arrow} ${label}  ${raw}`);
+    }
+    catch {
+        const raw = truncate(json.trim(), 200);
+        logger.write(`${c.DIM}${ts}${c.RESET} ${dirColor}${arrow} ${label}${c.RESET}  ${c.YELLOW}[raw]${c.RESET} ${raw}`, `${ts} ${arrow} ${label}  [raw] ${raw}`);
+    }
+};

package/dist/formatter.test.d.ts

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

package/dist/formatter.test.js

@@ -0,0 +1,100 @@
+import { describe, it, expect, vi } from "vitest";
+import { formatMessage } from "./formatter.js";
+import { PLAIN } from "./colors.js";
+function createMockCtx() {
+    const written = [];
+    const pendingRequests = new Map();
+    const logger = {
+        write: vi.fn((colored, plain) => {
+            written.push({ colored, plain });
+        }),
+    };
+    const ctx = {
+        logger: logger,
+        colors: PLAIN,
+        plainColors: PLAIN,
+        pendingRequests,
+    };
+    return { ctx, written, pendingRequests };
+}
+describe("formatMessage", () => {
+    it("formats a notification (method, no id)", () => {
+        const { ctx, written } = createMockCtx();
+        const json = JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" });
+        formatMessage(json, "client", ctx);
+        expect(written[0].plain).toContain("CLIENT");
+        expect(written[0].plain).toContain("notification");
+        expect(written[0].plain).toContain("notifications/initialized");
+    });
+    it("formats a request (method + id)", () => {
+        const { ctx, written, pendingRequests } = createMockCtx();
+        const json = JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list" });
+        formatMessage(json, "client", ctx);
+        expect(written[0].plain).toContain("request");
+        expect(written[0].plain).toContain("tools/list");
+        expect(written[0].plain).toContain("#1");
+        expect(pendingRequests.has(1)).toBe(true);
+    });
+    it("formats a tools/call request with tool name", () => {
+        const { ctx, written } = createMockCtx();
+        const json = JSON.stringify({
+            jsonrpc: "2.0", id: 5, method: "tools/call",
+            params: { name: "echo", arguments: { msg: "hi" } },
+        });
+        formatMessage(json, "client", ctx);
+        expect(written[0].plain).toContain("echo");
+        expect(written[0].plain).toContain("#5");
+        // arguments are printed on subsequent lines
+        expect(written.length).toBeGreaterThan(1);
+    });
+    it("formats a success response", () => {
+        const { ctx, written, pendingRequests } = createMockCtx();
+        pendingRequests.set(1, { method: "tools/list", toolName: null, ts: Date.now() - 50 });
+        const json = JSON.stringify({
+            jsonrpc: "2.0", id: 1,
+            result: { tools: [{ name: "echo" }] },
+        });
+        formatMessage(json, "server", ctx);
+        expect(written[0].plain).toContain("response");
+        expect(written[0].plain).toContain("tools/list");
+        expect(pendingRequests.has(1)).toBe(false);
+    });
+    it("formats an error response", () => {
+        const { ctx, written, pendingRequests } = createMockCtx();
+        pendingRequests.set(2, { method: "tools/call", toolName: "fail", ts: Date.now() });
+        const json = JSON.stringify({
+            jsonrpc: "2.0", id: 2,
+            error: { code: -32600, message: "Invalid request" },
+        });
+        formatMessage(json, "server", ctx);
+        expect(written[0].plain).toContain("ERROR");
+        expect(written[1].plain).toContain("-32600");
+        expect(written[1].plain).toContain("Invalid request");
+    });
+    it("handles invalid JSON gracefully", () => {
+        const { ctx, written } = createMockCtx();
+        formatMessage("not json at all", "client", ctx);
+        expect(written[0].plain).toContain("[raw]");
+        expect(written[0].plain).toContain("not json at all");
+    });
+    it("uses correct direction labels", () => {
+        const { ctx, written } = createMockCtx();
+        const json = JSON.stringify({ jsonrpc: "2.0", method: "notifications/test" });
+        formatMessage(json, "client", ctx);
+        expect(written[0].plain).toContain("→");
+        expect(written[0].plain).toContain("CLIENT");
+        formatMessage(json, "server", ctx);
+        expect(written[1].plain).toContain("←");
+        expect(written[1].plain).toContain("SERVER");
+    });
+    it("shows notification params when present", () => {
+        const { ctx, written } = createMockCtx();
+        const json = JSON.stringify({
+            jsonrpc: "2.0", method: "notifications/progress",
+            params: { token: "abc", progress: 50 },
+        });
+        formatMessage(json, "server", ctx);
+        expect(written.length).toBe(2);
+        expect(written[1].plain).toContain("token");
+    });
+});

package/dist/http-server.d.ts

@@ -0,0 +1,9 @@
+import type { Logger } from "./logger.js";
+/**
+ * Start an HTTP server to stream logs.
+ *
+ * @param port The port to listen on
+ * @param logger The logger to stream logs from
+ * @param serverDescription A description of the server being logged
+ */
+export declare const startHttpServer: (port: number, logger: Logger, serverDescription: string) => void;

package/dist/http-server.js

@@ -0,0 +1,26 @@
+import { createServer, } from "node:http";
+/**
+ * Start an HTTP server to stream logs.
+ *
+ * @param port The port to listen on
+ * @param logger The logger to stream logs from
+ * @param serverDescription A description of the server being logged
+ */
+export const startHttpServer = (port, logger, serverDescription) => {
+    const server = createServer((req, res) => {
+        res.writeHead(200, {
+            "Content-Type": "text/plain; charset=utf-8",
+            "Cache-Control": "no-cache",
+            Connection: "keep-alive",
+        });
+        res.write(`[serde] streaming logs for: ${serverDescription}\n\n`);
+        logger.addHttpClient(res);
+        req.on("close", () => logger.removeHttpClient(res));
+    });
+    server.listen(port, "127.0.0.1", () => {
+        process.stderr.write(`[serde] log server listening on http://127.0.0.1:${port}\n`);
+    });
+    server.on("error", (err) => {
+        process.stderr.write(`[serde] failed to start HTTP server: ${err.message}\n`);
+    });
+};

package/dist/line-buffer.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Create a line buffer that calls a callback for each complete line.
+ *
+ * @param onLine The callback to call for each complete line
+ * @returns A function that can be called with chunks of text
+ */
+export declare const createLineBuffer: (onLine: (line: string) => void) => ((chunk: string) => void);

package/dist/line-buffer.js

@@ -0,0 +1,20 @@
+/**
+ * Create a line buffer that calls a callback for each complete line.
+ *
+ * @param onLine The callback to call for each complete line
+ * @returns A function that can be called with chunks of text
+ */
+export const createLineBuffer = (onLine) => {
+    let buffer = "";
+    return (chunk) => {
+        buffer += chunk;
+        let newlineIdx;
+        while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
+            const line = buffer.slice(0, newlineIdx);
+            buffer = buffer.slice(newlineIdx + 1);
+            if (line.trim().length > 0) {
+                onLine(line);
+            }
+        }
+    };
+};

package/dist/line-buffer.test.d.ts

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

package/dist/line-buffer.test.js

@@ -0,0 +1,44 @@
+import { describe, it, expect } from "vitest";
+import { createLineBuffer } from "./line-buffer.js";
+describe("createLineBuffer", () => {
+    it("emits complete lines", () => {
+        const lines = [];
+        const feed = createLineBuffer((line) => lines.push(line));
+        feed("hello\nworld\n");
+        expect(lines).toEqual(["hello", "world"]);
+    });
+    it("buffers partial lines until newline arrives", () => {
+        const lines = [];
+        const feed = createLineBuffer((line) => lines.push(line));
+        feed("hel");
+        expect(lines).toEqual([]);
+        feed("lo\n");
+        expect(lines).toEqual(["hello"]);
+    });
+    it("handles multiple chunks assembling one line", () => {
+        const lines = [];
+        const feed = createLineBuffer((line) => lines.push(line));
+        feed("a");
+        feed("b");
+        feed("c\n");
+        expect(lines).toEqual(["abc"]);
+    });
+    it("skips empty lines", () => {
+        const lines = [];
+        const feed = createLineBuffer((line) => lines.push(line));
+        feed("one\n\n\ntwo\n");
+        expect(lines).toEqual(["one", "two"]);
+    });
+    it("skips whitespace-only lines", () => {
+        const lines = [];
+        const feed = createLineBuffer((line) => lines.push(line));
+        feed("one\n   \ntwo\n");
+        expect(lines).toEqual(["one", "two"]);
+    });
+    it("handles multiple messages in one chunk", () => {
+        const lines = [];
+        const feed = createLineBuffer((line) => lines.push(line));
+        feed('{"a":1}\n{"b":2}\n{"c":3}\n');
+        expect(lines).toEqual(['{"a":1}', '{"b":2}', '{"c":3}']);
+    });
+});

package/dist/logger.d.ts

@@ -0,0 +1,16 @@
+import type { ServerResponse } from "node:http";
+export declare class Logger {
+    private fileStream;
+    private httpClients;
+    private isTTY;
+    readonly logFilePath: string;
+    constructor(opts: {
+        logFilePath?: string | null;
+        isTTY: boolean;
+        serverCmd: string;
+    });
+    write(coloredLine: string, plainLine: string): void;
+    addHttpClient(res: ServerResponse): void;
+    removeHttpClient(res: ServerResponse): void;
+    close(): void;
+}

package/dist/logger.js

@@ -0,0 +1,51 @@
+import { createWriteStream, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, basename } from "node:path";
+export class Logger {
+    fileStream;
+    httpClients = new Set();
+    isTTY;
+    logFilePath;
+    constructor(opts) {
+        this.isTTY = opts.isTTY;
+        if (opts.logFilePath) {
+            this.logFilePath = opts.logFilePath;
+        }
+        else {
+            const serverName = basename(opts.serverCmd).replace(/\.[^.]+$/, "");
+            const logDir = join(homedir(), ".serde", "logs");
+            try {
+                mkdirSync(logDir, { recursive: true });
+            }
+            catch {
+                /* ignore */
+            }
+            this.logFilePath = join(logDir, `${serverName}-${process.pid}.log`);
+        }
+        this.fileStream = createWriteStream(this.logFilePath, { flags: "a" });
+        process.stderr.write(`[serde] logging to ${this.logFilePath}\n`);
+    }
+    write(coloredLine, plainLine) {
+        if (this.isTTY) {
+            process.stderr.write(coloredLine + "\n");
+        }
+        this.fileStream.write(plainLine + "\n");
+        for (const res of this.httpClients) {
+            try {
+                res.write(plainLine + "\n");
+            }
+            catch {
+                this.httpClients.delete(res);
+            }
+        }
+    }
+    addHttpClient(res) {
+        this.httpClients.add(res);
+    }
+    removeHttpClient(res) {
+        this.httpClients.delete(res);
+    }
+    close() {
+        this.fileStream.end();
+    }
+}

package/dist/proxy.d.ts

@@ -0,0 +1,16 @@
+import type { Colors } from "./colors.js";
+import { type MessageContext } from "./formatter.js";
+import type { Logger } from "./logger.js";
+export interface ProxyOptions {
+    serverCmd: string;
+    serverArgs: string[];
+    logger: Logger;
+    colors: Colors;
+    ctx: MessageContext;
+}
+/**
+ * Start a proxy between the client and the server, logging all messages.
+ *
+ * @param opts The options for the proxy
+ */
+export declare const startProxy: (opts: ProxyOptions) => void;

package/dist/proxy.js

@@ -0,0 +1,100 @@
+import { spawn } from "node:child_process";
+import { createLineBuffer } from "./line-buffer.js";
+import { formatMessage } from "./formatter.js";
+/**
+ * Start a proxy between the client and the server, logging all messages.
+ *
+ * @param opts The options for the proxy
+ */
+export const startProxy = (opts) => {
+    const { serverCmd, serverArgs, logger, colors: c, ctx } = opts;
+    const child = spawn(serverCmd, serverArgs, {
+        stdio: ["pipe", "pipe", "pipe"],
+        env: process.env,
+    });
+    child.on("error", (err) => {
+        const msg = `[serde] failed to start server: ${err.message}`;
+        logger.write(`${c.RED}${msg}${c.RESET}`, msg);
+        process.exit(1);
+    });
+    const clientLineBuffer = createLineBuffer((line) => {
+        formatMessage(line, "client", ctx);
+        child.stdin.write(line + "\n");
+    });
+    process.stdin.on("data", (chunk) => {
+        clientLineBuffer(chunk.toString("utf-8"));
+    });
+    process.stdin.on("end", () => {
+        try {
+            child.stdin.end();
+        }
+        catch {
+            // no-op
+        }
+    });
+    const serverLineBuffer = createLineBuffer((line) => {
+        formatMessage(line, "server", ctx);
+        process.stdout.write(line + "\n");
+    });
+    child.stdout.on("data", (chunk) => {
+        serverLineBuffer(chunk.toString("utf-8"));
+    });
+    child.stderr.on("data", (chunk) => {
+        const lines = chunk.toString("utf-8").split("\n");
+        for (const line of lines) {
+            if (line.trim().length === 0)
+                continue;
+            const colored = `${c.DIM}[server stderr]${c.RESET} ${line}`;
+            const plain = `[server stderr] ${line}`;
+            logger.write(colored, plain);
+        }
+    });
+    child.on("exit", (code, signal) => {
+        const exitCode = code ?? (signal ? 1 : 0);
+        const msg = signal
+            ? `[serde] server exited with signal ${signal}`
+            : `[serde] server exited with code ${exitCode}`;
+        logger.write(`${c.DIM}${msg}${c.RESET}`, msg);
+        logger.close();
+        process.exit(exitCode);
+    });
+    /**
+     * Shutdown the proxy and the child server process.
+     *
+     * @param sig The signal that triggered the shutdown
+     */
+    const shutdown = (sig) => {
+        const msg = `[serde] received ${sig}, shutting down`;
+        logger.write(`${c.DIM}${msg}${c.RESET}`, msg);
+        try {
+            child.kill(sig);
+        }
+        catch {
+            // no-op
+        }
+        setTimeout(() => {
+            try {
+                child.kill("SIGKILL");
+            }
+            catch {
+                // no-op
+            }
+            logger.close();
+            process.exit(1);
+        }, 3000);
+    };
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+    process.on("SIGINT", () => shutdown("SIGINT"));
+    process.stdout.on("error", (err) => {
+        if (err.code === "EPIPE") {
+            const msg = "[serde] client disconnected (EPIPE)";
+            logger.write(`${c.DIM}${msg}${c.RESET}`, msg);
+            try {
+                child.kill("SIGTERM");
+            }
+            catch {
+                // no-op
+            }
+        }
+    });
+};

package/dist/result-formatter.d.ts

@@ -0,0 +1,22 @@
+import type { Colors } from "./colors.js";
+import type { Logger } from "./logger.js";
+export interface PendingRequest {
+    method: string;
+    toolName: string | null;
+    ts: number;
+}
+export interface FormatterContext {
+    logger: Logger;
+    colors: Colors;
+    plainColors: Colors;
+}
+/**
+ * Format the result of a request and log it.
+ *
+ * @param method The method of the request
+ * @param result The result of the request
+ * @param _pending The pending request associated with this result
+ * @param ctx The formatter context containing the logger and colors
+ * @returns void
+ */
+export declare const formatResult: (method: string, result: Record<string, unknown> | undefined, _pending: PendingRequest | undefined, ctx: FormatterContext) => void;

package/dist/result-formatter.js

@@ -0,0 +1,90 @@
+import { truncate } from "./utils.js";
+/**
+ * Format the result of a request and log it.
+ *
+ * @param method The method of the request
+ * @param result The result of the request
+ * @param _pending The pending request associated with this result
+ * @param ctx The formatter context containing the logger and colors
+ * @returns void
+ */
+export const formatResult = (method, result, _pending, ctx) => {
+    if (!result)
+        return;
+    const { logger, colors: c, plainColors: pc } = ctx;
+    if (method === "tools/list" && Array.isArray(result.tools)) {
+        const tools = result.tools;
+        const names = tools.map((t) => t.name);
+        const summary = names.length <= 8
+            ? names.join(", ")
+            : names.slice(0, 6).join(", ") + `, ... +${names.length - 6} more`;
+        logger.write(`    ${c.GREEN}(${tools.length} tools: ${summary})${c.RESET}`, `    (${tools.length} tools: ${summary})`);
+        return;
+    }
+    if (method === "resources/list" && Array.isArray(result.resources)) {
+        const resources = result.resources;
+        const names = resources.map((r) => r.name || r.uri);
+        const summary = names.length <= 8
+            ? names.join(", ")
+            : names.slice(0, 6).join(", ") + `, ... +${names.length - 6} more`;
+        logger.write(`    ${c.CYAN}(${resources.length} resources: ${summary})${c.RESET}`, `    (${resources.length} resources: ${summary})`);
+        return;
+    }
+    // prompts/list — summarize
+    if (method === "prompts/list" && Array.isArray(result.prompts)) {
+        const prompts = result.prompts;
+        const names = prompts.map((p) => p.name);
+        const summary = names.length <= 8
+            ? names.join(", ")
+            : names.slice(0, 6).join(", ") + `, ... +${names.length - 6} more`;
+        logger.write(`    ${c.YELLOW}(${prompts.length} prompts: ${summary})${c.RESET}`, `    (${prompts.length} prompts: ${summary})`);
+        return;
+    }
+    // tools/call — show content blocks
+    if (method === "tools/call" && Array.isArray(result.content)) {
+        const content = result.content;
+        for (const block of content) {
+            if (block.type === "text") {
+                const lines = block.text.split("\n");
+                for (const line of lines) {
+                    logger.write(`    ${c.DIM}[text]${c.RESET} ${line}`, `    [text] ${line}`);
+                }
+            }
+            else if (block.type === "image") {
+                const data = block.data;
+                const size = data
+                    ? `${Math.round((data.length * 3) / 4 / 1024)}KB`
+                    : "?";
+                logger.write(`    ${c.DIM}[image ${block.mimeType || "?"}]${c.RESET} ${size}`, `    [image ${block.mimeType || "?"}] ${size}`);
+            }
+            else if (block.type === "resource") {
+                const resource = block.resource;
+                const uri = resource?.uri || "?";
+                logger.write(`    ${c.DIM}[resource]${c.RESET} ${truncate(uri)}`, `    [resource] ${truncate(uri)}`);
+            }
+            else {
+                const raw = truncate(JSON.stringify(block), 200);
+                logger.write(`    ${c.DIM}[${block.type || "?"}]${c.RESET} ${raw}`, `    [${block.type || "?"}] ${raw}`);
+            }
+        }
+        if (result.isError) {
+            logger.write(`    ${c.RED}(isError: true)${c.RESET}`, `    (isError: true)`);
+        }
+        return;
+    }
+    // initialize — show capabilities
+    if (method === "initialize" && result.capabilities) {
+        const caps = Object.keys(result.capabilities).join(", ");
+        const serverInfo = result.serverInfo;
+        const name = serverInfo?.name || "?";
+        const version = serverInfo?.version || "?";
+        logger.write(`    ${c.MAGENTA}${name} v${version}${c.RESET}  capabilities: ${caps}`, `    ${name} v${version}  capabilities: ${caps}`);
+        return;
+    }
+    // Generic: show truncated JSON
+    const raw = JSON.stringify(result);
+    if (raw.length > 2) {
+        const display = truncate(raw, 300);
+        logger.write(`    ${c.DIM}${display}${c.RESET}`, `    ${display}`);
+    }
+};

package/dist/result-formatter.test.d.ts

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

package/dist/result-formatter.test.js

@@ -0,0 +1,99 @@
+import { describe, it, expect, vi } from "vitest";
+import { formatResult } from "./result-formatter.js";
+import { PLAIN } from "./colors.js";
+function createMockCtx() {
+    const written = [];
+    const logger = {
+        write: vi.fn((colored, plain) => {
+            written.push({ colored, plain });
+        }),
+    };
+    return {
+        ctx: { logger, colors: PLAIN, plainColors: PLAIN },
+        written,
+        logger,
+    };
+}
+describe("formatResult", () => {
+    it("does nothing for undefined result", () => {
+        const { logger } = createMockCtx();
+        formatResult("tools/list", undefined, undefined, {
+            logger,
+            colors: PLAIN,
+            plainColors: PLAIN,
+        });
+        expect(logger.write).not.toHaveBeenCalled();
+    });
+    it("summarizes tools/list", () => {
+        const { ctx, written } = createMockCtx();
+        formatResult("tools/list", {
+            tools: [{ name: "echo" }, { name: "add" }],
+        }, undefined, ctx);
+        expect(written.length).toBe(1);
+        expect(written[0].plain).toContain("2 tools");
+        expect(written[0].plain).toContain("echo, add");
+    });
+    it("truncates long tools/list", () => {
+        const { ctx, written } = createMockCtx();
+        const tools = Array.from({ length: 20 }, (_, i) => ({ name: `tool${i}` }));
+        formatResult("tools/list", { tools }, undefined, ctx);
+        expect(written[0].plain).toContain("20 tools");
+        expect(written[0].plain).toContain("+14 more");
+    });
+    it("summarizes resources/list", () => {
+        const { ctx, written } = createMockCtx();
+        formatResult("resources/list", {
+            resources: [{ name: "readme", uri: "file:///readme" }],
+        }, undefined, ctx);
+        expect(written[0].plain).toContain("1 resources");
+        expect(written[0].plain).toContain("readme");
+    });
+    it("summarizes prompts/list", () => {
+        const { ctx, written } = createMockCtx();
+        formatResult("prompts/list", {
+            prompts: [{ name: "greeting" }],
+        }, undefined, ctx);
+        expect(written[0].plain).toContain("1 prompts");
+        expect(written[0].plain).toContain("greeting");
+    });
+    it("formats tools/call text content", () => {
+        const { ctx, written } = createMockCtx();
+        formatResult("tools/call", {
+            content: [{ type: "text", text: "hello\nworld" }],
+        }, undefined, ctx);
+        expect(written.length).toBe(2);
+        expect(written[0].plain).toContain("[text] hello");
+        expect(written[1].plain).toContain("[text] world");
+    });
+    it("formats tools/call image content", () => {
+        const { ctx, written } = createMockCtx();
+        formatResult("tools/call", {
+            content: [{ type: "image", mimeType: "image/png", data: "a".repeat(4096) }],
+        }, undefined, ctx);
+        expect(written[0].plain).toContain("[image image/png]");
+        expect(written[0].plain).toContain("KB");
+    });
+    it("shows isError flag", () => {
+        const { ctx, written } = createMockCtx();
+        formatResult("tools/call", {
+            content: [{ type: "text", text: "fail" }],
+            isError: true,
+        }, undefined, ctx);
+        const last = written[written.length - 1];
+        expect(last.plain).toContain("isError: true");
+    });
+    it("formats initialize capabilities", () => {
+        const { ctx, written } = createMockCtx();
+        formatResult("initialize", {
+            capabilities: { tools: {}, resources: {} },
+            serverInfo: { name: "test-server", version: "1.0" },
+        }, undefined, ctx);
+        expect(written[0].plain).toContain("test-server v1.0");
+        expect(written[0].plain).toContain("tools, resources");
+    });
+    it("shows truncated JSON for unknown methods", () => {
+        const { ctx, written } = createMockCtx();
+        formatResult("unknown/method", { foo: "bar" }, undefined, ctx);
+        expect(written[0].plain).toContain("foo");
+    });
+});

package/dist/utils.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Get the current timestamp in the format HH:MM:SS.mmm
+ * @returns The current timestamp in the format HH:MM:SS.mmm
+ */
+export declare const timestamp: () => string;
+/**
+ * Truncate a string to a maximum length, adding "..." if truncated.
+ * @param str The string to truncate
+ * @param max The maximum length of the string
+ * @returns The truncated string
+ */
+export declare const truncate: (str: string, max?: number) => string;

package/dist/utils.js

@@ -0,0 +1,23 @@
+/**
+ * Get the current timestamp in the format HH:MM:SS.mmm
+ * @returns The current timestamp in the format HH:MM:SS.mmm
+ */
+export const timestamp = () => {
+    const d = new Date();
+    const h = String(d.getHours()).padStart(2, "0");
+    const m = String(d.getMinutes()).padStart(2, "0");
+    const s = String(d.getSeconds()).padStart(2, "0");
+    const ms = String(d.getMilliseconds()).padStart(3, "0");
+    return `${h}:${m}:${s}.${ms}`;
+};
+/**
+ * Truncate a string to a maximum length, adding "..." if truncated.
+ * @param str The string to truncate
+ * @param max The maximum length of the string
+ * @returns The truncated string
+ */
+export const truncate = (str, max = 200) => {
+    if (str.length <= max)
+        return str;
+    return str.slice(0, max - 3) + "...";
+};

package/dist/utils.test.d.ts

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

package/dist/utils.test.js

@@ -0,0 +1,28 @@
+import { describe, it, expect } from "vitest";
+import { timestamp, truncate } from "./utils.js";
+describe("timestamp", () => {
+    it("returns HH:MM:SS.mmm format", () => {
+        const ts = timestamp();
+        expect(ts).toMatch(/^\d{2}:\d{2}:\d{2}\.\d{3}$/);
+    });
+});
+describe("truncate", () => {
+    it("returns short strings unchanged", () => {
+        expect(truncate("hello", 200)).toBe("hello");
+    });
+    it("truncates long strings with ellipsis", () => {
+        const long = "a".repeat(300);
+        const result = truncate(long, 200);
+        expect(result.length).toBe(200);
+        expect(result.endsWith("...")).toBe(true);
+    });
+    it("returns string at exact max length unchanged", () => {
+        const exact = "b".repeat(200);
+        expect(truncate(exact, 200)).toBe(exact);
+    });
+    it("uses default max of 200", () => {
+        const long = "c".repeat(250);
+        const result = truncate(long);
+        expect(result.length).toBe(200);
+    });
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "ilya",
+  "version": "1.0.0",
+  "description": "See exactly what your MCP client sends and your server responds. Zero config, zero dependencies.",
+  "type": "module",
+  "bin": {
+    "ilya": "./bin/ilya.js"
+  },
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "npx vitest run",
+    "test:coverage": "npx vitest run --coverage",
+    "test:watch": "npx vitest"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "@vitest/coverage-v8": "4.0.18",
+    "typescript": "^5"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "debug",
+    "inspector",
+    "devtools",
+    "stdio",
+    "proxy",
+    "logging"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AugmentedMagic/ilya"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}