@standardbeagle/errlookup-mcp 0.1.0

package/README.md

@@ -0,0 +1,36 @@
+# @standardbeagle/errlookup-mcp
+
+MCP server that answers **"what is this error and how do I fix it"** for open-source libraries, from a locally cached static dataset published at [errors.standardbeagle.com](https://errors.standardbeagle.com).
+
+No backend: on first use it downloads versioned JSON from the CDN, caches under `~/.cache/errlookup/`, and serves every query offline-capable from disk.
+
+## Install
+
+```json
+{
+  "mcpServers": {
+    "errlookup": {
+      "command": "npx",
+      "args": ["-y", "@standardbeagle/errlookup-mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+- `search_error` — pass a raw runtime error message; tiered matching (exact code → message pattern → fuzzy) returns scored matches with citations.
+- `get_error` — full record for one error: explanation, ordered solutions, example fix, defensive patterns, source permalink.
+- `list_repos` — analyzed repositories and their error counts.
+- `refresh_dataset` — force a freshness check against the published manifest.
+
+## Config (env)
+
+| var | default | |
+|---|---|---|
+| `ERRLOOKUP_BASE_URL` | `https://errors.standardbeagle.com` | dataset origin |
+| `ERRLOOKUP_CACHE_DIR` | `$XDG_CACHE_HOME/errlookup` | cache location |
+| `ERRLOOKUP_TTL_SECONDS` | `300` | manifest poll interval |
+| `ERRLOOKUP_OFFLINE` | unset | `1` = never fetch, cache only |
+
+Data is AI-assisted analysis of public repositories, pinned to the analyzed commit SHA — every result links its source and its JSON twin.

package/dist/index.js

@@ -0,0 +1,452 @@
+#!/usr/bin/env node
+#!/usr/bin/env node
+
+// src/server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+
+// src/cache.ts
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { homedir } from "node:os";
+
+// src/base-url.ts
+var DEFAULT_BASE_URL = "https://errors.standardbeagle.com";
+function siteBaseUrl(env = process.env) {
+  return (env.ERRLOOKUP_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+}
+function siteErrorUrl(repo, slug) {
+  const [owner, name] = repo.split("/");
+  return `${siteBaseUrl()}/${owner}/${name}/${slug}/`;
+}
+
+// src/cache.ts
+function defaultCacheConfig(env = process.env) {
+  const xdg = env.XDG_CACHE_HOME || join(homedir(), ".cache");
+  return {
+    baseUrl: siteBaseUrl(env),
+    cacheDir: env.ERRLOOKUP_CACHE_DIR ?? join(xdg, "errlookup"),
+    ttlSeconds: Number.parseInt(env.ERRLOOKUP_TTL_SECONDS ?? "300", 10),
+    offline: env.ERRLOOKUP_OFFLINE === "1"
+  };
+}
+function fileExists(p) {
+  return existsSync(p);
+}
+function readJson(p) {
+  return JSON.parse(readFileSync(p, "utf8"));
+}
+function atomicWrite(p, content) {
+  mkdirSync(dirname(p), { recursive: true });
+  const tmp = `${p}.tmp-${process.pid}`;
+  writeFileSync(tmp, content, "utf8");
+  renameSync(tmp, p);
+}
+function sha256(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+var CacheStore = class {
+  constructor(cfg) {
+    this.cfg = cfg;
+  }
+  get dir() {
+    return this.cfg.cacheDir;
+  }
+  manifestPath() {
+    return join(this.cfg.cacheDir, "manifest.json");
+  }
+  indexPath() {
+    return join(this.cfg.cacheDir, "index.json");
+  }
+  repoPath(repo) {
+    const [owner, name] = repo.split("/");
+    return join(this.cfg.cacheDir, "repos", `${owner}`, `${name}.json`);
+  }
+  hasManifest() {
+    return fileExists(this.manifestPath());
+  }
+  readManifest() {
+    return this.hasManifest() ? readJson(this.manifestPath()) : null;
+  }
+  readIndex() {
+    return fileExists(this.indexPath()) ? readJson(this.indexPath()) : null;
+  }
+  readRepo(repo) {
+    const p = this.repoPath(repo);
+    return fileExists(p) ? readJson(p) : null;
+  }
+  /**
+   * Download a file, verify its sha256 against the manifest, write atomically.
+   * Returns false (and keeps the old cache) if the hash mismatches — corrupt
+   * downloads are rejected, never served (§8 mcp suite).
+   */
+  async fetchVerified(urlPath, dest, expectedSha) {
+    const url = `${this.cfg.baseUrl}${urlPath}`;
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`GET ${urlPath} \u2192 ${res.status}`);
+    const text = await res.text();
+    if (expectedSha && sha256(text) !== expectedSha) {
+      return false;
+    }
+    atomicWrite(dest, text);
+    return true;
+  }
+};
+
+// src/sync.ts
+async function syncDataset(store, ttlOk) {
+  const cachedManifest = store.readManifest();
+  const cachedIndex = store.readIndex();
+  if (ttlOk) {
+    return {
+      updated: false,
+      datasetVersion: cachedManifest?.datasetVersion ?? null,
+      errorCount: cachedIndex?.errors.length ?? 0,
+      stale: false
+    };
+  }
+  let manifest;
+  try {
+    const ok = await store.fetchVerified("/data/manifest.json", store.manifestPath());
+    if (!ok) {
+      return staleOrError(store, cachedManifest, cachedIndex);
+    }
+    manifest = store.readManifest();
+  } catch {
+    return staleOrError(store, cachedManifest, cachedIndex);
+  }
+  if (cachedManifest && manifest.datasetVersion === cachedManifest.datasetVersion && cachedIndex) {
+    return { updated: false, datasetVersion: manifest.datasetVersion, errorCount: cachedIndex.errors.length, stale: false };
+  }
+  try {
+    const ok = await store.fetchVerified(
+      "/data/index.json",
+      store.indexPath(),
+      manifest.files.index?.sha256
+    );
+    if (!ok) {
+      return staleOrError(store, cachedManifest, cachedIndex);
+    }
+    const idx = store.readIndex();
+    return { updated: true, datasetVersion: manifest.datasetVersion, errorCount: idx.errors.length, stale: false };
+  } catch {
+    return staleOrError(store, cachedManifest, cachedIndex);
+  }
+}
+function staleOrError(store, cachedManifest, cachedIndex) {
+  if (cachedManifest && cachedIndex) {
+    return {
+      updated: false,
+      datasetVersion: cachedManifest.datasetVersion,
+      errorCount: cachedIndex.errors.length,
+      stale: true
+    };
+  }
+  return { updated: false, datasetVersion: null, errorCount: 0, stale: true };
+}
+
+// src/search.ts
+var PATTERN_BUDGET_MS = 50;
+var FUZZY_THRESHOLD = 0.4;
+function extractCodeTokens(input) {
+  const tokens = /* @__PURE__ */ new Set();
+  for (const m of input.matchAll(/\b[A-Z][A-Z0-9_]{2,}\b/g)) tokens.add(m[0]);
+  for (const m of input.matchAll(/\bE[A-Z]+\b/g)) tokens.add(m[0]);
+  return tokens;
+}
+function tierExactCode(input, errors) {
+  const tokens = extractCodeTokens(input);
+  if (tokens.size === 0) return [];
+  return errors.filter((e) => e.code !== null && tokens.has(e.code));
+}
+function tierPattern(input, errors) {
+  const start = Date.now();
+  const hits = [];
+  for (const e of errors) {
+    if (e.pattern.length > 500) continue;
+    if (Date.now() - start > PATTERN_BUDGET_MS) break;
+    try {
+      if (new RegExp(e.pattern).test(input)) hits.push(e);
+    } catch {
+    }
+  }
+  return hits;
+}
+function normalizeForFuzzy(s) {
+  return s.toLowerCase().replace(/\/[\w./-]+/g, " ").replace(/0x[0-9a-f]+/g, " ").replace(/\b\d+\b/g, " ").replace(/'[^']*'|"[^"]*"/g, " ").replace(/[^a-z ]+/g, " ").replace(/\s+/g, " ").trim();
+}
+function buildIdf(errors) {
+  const df = /* @__PURE__ */ new Map();
+  const N = errors.length || 1;
+  for (const e of errors) {
+    const seen = new Set(normalizeForFuzzy(e.msg).split(" ").filter(Boolean));
+    for (const t of seen) df.set(t, (df.get(t) ?? 0) + 1);
+  }
+  const idf = /* @__PURE__ */ new Map();
+  for (const [t, d] of df) idf.set(t, Math.log((N + 1) / (d + 1)) + 1);
+  return idf;
+}
+function tierFuzzy(input, errors, idf) {
+  const inTokens = new Set(normalizeForFuzzy(input).split(" ").filter(Boolean));
+  if (inTokens.size === 0) return [];
+  const scored = [];
+  for (const e of errors) {
+    const eTokens = new Set(normalizeForFuzzy(e.msg).split(" ").filter(Boolean));
+    if (eTokens.size === 0) continue;
+    let inter = 0;
+    let union = 0;
+    const all = /* @__PURE__ */ new Set([...inTokens, ...eTokens]);
+    for (const t of all) {
+      const w = idf.get(t) ?? 1;
+      const inA = inTokens.has(t);
+      const inB = eTokens.has(t);
+      if (inA && inB) inter += w;
+      union += w;
+    }
+    const score = union > 0 ? inter / union : 0;
+    if (score >= FUZZY_THRESHOLD) scored.push({ entry: e, score });
+  }
+  return scored.sort((a, b) => b.score - a.score);
+}
+function toHit(e, score, matchType) {
+  return {
+    id: e.id,
+    repo: e.repo,
+    code: e.code,
+    message: e.msg,
+    score,
+    matchType,
+    url: siteErrorUrl(e.repo, e.slug)
+  };
+}
+function searchErrors(input, errors, opts = {}) {
+  const limit = opts.limit ?? 5;
+  const pool = opts.repo ? errors.filter((e) => e.repo === opts.repo) : errors;
+  if (pool.length === 0) return [];
+  const code = tierExactCode(input, pool);
+  if (code.length > 0) {
+    return dedupe(code.map((e) => toHit(e, 1, "exact-code"))).slice(0, limit);
+  }
+  const pat = tierPattern(input, pool);
+  if (pat.length > 0) {
+    return dedupe(pat.map((e) => toHit(e, 0.9, "pattern"))).slice(0, limit);
+  }
+  const idf = buildIdf(pool);
+  const fuzzy = tierFuzzy(input, pool, idf);
+  if (fuzzy.length > 0) {
+    return dedupe(fuzzy.map((f) => toHit(f.entry, round(f.score), "fuzzy"))).slice(0, limit);
+  }
+  return [];
+}
+function dedupe(hits) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const h of hits) if (!seen.has(h.id)) seen.set(h.id, h);
+  return [...seen.values()];
+}
+function round(n) {
+  return Math.round(n * 1e3) / 1e3;
+}
+
+// src/tools.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
+async function ensureFresh(ctx) {
+  const now = Date.now();
+  const ttlOk = now - ctx.lastSyncAt < ctx.ttlSeconds * 1e3;
+  return syncDataset(ctx.store, ttlOk);
+}
+function manifestVersion(ctx) {
+  return ctx.store.readManifest()?.datasetVersion ?? null;
+}
+async function toolSearchError(ctx, args) {
+  await ensureFresh(ctx);
+  const idx = ctx.store.readIndex();
+  if (!idx) {
+    throw new Error("No dataset cached and network unavailable. Run `refresh_dataset` while online.");
+  }
+  const matches = searchErrors(args.message, idx.errors, { repo: args.repo, limit: args.limit });
+  return { matches, datasetVersion: idx.datasetVersion, stale: false };
+}
+async function loadRepoRecords(ctx, repo) {
+  let cached = ctx.store.readRepo(repo);
+  if (!cached) {
+    const manifest = ctx.store.readManifest();
+    if (!manifest) throw new Error("No manifest cached; refresh while online.");
+    await ctx.store.fetchVerified(`/data/repos/${repo.split("/").join("/")}.json`, ctx.store.repoPath(repo));
+    cached = ctx.store.readRepo(repo);
+  }
+  return cached ?? [];
+}
+async function toolGetError(ctx, args) {
+  await ensureFresh(ctx);
+  const idx = ctx.store.readIndex();
+  if (!idx) throw new Error("No dataset cached and network unavailable.");
+  let match;
+  if (args.id) {
+    match = idx.errors.find((e) => e.id === args.id);
+  } else if (args.repo && args.slug) {
+    match = idx.errors.find((e) => e.repo === args.repo && e.slug === args.slug);
+  }
+  if (!match) throw new Error("Error not found in index.");
+  const url = siteErrorUrl(match.repo, match.slug);
+  const records = await loadRepoRecords(ctx, match.repo);
+  const full = records.find((r) => r.id === match.id);
+  if (!full) throw new Error(`Record ${match.id} missing from repo file.`);
+  return { markdown: renderMarkdown(full), url, datasetVersion: idx.datasetVersion };
+}
+async function toolListRepos(ctx) {
+  await ensureFresh(ctx);
+  const reposPath = `${ctx.store.dir}/repos.json`;
+  if (!existsSync2(reposPath)) {
+    try {
+      await ctx.store.fetchVerified("/data/repos.json", reposPath);
+    } catch {
+    }
+  }
+  let repos = [];
+  try {
+    repos = JSON.parse(readFileSync2(reposPath, "utf8"));
+  } catch {
+    const idx = ctx.store.readIndex();
+    if (idx) {
+      const byRepo = /* @__PURE__ */ new Map();
+      for (const e of idx.errors) byRepo.set(e.repo, (byRepo.get(e.repo) ?? 0) + 1);
+      repos = [...byRepo.entries()].map(([repo, errorCount]) => ({ repo, description: null, errorCount }));
+    }
+  }
+  return { repos, datasetVersion: manifestVersion(ctx) };
+}
+async function toolRefreshDataset(ctx) {
+  const r = await syncDataset(ctx.store, false);
+  if (r.datasetVersion) ctx.lastSyncAt = Date.now();
+  return { updated: r.updated, datasetVersion: r.datasetVersion, errors: r.errorCount };
+}
+function renderMarkdown(e) {
+  const lines = [];
+  lines.push(`# ${e.errorCode ?? e.errorMessage.slice(0, 80)}`);
+  lines.push("");
+  lines.push(`**Repo:** ${e.repo}`);
+  lines.push(`**Message:** \`${e.errorMessage}\``);
+  if (e.errorClass) lines.push(`**Class:** ${e.errorClass}`);
+  lines.push(`**Severity:** ${e.severity}`);
+  lines.push("");
+  lines.push("## What it means");
+  lines.push(e.documentation);
+  lines.push("");
+  if (e.solutions.length > 0) {
+    lines.push("## Solutions");
+    for (let i = 0; i < e.solutions.length; i++) lines.push(`${i + 1}. ${e.solutions[i]}`);
+    lines.push("");
+  }
+  if (e.exampleFix) {
+    lines.push("## Example fix");
+    lines.push("```");
+    lines.push(e.exampleFix);
+    lines.push("```");
+    lines.push("");
+  }
+  if (e.handlingStrategy || e.tryCatchPattern || e.preventionTips.length > 0) {
+    lines.push("## Defensive pattern");
+    if (e.handlingStrategy) lines.push(`Strategy: ${e.handlingStrategy}`);
+    if (e.tryCatchPattern) {
+      lines.push("```");
+      lines.push(e.tryCatchPattern);
+      lines.push("```");
+    }
+    if (e.preventionTips.length > 0) lines.push(`Prevention: ${e.preventionTips.join("; ")}`);
+    lines.push("");
+  }
+  lines.push(`Source: ${e.githubUrl}`);
+  lines.push(`Analyzed: ${e.repo}@${e.analyzedSha.slice(0, 10)} on ${e.analyzedAt.slice(0, 10)}`);
+  return lines.join("\n");
+}
+
+// src/server.ts
+var TOOLS = [
+  {
+    name: "search_error",
+    description: "Look up what a runtime error from an open-source library means and how to fix it. Call this when you encounter an error message from a library. Pass the raw message verbatim; error codes (SCREAMING_SNAKE / E[A-Z]+) are matched exactly first.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        message: { type: "string", description: "The raw error message verbatim." },
+        repo: { type: "string", description: "Optional 'owner/name' filter." },
+        limit: { type: "number", description: "Max results (default 5)." }
+      },
+      required: ["message"]
+    }
+  },
+  {
+    name: "get_error",
+    description: "Fetch the full record for one error by id, or by repo+slug. Returns markdown documentation, solutions, and a defensive pattern ready to apply. Cite the returned URL.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string" },
+        repo: { type: "string" },
+        slug: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "list_repos",
+    description: "List the open-source repos covered by the ErrLookup dataset.",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "refresh_dataset",
+    description: "Force a freshness check against the ErrLookup CDN. Returns the current dataset version.",
+    inputSchema: { type: "object", properties: {} }
+  }
+];
+function createContext() {
+  const cfg = defaultCacheConfig();
+  const store = new CacheStore(cfg);
+  return { store, lastSyncAt: 0, ttlSeconds: cfg.ttlSeconds };
+}
+async function runServer(ctx = createContext()) {
+  const server = new Server(
+    { name: "errlookup", version: "0.1.0" },
+    { capabilities: { tools: {} } }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: TOOLS }));
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args } = req.params;
+    try {
+      switch (name) {
+        case "search_error": {
+          const r = await toolSearchError(ctx, args ?? {});
+          return { content: [{ type: "text", text: JSON.stringify(r) }] };
+        }
+        case "get_error": {
+          const r = await toolGetError(ctx, args ?? {});
+          return { content: [{ type: "text", text: r.markdown }, { type: "text", text: `Source: ${r.url}` }] };
+        }
+        case "list_repos": {
+          const r = await toolListRepos(ctx);
+          return { content: [{ type: "text", text: JSON.stringify(r) }] };
+        }
+        case "refresh_dataset": {
+          const r = await toolRefreshDataset(ctx);
+          return { content: [{ type: "text", text: JSON.stringify(r) }] };
+        }
+        default:
+          return { content: [{ type: "text", text: `unknown tool: ${name}` }], isError: true };
+      }
+    } catch (e) {
+      return { content: [{ type: "text", text: e.message }], isError: true };
+    }
+  });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+// src/index.ts
+runServer().catch((e) => {
+  console.error(e.stack ?? e.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@standardbeagle/errlookup-mcp",
+  "version": "0.1.0",
+  "description": "ErrLookup MCP server — answers 'what is this error and how do I fix it' from a cached static dataset (errors.standardbeagle.com).",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "errlookup-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node20 --outfile=dist/index.js --external:@modelcontextprotocol/sdk --banner:js=\"#!/usr/bin/env node\"",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8",
+    "esbuild": "^0.25.0",
+    "@errlookup/schema": "workspace:*"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/standardbeagle/err-lookup.git",
+    "directory": "packages/mcp"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}