spect8-mcp 0.1.0

package/dist/transport/ingest_client.js

@@ -0,0 +1,78 @@
+import { request } from "undici";
+import { signRequest } from "./sign.js";
+export class IngestClient {
+    baseUrl;
+    hmacKey;
+    developerId;
+    logger;
+    timeoutMs;
+    constructor(baseUrl, hmacKey, developerId, logger, timeoutMs = 10_000) {
+        this.baseUrl = baseUrl;
+        this.hmacKey = hmacKey;
+        this.developerId = developerId;
+        this.logger = logger;
+        this.timeoutMs = timeoutMs;
+    }
+    async postEvents(events) {
+        return this.post("/api/v1/events", events);
+    }
+    async postTokenEvents(events) {
+        return this.post("/api/v1/token_events", events);
+    }
+    async get(path) {
+        const url = `${this.baseUrl}${path}`;
+        try {
+            const { statusCode, body } = await request(url, {
+                method: "GET",
+                headers: {
+                    "x-spect8-dev-id": this.developerId,
+                },
+                headersTimeout: this.timeoutMs,
+                bodyTimeout: this.timeoutMs,
+            });
+            const text = await body.text();
+            return {
+                ok: statusCode >= 200 && statusCode < 300,
+                status: statusCode,
+                body: text,
+            };
+        }
+        catch (err) {
+            this.logger.warn(`GET ${path} failed`, err.message);
+            return { ok: false, status: 0, body: err.message };
+        }
+    }
+    async post(path, payload) {
+        const url = `${this.baseUrl}${path}`;
+        const body = JSON.stringify(payload);
+        const ts = Date.now();
+        const signature = signRequest(this.hmacKey, ts, body);
+        try {
+            const { statusCode, body: resBody } = await request(url, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    "x-spect8-timestamp": String(ts),
+                    "x-spect8-signature": signature,
+                    "x-spect8-dev-id": this.developerId,
+                },
+                body,
+                headersTimeout: this.timeoutMs,
+                bodyTimeout: this.timeoutMs,
+            });
+            const text = await resBody.text();
+            if (statusCode >= 200 && statusCode < 300) {
+                this.logger.debug(`POST ${path} succeeded`);
+                return { ok: true, status: statusCode, body: text };
+            }
+            this.logger.warn(`POST ${path} returned ${statusCode}`, text.slice(0, 200));
+            return { ok: false, status: statusCode, body: text };
+        }
+        catch (err) {
+            this.logger.debug(`POST ${path} exception: ${err.message}`);
+            this.logger.warn(`POST ${path} failed`, err.message);
+            return { ok: false, status: 0, body: err.message };
+        }
+    }
+}
+//# sourceMappingURL=ingest_client.js.map

package/dist/transport/ingest_client.js.map

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

package/dist/transport/offline_queue.d.ts

@@ -0,0 +1,30 @@
+import type { Logger } from "../logger.js";
+export type QueueKind = "event" | "token_event";
+export interface QueuedRow {
+    id: number;
+    kind: QueueKind;
+    payload: string;
+    created_at_ms: number;
+    attempts: number;
+}
+/**
+ * Durable, append-only FIFO backed by SQLite. Used when the ingest endpoint is
+ * unreachable so no captured event is lost across crashes or network outages.
+ *
+ * Rows are keyed by auto-incremented id to preserve ordering; `dequeue()`
+ * returns the oldest unsent rows and callers call `ack()` after a successful
+ * POST. On retry storms we also track `attempts` so pathological rows can be
+ * drained manually by an operator.
+ */
+export declare class OfflineQueue {
+    private readonly logger;
+    private readonly db;
+    constructor(dbPath: string, logger: Logger);
+    enqueueMany(kind: QueueKind, payloads: string[]): void;
+    dequeue(kind: QueueKind, limit: number): QueuedRow[];
+    ack(ids: number[]): void;
+    bump(ids: number[]): void;
+    size(): number;
+    close(): void;
+}
+//# sourceMappingURL=offline_queue.d.ts.map

package/dist/transport/offline_queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"offline_queue.d.ts","sourceRoot":"","sources":["../../src/transport/offline_queue.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,aAAa,CAAC;AAEhD,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,qBAAa,YAAY;IAGK,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAoB;gBAE3B,MAAM,EAAE,MAAM,EAAmB,MAAM,EAAE,MAAM;IAmB3D,WAAW,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI;IAgBtD,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE;IASpD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI;IAQxB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI;IAUzB,IAAI,IAAI,MAAM;IAOd,KAAK,IAAI,IAAI;CAGd"}

package/dist/transport/offline_queue.js

