evrex-mcp 0.1.0 → 0.2.0

package/README.md

@@ -49,13 +49,27 @@ Reload Cursor afterwards so it picks up the new server.
 | 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. |
+| `MODEL_API_KEY` | no | Only used when `EVREX_SYNTHESIZE` is on. Anthropic, OpenAI or Google — the provider is recognised from the key prefix (`sk-ant-…`, `sk-…`, `AIza…`). `ANTHROPIC_API_KEY` is still accepted. |
+| `EVREX_SYNTHESIZE` | no | Set to `1` to have the server summarize evidence into a prose answer before returning it. **Off by default** — see below. |
 | `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.
+## No API credits needed to query
+
+The tools return the recorded context — constraints, rejected approaches, prior
+decisions, and ranked evidence — and let *your agent* reason over it. Your agent
+is already a model reading this output, so summarizing it first would spend a
+model call and latency to hand it *less* to work with.
+
+That means `evrex_why` and friends cost nothing per call. The one place a model
+runs is extraction, once per session when a repo is indexed, on the machine
+that has the transcript — and already-extracted sessions are skipped, so
+re-indexing is nearly free.
+
+Set `EVREX_SYNTHESIZE=1` if you're consuming these tools from something with no
+model of its own — a dashboard, a CI bot. That path uses your own key. The
+evrex backend never holds a model-provider credential either way, so your
+transcripts are never sent through someone else's API account.
 
 ## What it does not do
 

package/dist/index.js

@@ -55,84 +55,10 @@ var evrexApi = {
 
 // ../../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;
@@ -188,16 +114,26 @@ function isValidSynthesis(result, 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;
+  if (!client2) return null;
+  let body;
+  try {
+    body = await client2.completeJson({
+      system: SYNTHESIS_SYSTEM_PROMPT,
+      user: buildSynthesisPrompt(question, evidence),
+      schema: SYNTHESIS_SCHEMA,
+      model: options.model
+    });
+  } catch (err) {
+    options.logger?.error(
+      `synthesis call failed: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return null;
+  }
+  if (typeof body !== "object" || body === null || !isValidSynthesis(body, evidence.length)) {
+    options.logger?.warn("synthesis response cited evidence it was not given");
+    return null;
+  }
+  const raw = body;
   return {
     sentences: raw.sentences ?? [],
     sentenceEvidence: raw.sentenceEvidence ?? [],
@@ -205,8 +141,169 @@ async function synthesizeAnswer(question, evidence, client2, options = {}) {
   };
 }
 
