@edda-business/mcp 0.65.0 → 0.66.1

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@edda-business/mcp",
-  "version": "0.65.0",
+  "version": "0.66.1",
   "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

@@ -22,7 +22,8 @@
  * TOOLS:
  *   search        RETRIEVE across BOTH natures (documents + distilled), kind filter
  *   read     read one full wiki page (by path from a search result, or id)
- *   push     PUSH one or many files up into the company folders (shared wiki)
+ *   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
  *
@@ -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.65.0";
+export const SERVER_VERSION = "0.66.0";
 
 // ─── helpers ──────────────────────────────────────────────────────────────────
 
@@ -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,
@@ -189,44 +195,74 @@ export function createServer() {
     },
   );
 
+  // 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  —  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",
-    "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. 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.) This stages PAGES (content) only — " +
+    "NEVER folders: if the person asks to create a folder, call `create` instead; folder creation " +
+    "is direct and immediate, it does not go through the Inbox.",
     {
-      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;
       }
     },
@@ -241,8 +277,8 @@ export function createServer() {
     "Edit an EXISTING company wiki page — revise it or append to it. Identify the page by `path` " +
     "(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. 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."),
@@ -288,9 +324,10 @@ export function createServer() {
     "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 using the same " +
-    "path. Returns the folder id.",
+    "path with it, e.g. 'Company/Policies' or 'Projects/Data Centre/Specs'. When the person asks to " +
+    "create a folder, ALWAYS call this tool directly — never stage a folder request into the Inbox " +
+    "(the Inbox is for page content only). A write role is required; 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 {