mcp-telemetry-sdk 0.1.0

package/README.md

@@ -0,0 +1,37 @@
+# mcp-telemetry-sdk
+
+Zero-dependency instrumentation for MCP servers. Emit `job`/`step`/`log`/`cost` telemetry from your tool handlers; any `mcp-telemetry-server` (or your own collector) picks it up over a local socket.
+
+Full documentation, architecture, and the companion server: [github.com/arnavranjan005/mcp-telemetry](https://github.com/arnavranjan005/mcp-telemetry)
+
+## Install
+
+```bash
+npm install mcp-telemetry-sdk
+```
+
+## Usage
+
+```js
+import { MCPTelemetry } from 'mcp-telemetry-sdk';
+
+const telemetry = new MCPTelemetry(); // zero config
+
+server.tool('deploy', schema, async (args) => {
+  const job = telemetry.createJob({ task: 'deploy' });
+  job.start();
+  job.stepStart('build');
+  await runBuild();
+  job.stepDone('build');
+  await job.done(0);
+  return { content: [{ type: 'text', text: 'done' }] };
+});
+```
+
+If nothing is listening on the socket, every call is a fast no-op — this library never throws and never blocks your tool call.
+
+See the [main README](https://github.com/arnavranjan005/mcp-telemetry#api-reference) for the full API reference.
+
+## License
+
+MIT

package/dist/connection.d.ts

@@ -0,0 +1,15 @@
+export declare class QueuedConnection {
+    private readonly socketPath;
+    private socket;
+    private connecting;
+    private closed;
+    private nextAttemptAt;
+    private readonly queue;
+    constructor(socketPath: string);
+    send(line: string): void;
+    private flush;
+    private connect;
+    close(): void;
+    drain(maxWaitMs?: number): Promise<void>;
+}
+//# sourceMappingURL=connection.d.ts.map

package/dist/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAaA,qBAAa,gBAAgB;IAOf,OAAO,CAAC,QAAQ,CAAC,UAAU;IANvC,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;gBAET,UAAU,EAAE,MAAM;IAE/C,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAOxB,OAAO,CAAC,KAAK;IAab,OAAO,CAAC,OAAO;IA2Bf,KAAK,IAAI,IAAI;IAeb,KAAK,CAAC,SAAS,SAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CAmBvC"}

package/dist/connection.js

@@ -0,0 +1,108 @@
+import net from 'net';
+const CONNECT_TIMEOUT_MS = 300;
+const RETRY_DELAY_MS = 250;
+const MAX_QUEUE = 1000;
+// One persistent socket per socketPath, shared by every JobHandle created
+// from the same MCPTelemetry instance — replaces the old connect-per-event
+// emitter. Writes are queued and flushed in order over a single connection;
+// if the collector isn't reachable yet (or drops), lines stay queued and are
+// flushed on the next successful connect, up to MAX_QUEUE entries (oldest
+// dropped beyond that — this is still best-effort telemetry, never a
+// blocking or throwing guarantee for the caller).
+export class QueuedConnection {
+    socketPath;
+    socket = null;
+    connecting = false;
+    closed = false;
+    nextAttemptAt = 0;
+    queue = [];
+    constructor(socketPath) {
+        this.socketPath = socketPath;
+    }
+    send(line) {
+        if (this.closed)
+            return;
+        this.queue.push(line);
+        if (this.queue.length > MAX_QUEUE)
+            this.queue.shift();
+        this.flush();
+    }
+    flush() {
+        if (this.closed || !this.queue.length)
+            return;
+        if (this.socket && this.socket.writable) {
+            const batch = this.queue.splice(0, this.queue.length);
+            for (const item of batch)
+                this.socket.write(item);
+            return;
+        }
+        if (this.connecting || Date.now() < this.nextAttemptAt)
+            return;
+        this.connect();
+    }
+    connect() {
+        this.connecting = true;
+        const socket = net.createConnection({ path: this.socketPath });
+        socket.unref(); // never keep the host process alive just for this
+        const timer = setTimeout(() => socket.destroy(), CONNECT_TIMEOUT_MS);
+        socket.on('connect', () => {
+            clearTimeout(timer);
+            this.connecting = false;
+            this.socket = socket;
+            this.flush();
+        });
+        socket.on('error', () => {
+            clearTimeout(timer);
+            this.connecting = false;
+            this.nextAttemptAt = Date.now() + RETRY_DELAY_MS;
+            if (this.socket === socket)
+                this.socket = null;
+        });
+        socket.on('close', () => {
+            this.connecting = false;
+            if (this.socket === socket)
+                this.socket = null;
+        });
+    }
+    close() {
+        this.closed = true;
+        this.queue.length = 0;
+        this.socket?.end();
+        this.socket = null;
+    }
+    // Actively retry delivery of whatever is currently queued instead of
+    // passively waiting for another send() to trigger the next attempt — for
+    // the last event in a job's lifecycle (job_done), nothing else may ever
+    // call send() again, so the normal retry-on-next-send behavior would mean
+    // that event silently never gets a second chance if the host process exits
+    // right after. Unlike connect()'s socket, this deliberately uses a
+    // ref'd setTimeout so it keeps the process alive for up to maxWaitMs —
+    // a bounded delay to give the last event a real chance, not indefinite.
+    drain(maxWaitMs = 1500) {
+        if (this.closed || !this.queue.length)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const deadline = Date.now() + maxWaitMs;
+            const attempt = () => {
+                if (this.closed || !this.queue.length) {
+                    resolve();
+                    return;
+                }
+                if (this.socket && this.socket.writable) {
+                    this.flush();
+                    resolve();
+                    return;
+                }
+                if (Date.now() >= deadline) {
+                    resolve();
+                    return;
+                }
+                if (!this.connecting)
+                    this.connect();
+                setTimeout(attempt, RETRY_DELAY_MS);
+            };
+            attempt();
+        });
+    }
+}
+//# sourceMappingURL=connection.js.map