+// ../../packages/llm-core/src/providers.ts
+var DEFAULT_MODELS = {
+  anthropic: "claude-opus-5",
+  openai: "gpt-4o",
+  google: "gemini-2.0-flash"
+};
+function detectProvider(key) {
+  const k = (key ?? "").trim();
+  if (!k) return null;
+  if (k.startsWith("sk-ant-")) return "anthropic";
+  if (k.startsWith("AIza")) return "google";
+  if (k.startsWith("sk-")) return "openai";
+  return null;
+}
+
+// ../../packages/llm-core/src/provider-clients.ts
+import Anthropic3 from "@anthropic-ai/sdk";
+var NOOP = { warn: () => void 0, error: () => void 0 };
+function parseJsonBody(text) {
+  const trimmed = text.trim();
+  const fenced = /^```(?:json)?\s*([\s\S]*?)\s*```$/.exec(trimmed);
+  const body = fenced ? fenced[1] : trimmed;
+  try {
+    return JSON.parse(body);
+  } catch {
+    return null;
+  }
+}
+var AnthropicClient = class {
+  constructor(key, model, logger) {
+    this.model = model;
+    this.logger = logger;
+    this.sdk = new Anthropic3({ apiKey: key });
+  }
+  provider = "anthropic";
+  sdk;
+  async completeJson(request) {
+    try {
+      const message = await this.sdk.messages.create({
+        model: request.model ?? this.model,
+        max_tokens: request.maxTokens ?? DEFAULT_MAX_TOKENS,
+        system: request.system,
+        messages: [{ role: "user", content: request.user }],
+        ...request.schema ? {
+          output_config: {
+            format: { type: "json_schema", schema: request.schema }
+          }
+        } : {}
+      });
+      const text = message.content.filter((b) => b.type === "text").map((b) => b.text).join("");
+      return parseJsonBody(text);
+    } catch (err) {
+      this.logger.warn(`anthropic call failed: ${describeError(err)}`);
+      return null;
+    }
+  }
+};
+var OpenAiClient = class {
+  constructor(key, model, logger) {
+    this.key = key;
+    this.model = model;
+    this.logger = logger;
+  }
+  provider = "openai";
+  async completeJson(request) {
+    try {
+      const res = await fetch("https://api.openai.com/v1/chat/completions", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.key}`
+        },
+        body: JSON.stringify({
+          model: request.model ?? this.model,
+          messages: [
+            { role: "system", content: request.system },
+            { role: "user", content: request.user }
+          ],
+          ...request.schema ? {
+            response_format: {
+              type: "json_schema",
+              json_schema: {
+                name: "evrex_result",
+                strict: true,
+                schema: request.schema
+              }
+            }
+          } : { response_format: { type: "json_object" } }
+        })
+      });
+      if (!res.ok) {
+        this.logger.warn(
+          `openai call failed: ${res.status} ${(await res.text()).slice(0, 200)}`
+        );
+        return null;
+      }
+      const body = await res.json();
+      const text = body.choices?.[0]?.message?.content;
+      return typeof text === "string" ? parseJsonBody(text) : null;
+    } catch (err) {
+      this.logger.warn(`openai call failed: ${describeError(err)}`);
+      return null;
+    }
+  }
+};
+var GoogleClient = class {
+  constructor(key, model, logger) {
+    this.key = key;
+    this.model = model;
+    this.logger = logger;
+  }
+  provider = "google";
+  async completeJson(request) {
+    const model = request.model ?? this.model;
+    const url = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(model)}:generateContent`;
+    const shape = request.schema ? `
+
+Respond with JSON matching exactly this schema:
+${JSON.stringify(request.schema)}` : "";
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-goog-api-key": this.key
+        },
+        body: JSON.stringify({
+          systemInstruction: { parts: [{ text: request.system + shape }] },
+          contents: [{ role: "user", parts: [{ text: request.user }] }],
+          generationConfig: { responseMimeType: "application/json" }
+        })
+      });
+      if (!res.ok) {
+        this.logger.warn(
+          `google call failed: ${res.status} ${(await res.text()).slice(0, 200)}`
+        );
+        return null;
+      }
+      const body = await res.json();
+      const text = body.candidates?.[0]?.content?.parts?.map((p) => p.text ?? "").join("");
+      return text ? parseJsonBody(text) : null;
+    } catch (err) {
+      this.logger.warn(`google call failed: ${describeError(err)}`);
+      return null;
+    }
+  }
+};
+function describeError(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function createModelClient(key, options = {}) {
+  const provider = detectProvider(key);
+  if (!provider || !key) return null;
+  const logger = options.logger ?? NOOP;
+  const model = options.model ?? DEFAULT_MODELS[provider];
+  const trimmed = key.trim();
+  if (provider === "anthropic") return new AnthropicClient(trimmed, model, logger);
+  if (provider === "openai") return new OpenAiClient(trimmed, model, logger);
+  return new GoogleClient(trimmed, model, logger);
+}
+
 // src/synthesize.ts
-var ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY ?? void 0;
+var ANTHROPIC_API_KEY = process.env.MODEL_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}
@@ -216,7 +313,11 @@ var stderrLogger = {
 };
 var client = createAnthropicKeyClient();
 function createAnthropicKeyClient() {
-  return createAnthropicClient(ANTHROPIC_API_KEY);
+  return createModelClient(ANTHROPIC_API_KEY, { logger: stderrLogger });
+}
+function synthesisEnabled() {
+  const flag = process.env.EVREX_SYNTHESIZE;
+  return flag === "1" || flag?.toLowerCase() === "true";
 }
 function toSynthesisEvidence(evidence) {
   return evidence.map((e) => ({
@@ -378,8 +479,16 @@ async function evrexWhy(filePath, question) {
       "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}`);
+  if (synthesisEnabled()) {
+    const answer = await synthesize(text, evidence);
+    parts.push(
+      answer.sentences ? `ANSWER: ${answer.sentences.join(" ")}` : `ANSWER: ${answer.reason}`
+    );
+  } else {
+    parts.push(
+      "HOW TO USE THIS: treat the constraints and rejected approaches above as binding \u2014 they are what this team already decided, not suggestions. Do not re-propose a rejected approach unless you have new information that specifically invalidates the stated reason, and say so if you do. Answer the user from the evidence below; if it does not actually cover their question, say that rather than inferring."
+    );
+  }
   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)}`;
@@ -460,7 +569,7 @@ 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.",
+    description: "Prior reasoning for a file: decisions, hard constraints, and explicitly REJECTED approaches, with sources and confidence. Call this BEFORE reasoning from scratch about an existing file \u2014 not only when the user says 'why'. Use it when you are about to change, refactor, simplify, or remove existing code; when a design choice looks odd, redundant, or wrong; when you are about to infer a constraint from what the code happens to do; or when you would otherwise say 'probably' or 'this was likely done because'. Cheaper than the alternative: one call returns the recorded answer instead of many tool calls reconstructing a guess from code \u2014 and reconstruction cannot recover a rejected approach at all, since rejected work leaves no trace in the repo. Returns a plain 'no recorded reasoning found' when it has nothing, so the cost of checking is one call. 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")
@@ -475,7 +584,7 @@ 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.",
+    description: "Free-text search across this repo's indexed agent session history and git commits \u2014 prior discussion and reasoning that lives in conversation, not in code, so grep, git log and git blame cannot find it. Use for open-ended questions ('has this been discussed', 'when/why did we start doing X', 'what do we know about Y'), and before concluding that something was never considered \u2014 absence in the code is not absence of a decision. If you have a specific file path, prefer evrex_why.",
     inputSchema: {
       query: z.string().describe("Free-text search query")
     }

package/package.json

@@ -1,15 +1,24 @@
 {
   "name": "evrex-mcp",
-  "version": "0.1.0",
+  "version": "0.2.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"],
+  "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"],
+  "files": [
+    "dist/index.js",
+    "README.md"
+  ],
   "engines": {
     "node": ">=20"
   },