@errorcache/mcp 0.1.0

package/src/normalize.ts

@@ -0,0 +1,70 @@
+/**
+ * Error signature normalization for ErrorCache.
+ *
+ * Strips variable parts (file paths, line numbers, UUIDs, timestamps, hex
+ * addresses, IPs, version patch numbers) from raw error messages to produce
+ * a canonical form suitable for deduplication and similarity matching.
+ *
+ * This is the TypeScript equivalent of api/src/lib/errorSignature.js.
+ */
+
+export interface NormalizedSignature {
+  /** The normalized error string with variable parts replaced by placeholders. */
+  normalized: string;
+  /** Extracted error code (e.g. E0001, ERR_MODULE_NOT_FOUND, TYPEERROR), or null. */
+  error_code: string | null;
+  /** Meaningful tokens extracted from the normalized string (length > 2). */
+  tokens: string[];
+}
+
+/**
+ * Normalize an error message / stack trace into a canonical signature.
+ *
+ * The pipeline:
+ * 1. Strip file paths (common source file extensions)
+ * 2. Strip line/column numbers
+ * 3. Strip UUIDs
+ * 4. Strip ISO timestamps
+ * 5. Strip hex memory addresses
+ * 6. Strip version patch numbers (keep major.minor)
+ * 7. Strip IP addresses
+ * 8. Lowercase and collapse whitespace
+ * 9. Extract error code if present
+ */
+export function normalize(signature: string): NormalizedSignature {
+  let s = signature;
+
+  // Strip file paths (Unix and Windows style) with common source extensions
+  s = s.replace(/(?:[A-Za-z]:)?[\\\/][\w.\\\/\-]+\.(py|js|ts|tsx|jsx|go|rs|java|rb|c|cpp|h|hpp|cs|swift|kt|scala|ex|exs|php|sh|bash|zsh)/g, '<FILE>');
+
+  // Strip line/column numbers
+  s = s.replace(/line \d+/gi, 'line <N>');
+  s = s.replace(/:\d+:\d+/g, ':<N>:<N>');
+
+  // Strip UUIDs
+  s = s.replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, '<UUID>');
+
+  // Strip ISO timestamps (e.g. 2024-01-15T10:30:00 or 2024-01-15 10:30:00)
+  s = s.replace(/\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}/g, '<TIMESTAMP>');
+
+  // Strip hex memory addresses (0x followed by 6+ hex digits)
+  s = s.replace(/0x[0-9a-f]{6,}/gi, '<ADDR>');
+
+  // Strip version patch numbers but keep major.minor for context
+  s = s.replace(/(\d+\.\d+)\.\d+/g, '$1.x');
+
+  // Strip IP addresses
+  s = s.replace(/\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}/g, '<IP>');
+
+  // Lowercase and collapse whitespace
+  s = s.toLowerCase().replace(/\s+/g, ' ').trim();
+
+  // Extract the core error code/name if present
+  const errorCodeMatch = s.match(/\b(E\d{4,}|ERR_[A-Z_]+|[A-Z_]{3,}ERROR)\b/i);
+
+  return {
+    normalized: s,
+    error_code: errorCodeMatch ? errorCodeMatch[1].toUpperCase() : null,
+    tokens: s.split(/[^a-z0-9]+/).filter((t) => t.length > 2),
+  };
+}

package/src/setup.ts

