@edda-business/mcp 0.71.0 → 0.73.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edda-business/mcp",
-  "version": "0.71.0",
+  "version": "0.73.0",
   "description": "Edda — the company data layer for AI agents.",
   "license": "Apache-2.0",
   "publishConfig": {

package/src/client.js

@@ -156,6 +156,34 @@ async function request(method, path, { body, query } = {}) {
   return res.json();
 }
 
+// Stream raw bytes with metadata on headers — the shape POST /v2/company/river/original expects.
+// A real file (a spreadsheet, a scanned contract) has no business being base64'd into a JSON tool
+// argument: it inflates by a third, buffers whole in memory at both ends, and blows the body limit.
+export async function postRaw(path, bytes, headers = {}) {
+  const apiKey = currentApiKey();
+  if (!apiKey) throw new Error("Missing Edda API key. Pass it as an Authorization: Bearer header.");
+  if (isReadOnly() && !currentApiUrl()) {
+    throw new Error("Read-only seat mode requires an explicit company API URL (EDDA_API_URL or the login config's apiUrl). No request was made.");
+  }
+  const url = new URL(path, currentApiUrl());
+  const res = await fetch(url.toString(), {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/octet-stream",
+      "X-Edda-Client": "mcp",
+      ...headers,
+    },
+    body: bytes,
+  });
+  if (!res.ok) {
+    let err = {};
+    try { err = await res.json(); } catch { /* non-JSON body */ }
+    throw new Error(`Edda API error (${res.status}): ${err.error || err.detail || res.statusText}`);
+  }
+  return res.json();
+}
+
 export function get(path, query) {
   return request("GET", path, { query });
 }

package/src/server.js

@@ -33,7 +33,7 @@
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { get, post, patch, isReadOnly } from "./client.js";
+import { get, post, patch, postRaw, isReadOnly } from "./client.js";
 
 export const SERVER_VERSION = "0.66.0";
 
@@ -66,28 +66,68 @@ async function resolvePathToId(path) {
   const base = norm(segs[segs.length - 1] ?? "");
   const folderSegs = segs.length > 1 ? segs.slice(0, -1).map(norm) : null;
   let cands = pages.filter((p) => norm(p.name) === base);
-  // EDDA-91: a folder-qualified request MUST honour its folder. The old basename-only match
-  // silently substituted an unrelated same-named page from the caller's visible scope when the
-  // requested folder was out of scope (or misspelled) — an exact read must return THAT document
-  // or a truthful unavailable, never masquerade. The message deliberately does not reveal
-  // whether the path exists for someone else.
+
+  // EDDA-91: a folder-qualified request MUST honour its folder. A basename-only match silently
+  // substituted an unrelated same-named page — an exact read returns THAT document or a truthful
+  // unavailable, never a masquerade.
+  //
+  // EDDA-151: it must honour the WHOLE folder path. The previous check asked only whether the
+  // page's leaf folder name appeared somewhere among the requested segments, so
+  // `AION/Context/_context` matched every project's `Context/_context.md` — six indistinguishable
+  // candidates, and the agent opening unrelated projects to find the one it asked for. Match
+  // against the page's full path (now returned by /pages) as a trailing sequence of segments, so
+  // `AION/Context/_context` matches `Projects/AION/Context/_context.md` and nothing else.
   if (folderSegs) {
-    cands = cands.filter((p) => p.folder && folderSegs.includes(norm(p.folder)));
+    const wanted = segs.map(norm);
+    const scored = cands.map((p) => {
+      const full = String(p.path || [p.folder, p.name].filter(Boolean).join("/")).split("/").map(norm);
+      // strip the extension from the final segment for comparison
+      const tail = full.slice(-wanted.length);
+      const exact = tail.length === wanted.length && tail.every((seg, i) => seg === wanted[i]);
+      return { p, exact };
+    });
+    const exact = scored.filter((x) => x.exact).map((x) => x.p);
+    // Fall back to the old leaf-name behaviour only when nothing matches the full path, so a
+    // legacy flat row (no folder tree) still resolves.
+    cands = exact.length ? exact : cands.filter((p) => !p.path && p.folder && folderSegs.includes(norm(p.folder)));
   }
+
   if (!cands.length) {
     return { error: folderSegs
       ? `"${String(path)}" is not available here — it either does not exist or is outside what this seat can read. Use search to see what you can access.`
       : `No company page named "${String(path).split("/").pop()}". Use search to find the exact path first.` };
   }
   if (cands.length > 1) {
-    const opts = cands.map((p) => `  • ${[p.folder, p.name].filter(Boolean).join("/")}  (id: ${p.id})`).join("\n");
-    return { error: `Several pages match "${base}". Pass one of these ids as \`id\`:\n${opts}` };
+    const opts = cands.map((p) => `  • ${p.path || [p.folder, p.name].filter(Boolean).join("/")}  (id: ${p.id})`).join("\n");
+    return { error: `Several pages match "${String(path)}". Pass one of these ids as \`id\`:\n${opts}` };
   }
   return { id: cands[0].id };
 }
 
 // ─── factory ──────────────────────────────────────────────────────────────────
 
