@edda-business/mcp 0.64.0 → 0.66.0

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@edda-business/mcp",
-  "version": "0.64.0",
+  "version": "0.66.0",
   "description": "Edda — the company data layer for AI agents.",
   "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/NousC/opennous.git",
+    "url": "git+https://github.com/EddaBusiness/edda.git",
     "directory": "apps/mcp"
   },
   "type": "module",
@@ -21,6 +24,7 @@
     "start": "node src/index.js",
     "dev:http": "node --watch src/http.js",
     "start:http": "node src/http.js",
+    "test": "node --test tests/*.test.mjs",
     "typecheck": "echo 'no ts in mcp — skipping'"
   },
   "keywords": [

package/src/client.js

@@ -29,6 +29,15 @@ const envKey = () => resolvedEnv("EDDA_API_KEY") ?? resolvedEnv("NOUS_API_KEY");
 const envUrl = () => resolvedEnv("EDDA_API_URL") ?? resolvedEnv("NOUS_API_URL");
 const API_URL = envUrl() || "https://api.opennous.cloud";
 
+// EfB seat boundary (EDDA_MCP_READONLY=1|true|yes — the stable flag name Hermes EfB box
+// profiles set). In this mode the server registers ONLY search/read (see server.js), and the
+// client FAILS CLOSED: it requires an explicitly configured API URL and key, and never falls
+// back to the vendor cloud default — a seat's company questions must only ever reach the
+// company's own instance. Read per-call so the flag is testable and honored at request time.
+export function isReadOnly() {
+  return /^(1|true|yes)$/i.test(process.env.EDDA_MCP_READONLY ?? "");
+}
+
 // Per-request key context for the hosted HTTP server. Empty in stdio mode.
 export const apiKeyStore = new AsyncLocalStorage();
 
@@ -61,7 +70,10 @@ function currentApiKey() {
 
 // Resolve the API base per call: env → config.json (set by the CLI login on self-host) → cloud
 // default. So a self-hoster who logs in via the CLI gets the MCP pointed at their own instance.
+// In read-only seat mode there is NO cloud default — an unconfigured URL resolves to undefined
+// and request() refuses to issue anything.
 function currentApiUrl() {
+  if (isReadOnly()) return envUrl() ?? fileApiUrl();
   return envUrl() ?? fileApiUrl() ?? "https://api.opennous.cloud";
 }
 
@@ -74,6 +86,12 @@ export function validateConfig() {
       "to set up from scratch), or set EDDA_API_KEY."
     );
   }
+  if (isReadOnly() && !currentApiUrl()) {
+    throw new Error(
+      "Read-only seat mode (EDDA_MCP_READONLY) requires an explicit company API URL — set EDDA_API_URL " +
+      "or log in with `edda login --url <company-api-url>`. There is no cloud fallback in this mode."
+    );
+  }
 }
 
 async function request(method, path, { body, query } = {}) {
@@ -81,6 +99,14 @@ async function request(method, path, { body, query } = {}) {
   if (!apiKey) {
     throw new Error("Missing Edda API key. Pass it as an Authorization: Bearer header.");
   }
+  if (isReadOnly() && !currentApiUrl()) {
+    // Fail closed BEFORE any network I/O: a seat without an explicit company URL must not
+    // leak its question (or key) to the vendor cloud default.
+    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());
 

package/src/index.js

@@ -10,13 +10,20 @@
  * Required env:
  *   EDDA_API_KEY   — workspace API key (Sources -> API Keys). Encodes the workspace + scope.
  * Optional:
- *   EDDA_API_URL   — API base URL for your instance, e.g. https://api.whitehayai.com
+ *   EDDA_API_URL   — API base URL for your instance, e.g. https://api.<client>
  * (Legacy NOUS_API_KEY / NOUS_API_URL are still accepted as a fallback.)
  */
 
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { validateConfig } from "./client.js";
-import { createServer } from "./server.js";
+import { createServer, SERVER_VERSION } from "./server.js";
+
+// Edda Skeleton calls this after installation. It must be entirely local: no config lookup,
+// validation or network access can make an installed package look unavailable.
+if (process.argv.includes("--version") || process.argv.includes("-V")) {
+  console.log(SERVER_VERSION);
+  process.exit(0);
+}
 
 // Advisory only — don't hard-exit if there's no key yet. The user may register
 // the MCP first and sign in after (`npx @edda-business/cli login`); the server must

package/src/server.js

@@ -20,11 +20,12 @@
  *     + embeds them. You only RETRIEVE them (they surface in search tagged ·distilled).
  *
  * TOOLS:
- *   search_company        RETRIEVE across BOTH natures (documents + distilled), kind filter
- *   read_company_page     read one full wiki page (by path from a search result, or id)
- *   push_company_file     PUSH one or many files up into the company folders (shared wiki)
- *   update_company_page   edit an existing wiki page (replace or append)
- *   create_company_folder organize the wiki tree
+ *   search        RETRIEVE across BOTH natures (documents + distilled), kind filter
+ *   read     read one full wiki page (by path from a search result, or id)
+ *   submit_company_candidate  STAGE one user-approved file into the company Inbox (the River places it)
+ *   reconcile                 PROCESS the company Inbox — file staged items into the right folders
+ *   update   edit an existing wiki page (replace or append)
+ *   create organize the wiki tree
  *
  * Sources (connecting Slack/HubSpot/… so distillation happens) are wired in the Edda web
  * app, not here — the agent only reads and writes knowledge.
@@ -32,9 +33,9 @@
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { get, post, patch } from "./client.js";
+import { get, post, patch, isReadOnly } from "./client.js";
 
-export const SERVER_VERSION = "0.64.0";
+export const SERVER_VERSION = "0.66.0";
 
 // ─── helpers ──────────────────────────────────────────────────────────────────
 
@@ -63,7 +64,7 @@ async function resolvePathToId(path) {
   const pages = list?.pages ?? [];
   const base = norm(String(path).split("/").pop());
   let cands = pages.filter((p) => norm(p.name) === base);
-  if (!cands.length) return { error: `No company page named "${String(path).split("/").pop()}". Use search_company to find the exact path first.` };
+  if (!cands.length) return { error: `No company page named "${String(path).split("/").pop()}". Use search to find the exact path first.` };
   if (cands.length > 1) {
     // Prefer a candidate whose folder slug appears in the requested path.
     const pref = cands.filter((p) => p.folder && norm(path).includes(norm(p.folder)));
@@ -80,6 +81,11 @@ async function resolvePathToId(path) {
 // ─── factory ──────────────────────────────────────────────────────────────────
 
 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
+  // never registered, so a member key that could overwrite shared pages can't do so from a
+  // seat. Without the flag, registration below is untouched five-tool behavior.
+  const readOnly = isReadOnly();
   const server = new McpServer({
     name: "edda",
     version: SERVER_VERSION,
@@ -87,7 +93,7 @@ export function createServer() {
       "Edda — the company's shared knowledge for AI agents. Search the company wiki (declared " +
       "policies, playbooks, decisions) AND distilled knowledge from connected sources (Slack, " +
       "HubSpot, calls) in one call; read a full page; and contribute pages/folders back. Reach " +
-      "for search_company before answering from generic knowledge. (Personal files live on the " +
+      "for search before answering from generic knowledge. (Personal files live on the " +
       "user's own disk; this is the shared company layer only.)",
     icons: [
       { src: "https://opennous.cloud/newlogoP.png", mimeType: "image/png", sizes: ["64x64"] },
@@ -95,18 +101,18 @@ export function createServer() {
   });
 
   // ===========================================================================
-  // TOOL: search_company  —  POST /v2/company/search
+  // TOOL: search  —  POST /v2/company/search
   // The primary read surface. Hybrid retrieval (RRF + rerank) fused across the DECLARED wiki
   // and the DERIVED distilled layer, ACL-filtered. `kind` narrows to one nature.
   // ===========================================================================
   server.tool(
-    "search_company",
+    "search",
     "Search the COMPANY'S SHARED KNOWLEDGE in one call — both natures at once: the DECLARED wiki " +
     "(policies, playbooks, decisions, SOPs, how-we-work) AND DERIVED knowledge distilled from " +
     "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_company_page for the full text. " +
+    "snippet; wiki hits include a `path:` you can pass to read for the full text. " +
     "Narrow with `kind`: 'documents' (wiki only), 'distilled' (activity only), or 'all' (default).",
     {
       question: z.string().describe("Natural-language query."),
@@ -132,7 +138,7 @@ 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_company_page
+        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
         if (d.snippet) lines.push(`  ${d.snippet}`);
         lines.push("");
@@ -142,12 +148,12 @@ export function createServer() {
   );
 
   // ===========================================================================
-  // TOOL: read_company_page  —  GET /v2/company/pages/:id
-  // Read one full wiki page. Take the `path:` from a search_company result, or an id.
+  // TOOL: read  —  GET /v2/company/pages/:id
+  // Read one full wiki page. Take the `path:` from a search result, or an id.
   // ===========================================================================
   server.tool(
-    "read_company_page",
-    "Read the FULL text of one company wiki page — search_company returns snippets; use this to " +
+    "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 " +
     "page's LINK GRAPH — outgoing [[links]] and backlinks — so you can TRAVERSE the wiki to " +
@@ -164,7 +170,7 @@ export function createServer() {
         if (res.error) return text(res.error);
         pageId = res.id;
       }
-      if (!pageId) return text("Tell me which page to read — pass the `path` from a search_company result (its `path:` line), or an `id`.");
+      if (!pageId) return text("Tell me which page to read — pass the `path` from a search result (its `path:` line), or an `id`.");
       try {
         const r = await get(`/v2/company/pages/${encodeURIComponent(pageId)}`);
         const p = r?.page;
@@ -175,74 +181,102 @@ export function createServer() {
         const outgoing = p.ingest?.outgoing ?? [];
         const backlinks = p.ingest?.backlinks ?? [];
         if (outgoing.length || backlinks.length) {
-          out.push("", "---", "Links (read_company_page on any of these to traverse):");
+          out.push("", "---", "Links (read on any of these to traverse):");
           if (outgoing.length) out.push("  → links to: " + outgoing.map((l) => `${l.target}${l.resolved ? "" : " (unresolved)"}`).join(", "));
           if (backlinks.length) out.push("  ← linked from: " + backlinks.map((b) => b.source).join(", "));
         }
         return text(out.join("\n"));
       } catch (e) {
         const msg = String(e?.message || e);
-        if (msg.includes("not_found") || msg.includes("(404)")) return text("No page with that id — use search_company to find the path, then read it.");
+        if (msg.includes("not_found") || msg.includes("(404)")) return text("No page with that id — use search to find the path, then read it.");
         if (msg.includes("forbidden") || msg.includes("(403)")) return text("You don't have access to read that company page.");
         throw e;
       }
     },
   );
 
+  // EfB read-only seat mode stops here: tools/list is exactly search + read, and the write
+  // tools below don't exist for the seat at all (unavailable, not merely rejected).
+  if (readOnly) return server;
+
   // ===========================================================================
-  // TOOL: push_company_file  —  POST /v2/company/pages/batch
-  // PUSH one or many files UP into the shared company folders (the personal→company promotion).
-  // Hybrid write policy: a write role publishes live; a viewer sends the batch to the company
-  // inbox to approve.
+  // TOOL: submit_company_candidate  —  POST /v2/company/river/stage
+  // The seat's ONE write: STAGE a user-approved item into the company Edda's Inbox. The seat
+  // never chooses the destination — it hands over one exact item (and may SUGGEST a folder);
+  // the company app (the River) classifies + places it on reconcile. Mirrors the personal
+  // side: everything lands in the Inbox first, then gets routed.
   // ===========================================================================
   server.tool(
-    "push_company_file",
-    "PUSH a file (or several) UP into the COMPANY WIKI — promote knowledge from your own work into " +
-    "the shared company folders every member's agent can read via search_company. Typically you " +
-    "push a personal/working file up so the company has it. All pushed files go into the SAME " +
-    "folder (resolved or created once). Name the target with `folder` — a name or path like " +
-    "'Projects/Data Centre' (top-level folders are fixed; a bare name becomes a project under " +
-    "Projects) — plus optional `subfolder`, or an existing `folder_id`. A write role publishes it " +
-    "live (searchable now); a viewer's push lands in the company inbox for an admin to approve. " +
-    "Max 50 files. This is the SHARED company wiki — the user's own private files live on their disk.",
+    "submit_company_candidate",
+    "SHARE a file up into the COMPANY knowledge — stage one user-approved item into the company " +
+    "Edda's Inbox. You do NOT pick where it lands: the company routes it into the right folder " +
+    "itself (on the next reconcile). You may optionally `suggest` a destination as a hint. Use " +
+    "this to promote a finished note from your own work into the shared company brain. Only stage " +
+    "what the person has approved sharing — this leaves their private vault. (Their private files " +
+    "stay on their disk; this is the shared company layer.)",
     {
-      folder: z.string().optional().describe("Folder to file all pages under, by NAME or path. Top-level is fixed — a bare name becomes a project under Projects; 'Top-Level/Sub' nests under a fixed folder. Created if missing."),
-      subfolder: z.string().optional().describe("Optional subfolder within `folder`."),
-      folder_id: z.string().optional().describe("Id of an existing folder (alternative to `folder`). Omit both for the default folder."),
-      visibility: z.enum(["owner", "department", "company"]).optional().describe("Default visibility: 'department' (default), 'company' (everyone), or 'owner' (just you). A page can override its own."),
-      pages: z.array(z.object({
-        name: z.string().describe("File/page name, e.g. 'Refund Policy'. A '.md' suffix is added if missing."),
-        content: z.string().optional().describe("The full markdown content."),
-        visibility: z.enum(["owner", "department", "company"]).optional().describe("Optional per-file visibility override."),
-      })).describe("The file(s) to push — one entry for a single file, many for a bulk push. Each { name, content, visibility? }."),
+      name: z.string().describe("File/page name, e.g. 'MCP Overview EFB'. A '.md' suffix is added if missing."),
+      content: z.string().describe("The full markdown content of the item to share."),
+      suggested: z.string().optional().describe("Optional destination HINT, e.g. 'Projects/Data Centre/Working Documents' or 'General Edda'. The company still resolves/creates and places it — this only nudges."),
+      grade: z.enum(["fact", "summary", "full"]).optional().describe("How much of the source this carries: a single fact, a summary, or the full document."),
+      audience: z.enum(["company-wide", "department", "owner", "filing-agent-decides"]).optional().describe("The MOST this may be seen by (an upper bound the company may narrow, never broaden). Default: filing-agent-decides."),
+      idempotency_key: z.string().optional().describe("Optional stable key so re-submitting the same approved item files it at most once."),
+    },
+    async ({ name, content, suggested, grade, audience, idempotency_key }) => {
+      try {
+        const r = await post("/v2/company/river/stage", { name, content, suggested, grade, audience, idempotency_key });
+        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.`);
+        if (rc?.staged === false) return text(`Couldn't stage "${name}": ${rc?.reason ?? "unknown error"}.`);
+        return text(`Staged "${name}" into the company Inbox (${rc?.location ?? "Inbox"}). The company will route it to the right folder on the next reconcile.`);
+      } catch (e) {
+        const msg = String(e?.message || e);
+        if (msg.includes("admins_only") || msg.includes("(403)")) return text("You don't have a role that can share into this company wiki (members are read-only).");
+        if (msg.includes("name_required")) return text("Give the item a name and content to stage.");
+        throw e;
+      }
     },
-    async ({ folder, subfolder, folder_id, visibility, pages }) => {
+  );
+
+  // ===========================================================================
+  // TOOL: reconcile  —  POST /v2/company/river/reconcile
+  // Process the company Edda's Inbox: the River classifies + places each staged item into the
+  // right folder, embeds + links it. "Process the company inbox." Admin/ambassador only.
+  // ===========================================================================
+  server.tool(
+    "reconcile",
+    "PROCESS the company Inbox — have the company file every item waiting in its Inbox into the " +
+    "right folder (classify → place → make searchable). Run this after staging, or when the person " +
+    "says 'process the company inbox'. Optionally pass a single `stagingId` to file just that item. " +
+    "Returns where each item landed.",
+    { stagingId: z.string().optional().describe("Optional id of one staged item to file (from a submit_company_candidate receipt). Omit to process the whole Inbox.") },
+    async ({ stagingId }) => {
       try {
-        const r = await post("/v2/company/pages/batch", { folder, subfolder, folder_id, visibility, pages });
-        const where = r?.status === "live" ? "published live — searchable now" : "sent to the company inbox for an admin to approve";
-        return text(`${r?.count ?? pages?.length ?? 0} file(s) ${where} in "${r?.folder ?? folder ?? "wiki"}".`);
+        const r = await post("/v2/company/river/reconcile", { stagingId });
+        const receipts = r?.receipts ?? [];
+        if (!receipts.length) return text("Nothing waiting in the company Inbox.");
+        const lines = receipts.map((x) => `  ${x.filed ? "✓ filed" : x.status} → ${x.location}${x.audience && x.audience !== "company" ? ` [${x.audience}]` : ""}  (${x.reason})`);
+        return text(`Processed ${receipts.length} item(s) from the company Inbox:\n${lines.join("\n")}`);
       } catch (e) {
         const msg = String(e?.message || e);
-        if (msg.includes("forbidden") || msg.includes("(403)")) return text("You don't have access to push to this company wiki.");
-        if (msg.includes("bad_folder")) return text("That folder path couldn't be resolved or created — check the name, or pass folder_id.");
-        if (msg.includes("too_many")) return text("Too many files — max 50 per call. Split into batches.");
-        if (msg.includes("pages_required")) return text("Give at least one file ({ name, content }).");
+        if (msg.includes("admins_only") || msg.includes("(403)")) return text("Only an admin or ambassador can process the company Inbox.");
         throw e;
       }
     },
   );
 
   // ===========================================================================
-  // TOOL: update_company_page  —  PATCH /v2/company/pages/:id
+  // TOOL: update  —  PATCH /v2/company/pages/:id
   // Edit an existing wiki page: replace its content, or append. Re-embeds on the server.
   // ===========================================================================
   server.tool(
-    "update_company_page",
+    "update",
     "Edit an EXISTING company wiki page — revise it or append to it. Identify the page by `path` " +
-    "(the `path:` from a search_company result) or `id`. By default the new `content` REPLACES the " +
+    "(the `path:` from a search result) or `id`. By default the new `content` REPLACES the " +
     "page; set append:true to add to the end instead (kept for a rolling log or a running doc). " +
-    "You can also rename it with `name`. Re-embedded so search picks up the change. For a NEW page " +
-    "use push_company_file. Distilled items (from sources) are read-only and can't be edited here.",
+    "You can also rename it with `name`. Re-embedded so search picks up the change. To SHARE a NEW " +
+    "item into the company use submit_company_candidate. Distilled items (from sources) are read-only and can't be edited here.",
     {
       path: z.string().optional().describe("The page path from a search result's `path:` line. Provide this OR id."),
       id: z.string().optional().describe("The page id (advanced). Provide this OR path."),
@@ -257,7 +291,7 @@ export function createServer() {
         if (res.error) return text(res.error);
         pageId = res.id;
       }
-      if (!pageId) return text("Tell me which page to edit — pass the `path` from a search_company result, or an `id`.");
+      if (!pageId) return text("Tell me which page to edit — pass the `path` from a search result, or an `id`.");
       try {
         const body = {};
         if (append) {
@@ -271,7 +305,7 @@ export function createServer() {
         return text(`Updated "${name ? name.replace(/\.md$/, "") : (path ? String(path).split("/").pop().replace(/\.md$/, "") : pageId)}"${append ? " (appended)" : ""} — re-embedded, searchable now.`);
       } catch (e) {
         const msg = String(e?.message || e);
-        if (msg.includes("not_found") || msg.includes("(404)")) return text("No editable page with that id — distilled items are read-only. Use search_company to find a wiki page.");
+        if (msg.includes("not_found") || msg.includes("(404)")) return text("No editable page with that id — distilled items are read-only. Use search to find a wiki page.");
         if (msg.includes("forbidden") || msg.includes("(403)")) return text("You don't have access to edit that company page.");
         throw e;
       }
@@ -279,18 +313,18 @@ export function createServer() {
   );
 
   // ===========================================================================
-  // TOOL: create_company_folder  —  POST /v2/company/folders
+  // TOOL: create  —  POST /v2/company/folders
   // Create a folder / nested path in the shared company tree so pages can be filed into it.
   // ===========================================================================
   server.tool(
-    "create_company_folder",
+    "create",
     "Create a folder in the COMPANY WIKI tree so you can file pages into it. The TOP-LEVEL folders " +
     "are FIXED (Company · Projects · Decisions · Companies · People · Raw Documents · Archive) — you " +
     "cannot add new ones. A bare name (or a path not starting with a fixed folder) becomes a PROJECT " +
     "under Projects: 'Agency' → Projects/Agency. To nest under a specific top-level folder, start the " +
     "path with it, e.g. 'Company/Policies' or 'Projects/Data Centre/Specs'. A write role is required; " +
-    "the folder appears immediately. Then push files into it with push_company_file using the same " +
-    "path. Returns the folder id.",
+    "the folder appears immediately, and you can suggest it as a destination when you " +
+    "submit_company_candidate. Returns the folder id.",
     { path: z.string().describe("Folder name or path. A bare name → a project under Projects; 'Top-Level/Sub' nests under a fixed top-level folder.") },
     async ({ path }) => {
       try {