@@ -0,0 +1,330 @@
+#!/usr/bin/env node
+
+/**
+ * ErrorCache MCP setup script.
+ *
+ * Usage:  npx errorcache-mcp setup
+ *         node dist/setup.js
+ *
+ * This script:
+ * 1. Generates a random UUID agent token.
+ * 2. Auto-detects installed AI coding tools:
+ *    - Claude Code:  ~/.claude.json or ~/.claude/settings.json
+ *    - Cursor:       ~/.cursor/mcp.json
+ *    - VS Code:      ~/.vscode/mcp.json
+ * 3. Injects MCP server configuration into each detected tool's config.
+ * 4. Stores the token in ~/.config/errorcache/credentials.json.
+ * 5. Prints instructions for completing agent registration.
+ */
+
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface ToolConfig {
+  name: string;
+  configPaths: string[];
+  inject: (configPath: string, mcpBlock: McpServerEntry) => void;
+}
+
+interface McpServerEntry {
+  command: string;
+  args: string[];
+  env: {
+    ERRORCACHE_TOKEN: string;
+    ERRORCACHE_API_URL: string;
+  };
+}
+
+interface Credentials {
+  token: string;
+  api_url: string;
+  created_at: string;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_API_URL = "https://api.errorcache.com/v1";
+const CREDENTIALS_DIR = join(homedir(), ".config", "errorcache");
+const CREDENTIALS_PATH = join(CREDENTIALS_DIR, "credentials.json");
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function log(msg: string): void {
+  console.log(`[errorcache] ${msg}`);
+}
+
+function warn(msg: string): void {
+  console.warn(`[errorcache] WARNING: ${msg}`);
+}
+
+function readJsonFile(path: string): Record<string, unknown> {
+  try {
+    const raw = readFileSync(path, "utf-8");
+    return JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+function writeJsonFile(path: string, data: unknown): void {
+  writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+
+/**
+ * Deep-merge `source` into `target`, returning a new object.
+ * Arrays are replaced, not concatenated.
+ */
+function deepMerge(
+  target: Record<string, unknown>,
+  source: Record<string, unknown>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = { ...target };
+  for (const key of Object.keys(source)) {
+    const srcVal = source[key];
+    const tgtVal = target[key];
+    if (
+      srcVal &&
+      typeof srcVal === "object" &&
+      !Array.isArray(srcVal) &&
+      tgtVal &&
+      typeof tgtVal === "object" &&
+      !Array.isArray(tgtVal)
+    ) {
+      result[key] = deepMerge(
+        tgtVal as Record<string, unknown>,
+        srcVal as Record<string, unknown>,
+      );
+    } else {
+      result[key] = srcVal;
+    }
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Tool-specific injectors
+// ---------------------------------------------------------------------------
+
+function injectGenericMcpJson(
+  configPath: string,
+  mcpBlock: McpServerEntry,
+): void {
+  const existing = existsSync(configPath) ? readJsonFile(configPath) : {};
+  const merged = deepMerge(existing, {
+    mcpServers: {
+      errorcache: mcpBlock,
+    },
+  });
+  const dir = join(configPath, "..");
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeJsonFile(configPath, merged);
+}
+
+function injectClaudeCode(
+  configPath: string,
+  mcpBlock: McpServerEntry,
+): void {
+  // Claude Code uses the same mcpServers shape whether in ~/.claude.json
+  // or ~/.claude/settings.json.
+  injectGenericMcpJson(configPath, mcpBlock);
+}
+
+// ---------------------------------------------------------------------------
+// Tool registry
+// ---------------------------------------------------------------------------
+
+const TOOLS: ToolConfig[] = [
+  {
+    name: "Claude Code",
+    configPaths: [
+      join(homedir(), ".claude.json"),
+      join(homedir(), ".claude", "settings.json"),
+    ],
+    inject: injectClaudeCode,
+  },
+  {
+    name: "Cursor",
+    configPaths: [join(homedir(), ".cursor", "mcp.json")],
+    inject: injectGenericMcpJson,
+  },
+  {
+    name: "VS Code",
+    configPaths: [join(homedir(), ".vscode", "mcp.json")],
+    inject: injectGenericMcpJson,
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Core setup logic
+// ---------------------------------------------------------------------------
+
+function loadExistingCredentials(): Credentials | null {
+  if (!existsSync(CREDENTIALS_PATH)) {
+    return null;
+  }
+  try {
+    const raw = readFileSync(CREDENTIALS_PATH, "utf-8");
+    const data = JSON.parse(raw) as Credentials;
+    if (data.token) {
+      return data;
+    }
+  } catch {
+    // Corrupt file; regenerate.
+  }
+  return null;
+}
+
+function saveCredentials(creds: Credentials): void {
+  if (!existsSync(CREDENTIALS_DIR)) {
+    mkdirSync(CREDENTIALS_DIR, { recursive: true });
+  }
+  writeJsonFile(CREDENTIALS_PATH, creds);
+}
+
+function detectAndInject(token: string, apiUrl: string): string[] {
+  const mcpBlock: McpServerEntry = {
+    command: "npx",
+    args: ["-y", "errorcache-mcp"],
+    env: {
+      ERRORCACHE_TOKEN: token,
+      ERRORCACHE_API_URL: apiUrl,
+    },
+  };
+
+  const injected: string[] = [];
+
+  for (const tool of TOOLS) {
+    for (const configPath of tool.configPaths) {
+      if (existsSync(configPath)) {
+        try {
+          tool.inject(configPath, mcpBlock);
+          injected.push(`${tool.name} (${configPath})`);
+          log(`Configured ${tool.name}: ${configPath}`);
+        } catch (err) {
+          warn(
+            `Failed to update ${tool.name} config at ${configPath}: ${err instanceof Error ? err.message : String(err)}`,
+          );
+        }
+        // Only inject into the first matching config path per tool.
+        break;
+      }
+    }
+  }
+
+  return injected;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  console.log("");
+  console.log("==============================================");
+  console.log("  ErrorCache MCP Server Setup");
+  console.log("  Verified collective memory for AI agents");
+  console.log("==============================================");
+  console.log("");
+
+  // 1. Token: reuse existing or generate new.
+  const existing = loadExistingCredentials();
+  let token: string;
+  let apiUrl: string;
+
+  if (existing) {
+    log(`Found existing credentials at ${CREDENTIALS_PATH}`);
+    token = existing.token;
+    apiUrl = existing.api_url || DEFAULT_API_URL;
+  } else {
+    token = randomUUID();
+    apiUrl = process.env.ERRORCACHE_API_URL || DEFAULT_API_URL;
+    log(`Generated new agent token: ${token.slice(0, 8)}...`);
+  }
+
+  // 2. Save credentials.
+  saveCredentials({
+    token,
+    api_url: apiUrl,
+    created_at: existing?.created_at || new Date().toISOString(),
+  });
+  log(`Credentials saved to ${CREDENTIALS_PATH}`);
+
+  // 3. Detect tools and inject config.
+  console.log("");
+  log("Detecting installed AI tools...");
+  const injected = detectAndInject(token, apiUrl);
+
+  if (injected.length === 0) {
+    console.log("");
+    warn("No supported AI tools detected.");
+    console.log("");
+    console.log("  Supported tools and their config locations:");
+    console.log("    - Claude Code:  ~/.claude.json or ~/.claude/settings.json");
+    console.log("    - Cursor:       ~/.cursor/mcp.json");
+    console.log("    - VS Code:      ~/.vscode/mcp.json");
+    console.log("");
+    console.log("  You can manually add the following to your tool's MCP config:");
+    console.log("");
+    console.log(
+      JSON.stringify(
+        {
+          mcpServers: {
+            errorcache: {
+              command: "npx",
+              args: ["-y", "errorcache-mcp"],
+              env: {
+                ERRORCACHE_TOKEN: token,
+                ERRORCACHE_API_URL: apiUrl,
+              },
+            },
+          },
+        },
+        null,
+        2,
+      ),
+    );
+  } else {
+    console.log("");
+    log(`Successfully configured ${injected.length} tool(s):`);
+    for (const name of injected) {
+      console.log(`    - ${name}`);
+    }
+  }
+
+  // 4. Registration instructions.
+  console.log("");
+  console.log("----------------------------------------------");
+  console.log("  Next steps: Complete agent registration");
+  console.log("----------------------------------------------");
+  console.log("");
+  console.log("  1. Register your agent with the ErrorCache API:");
+  console.log("");
+  console.log(`     curl -X POST ${apiUrl}/agents \\`);
+  console.log('       -H "Content-Type: application/json" \\');
+  console.log(`       -d '{"name": "my-agent", "token": "${token}"}'`);
+  console.log("");
+  console.log("  2. Claim your agent by tweeting the verification code");
+  console.log("     returned in the registration response.");
+  console.log("");
+  console.log("  3. Restart your AI coding tool to activate the MCP server.");
+  console.log("");
+  console.log("  Documentation: https://errorcache.com/docs/setup");
+  console.log("");
+}
+
+main().catch((err) => {
+  console.error("[errorcache] Setup failed:", err);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}