evrex-mcp 0.1.0

package/README.md

@@ -0,0 +1,72 @@
+# evrex-mcp
+
+Gives a coding agent the reasoning behind a repo that the code itself doesn't
+carry: prior decisions, hard constraints, and approaches the team already tried
+and rejected.
+
+Your agent reads the code. It cannot read the conversation where someone
+explained *why* the cache was dropped, or the afternoon you spent proving an
+approach doesn't work. So it re-proposes it. This server closes that gap by
+indexing your Claude Code and Cursor session transcripts alongside git history,
+linking sessions to the commits they produced, and serving that back as tools.
+
+## Install
+
+You need an evrex API token — issue one from the evrex dashboard.
+
+**Claude Code**
+
+```bash
+claude mcp add evrex --env EVREX_TOKEN=evx_your_token -- npx -y evrex-mcp
+```
+
+**Cursor** — add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "evrex": {
+      "command": "npx",
+      "args": ["-y", "evrex-mcp"],
+      "env": { "EVREX_TOKEN": "evx_your_token" }
+    }
+  }
+}
+```
+
+Reload Cursor afterwards so it picks up the new server.
+
+## Tools
+
+| Tool | Use it for |
+|---|---|
+| `evrex_why` | Why a specific file is built the way it is, and what was already rejected for it. Call it before a nontrivial edit. |
+| `evrex_search` | Open-ended questions across session and commit history — "have we discussed this", "when did we start doing X". |
+| `evrex_commit_context` | The session behind a commit: what was being attempted and what it decided. |
+
+## Configuration
+
+| Variable | Required | Purpose |
+|---|---|---|
+| `EVREX_TOKEN` | **yes** | Your evrex API token. The server exits at startup with instructions if it's missing. |
+| `ANTHROPIC_API_KEY` | no | Synthesizes retrieved evidence into a direct answer. Without it, tools return ranked evidence excerpts and say why they're unsummarized — a working server, just a quieter one. |
+| `EVREX_API_BASE_URL` | no | Point at a self-hosted evrex backend. Defaults to the hosted one. |
+| `ANTHROPIC_MODEL` | no | Defaults to `claude-opus-5`. |
+
+Answer synthesis runs **on your machine with your own key**. The evrex backend
+holds no model-provider credential, so your transcripts are never sent through
+someone else's API account.
+
+## What it does not do
+
+- It won't invent reasoning. A file with nothing indexed about it returns "no
+  recorded reasoning found" rather than a plausible guess.
+- Extraction done without an Anthropic key falls back to cue-phrase matching,
+  and output derived that way is labeled as such — so you can tell a regex hit
+  from a model that actually read the conversation.
+- Every answer sentence cites the evidence supporting it. An answer citing
+  evidence that wasn't retrieved is rejected rather than shown.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,517 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// src/tools.ts
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve as resolvePath } from "node:path";
+
+// src/client.ts
+var DEFAULT_API_BASE_URL = "https://evrex-backend-production.up.railway.app";
+var API_BASE_URL = (process.env.EVREX_API_BASE_URL ?? process.env.EVREX_API_URL ?? DEFAULT_API_BASE_URL).replace(/\/+$/, "");
+var EVREX_TOKEN = process.env.EVREX_TOKEN ?? process.env.EVREX_API_TOKEN ?? null;
+function headers() {
+  const base = { "Content-Type": "application/json" };
+  if (EVREX_TOKEN) base.Authorization = `Bearer ${EVREX_TOKEN}`;
+  return base;
+}
+function describeFailure(method, path, status, statusText) {
+  if (status === 401 || status === 403) {
+    return EVREX_TOKEN ? `${method} ${path} -> ${status}: the EVREX_TOKEN this server was started with was rejected. It may be revoked or expired.` : `${method} ${path} -> ${status}: this evrex backend requires a credential, but no EVREX_TOKEN is set for this MCP server.`;
+  }
+  return `${method} ${path} -> ${status} ${statusText}`;
+}
+async function get(path) {
+  const res = await fetch(`${API_BASE_URL}${path}`, { headers: headers() });
+  if (!res.ok) throw new Error(describeFailure("GET", path, res.status, res.statusText));
+  return await res.json();
+}
+async function post(path, body) {
+  const res = await fetch(`${API_BASE_URL}${path}`, {
+    method: "POST",
+    headers: headers(),
+    body: JSON.stringify(body)
+  });
+  if (!res.ok) throw new Error(describeFailure("POST", path, res.status, res.statusText));
+  return await res.json();
+}
+var evrexApi = {
+  baseUrl: API_BASE_URL,
+  repos: () => get("/repos"),
+  commits: (repoPath) => get(`/commits?repoPath=${encodeURIComponent(repoPath)}`),
+  commit: (sha) => get(`/commits/${sha}`).catch(() => null),
+  sessions: (repoPath) => get(`/sessions?repoPath=${encodeURIComponent(repoPath)}`),
+  session: (id) => get(`/sessions/${id}`).catch(() => null),
+  ask: (repoPath, text, filePaths) => post("/ask", { repoPath, text, filePaths }),
+  // Evidence-only retrieval (BM25 + embedding), no LLM synthesis call — see
+  // apps/backend/src/query/query.service.ts#search. Used by evrex_search,
+  // which wants ranked hits fast, not a synthesized paragraph.
+  search: (repoPath, text, filePaths) => post("/search", { repoPath, text, filePaths })
+};
+
+// ../../packages/llm-core/src/client.ts
+import Anthropic from "@anthropic-ai/sdk";
+var DEFAULT_MODEL = "claude-opus-5";
+var DEFAULT_MAX_TOKENS = 16e3;
+function createAnthropicClient(apiKey) {
+  if (!apiKey || apiKey.trim().length === 0) return null;
+  return new Anthropic({ apiKey });
+}
+
+// ../../packages/llm-core/src/complete.ts
+import Anthropic2 from "@anthropic-ai/sdk";
+var NOOP_LOGGER = { warn: () => void 0, error: () => void 0 };
+function parseableFormat(schema) {
+  return {
+    type: "json_schema",
+    schema,
+    parse: (content) => JSON.parse(content)
+  };
+}
+function textOf(message) {
+  return message.content.filter((block) => block.type === "text").map((block) => block.text).join("");
+}
+function describe(err) {
+  if (err instanceof Anthropic2.RateLimitError) {
+    return `rate limited (${err.status}): ${err.message}`;
+  }
+  if (err instanceof Anthropic2.APIConnectionError) {
+    return `could not reach the provider: ${err.message}`;
+  }
+  if (err instanceof Anthropic2.APIError) {
+    return `provider returned ${err.status ?? "an error"}: ${err.message}`;
+  }
+  return String(err);
+}
+async function completeJson(client2, options) {
+  if (!client2) return null;
+  const logger = options.logger ?? NOOP_LOGGER;
+  const model = options.model ?? DEFAULT_MODEL;
+  const max_tokens = options.maxTokens ?? DEFAULT_MAX_TOKENS;
+  const output_config = {};
+  if (options.schema) output_config.format = parseableFormat(options.schema);
+  if (options.effort) output_config.effort = options.effort;
+  const request = {
+    model,
+    max_tokens,
+    system: options.system,
+    messages: [{ role: "user", content: options.user }],
+    ...Object.keys(output_config).length > 0 ? { output_config } : {}
+  };
+  let raw;
+  try {
+    if (options.schema) {
+      const message = await client2.messages.parse(request);
+      raw = message.parsed_output;
+      if (raw === null || raw === void 0) {
+        logger.warn(
+          "Model returned no parseable JSON for a schema-constrained call."
+        );
+        return null;
+      }
+    } else {
+      const message = await client2.messages.create(request);
+      const text = textOf(message).trim();
+      if (!text) return null;
+      raw = JSON.parse(text);
+    }
+  } catch (err) {
+    logger.error(`Model call failed: ${describe(err)}`);
+    return null;
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    logger.warn("Model returned a non-object JSON body; discarding it.");
+    return null;
+  }
+  if (options.validate && !options.validate(raw)) {
+    logger.warn("Model response violated the expected schema; discarding it.");
+    return null;
+  }
+  return raw;
+}
+
+// ../../packages/llm-core/src/extraction.ts
+var MAX_ITEMS_PER_CATEGORY = 6;
+var EXTRACTION_SYSTEM_PROMPT = [
+  "You extract structured reasoning from a real coding-agent session transcript for Evrex, a tool that recovers WHY code changed, not just what changed.",
+  `Each line is labeled "user" (the human engineer actually typed this), "assistant" (the agent), or "tool_result" (raw output from a tool call, e.g. command stdout \u2014 NOT something either party said; never attribute a "tool_result" line's content to "engineer" as raisedBy/source).`,
+  "Only extract items explicitly present in the transcript below. Never invent, infer beyond the text, or pad categories with generic filler.",
+  "If a category has nothing genuinely present, return an empty array for it \u2014 an empty result is correct and expected, not a failure.",
+  `Cap each array at ${MAX_ITEMS_PER_CATEGORY} items \u2014 pick the most consequential ones.`,
+  '"atMessage" is the [N] index of the transcript line the item came from.',
+  'For a rejected approach, "reason" is why it was turned down and "tradeoff" is what was given up by not taking it. Fill "tradeoff" from the transcript whenever the cost is stated or clearly implied; leave it empty only when the transcript genuinely says nothing about it.'
+].join(" ");
+
+// ../../packages/llm-core/src/synthesis.ts
+var MIN_SENTENCES = 1;
+var MAX_SENTENCES = 4;
+var SYNTHESIS_SYSTEM_PROMPT = `You answer questions about why code changed, using ONLY the evidence provided below. Never state a claim that is not directly supported by the evidence text. Respond with a JSON object: {"sentences": string[], "sentenceEvidence": number[][], "noRecordedReasoning": boolean}. Write 2-4 sentences when the evidence supports an answer; each sentence's entry in "sentenceEvidence" lists only the evidence indices (0-based) that directly support it. If the evidence is too thin or unrelated to actually answer the question, set "noRecordedReasoning": true and return empty arrays for "sentences" and "sentenceEvidence" \u2014 do not speculate or hedge.`;
+var SYNTHESIS_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  required: ["sentences", "sentenceEvidence", "noRecordedReasoning"],
+  properties: {
+    sentences: { type: "array", items: { type: "string" } },
+    sentenceEvidence: {
+      type: "array",
+      items: { type: "array", items: { type: "integer" } }
+    },
+    noRecordedReasoning: { type: "boolean" }
+  }
+};
+function buildSynthesisPrompt(question, evidence) {
+  const list = evidence.map(
+    (e, i) => `[${i}] (${e.kind}, confidence ${(e.confidence ?? 1).toFixed(2)}): ${e.excerpt}`
+  ).join("\n");
+  return `Question: ${question}
+
+Evidence:
+${list}`;
+}
+function isValidSynthesis(result, evidenceCount) {
+  if (result.noRecordedReasoning === true) return true;
+  if (!Array.isArray(result.sentences) || !Array.isArray(result.sentenceEvidence)) {
+    return false;
+  }
+  if (result.sentences.length < MIN_SENTENCES || result.sentences.length > MAX_SENTENCES) {
+    return false;
+  }
+  if (result.sentences.length !== result.sentenceEvidence.length) return false;
+  return result.sentenceEvidence.every(
+    (indices) => Array.isArray(indices) && indices.every(
+      (i) => typeof i === "number" && Number.isInteger(i) && i >= 0 && i < evidenceCount
+    )
+  );
+}
+async function synthesizeAnswer(question, evidence, client2, options = {}) {
+  const raw = await completeJson(client2, {
+    system: SYNTHESIS_SYSTEM_PROMPT,
+    user: buildSynthesisPrompt(question, evidence),
+    schema: SYNTHESIS_SCHEMA,
+    validate: (value) => typeof value === "object" && value !== null && isValidSynthesis(value, evidence.length),
+    logger: options.logger,
+    model: options.model,
+    effort: options.effort
+  });
+  if (!raw) return null;
+  return {
+    sentences: raw.sentences ?? [],
+    sentenceEvidence: raw.sentenceEvidence ?? [],
+    noRecordedReasoning: Boolean(raw.noRecordedReasoning)
+  };
+}
+
+// src/synthesize.ts
+var ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY ?? void 0;
+var ANTHROPIC_MODEL = process.env.ANTHROPIC_MODEL;
+var stderrLogger = {
+  warn: (message) => process.stderr.write(`[evrex] ${message}
+`),
+  error: (message) => process.stderr.write(`[evrex] ${message}
+`)
+};
+var client = createAnthropicKeyClient();
+function createAnthropicKeyClient() {
+  return createAnthropicClient(ANTHROPIC_API_KEY);
+}
+function toSynthesisEvidence(evidence) {
+  return evidence.map((e) => ({
+    kind: e.kind,
+    excerpt: e.excerpt,
+    confidence: e.provenance.confidence
+  }));
+}
+async function synthesize(question, evidence) {
+  if (evidence.length === 0) {
+    throw new Error("synthesize() requires evidence; check for an empty set before calling.");
+  }
+  if (!client) {
+    return {
+      sentences: null,
+      reason: "No ANTHROPIC_API_KEY is set for this MCP server, so the evidence below is ranked but not summarized."
+    };
+  }
+  const result = await synthesizeAnswer(question, toSynthesisEvidence(evidence), client, {
+    logger: stderrLogger,
+    model: ANTHROPIC_MODEL
+  });
+  if (!result) {
+    return {
+      sentences: null,
+      reason: "Answer synthesis failed or returned an answer citing evidence it was not given, so the evidence below is ranked but not summarized."
+    };
+  }
+  if (result.noRecordedReasoning || result.sentences.length === 0) {
+    return {
+      sentences: null,
+      reason: "The retrieved evidence was too thin to answer the question directly, so it is listed below unsummarized."
+    };
+  }
+  return { sentences: result.sentences };
+}
+
+// src/tools.ts
+var MAX_EXCERPT = 220;
+var MAX_ITEMS = 5;
+function truncate(text, max) {
+  return text.length > max ? `${text.slice(0, max - 1)}\u2026` : text;
+}
+function normalizeRepoRemote(url) {
+  const trimmed = url.trim();
+  if (!trimmed) return null;
+  let host;
+  let path;
+  const scpLike = /^(?:[^/@]+@)?([^/:@]+\.[^/:@]+):(?!\/)(.+)$/.exec(trimmed);
+  if (scpLike?.[1] && scpLike[2]) {
+    host = scpLike[1];
+    path = scpLike[2];
+  } else {
+    let parsed;
+    try {
+      parsed = new URL(trimmed);
+    } catch {
+      return null;
+    }
+    if (parsed.protocol === "file:" || !parsed.hostname) return null;
+    host = parsed.hostname;
+    path = parsed.pathname;
+  }
+  const cleanedPath = path.replace(/^\/+/, "").replace(/\/+$/, "").replace(/\.git$/i, "");
+  if (!cleanedPath) return null;
+  return `${host}/${cleanedPath}`.toLowerCase();
+}
+function git(cwd, args) {
+  try {
+    return execFileSync("git", args, {
+      cwd,
+      maxBuffer: 1024 * 1024 * 8,
+      stdio: ["ignore", "pipe", "ignore"]
+    }).toString("utf-8").trim();
+  } catch {
+    return null;
+  }
+}
+function gitRootFor(dir) {
+  const root = git(dir, ["rev-parse", "--show-toplevel"]);
+  return root ? root : null;
+}
+function repoIdForRoot(root) {
+  const origin = git(root, ["remote", "get-url", "origin"]);
+  const remotes = origin ? [origin] : (git(root, ["remote"]) ?? "").split("\n").map((n) => n.trim()).filter(Boolean).sort().map((name) => git(root, ["remote", "get-url", name])).filter((url) => !!url);
+  for (const url of remotes) {
+    const normalized = normalizeRepoRemote(url);
+    if (normalized) return `remote:${normalized}`;
+  }
+  const rootShas = (git(root, ["rev-list", "--max-parents=0", "HEAD"]) ?? "").split("\n").map((s) => s.trim()).filter(Boolean).sort();
+  if (rootShas[0]) return `root:${rootShas[0]}`;
+  return `path:${root}`;
+}
+function resolveRepoContext(filePath) {
+  const override = process.env.EVREX_REPO_PATH;
+  if (override) {
+    const root2 = gitRootFor(override) ?? override;
+    return { repoRef: repoIdForRoot(root2), root: root2 };
+  }
+  const absolute = isAbsolute(filePath) ? filePath : resolvePath(process.cwd(), filePath);
+  const root = gitRootFor(dirname(absolute)) ?? gitRootFor(process.cwd());
+  if (!root) return { repoRef: process.cwd(), root: null };
+  return { repoRef: repoIdForRoot(root), root };
+}
+function toRepoRelative(filePath, root) {
+  if (!root || !isAbsolute(filePath)) return filePath;
+  const rel = relative(root, filePath);
+  if (rel && !rel.startsWith("..")) return rel;
+  try {
+    const real = relative(root, realpathSync(filePath));
+    if (real && !real.startsWith("..")) return real;
+  } catch {
+  }
+  return filePath;
+}
+async function resolveRepos() {
+  const override = process.env.EVREX_REPO_PATH;
+  if (override) {
+    const { repoRef } = resolveRepoContext(override);
+    return [{ id: repoRef, name: repoRef, slug: repoRef, commitCount: 0, sessionCount: 0 }];
+  }
+  try {
+    return await evrexApi.repos();
+  } catch {
+    return [];
+  }
+}
+async function evrexWhy(filePath, question) {
+  const { repoRef, root } = resolveRepoContext(filePath);
+  const text = question ?? `What decisions, constraints, and rejected approaches apply to ${filePath}?`;
+  const { evidence } = await evrexApi.search(repoRef, text, [
+    toRepoRelative(isAbsolute(filePath) ? filePath : resolvePath(process.cwd(), filePath), root)
+  ]);
+  if (evidence.length === 0) {
+    return `No recorded reasoning found for ${filePath}. Nothing in the indexed sessions or commit history covers this file's design.`;
+  }
+  const sessionIds = [...new Set(evidence.filter((e) => e.kind === "session").map((e) => e.refId))];
+  const sessions = (await Promise.all(sessionIds.map((id) => evrexApi.session(id)))).filter(
+    (s) => s !== null
+  );
+  const rejected = sessions.flatMap((s) => s.rejected).slice(0, MAX_ITEMS);
+  const constraints = sessions.flatMap((s) => s.constraints).slice(0, MAX_ITEMS);
+  const decisions = sessions.flatMap((s) => s.decisions).slice(0, MAX_ITEMS);
+  const parts = [];
+  const heuristic = sessions.some((s) => s.insightsSource === "heuristic");
+  if (rejected.length > 0) {
+    parts.push(
+      "REJECTED APPROACHES (do not re-propose these without new information):\n" + rejected.map((r) => `- ${r.title} \u2014 ${r.reason}${r.tradeoff ? ` (tradeoff: ${r.tradeoff})` : ""}`).join("\n")
+    );
+  }
+  if (constraints.length > 0) {
+    parts.push("CONSTRAINTS:\n" + constraints.map((c) => `- [${c.source}] ${c.text}`).join("\n"));
+  }
+  if (decisions.length > 0) {
+    parts.push("PRIOR DECISIONS:\n" + decisions.map((d) => `- ${d.title}: ${d.detail}`).join("\n"));
+  }
+  if (heuristic && (rejected.length > 0 || constraints.length > 0 || decisions.length > 0)) {
+    parts.push(
+      "NOTE: the blocks above were extracted by cue-phrase matching, not by a model reading the conversation \u2014 they may be incomplete or miss context."
+    );
+  }
+  const answer = await synthesize(text, evidence);
+  parts.push(answer.sentences ? `ANSWER: ${answer.sentences.join(" ")}` : `ANSWER: ${answer.reason}`);
+  const evidenceLines = evidence.slice(0, MAX_ITEMS).map((e) => {
+    const conf = e.provenance.status === "verified" ? "verified" : `${Math.round((e.provenance.confidence ?? 0) * 100)}%`;
+    return `- [${e.kind} ${conf}] ${truncate(e.excerpt, MAX_EXCERPT)}`;
+  });
+  parts.push(`EVIDENCE:
+${evidenceLines.join("\n")}`);
+  return parts.join("\n\n");
+}
+async function evrexSearch(query) {
+  if (!query.trim()) return "Empty query.";
+  const repos = await resolveRepos();
+  if (repos.length === 0) return "No indexed repos found (GET /repos returned none).";
+  const multiRepo = repos.length > 1;
+  const perRepo = await Promise.all(
+    repos.map(async (repo) => {
+      try {
+        const { evidence } = await evrexApi.search(repo.id, query);
+        return evidence.map((e) => ({ repo, e }));
+      } catch {
+        return [];
+      }
+    })
+  );
+  const results = perRepo.flat();
+  if (results.length === 0) return `No matches for "${query}" across indexed sessions and commits.`;
+  const rank = (e) => e.provenance.status === "verified" ? 1 : e.provenance.confidence ?? 0;
+  results.sort((a, b) => rank(b.e) - rank(a.e));
+  const lines = results.slice(0, MAX_ITEMS * 2).map(({ repo, e }) => {
+    const conf = e.provenance.status === "verified" ? "verified" : `${Math.round((e.provenance.confidence ?? 0) * 100)}%`;
+    const repoTag = multiRepo ? ` \xB7 ${repo.name}` : "";
+    return `- [${e.kind} ${e.refId.slice(0, 8)} ${conf}${repoTag}] ${truncate(e.excerpt.replace(/\s+/g, " ").trim(), MAX_EXCERPT)}`;
+  });
+  return lines.join("\n");
+}
+async function evrexCommitContext(sha) {
+  const commit = await evrexApi.commit(sha);
+  if (!commit) return `No commit found for sha ${sha}.`;
+  const parts = [
+    `COMMIT ${commit.sha.slice(0, 8)}: ${commit.message}${commit.body ? `
+${truncate(commit.body, MAX_EXCERPT)}` : ""}`
+  ];
+  if (commit.link) {
+    const session = await evrexApi.session(commit.link.sessionId);
+    const status = commit.link.provenance.status === "verified" ? "verified" : "inferred";
+    const conf = commit.link.provenance.status === "verified" ? "" : ` (${Math.round((commit.link.provenance.confidence ?? 0) * 100)}%)`;
+    parts.push(`LINKED SESSION (${status}${conf}): ${session ? session.intent : commit.link.sessionId}`);
+    if (session) {
+      if (session.rejected.length > 0) {
+        parts.push(
+          "REJECTED APPROACHES:\n" + session.rejected.slice(0, MAX_ITEMS).map((r) => `- ${r.title} \u2014 ${r.reason}${r.tradeoff ? ` (tradeoff: ${r.tradeoff})` : ""}`).join("\n")
+        );
+      }
+      if (session.constraints.length > 0) {
+        parts.push(
+          "CONSTRAINTS:\n" + session.constraints.slice(0, MAX_ITEMS).map((c) => `- [${c.source}] ${c.text}`).join("\n")
+        );
+      }
+      parts.push(`OUTCOME: ${truncate(session.outcome, MAX_EXCERPT)}`);
+    }
+  } else {
+    parts.push("No session linked \u2014 no recorded reasoning behind this commit.");
+  }
+  if (commit.relatedCommitIds.length > 0) {
+    const relatedShas = commit.relatedCommitIds.slice(0, MAX_ITEMS);
+    const related = (await Promise.all(relatedShas.map((s) => evrexApi.commit(s)))).filter(
+      (c) => c !== null
+    );
+    const lines = related.map((c) => `- ${c.sha.slice(0, 8)}: ${truncate(c.message, 100)}`);
+    parts.push(`RELATED COMMITS:
+${lines.join("\n")}`);
+  }
+  return parts.join("\n\n");
+}
+
+// src/index.ts
+var server = new McpServer({ name: "evrex", version: "0.1.0" });
+server.registerTool(
+  "evrex_why",
+  {
+    title: "Why does this file/change exist?",
+    description: "Prior reasoning for a file: decisions, hard constraints, and explicitly REJECTED approaches, with sources and confidence. Use whenever a question asks 'why' a file or module is built the way it is, what was already considered and rejected, or what constraints apply to it \u2014 and call it before making a nontrivial edit to that file, to avoid re-proposing something already rejected. Not for 'what does this code do' \u2014 read the file for that.",
+    inputSchema: {
+      file_path: z.string().describe("Path to the file, relative to the repo root or absolute"),
+      question: z.string().optional().describe("Optional specific question; defaults to a general 'why' query")
+    }
+  },
+  async ({ file_path, question }) => {
+    const text = await evrexWhy(file_path, question);
+    return { content: [{ type: "text", text }] };
+  }
+);
+server.registerTool(
+  "evrex_search",
+  {
+    title: "Search Evrex sessions and commits",
+    description: "Free-text search across this repo's indexed Claude Code/Cursor session history and git commit history \u2014 surfaces prior discussion and reasoning that lives in conversation, not in the code itself, so grep and git log can't find it. Use for open-ended questions like 'has this been discussed before', 'when/why did we start doing X', or 'what do we know about Y' when you don't have one specific file in mind. If you do have a specific file path, prefer evrex_why instead.",
+    inputSchema: {
+      query: z.string().describe("Free-text search query")
+    }
+  },
+  async ({ query }) => {
+    const text = await evrexSearch(query);
+    return { content: [{ type: "text", text }] };
+  }
+);
+server.registerTool(
+  "evrex_commit_context",
+  {
+    title: "Commit context",
+    description: "The session, tradeoffs, and related commits behind a specific git commit. Use when asked about the story or rationale behind a specific SHA (from `git log`/`git blame`/a PR). If you have a file path instead of a SHA, prefer evrex_why.",
+    inputSchema: {
+      sha: z.string().describe("Git commit SHA (full or abbreviated)")
+    }
+  },
+  async ({ sha }) => {
+    const text = await evrexCommitContext(sha);
+    return { content: [{ type: "text", text }] };
+  }
+);
+function assertConfigured() {
+  if (process.env.EVREX_TOKEN ?? process.env.EVREX_API_TOKEN) return;
+  console.error(
+    "evrex-mcp: EVREX_TOKEN is not set.\n  This server needs an evrex API token to read your team's indexed history.\n  Issue one from the evrex dashboard, then register the server with it:\n    claude mcp add evrex --env EVREX_TOKEN=evx_... -- npx -y evrex-mcp\n  See https://www.npmjs.com/package/evrex-mcp for the Cursor equivalent."
+  );
+  process.exit(1);
+}
+async function main() {
+  assertConfigured();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  console.error("evrex-mcp fatal error:", err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "evrex-mcp",
+  "version": "0.1.0",
+  "description": "MCP server that gives coding agents the recorded reasoning behind a repo: prior decisions, hard constraints, and approaches already rejected.",
+  "keywords": ["mcp", "claude", "cursor", "evrex", "code-context"],
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "evrex-mcp": "dist/index.js"
+  },
+  "files": ["dist/index.js", "README.md"],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "bundle": "node scripts/bundle.mjs",
+    "dev": "tsc -p tsconfig.json --watch",
+    "lint": "eslint .",
+    "check-types": "tsc --noEmit",
+    "test": "tsc -p tsconfig.json && node --test dist/*.test.js",
+    "prepack": "pnpm run bundle"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.72.0",
+    "@modelcontextprotocol/sdk": "^1.20.1",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@repo/eslint-config": "workspace:*",
+    "@repo/llm-core": "workspace:*",
+    "@repo/typescript-config": "workspace:*",
+    "@types/node": "^24.0.0",
+    "esbuild": "^0.25.12",
+    "eslint": "^9.39.1",
+    "typescript": "^5.9.2"
+  }
+}