package/dist/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import { JobHandle } from './job.js';
+export interface CreateJobOptions {
+    id?: string;
+    task: string;
+}
+export interface MCPTelemetryOptions {
+    socketPath?: string;
+}
+export declare class MCPTelemetry {
+    private readonly connection;
+    constructor(opts?: MCPTelemetryOptions);
+    createJob(opts: CreateJobOptions): JobHandle;
+    disconnect(): void;
+}
+export { JobHandle } from './job.js';
+export { MonitorEvent, TaskStatus, getSocketPath } from './protocol.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAIrC,MAAM,WAAW,gBAAgB;IAC/B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAID,qBAAa,YAAY;IAGvB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmB;gBAElC,IAAI,GAAE,mBAAwB;IAI1C,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,SAAS;IAQ5C,UAAU,IAAI,IAAI;CAGnB;AAED,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,25 @@
+import { JobHandle } from './job.js';
+import { QueuedConnection } from './connection.js';
+import { getSocketPath } from './protocol.js';
+let counter = 0;
+export class MCPTelemetry {
+    // One persistent connection per instance, shared by every job it creates —
+    // replaces opening a fresh socket for every single event.
+    connection;
+    constructor(opts = {}) {
+        this.connection = new QueuedConnection(opts.socketPath ?? getSocketPath());
+    }
+    createJob(opts) {
+        const jobId = opts.id ?? `job-${++counter}`;
+        return new JobHandle(jobId, opts.task, this.connection);
+    }
+    // Call when the host MCP server is done emitting telemetry (e.g. on
+    // shutdown, or once a job's lifecycle is fully over) to drop the
+    // connection instead of leaving it idle.
+    disconnect() {
+        this.connection.close();
+    }
+}
+export { JobHandle } from './job.js';
+export { getSocketPath } from './protocol.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAW9C,IAAI,OAAO,GAAG,CAAC,CAAC;AAEhB,MAAM,OAAO,YAAY;IACvB,2EAA2E;IAC3E,0DAA0D;IACzC,UAAU,CAAmB;IAE9C,YAAY,OAA4B,EAAE;QACxC,IAAI,CAAC,UAAU,GAAG,IAAI,gBAAgB,CAAC,IAAI,CAAC,UAAU,IAAI,aAAa,EAAE,CAAC,CAAC;IAC7E,CAAC;IAED,SAAS,CAAC,IAAsB;QAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,EAAE,IAAI,OAAO,EAAE,OAAO,EAAE,CAAC;QAC5C,OAAO,IAAI,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IAC1D,CAAC;IAED,oEAAoE;IACpE,iEAAiE;IACjE,yCAAyC;IACzC,UAAU;QACR,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;IAC1B,CAAC;CACF;AAED,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAA4B,aAAa,EAAE,MAAM,eAAe,CAAC"}