@@ -0,0 +1,83 @@
+import Database from "better-sqlite3";
+import { dirname } from "node:path";
+import { mkdirSync, existsSync } from "node:fs";
+/**
+ * Durable, append-only FIFO backed by SQLite. Used when the ingest endpoint is
+ * unreachable so no captured event is lost across crashes or network outages.
+ *
+ * Rows are keyed by auto-incremented id to preserve ordering; `dequeue()`
+ * returns the oldest unsent rows and callers call `ack()` after a successful
+ * POST. On retry storms we also track `attempts` so pathological rows can be
+ * drained manually by an operator.
+ */
+export class OfflineQueue {
+    logger;
+    db;
+    constructor(dbPath, logger) {
+        this.logger = logger;
+        if (!existsSync(dirname(dbPath))) {
+            mkdirSync(dirname(dbPath), { recursive: true });
+        }
+        this.db = new Database(dbPath);
+        this.db.pragma("journal_mode = WAL");
+        this.db.pragma("synchronous = NORMAL");
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS spect8_queue (
+        id           INTEGER PRIMARY KEY AUTOINCREMENT,
+        kind         TEXT NOT NULL,
+        payload      TEXT NOT NULL,
+        created_at_ms INTEGER NOT NULL,
+        attempts     INTEGER NOT NULL DEFAULT 0
+      );
+      CREATE INDEX IF NOT EXISTS ix_spect8_queue_kind ON spect8_queue(kind, id);
+    `);
+    }
+    enqueueMany(kind, payloads) {
+        if (payloads.length === 0)
+            return;
+        const stmt = this.db.prepare("INSERT INTO spect8_queue(kind, payload, created_at_ms) VALUES (?, ?, ?)");
+        const now = Date.now();
+        const tx = this.db.transaction((rows) => {
+            for (const p of rows)
+                stmt.run(kind, p, now);
+        });
+        try {
+            tx(payloads);
+        }
+        catch (err) {
+            this.logger.error("offline queue enqueue failed", err.message);
+        }
+    }
+    dequeue(kind, limit) {
+        const rows = this.db
+            .prepare("SELECT id, kind, payload, created_at_ms, attempts FROM spect8_queue WHERE kind = ? ORDER BY id LIMIT ?")
+            .all(kind, limit);
+        return rows;
+    }
+    ack(ids) {
+        if (ids.length === 0)
+            return;
+        const placeholders = ids.map(() => "?").join(",");
+        this.db
+            .prepare(`DELETE FROM spect8_queue WHERE id IN (${placeholders})`)
+            .run(...ids);
+    }
+    bump(ids) {
+        if (ids.length === 0)
+            return;
+        const placeholders = ids.map(() => "?").join(",");
+        this.db
+            .prepare(`UPDATE spect8_queue SET attempts = attempts + 1 WHERE id IN (${placeholders})`)
+            .run(...ids);
+    }
+    size() {
+        const row = this.db
+            .prepare("SELECT COUNT(*) AS n FROM spect8_queue")
+            .get();
+        return row.n;
+    }
+    close() {
+        this.db.close();
+    }
+}
+//# sourceMappingURL=offline_queue.js.map

package/dist/transport/offline_queue.js.map

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

package/dist/transport/sign.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Compute the `X-Spect8-Signature` header value for a signed request. The
+ * backend verifies the signature as HMAC_SHA256(key, `${ts}.${body}`) so both
+ * ts and body must be identical byte-for-byte on both sides.
+ */
+export declare function signRequest(key: string, timestampMs: number, body: string | Uint8Array): string;
+//# sourceMappingURL=sign.d.ts.map

package/dist/transport/sign.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign.d.ts","sourceRoot":"","sources":["../../src/transport/sign.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,GAAG,UAAU,GACxB,MAAM,CAMR"}

package/dist/transport/sign.js

@@ -0,0 +1,14 @@
+import { createHmac } from "node:crypto";
+/**
+ * Compute the `X-Spect8-Signature` header value for a signed request. The
+ * backend verifies the signature as HMAC_SHA256(key, `${ts}.${body}`) so both
+ * ts and body must be identical byte-for-byte on both sides.
+ */
+export function signRequest(key, timestampMs, body) {
+    const mac = createHmac("sha256", key);
+    mac.update(String(timestampMs));
+    mac.update(".");
+    mac.update(body);
+    return "sha256=" + mac.digest("hex");
+}
+//# sourceMappingURL=sign.js.map

package/dist/transport/sign.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign.js","sourceRoot":"","sources":["../../src/transport/sign.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;GAIG;AACH,MAAM,UAAU,WAAW,CACzB,GAAW,EACX,WAAmB,EACnB,IAAyB;IAEzB,MAAM,GAAG,GAAG,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACtC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC;IAChC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAChB,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACjB,OAAO,SAAS,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACvC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,123 @@
+import { z } from "zod";
+export declare const TOOL_NAMES: readonly ["read_file", "write_file", "run_command", "git_diff", "search_files", "prompt_start", "start_task", "end_task", "get_score"];
+export type ToolName = (typeof TOOL_NAMES)[number];
+export type IdeName = string;
+export declare const ToolEventSchema: z.ZodObject<{
+    event_id: z.ZodString;
+    session_id: z.ZodString;
+    task_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    developer_id: z.ZodString;
+    tool_name: z.ZodEnum<["read_file", "write_file", "run_command", "git_diff", "search_files", "prompt_start", "start_task", "end_task", "get_score"]>;
+    timestamp_ms: z.ZodNumber;
+    file_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    file_size_bytes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    lines_count: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    command: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    exit_code: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    command_duration_ms: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    search_query: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    search_results_count: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    diff_lines_added: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    diff_lines_removed: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    diff_files_changed: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    task_label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    latency_since_prev_ms: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    input_tokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    output_tokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    cache_read_input_tokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    cache_creation_input_tokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    ide_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    model_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    request_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    developer_id: string;
+    event_id: string;
+    session_id: string;
+    tool_name: "read_file" | "write_file" | "run_command" | "git_diff" | "search_files" | "prompt_start" | "start_task" | "end_task" | "get_score";
+    timestamp_ms: number;
+    ide_name?: string | null | undefined;
+    task_id?: string | null | undefined;
+    file_path?: string | null | undefined;
+    file_size_bytes?: number | null | undefined;
+    lines_count?: number | null | undefined;
+    command?: string | null | undefined;
+    exit_code?: number | null | undefined;
+    command_duration_ms?: number | null | undefined;
+    search_query?: string | null | undefined;
+    search_results_count?: number | null | undefined;
+    diff_lines_added?: number | null | undefined;
+    diff_lines_removed?: number | null | undefined;
+    diff_files_changed?: number | null | undefined;
+    task_label?: string | null | undefined;
+    latency_since_prev_ms?: number | null | undefined;
+    input_tokens?: number | null | undefined;
+    output_tokens?: number | null | undefined;
+    cache_read_input_tokens?: number | null | undefined;
+    cache_creation_input_tokens?: number | null | undefined;
+    model_name?: string | null | undefined;
+    request_id?: string | null | undefined;
+}, {
+    developer_id: string;
+    event_id: string;
+    session_id: string;
+    tool_name: "read_file" | "write_file" | "run_command" | "git_diff" | "search_files" | "prompt_start" | "start_task" | "end_task" | "get_score";
+    timestamp_ms: number;
+    ide_name?: string | null | undefined;
+    task_id?: string | null | undefined;
+    file_path?: string | null | undefined;
+    file_size_bytes?: number | null | undefined;
+    lines_count?: number | null | undefined;
+    command?: string | null | undefined;
+    exit_code?: number | null | undefined;
+    command_duration_ms?: number | null | undefined;
+    search_query?: string | null | undefined;
+    search_results_count?: number | null | undefined;
+    diff_lines_added?: number | null | undefined;
+    diff_lines_removed?: number | null | undefined;
+    diff_files_changed?: number | null | undefined;
+    task_label?: string | null | undefined;
+    latency_since_prev_ms?: number | null | undefined;
+    input_tokens?: number | null | undefined;
+    output_tokens?: number | null | undefined;
+    cache_read_input_tokens?: number | null | undefined;
+    cache_creation_input_tokens?: number | null | undefined;
+    model_name?: string | null | undefined;
+    request_id?: string | null | undefined;
+}>;
+export type ToolEvent = z.infer<typeof ToolEventSchema>;
+export declare const TokenEventSchema: z.ZodObject<{
+    request_id: z.ZodString;
+    session_id: z.ZodString;
+    developer_id: z.ZodString;
+    timestamp_ms: z.ZodNumber;
+    ide_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    model_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    input_tokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    output_tokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    cache_read_input_tokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    cache_creation_input_tokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    developer_id: string;
+    session_id: string;
+    timestamp_ms: number;
+    request_id: string;
+    ide_name?: string | null | undefined;
+    input_tokens?: number | null | undefined;
+    output_tokens?: number | null | undefined;
+    cache_read_input_tokens?: number | null | undefined;
+    cache_creation_input_tokens?: number | null | undefined;
+    model_name?: string | null | undefined;
+}, {
+    developer_id: string;
+    session_id: string;
+    timestamp_ms: number;
+    request_id: string;
+    ide_name?: string | null | undefined;
+    input_tokens?: number | null | undefined;
+    output_tokens?: number | null | undefined;
+    cache_read_input_tokens?: number | null | undefined;
+    cache_creation_input_tokens?: number | null | undefined;
+    model_name?: string | null | undefined;
+}>;
+export type TokenEvent = z.infer<typeof TokenEventSchema>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,UAAU,wIAUb,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC;AAE7B,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6B1B,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAW3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/types.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+export const TOOL_NAMES = [
+    "read_file",
+    "write_file",
+    "run_command",
+    "git_diff",
+    "search_files",
+    "prompt_start",
+    "start_task",
+    "end_task",
+    "get_score",
+];
+export const ToolEventSchema = z.object({
+    event_id: z.string(),
+    session_id: z.string(),
+    task_id: z.string().nullable().optional(),
+    developer_id: z.string(),
+    tool_name: z.enum(TOOL_NAMES),
+    timestamp_ms: z.number().int(),
+    file_path: z.string().nullable().optional(),
+    file_size_bytes: z.number().int().nullable().optional(),
+    lines_count: z.number().int().nullable().optional(),
+    command: z.string().nullable().optional(),
+    exit_code: z.number().int().nullable().optional(),
+    command_duration_ms: z.number().int().nullable().optional(),
+    search_query: z.string().nullable().optional(),
+    search_results_count: z.number().int().nullable().optional(),
+    diff_lines_added: z.number().int().nullable().optional(),
+    diff_lines_removed: z.number().int().nullable().optional(),
+    diff_files_changed: z.number().int().nullable().optional(),
+    task_label: z.string().nullable().optional(),
+    latency_since_prev_ms: z.number().int().nullable().optional(),
+    input_tokens: z.number().int().nullable().optional(),
+    output_tokens: z.number().int().nullable().optional(),
+    cache_read_input_tokens: z.number().int().nullable().optional(),
+    cache_creation_input_tokens: z.number().int().nullable().optional(),
+    ide_name: z.string().nullable().optional(),
+    model_name: z.string().nullable().optional(),
+    request_id: z.string().nullable().optional(),
+});
+export const TokenEventSchema = z.object({
+    request_id: z.string(),
+    session_id: z.string(),
+    developer_id: z.string(),
+    timestamp_ms: z.number().int(),
+    ide_name: z.string().nullable().optional(),
+    model_name: z.string().nullable().optional(),
+    input_tokens: z.number().int().nullable().optional(),
+    output_tokens: z.number().int().nullable().optional(),
+    cache_read_input_tokens: z.number().int().nullable().optional(),
+    cache_creation_input_tokens: z.number().int().nullable().optional(),
+});
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/examples/claude/hooks.json

@@ -0,0 +1,37 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "SPECT8_INGEST_URL=${SPECT8_INGEST_URL:-https://spect8-api.herokuapp.com} SPECT8_IDE_NAME=claude_code npx -y --package @spect8/mcp -- spect8-mcp-claude-hook session-start"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "SPECT8_INGEST_URL=${SPECT8_INGEST_URL:-https://spect8-api.herokuapp.com} SPECT8_IDE_NAME=claude_code npx -y --package @spect8/mcp -- spect8-mcp-claude-hook post-tool"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "SPECT8_INGEST_URL=${SPECT8_INGEST_URL:-https://spect8-api.herokuapp.com} SPECT8_IDE_NAME=claude_code npx -y --package @spect8/mcp -- spect8-mcp-claude-hook stop"
+          }
+        ]
+      }
+    ]
+  }
+}

package/examples/cursor/mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "spect8": {
+      "command": "npx",
+      "args": ["-y", "@spect8/mcp"],
+      "env": {
+        "SPECT8_INGEST_URL": "https://spect8-api.herokuapp.com",
+        "SPECT8_INGEST_HMAC_KEY": "replace-with-shared-secret",
+        "SPECT8_DEVELOPER_ID": "replace-with-your-id",
+        "SPECT8_IDE_NAME": "cursor"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "spect8-mcp",
+  "version": "0.1.0",
+  "description": "Spect8 local MCP server: captures tool events + token usage from Cursor and Claude Code, posts HMAC-signed batches to the Spect8 ingest API.",
+  "type": "module",
+  "main": "dist/server.js",
+  "bin": {
+    "spect8": "dist/cli.js",
+    "spect8-mcp": "dist/server.js",
+    "spect8-mcp-claude-hook": "dist/hooks/cli.js"
+  },
+  "files": [
+    "dist",
+    "examples",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -w -p tsconfig.json",
+    "start": "node dist/server.js",
+    "lint": "eslint src --ext .ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "better-sqlite3": "^11.5.0",
+    "chokidar": "^3.6.0",
+    "undici": "^6.20.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.11",
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "eslint": "^8.57.0",
+    "typescript": "^5.5.4",
+    "vitest": "^1.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-org/spect8"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}