+// A real file goes up as a STREAM with a declared hash, not as base64 in a tool argument. The
+// agent names a path on its own disk; the MCP reads it, uploads the bytes to the original store,
+// and stages a candidate that references the registered original. `sha256` is declared so the
+// server fails closed if what arrived is not what the agent read.
+async function uploadLocalFile(filePath, { sourceId } = {}) {
+  const { readFile } = await import("node:fs/promises");
+  const { basename } = await import("node:path");
+  const crypto = await import("node:crypto");
+  let bytes;
+  try { bytes = await readFile(filePath); }
+  catch (e) { throw new Error(`Could not read ${filePath}: ${e.code === "ENOENT" ? "no such file" : e.message}`); }
+  const sha256 = crypto.createHash("sha256").update(bytes).digest("hex");
+  const name = basename(filePath);
+  const r = await postRaw("/v2/company/river/original", bytes, {
+    // The hash doubles as the idempotency key: the same bytes re-uploaded register once.
+    "X-Source-Id": sourceId || `mcp:${sha256}`,
+    "X-Original-Filename": encodeURIComponent(name),
+    "X-Sha256": sha256,
+  });
+  return { originalId: r?.original?.id ?? null, name, sha256, bytes: r?.original?.byte_size ?? bytes.length };
+}
+
 export function createServer() {
   // EfB seat boundary: with EDDA_MCP_READONLY set (the flag Hermes EfB box profiles use),
   // the personal agent gets EXACTLY search + read — the write tools (push/update/create) are
@@ -120,7 +160,9 @@ export function createServer() {
     "connected sources (Slack, HubSpot, Stripe, calls). This is the default retrieval tool: reach " +
     "for it before answering from generic knowledge about how the company works or what happened. " +
     "Each hit is tagged [company] (a wiki page) or [company·distilled] (from activity), with a " +
-    "snippet; wiki hits include a `path:` you can pass to read for the full text. " +
+    "snippet. A [company] hit carries an `id:` — pass THAT to read, it opens exactly the document " +
+    "you found. The `path:` is shown for context; prefer the id. Every hit returned is one you " +
+    "can actually open. " +
     "Narrow with `kind`: 'documents' (wiki only), 'distilled' (activity only), or 'all' (default).",
     {
       question: z.string().describe("Natural-language query."),
@@ -163,8 +205,13 @@ export function createServer() {
         const tag = declared ? "[company]" : "[company·distilled]";
         const from = d.source_member ? ` · from ${d.source_member}` : "";
         lines.push(`${tag} ${String(d.name ?? "").replace(/\.md$/, "")}${from}  (${pct(d.similarity)})`);
-        if (declared && d.ref) lines.push(`  path: ${d.ref}`);          // pass to read
-        else if (d.ref) lines.push(`  source: ${d.ref}`);              // distilled: origin, read-only
+        // EDDA-151: the ID is what reliably opens the document. The API always returned it and
+        // this tool never printed it, so the agent had to go back through a path — and a path
+        // built from the leaf folder name could not tell one project's `Context/_context.md` from
+        // another's. Print the id first and say plainly that it is the thing to use.
+        if (declared && d.id) lines.push(`  id: ${d.id}   ← pass this to read`);
+        if (declared && d.ref) lines.push(`  path: ${d.ref}`);
+        else if (!declared && d.ref) lines.push(`  source: ${d.ref}`);   // distilled: origin, read-only
         if (d.snippet) lines.push(`  ${d.snippet}`);
         lines.push("");
       }
@@ -179,8 +226,9 @@ export function createServer() {
   server.tool(
     "read",
     "Read the FULL text of one company wiki page — search returns snippets; use this to " +
-    "get the whole document. Pass the `path:` shown under a [company] search hit (e.g. " +
-    "'Company/Policies/Refund Policy.md'), or an `id` if you already have one. Also returns the " +
+    "get the whole document. PREFER the `id:` from a [company] search hit — it opens exactly that " +
+    "document with no ambiguity. A `path` also works, but pass the FULL project-qualified path as " +
+    "search printed it (e.g. 'Projects/AION/Context/_context.md'), not a fragment. Also returns the " +
     "page's LINK GRAPH — outgoing [[links]] and backlinks — so you can TRAVERSE the wiki to " +
     "complete the picture (read a linked page next, or see what references this one). Distilled " +
     "hits ([company·distilled]) aren't pages — their content is in the search snippet.",
@@ -288,6 +336,7 @@ export function createServer() {
     {
       name: z.string().describe("File/page name, e.g. 'MCP Overview EFB' or 'Q3 invoices.xlsx'. A '.md' suffix is added to markdown items if missing."),
       content: z.string().optional().describe("The full markdown content, when you are sharing text you wrote. Omit when sending a FILE via file_base64."),
+      file_path: z.string().optional().describe("Absolute path to a file on THIS machine — PDF, Word, Excel, image, CSV. PREFER THIS over file_base64 for any real file: the bytes stream up with a checksum instead of being encoded into this argument. Use file_base64 only when you hold the bytes in memory and have no path."),
       file_base64: z.string().optional().describe(
         "A real FILE, base64-encoded — a proposal, invoice, report, financial model, scan. The server extracts the text: " +
         "PDF (scans are OCR'd), Word, Excel and legacy .xls (one heading per sheet), images (OCR'd), CSV and plain text. " +
@@ -320,10 +369,18 @@ export function createServer() {
         "and are applied only when a person approves the item. Cite nothing yourself — the filed document becomes the evidence."
       ),
     },
-    async ({ name, content, file_base64, mime, suggested, grade, audience, idempotency_key, claims }) => {
+    async ({ name, content, file_path, file_base64, mime, suggested, grade, audience, idempotency_key, claims }) => {
       try {
-        if (!content && !file_base64) return text(`Give "${name}" either markdown content or a file (file_base64) to stage.`);
-        const r = await post("/v2/company/river/stage", { name, content, file_base64, mime, suggested, grade, audience, idempotency_key, claims });
+        if (!content && !file_base64 && !file_path) return text(`Give "${name}" either markdown content or a file (file_path) to stage.`);
+        // A path wins: stream the bytes into the original store first, then stage a candidate that
+        // references the registered original. The server extracts the text from the original.
+        let original_id = null;
+        if (file_path) {
+          const up = await uploadLocalFile(file_path, { sourceId: idempotency_key ? `mcp:${idempotency_key}` : undefined });
+          original_id = up.originalId;
+          if (!name) name = up.name;
+        }
+        const r = await post("/v2/company/river/stage", { name, content, file_base64, original_id, mime, suggested, grade, audience, idempotency_key, claims });
         const rc = r?.receipt ?? r;
         if (rc?.idempotent) return text(`Already staged — "${name}" is in the company Inbox (${rc.location}). Nothing duplicated.`);
         if (rc?.rejected === "hash_mismatch") return text(`Couldn't stage "${name}": the content didn't match its declared checksum (it may have changed after approval). Re-capture and try again.`);
@@ -367,7 +424,8 @@ export function createServer() {
       items: z.array(z.object({
         name: z.string().describe("File/page name, e.g. 'Cook Street construction proposal.pdf'."),
         content: z.string().optional().describe("Markdown content, when sharing text you wrote. Omit when sending a file."),
-        file_base64: z.string().optional().describe("The file itself, base64-encoded — PDF, Word, Excel, image, CSV. Send the file rather than a summary of it."),
+        file_path: z.string().optional().describe("Absolute path to a file on THIS machine. PREFER THIS for any real file — the bytes stream up with a checksum instead of riding inside this argument."),
+        file_base64: z.string().optional().describe("The file itself, base64-encoded. Only when you hold the bytes in memory and have no path. Send the file rather than a summary of it."),
         mime: z.string().optional().describe("MIME type when known."),
         suggested: z.string().optional().describe("Optional destination HINT. A path you cannot see is dropped, and the item still lands in the Inbox."),
         grade: z.enum(["fact", "summary", "full"]).optional(),
@@ -386,10 +444,26 @@ export function createServer() {
     },
     async ({ items }) => {
       try {
-        const r = await post("/v2/company/river/stage-batch", { candidates: items });
+        // Upload any local files first, so the batch body stays small however large the documents
+        // are. A per-file failure becomes that item's receipt rather than killing the whole run.
+        const prepared = [];
+        for (const it of items) {
+          if (!it.file_path) { prepared.push(it); continue; }
+          try {
+            const up = await uploadLocalFile(it.file_path, { sourceId: it.idempotency_key ? `mcp:${it.idempotency_key}` : undefined });
+            const { file_path: _drop, ...rest } = it;
+            prepared.push({ ...rest, name: it.name || up.name, original_id: up.originalId });
+          } catch (e) {
+            prepared.push({ ...it, __upload_error: String(e.message || e) });
+          }
+        }
+        const failedUploads = prepared.filter((p) => p.__upload_error);
+        const sendable = prepared.filter((p) => !p.__upload_error);
+        const r = await post("/v2/company/river/stage-batch", { candidates: sendable });
         const staged = r?.staged ?? 0;
         const failed = r?.failed ?? 0;
-        const lines = [`Staged ${staged} item(s) into the company Inbox${failed ? `, ${failed} rejected` : ""}.`];
+        const lines = [`Staged ${staged} item(s) into the company Inbox${failed ? `, ${failed} rejected` : ""}${failedUploads.length ? `, ${failedUploads.length} unreadable` : ""}.`];
+        for (const f of failedUploads) lines.push(`  ✗ ${f.name ?? f.file_path} — ${f.__upload_error}`);
         for (const rec of r?.receipts ?? []) {
           if (rec.staged === false) lines.push(`  ✗ ${rec.name ?? "(unnamed)"} — ${rec.reason ?? rec.rejected ?? "unknown"}`);
           else if (rec.suggestion_dropped) lines.push(`  • ${rec.name} — staged; your suggested destination was dropped (not visible to you)`);