package/dist/job.d.ts

@@ -0,0 +1,16 @@
+import type { QueuedConnection } from './connection.js';
+export declare class JobHandle {
+    private readonly jobId;
+    private readonly task;
+    private readonly connection;
+    constructor(jobId: string, task: string, connection: QueuedConnection);
+    private send;
+    start(): void;
+    done(exitCode?: number): Promise<void>;
+    stepStart(step: string, meta?: Record<string, unknown>): void;
+    stepDone(step: string, meta?: Record<string, unknown>): void;
+    stepFailed(step: string, reason?: string): void;
+    log(line: string, stream?: 'stdout' | 'stderr'): void;
+    cost(amount: number, meta?: Record<string, unknown>): void;
+}
+//# sourceMappingURL=job.d.ts.map

package/dist/job.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job.d.ts","sourceRoot":"","sources":["../src/job.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAKxD,qBAAa,SAAS;IAElB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAFV,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,gBAAgB;IAG/C,OAAO,CAAC,IAAI;IAIZ,KAAK,IAAI,IAAI;IAQP,IAAI,CAAC,QAAQ,SAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAKvC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI7D,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI5D,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAI/C,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,IAAI;IAIrD,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;CAG3D"}

package/dist/job.js

@@ -0,0 +1,41 @@
+function now() { return new Date().toISOString(); }
+export class JobHandle {
+    jobId;
+    task;
+    connection;
+    constructor(jobId, task, connection) {
+        this.jobId = jobId;
+        this.task = task;
+        this.connection = connection;
+    }
+    send(event) {
+        this.connection.send(JSON.stringify(event) + '\n');
+    }
+    start() {
+        this.send({ type: 'job_start', jobId: this.jobId, task: this.task, timestamp: now() });
+    }
+    // Async because this is the terminal event — nothing else may ever call
+    // send() again on this job, so it actively drains instead of relying on a
+    // future send() to retry delivery (see QueuedConnection.drain). Safe to
+    // call without awaiting; the drain still runs in the background either way.
+    async done(exitCode = 0) {
+        this.send({ type: 'job_done', jobId: this.jobId, exitCode, timestamp: now() });
+        await this.connection.drain();
+    }
+    stepStart(step, meta) {
+        this.send({ type: 'step_start', jobId: this.jobId, step, meta, timestamp: now() });
+    }
+    stepDone(step, meta) {
+        this.send({ type: 'step_done', jobId: this.jobId, step, meta, timestamp: now() });
+    }
+    stepFailed(step, reason) {
+        this.send({ type: 'step_failed', jobId: this.jobId, step, reason, timestamp: now() });
+    }
+    log(line, stream) {
+        this.send({ type: 'log', jobId: this.jobId, line, stream, timestamp: now() });
+    }
+    cost(amount, meta) {
+        this.send({ type: 'cost', jobId: this.jobId, amount, meta, timestamp: now() });
+    }
+}
+//# sourceMappingURL=job.js.map

package/dist/job.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job.js","sourceRoot":"","sources":["../src/job.ts"],"names":[],"mappings":"AAGA,SAAS,GAAG,KAAa,OAAO,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;AAE3D,MAAM,OAAO,SAAS;IAED;IACA;IACA;IAHnB,YACmB,KAAa,EACb,IAAY,EACZ,UAA4B;QAF5B,UAAK,GAAL,KAAK,CAAQ;QACb,SAAI,GAAJ,IAAI,CAAQ;QACZ,eAAU,GAAV,UAAU,CAAkB;IAC5C,CAAC;IAEI,IAAI,CAAC,KAAmB;QAC9B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;IACrD,CAAC;IAED,KAAK;QACH,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IACzF,CAAC;IAED,wEAAwE;IACxE,0EAA0E;IAC1E,wEAAwE;IACxE,4EAA4E;IAC5E,KAAK,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC;QACrB,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;QAC/E,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;IAChC,CAAC;IAED,SAAS,CAAC,IAAY,EAAE,IAA8B;QACpD,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IACrF,CAAC;IAED,QAAQ,CAAC,IAAY,EAAE,IAA8B;QACnD,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IACpF,CAAC;IAED,UAAU,CAAC,IAAY,EAAE,MAAe;QACtC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IACxF,CAAC;IAED,GAAG,CAAC,IAAY,EAAE,MAA4B;QAC5C,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IAChF,CAAC;IAED,IAAI,CAAC,MAAc,EAAE,IAA8B;QACjD,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IACjF,CAAC;CACF"}

