mcp-telemetry-server 0.1.0

package/README.md

@@ -0,0 +1,33 @@
+# mcp-telemetry-server
+
+The collector half of [mcp-telemetry](https://github.com/arnavranjan005/mcp-telemetry). Register it as an MCP server to watch live progress from any tool instrumented with [`mcp-telemetry-sdk`](https://www.npmjs.com/package/mcp-telemetry-sdk).
+
+## Install
+
+```bash
+npm install -g mcp-telemetry-server
+```
+
+## Register it
+
+```json
+{
+  "mcpServers": {
+    "telemetry": { "command": "npx", "args": ["-y", "mcp-telemetry-server"] }
+  }
+}
+```
+
+## Tools it exposes
+
+| Tool | Behavior |
+|---|---|
+| `telemetry_subscribe({ jobId?, timeoutMs? })` | Blocks and streams live progress for a job until it finishes. |
+| `telemetry_jobs()` | Lists all known jobs with status and cost. |
+| `telemetry_job_status({ jobId })` | Full state of one job — steps, cost, failure reason. |
+
+See the [main README](https://github.com/arnavranjan005/mcp-telemetry#quickstart) for a full worked example.
+
+## License
+
+MIT

package/bin/server.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/index.js';

package/dist/collector.d.ts

@@ -0,0 +1,11 @@
+import type { MonitorEvent } from 'mcp-telemetry-sdk';
+export declare class Collector {
+    private readonly socketPath;
+    private readonly server;
+    private readonly handlers;
+    constructor(socketPath: string);
+    onEvent(handler: (event: MonitorEvent) => void): void;
+    offEvent(handler: (event: MonitorEvent) => void): void;
+    listen(): Promise<void>;
+    close(): void;
+}

package/dist/collector.js

@@ -0,0 +1,54 @@
+import net from 'net';
+import { existsSync, unlinkSync } from 'fs';
+export class Collector {
+    socketPath;
+    server;
+    handlers = [];
+    constructor(socketPath) {
+        this.socketPath = socketPath;
+        this.server = net.createServer((socket) => {
+            let buffer = '';
+            socket.on('data', (chunk) => {
+                buffer += chunk.toString();
+                const lines = buffer.split('\n');
+                buffer = lines.pop() ?? '';
+                for (const line of lines) {
+                    if (!line.trim())
+                        continue;
+                    try {
+                        const event = JSON.parse(line);
+                        for (const h of this.handlers)
+                            h(event);
+                    }
+                    catch { /* ignore malformed NDJSON */ }
+                }
+            });
+        });
+    }
+    onEvent(handler) {
+        this.handlers.push(handler);
+    }
+    offEvent(handler) {
+        const idx = this.handlers.indexOf(handler);
+        if (idx !== -1)
+            this.handlers.splice(idx, 1);
+    }
+    listen() {
+        return new Promise((resolve, reject) => {
+            if (process.platform !== 'win32' && existsSync(this.socketPath)) {
+                unlinkSync(this.socketPath);
+            }
+            this.server.listen(this.socketPath, () => resolve());
+            this.server.on('error', reject);
+        });
+    }
+    close() {
+        this.server.close();
+        if (process.platform !== 'win32' && existsSync(this.socketPath)) {
+            try {
+                unlinkSync(this.socketPath);
+            }
+            catch { /* best-effort */ }
+        }
+    }
+}

package/dist/format.d.ts

@@ -0,0 +1,5 @@
+import type { MonitorEvent } from 'mcp-telemetry-sdk';
+import type { JobState } from './store.js';
+export declare function formatMeta(meta: Record<string, unknown> | undefined): string;
+export declare function formatEvent(event: MonitorEvent): string;
+export declare function formatJob(job: JobState): string;

package/dist/format.js

@@ -0,0 +1,28 @@
+export function formatMeta(meta) {
+    if (!meta || !Object.keys(meta).length)
+        return '';
+    return ` (${Object.entries(meta).map(([k, v]) => `${k}=${v}`).join(', ')})`;
+}
+export function formatEvent(event) {
+    switch (event.type) {
+        case 'job_start': return `▶ ${event.task}`;
+        case 'job_done': return `${event.exitCode === 0 ? '✓' : '✗'} job done (exit ${event.exitCode})`;
+        case 'step_start': return `↻ ${event.step}${formatMeta(event.meta)}`;
+        case 'step_done': return `✓ ${event.step}${formatMeta(event.meta)}`;
+        case 'step_failed': return `✗ ${event.step}${event.reason ? ` — ${event.reason}` : ''}`;
+        case 'log': return event.stream === 'stderr' ? `[stderr] ${event.line}` : event.line;
+        case 'cost': return `$${event.amount.toFixed(4)}${formatMeta(event.meta)}`;
+    }
+}
+export function formatJob(job) {
+    const ICONS = { done: '✓', failed: '✗', running: '↻' };
+    const steps = job.steps.length
+        ? job.steps.map((s) => `  ${ICONS[s.status] ?? '?'} ${s.name}${s.reason ? ` — ${s.reason}` : ''}`).join('\n')
+        : '  (no steps yet)';
+    return [
+        `[${job.jobId}] ${job.task}`,
+        `status: ${job.status}  cost: $${job.totalCost.toFixed(4)}`,
+        '',
+        steps,
+    ].join('\n');
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,130 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { getSocketPath } from 'mcp-telemetry-sdk';
+import { Collector } from './collector.js';
+import { JobStore } from './store.js';
+import { formatEvent, formatJob } from './format.js';
+const JOBS_RESOURCE_URI = 'telemetry://jobs';
+const store = new JobStore();
+const collector = new Collector(getSocketPath());
+const server = new McpServer({ name: 'mcp-telemetry', version: '0.1.0' });
+// ── Tools ─────────────────────────────────────────────────────────────────────
+server.tool('telemetry_jobs', 'List all active and recently completed jobs across all connected MCP servers.', {}, async () => {
+    const jobs = store.getJobs();
+    if (!jobs.length)
+        return { content: [{ type: 'text', text: 'No jobs yet.' }] };
+    const lines = jobs.map((j) => {
+        const icon = { completed: '✓', failed: '✗', input_required: '!', working: '↻', cancelled: '⊘' }[j.status];
+        const cost = j.totalCost > 0 ? `  $${j.totalCost.toFixed(4)}` : '';
+        return `${icon} [${j.jobId}] ${j.task}${cost}`;
+    });
+    return { content: [{ type: 'text', text: lines.join('\n') }] };
+});
+server.tool('telemetry_job_status', 'Get the full status of a specific job — all steps, cost, and any failure reason.', { jobId: z.string().describe('Job ID returned by job_start event or telemetry_jobs.') }, async ({ jobId }) => {
+    const job = store.getJob(jobId);
+    if (!job)
+        return { content: [{ type: 'text', text: `No job found: ${jobId}` }], isError: true };
+    return { content: [{ type: 'text', text: formatJob(job) }] };
+});
+server.tool('telemetry_subscribe', 'Watch live job events as they happen — blocks and streams inline progress until the job (or, with no jobId, the next job) finishes, or until timeoutMs elapses.', {
+    jobId: z.string().optional().describe('Watch only this job. Omit to watch the next job to start.'),
+    timeoutMs: z.number().optional().describe('Give up and return after this many ms. Default 5 minutes.'),
+}, async ({ jobId, timeoutMs }, extra) => {
+    const progressToken = extra._meta?.progressToken;
+    const deadline = timeoutMs ?? 5 * 60 * 1000;
+    const LOG_THROTTLE_MS = 1500;
+    const LOG_BATCH_MAX = 20;
+    return new Promise((resolve) => {
+        let n = 0;
+        let settled = false;
+        let pendingLogs = [];
+        let logTimer = null;
+        const push = (message) => {
+            n += 1;
+            if (progressToken !== undefined) {
+                extra.sendNotification({
+                    method: 'notifications/progress',
+                    params: { progressToken, progress: n, message },
+                }).catch(() => { });
+            }
+        };
+        // Raw log lines are usually too frequent to push one-by-one (a verbose
+        // run can emit hundreds) — coalesce them into one notification every
+        // LOG_THROTTLE_MS or LOG_BATCH_MAX lines, whichever comes first.
+        // Structured events (step/cost/done) always flush any pending logs
+        // first so ordering in the stream matches what actually happened, then
+        // push immediately themselves — they're infrequent enough not to need
+        // throttling.
+        const flushLogs = () => {
+            if (logTimer) {
+                clearTimeout(logTimer);
+                logTimer = null;
+            }
+            if (!pendingLogs.length)
+                return;
+            push(pendingLogs.join('\n'));
+            pendingLogs = [];
+        };
+        const finish = (text) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            flushLogs();
+            collector.offEvent(handler);
+            resolve({ content: [{ type: 'text', text }] });
+        };
+        const handler = (event) => {
+            if (jobId && event.jobId !== jobId)
+                return;
+            if (event.type === 'log') {
+                pendingLogs.push(formatEvent(event));
+                if (pendingLogs.length >= LOG_BATCH_MAX) {
+                    flushLogs();
+                    return;
+                }
+                if (!logTimer)
+                    logTimer = setTimeout(flushLogs, LOG_THROTTLE_MS);
+                return;
+            }
+            flushLogs();
+            push(formatEvent(event));
+            if (event.type === 'job_done') {
+                finish(`Job ${event.jobId} finished (exit ${event.exitCode}).`);
+            }
+        };
+        collector.onEvent(handler);
+        const timer = setTimeout(() => finish('Timed out waiting for job completion.'), deadline);
+    });
+});
+// ── Resource — auto-push via MCP resource subscriptions ───────────────────────
+server.resource('telemetry-jobs', JOBS_RESOURCE_URI, { description: 'Live job state for all connected MCP servers. Subscribe to receive updates.' }, async () => ({
+    contents: [{
+            uri: JOBS_RESOURCE_URI,
+            mimeType: 'application/json',
+            text: JSON.stringify(store.getJobs(), null, 2),
+        }],
+}));
+// ── Collector → store → notify all subscribed agents ─────────────────────────
+collector.onEvent((event) => {
+    store.apply(event);
+    // Push resource update notification — agents that subscribed to telemetry://jobs
+    // will be notified and can re-read the resource to get the latest state.
+    server.server.notification({
+        method: 'notifications/resources/updated',
+        params: { uri: JOBS_RESOURCE_URI },
+    }).catch(() => { });
+});
+const pruneTimer = setInterval(() => store.prune(), 5 * 60 * 1000);
+pruneTimer.unref();
+// ── Bootstrap ─────────────────────────────────────────────────────────────────
+async function main() {
+    await collector.listen();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    const shutdown = () => { collector.close(); process.exit(0); };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}
+main().catch((err) => { console.error(err); process.exit(1); });

package/dist/store.d.ts

@@ -0,0 +1,27 @@
+import type { MonitorEvent, TaskStatus } from 'mcp-telemetry-sdk';
+export interface StepState {
+    name: string;
+    status: 'running' | 'done' | 'failed';
+    startedAt: string;
+    endedAt?: string;
+    meta?: Record<string, unknown>;
+    reason?: string;
+}
+export interface JobState {
+    jobId: string;
+    task: string;
+    status: TaskStatus;
+    steps: StepState[];
+    logs: string[];
+    totalCost: number;
+    startedAt: string;
+    endedAt?: string;
+    exitCode?: number;
+}
+export declare class JobStore {
+    private readonly jobs;
+    apply(event: MonitorEvent): void;
+    getJob(jobId: string): JobState | undefined;
+    getJobs(): JobState[];
+    prune(): void;
+}

package/dist/store.js

@@ -0,0 +1,83 @@
+const JOB_TTL_MS = 5 * 60 * 1000;
+export class JobStore {
+    jobs = new Map();
+    apply(event) {
+        switch (event.type) {
+            case 'job_start':
+                this.jobs.set(event.jobId, {
+                    jobId: event.jobId,
+                    task: event.task,
+                    status: 'working',
+                    steps: [],
+                    logs: [],
+                    totalCost: 0,
+                    startedAt: event.timestamp,
+                });
+                break;
+            case 'job_done': {
+                const job = this.jobs.get(event.jobId);
+                if (job) {
+                    job.status = event.exitCode === 0 ? 'completed' : 'failed';
+                    job.exitCode = event.exitCode;
+                    job.endedAt = event.timestamp;
+                }
+                break;
+            }
+            case 'step_start': {
+                const job = this.jobs.get(event.jobId);
+                job?.steps.push({ name: event.step, status: 'running', startedAt: event.timestamp, meta: event.meta });
+                break;
+            }
+            case 'step_done': {
+                const job = this.jobs.get(event.jobId);
+                if (job) {
+                    const step = [...job.steps].reverse().find(s => s.name === event.step && s.status === 'running');
+                    if (step) {
+                        step.status = 'done';
+                        step.endedAt = event.timestamp;
+                    }
+                }
+                break;
+            }
+            case 'step_failed': {
+                const job = this.jobs.get(event.jobId);
+                if (job) {
+                    const step = [...job.steps].reverse().find(s => s.name === event.step && s.status === 'running');
+                    if (step) {
+                        step.status = 'failed';
+                        step.endedAt = event.timestamp;
+                        step.reason = event.reason;
+                    }
+                    if (event.reason === 'input_required')
+                        job.status = 'input_required';
+                }
+                break;
+            }
+            case 'log': {
+                const job = this.jobs.get(event.jobId);
+                job?.logs.push(event.stream === 'stderr' ? `[stderr] ${event.line}` : event.line);
+                break;
+            }
+            case 'cost': {
+                const job = this.jobs.get(event.jobId);
+                if (job)
+                    job.totalCost += event.amount;
+                break;
+            }
+        }
+    }
+    getJob(jobId) {
+        return this.jobs.get(jobId);
+    }
+    getJobs() {
+        return [...this.jobs.values()].sort((a, b) => a.startedAt.localeCompare(b.startedAt));
+    }
+    prune() {
+        const cutoff = Date.now() - JOB_TTL_MS;
+        for (const [id, job] of this.jobs) {
+            if (job.endedAt && new Date(job.endedAt).getTime() < cutoff) {
+                this.jobs.delete(id);
+            }
+        }
+    }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "mcp-telemetry-server",
+  "version": "0.1.0",
+  "description": "MCP server that collects telemetry from any mcp-telemetry-sdk-instrumented tool and pushes live progress to any connected MCP client (Claude Code, Cursor, and others).",
+  "type": "module",
+  "license": "MIT",
+  "author": "Arnav Ranjan <arnavranjan005@gmail.com>",
+  "keywords": ["mcp", "model-context-protocol", "telemetry", "observability", "ai-agent", "monitoring", "claude-code", "progress", "notifications", "background-jobs", "long-running-tasks", "mcp-server", "cursor"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arnavranjan005/mcp-telemetry.git",
+    "directory": "packages/server"
+  },
+  "homepage": "https://github.com/arnavranjan005/mcp-telemetry/tree/main/packages/server#readme",
+  "bugs": {
+    "url": "https://github.com/arnavranjan005/mcp-telemetry/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "mcp-telemetry-server": "./bin/server.js"
+  },
+  "files": ["bin/", "dist/"],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node bin/server.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "mcp-telemetry-sdk": "^0.1.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.5.0"
+  }
+}