package/dist/protocol.d.ts

@@ -0,0 +1,44 @@
+export type TaskStatus = 'working' | 'input_required' | 'completed' | 'failed' | 'cancelled';
+export type MonitorEvent = {
+    type: 'job_start';
+    jobId: string;
+    task: string;
+    timestamp: string;
+} | {
+    type: 'job_done';
+    jobId: string;
+    exitCode: number;
+    timestamp: string;
+} | {
+    type: 'step_start';
+    jobId: string;
+    step: string;
+    meta?: Record<string, unknown>;
+    timestamp: string;
+} | {
+    type: 'step_done';
+    jobId: string;
+    step: string;
+    meta?: Record<string, unknown>;
+    timestamp: string;
+} | {
+    type: 'step_failed';
+    jobId: string;
+    step: string;
+    reason?: string;
+    timestamp: string;
+} | {
+    type: 'log';
+    jobId: string;
+    line: string;
+    stream?: 'stdout' | 'stderr';
+    timestamp: string;
+} | {
+    type: 'cost';
+    jobId: string;
+    amount: number;
+    meta?: Record<string, unknown>;
+    timestamp: string;
+};
+export declare function getSocketPath(root?: string): string;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,gBAAgB,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE7F,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAG,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAmC,SAAS,EAAE,MAAM,CAAA;CAAE,GACzG;IAAE,IAAI,EAAE,UAAU,CAAC;IAAI,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAgC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC1G;IAAE,IAAI,EAAE,YAAY,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GACzG;IAAE,IAAI,EAAE,WAAW,CAAC;IAAG,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GACzG;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAiB,SAAS,EAAE,MAAM,CAAA;CAAE,GACzG;IAAE,IAAI,EAAE,KAAK,CAAC;IAAS,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAAM,SAAS,EAAE,MAAM,CAAA;CAAE,GAC1G;IAAE,IAAI,EAAE,MAAM,CAAC;IAAQ,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9G,wBAAgB,aAAa,CAAC,IAAI,SAAgB,GAAG,MAAM,CAY1D"}

package/dist/protocol.js

@@ -0,0 +1,16 @@
+import { createHash } from 'crypto';
+import { join, resolve } from 'path';
+export function getSocketPath(root = process.cwd()) {
+    // Resolve (and, on Windows, lowercase) so callers pointing at the same
+    // directory always hash to the same pipe/socket regardless of trailing
+    // slashes or drive-letter casing — a mismatch here silently splits
+    // producers and the collector onto two different sockets with no error
+    // on either side. Unix paths stay case-sensitive.
+    const resolved = resolve(root);
+    if (process.platform === 'win32') {
+        const hash = createHash('md5').update(resolved.toLowerCase()).digest('hex').slice(0, 8);
+        return `\\\\.\\pipe\\mcp-telemetry-${hash}`;
+    }
+    return join(resolved, '.mcp-telemetry.sock');
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAcrC,MAAM,UAAU,aAAa,CAAC,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE;IAChD,uEAAuE;IACvE,uEAAuE;IACvE,mEAAmE;IACnE,uEAAuE;IACvE,kDAAkD;IAClD,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACxF,OAAO,8BAA8B,IAAI,EAAE,CAAC;IAC9C,CAAC;IACD,OAAO,IAAI,CAAC,QAAQ,EAAE,qBAAqB,CAAC,CAAC;AAC/C,CAAC"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "mcp-telemetry-sdk",
+  "version": "0.1.0",
+  "description": "Zero-dependency instrumentation library for MCP servers — emit job/step/log/cost telemetry that any mcp-telemetry-server (or your own collector) can pick up.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Arnav Ranjan <arnavranjan005@gmail.com>",
+  "keywords": ["mcp", "model-context-protocol", "telemetry", "observability", "ai-agent", "monitoring", "progress", "notifications", "claude-code", "long-running-tasks", "mcp-server"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arnavranjan005/mcp-telemetry.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://github.com/arnavranjan005/mcp-telemetry/tree/main/packages/sdk#readme",
+  "bugs": {
+    "url": "https://github.com/arnavranjan005/mcp-telemetry/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist/"],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.5.0"
+  }
+}