@edda-business/mcp 0.52.0 → 0.54.0

package/package.json

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

package/src/server.js

@@ -10,19 +10,19 @@
  * sees raw rows — it gets engineered, epistemics-tagged context. It never
  * "updates" — it records observations; Edda derives.
  *
- * Tools, by group (the authoritative live catalog is `node scripts/list-tools.mjs`):
+ * Tools, by group:
  *   READ    get_context · get_account · query · attention · verify ·
  *           search_notes · search_company_knowledge · search_my_vault
- *   WRITE   record · save_note · propose_vault_file · propose_company_file · merge_contacts
- *   CORRECT retract_observation · unmerge_contacts
- *   RUN     get_workspace_status · whoami · list_integrations · set_workspace_profile · connect_integration
+ *   WRITE   save_note · propose_vault_file · propose_company_file · merge_contacts
+ *   CORRECT unmerge_contacts
+ *   RUN     list_integrations · connect_integration
  */
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { get, post, del } from "./client.js";
 
-export const SERVER_VERSION = "0.51.0";
+export const SERVER_VERSION = "0.54.0";
 
 // ─── helpers ──────────────────────────────────────────────────────────────────
 
@@ -71,10 +71,10 @@ export function createServer() {
     name: "edda",
     version: SERVER_VERSION,
     description:
-      "Edda — the Context Graph for AI Agents. Edda is operated by the agent, not by a human " +
-      "clicking around: call get_workspace_status at the start of a session to see what's set up " +
-      "and what to set up next. Call get_context before drafting outreach or preparing for a " +
-      "meeting. Call record after every interaction, or whenever you learn something.",
+      "Edda — the company knowledge layer for AI agents. The agent reads engineered, " +
+      "epistemics-tagged context instead of raw rows. Call get_context before preparing for a " +
+      "meeting or a decision about a person; search_company_knowledge for how the company works; " +
+      "save_note to keep a brief or transcript on a contact.",
     icons: [
       { src: "https://opennous.cloud/newlogoP.png", mimeType: "image/png", sizes: ["64x64"] },
     ],
@@ -96,7 +96,7 @@ export function createServer() {
     "act on it, 'suspect'/'expired' verify first.",
     {
       focus: z.string().describe("Who to look up — an email, a LinkedIn URL, a domain, an entity UUID, or a name. A name may match several people; you'll get candidates to choose from."),
-      intent: z.enum(["draft_email", "follow_up", "meeting_prep", "call_prep", "account_review"])
+      intent: z.enum(["follow_up", "meeting_prep", "call_prep", "account_review"])
         .optional()
         .describe("What you are about to do — shapes which context surfaces (default: account_review)"),
       budget_tokens: z.number().optional().describe("Approximate token budget for the context block"),
@@ -190,7 +190,7 @@ export function createServer() {
     {
       id: z.string().describe("Who to look up — an email, an entity UUID, or a name. A name may match several people; you'll get candidates to choose from."),
       intent: z
-        .enum(["meeting_prep", "call_prep", "account_review", "follow_up", "draft_email"])
+        .enum(["meeting_prep", "call_prep", "account_review", "follow_up"])
         .optional()
         .describe(
           "What you're about to do. Shapes how much of their history comes back: a meeting brief wants " +
@@ -385,38 +385,6 @@ export function createServer() {
     }
   );
 
-  // ===========================================================================
-  // TOOL: record  —  POST /v2/observations
-  // The single write verb. You observe — Edda derives the updated facts.
-  // ===========================================================================
-  server.tool(
-    "record",
-    "Record what happened or what you learned about a person or company. You never overwrite " +
-    "anything — you observe, and Edda derives the updated facts. Use kind:'event' for an interaction " +
-    "(property like 'interaction.email_sent', 'interaction.call_held', 'interaction.email_reply') and " +
-    "kind:'state' for a fact (property like 'job_title', 'deal.proposal_amount'). Examples — sent an " +
-    "email: {kind:'event',property:'interaction.email_sent',value:{description:'intro email'}}; " +
-    "learned their title changed: {kind:'state',property:'job_title',value:'VP of Engineering'}; " +
-    "a fact ended (they left): {kind:'state',property:'job_title',value:null}.",
-    {
-      focus: z.string().describe("Email address or entity UUID of the person or company"),
-      observations: z.array(z.object({
-        kind: z.enum(["event", "state"]).describe("event = an interaction; state = a fact"),
-        property: z.string().describe("e.g. 'interaction.email_sent' or 'job_title'"),
-        value: z.any().optional().describe("the event detail or the fact value; null = the fact ended"),
-        source: z.string().optional().describe("where this came from (default: agent)"),
-      })).describe("One or more observations to record"),
-    },
-    async ({ focus, observations }) => {
-      const result = await post("/v2/observations", { focus, observations });
-      const parts = [`Recorded ${result.recorded} observation${result.recorded !== 1 ? "s" : ""}.`];
-      if (result.claims_recomputed?.length) {
-        parts.push(`Facts updated: ${result.claims_recomputed.join(", ")}.`);
-      }
-      parts.push(`(entity_id: ${result.entity_id})`);
-      return { content: [{ type: "text", text: parts.join("\n") }] };
-    }
-  );
 
 
   // ===========================================================================
@@ -566,8 +534,7 @@ export function createServer() {
   // TOOL: save_note  —  POST /v2/notes
   // Attach a long-form artifact to a CONTACT: a meeting brief you wrote, a
   // transcript, pre-meeting prep, or a plain note. Append-only and dated, so the
-  // contact builds a record across meetings. Distinct from `record` (which logs
-  // that an interaction happened) — this keeps the document itself.
+  // contact builds up a document trail across meetings.
   // ===========================================================================
   server.tool(
     "save_note",
@@ -575,11 +542,9 @@ export function createServer() {
     "brief you wrote, a transcript, pre-meeting prep, research, or a plain note. Use this whenever " +
     "you produce something durable about a specific contact that's worth keeping for next time (e.g. " +
     "after writing a meeting brief, save it to the contact so future meetings can reference it). " +
-    "Notes are append-only and dated, so a contact builds a record across meetings — later you can " +
-    "read the last few and see what changed. This is NOT for logging that an interaction happened " +
-    "(use `record` with an interaction.* event for that), and NOT for the user's own GTM profile " +
-    "(that lives in their context files — sync it with `sync_icp`). Put the full text in `content` — it's kept for agents to read; the " +
-    "UI shows the title and date, not the whole body.",
+    "Notes are append-only and dated, so a contact builds a document trail across meetings — later " +
+    "you can read the last few and see what changed. Put the full text in `content` — it's kept for " +
+    "agents to read; the UI shows the title and date, not the whole body.",
     {
       focus: z.string().describe("Who to attach it to — an email, LinkedIn URL, domain, or entity UUID (not a bare name)."),
       content: z.string().describe("The full note or document text (a short note or a complete brief/transcript)."),
@@ -745,131 +710,43 @@ export function createServer() {
   // ===========================================================================
   server.tool(
     "propose_company_file",
-    "Add or update a markdown file in the SHARED COMPANY vault — the workspace's declared " +
-    "knowledge (policies, playbooks, decisions, SOPs, how-we-work) that every member's agent can " +
-    "read via search_company_knowledge. Use this to contribute company-wide knowledge everyone " +
-    "should have. ADMIN-ONLY: only an owner/admin may write the company vault; a regular member's " +
-    "agent can read it but will get a permission message here. This is NOT the member's private " +
-    "notes (use propose_vault_file) and NOT a note on a contact (use save_note). Pick the " +
-    "destination company folder (it must be an existing folder in the company vault).",
+    "Propose a markdown file for the SHARED COMPANY vault — the workspace's declared knowledge " +
+    "(policies, playbooks, decisions, SOPs, how-we-work) that every member's agent can read via " +
+    "search_company_knowledge. This OPENS A PULL REQUEST against the connected company repo for a " +
+    "human to review and merge in GitHub — nothing goes live until it's merged (company knowledge " +
+    "is shared + institutional, so review-before-publish is the default; on merge the normal git " +
+    "sync ingests it). Use it to contribute company-wide knowledge. ADMIN-ONLY: only an owner/admin " +
+    "may propose; a regular member's agent can READ the vault but gets a permission message here. " +
+    "NOT the member's private notes (use propose_vault_file), NOT a note on a contact (use save_note).",
     {
       folder: z.string().describe("The company-vault folder to file under (e.g. 'company-wiki', 'decisions', 'projects', 'clients'). Must be an existing company folder; no slashes."),
       name: z.string().describe("The file name, ending in .md, e.g. 'Refund Policy.md' or 'Q3 Planning — 2026-08-22.md'."),
       content: z.string().describe("The full markdown content of the file."),
       subfolder: z.string().optional().describe("Optional subfolder within the folder."),
+      message: z.string().optional().describe("Optional PR title / commit message describing the change."),
+      pr_group: z.string().optional().describe("Optional key to batch several proposals from one work session into a SINGLE pull request (same key → same PR)."),
     },
-    async ({ folder, name, content, subfolder }) => {
+    async ({ folder, name, content, subfolder, message, pr_group }) => {
       try {
-        await post("/v2/company/propose", { folder, name, content, subfolder });
-        return { content: [{ type: "text", text: `Filed "${name}" into the company vault (${folder}). It's now searchable by the team's agents via search_company_knowledge.` }] };
+        const r = await post("/v2/company/propose", { folder, name, content, subfolder, message, pr_group });
+        const how = r?.added_to_existing ? "added to the open PR" : "opened a pull request";
+        return { content: [{ type: "text", text: `Proposed "${name}" — ${how}${r?.pr_url ? `: ${r.pr_url}` : ""}. Review the diff and merge it in GitHub to publish into company knowledge.` }] };
       } catch (e) {
         const msg = String(e?.message || e);
         if (msg.includes("admins_only") || msg.includes("(403)")) {
-          return { content: [{ type: "text", text: `Not filed — writing to the company vault is admin-only. You can READ it with search_company_knowledge, but only an owner/admin can add to it.` }] };
+          return { content: [{ type: "text", text: `Not proposed — writing to the company vault is admin-only. You can READ it with search_company_knowledge, but only an owner/admin can propose changes.` }] };
+        }
+        if (msg.includes("no_company_repo")) {
+          return { content: [{ type: "text", text: `Not proposed — no company GitHub repo is connected. An admin connects one under Company vault first.` }] };
+        }
+        if (msg.includes("repo_write_denied")) {
+          return { content: [{ type: "text", text: `Not proposed — the connected repo token is read-only. An admin must reconnect it with Contents:write + Pull requests:write.` }] };
         }
         throw e;
       }
     },
   );
 
-  // ===========================================================================
-  // TOOL: get_workspace_status  —  GET /v2/workspace/status
-  // The "one main call." Edda is operated by the agent, so the agent needs to
-  // know the state of the workspace: is it onboarded, is the GTM foundation built,
-  // which integrations are connected, is CRM sync configured, are events live —
-  // and what to set up next. Call this at the start of a session.
-  // ===========================================================================
-  server.tool(
-    "get_workspace_status",
-    "See the whole setup state of this workspace in one call, plus a ranked NEXT STEPS list (each step " +
-    "carries its own why/how). Edda is operated by you, the agent — call this at the START of a session " +
-    "and walk the user top-down through the steps it returns; the server sequences them by current " +
-    "state, so trust that order. Two constraints when acting on them: (1) Gmail (Google OAuth) and " +
-    "LinkedIn (no public API — Edda uses Unipile) CANNOT be connected by you — point the user to the " +
-    "Integrations page; key-based tools (Prospeo, Apollo, Instantly, HubSpot token) you CAN connect via " +
-    "connect_integration, and CSV import is a user action in the app. (2) Respect the plan — never push " +
-    "a feature it doesn't include (e.g. CRM sync on free). Recommend the next 1-2 steps, don't dump the " +
-    "whole list.",
-    {},
-    async () => {
-      const s = await get("/v2/workspace/status");
-      const setup = s.setup ?? {};
-      const lines = [];
-
-      const ws = s.workspace ?? {};
-      lines.push(`WORKSPACE: ${ws.name || "(unnamed)"}${ws.website ? ` · ${ws.website}` : ""}${ws.business_type ? ` · ${ws.business_type}` : ""}`);
-      const pl = s.plan ?? {};
-      lines.push(`PLAN: ${pl.name || pl.id || "free"}${pl.crm_sync === false ? "  (CRM sync not included — do not offer it)" : ""}`);
-      if (s.self_hosted) {
-        const e = s.env_integrations ?? {};
-        const mk = (b) => (b ? "✓ set" : "✗ NOT set");
-        lines.push("SELF-HOSTED — these channels are wired via edda.env (you can't set env vars; tell the operator to set + restart):");
-        lines.push(`  LinkedIn/Unipile: ${mk(e.linkedin_unipile)}   Email/Resend: ${mk(e.email_resend)}   Gmail OAuth: ${mk(e.gmail_oauth)}`);
-      }
-      lines.push("");
-
-      const mark = (b) => (b ? "✓" : "✗");
-      lines.push("SETUP:");
-      lines.push(`  ${mark(setup.onboarding?.done)} Profile${setup.onboarding?.done ? "" : ` — missing ${(setup.onboarding?.missing ?? []).join(", ") || "details"}`}`);
-      const ints = setup.integrations?.connected ?? [];
-      lines.push(`  ${mark((setup.integrations?.count ?? 0) > 0)} Integrations (${setup.integrations?.count ?? 0})${ints.length ? `: ${ints.map((i) => i.name).join(", ")}` : ""}`);
-      const crm = setup.crm_sync ?? {};
-      if (crm.available === false) {
-        lines.push(`  – CRM sync (not on the ${pl.name || pl.id || "current"} plan)`);
-      } else {
-        lines.push(`  ${mark(crm.configured)} CRM sync${crm.configured ? `: ${(crm.providers ?? []).map((p) => p.provider).join(", ")}` : ""}${crm.pending_hygiene_proposals ? ` · ${crm.pending_hygiene_proposals} hygiene proposal(s) to review` : ""}`);
-      }
-      lines.push(`  ${mark(setup.enrichment?.connected)} Enrichment${setup.enrichment?.provider ? `: ${setup.enrichment.provider}` : ""}`);
-      lines.push(`  ${mark((setup.webhooks?.count ?? 0) > 0 || (setup.triggers?.count ?? 0) > 0)} Events — ${setup.webhooks?.count ?? 0} webhook(s), ${setup.triggers?.count ?? 0} trigger(s)`);
-      const rec = setup.recommended ?? {};
-      lines.push("");
-      lines.push("RECOMMENDED CHANNELS (connect these first):");
-      lines.push(`  ${mark(rec.email)} Email / Gmail   ${mark(rec.linkedin)} LinkedIn   ${mark(rec.meeting_notetaker)} Meeting note-taker`);
-      lines.push(`  Records imported: ${setup.records?.count ?? 0}`);
-
-      if (s.next_steps?.length) {
-        lines.push("");
-        lines.push("NEXT STEPS:");
-        for (const step of s.next_steps) {
-          lines.push(`  • ${step.title}`);
-          if (step.why) lines.push(`      why: ${step.why}`);
-          if (step.how) lines.push(`      how: ${step.how}`);
-        }
-      } else {
-        lines.push("");
-        lines.push("Everything's set up. Nothing pending.");
-      }
-
-      return { content: [{ type: "text", text: lines.join("\n").trim() }] };
-    }
-  );
-
-  // ===========================================================================
-  // TOOL: set_workspace_profile  —  POST /v2/workspace/onboarding
-  // Agent-driven onboarding. Instead of a human clicking through a wizard in the
-  // app, you collect the basics from the user in conversation and write them
-  // here. This is the first thing get_workspace_status asks for when a workspace
-  // is new.
-  // ===========================================================================
-  server.tool(
-    "set_workspace_profile",
-    "Set or update the workspace's basic identity — its company name and website. Send only the fields " +
-    "you're setting or changing.",
-    {
-      name: z.string().optional().describe("The company / workspace name."),
-      website: z.string().optional().describe("The company website."),
-    },
-    async ({ name, website }) => {
-      const r = await post("/v2/workspace/onboarding", { name, website });
-      const w = r.workspace ?? {};
-      const set = [
-        w.name && `name=${w.name}`,
-        w.website && `site=${w.website}`,
-      ].filter(Boolean);
-      return { content: [{ type: "text", text:
-        `Workspace profile saved.${set.length ? ` ${set.join(" · ")}.` : ""}` }] };
-    }
-  );
 
   // ===========================================================================
   // TOOL: connect_integration  —  POST /v2/workspace/integrations
@@ -910,36 +787,6 @@ export function createServer() {
     }
   );
 
-  // ===========================================================================
-  // TOOLS: the CORRECTION layer — unsay something recorded by mistake. `record` and
-  // `save_note` are how you write; these are how you take it back. Both heal the
-  // derived layer: retracting an observation re-derives the claim from what remains,
-  // deleting a note drops it from search/context. DELETE /v2/observations|notes/:id.
-  // ===========================================================================
-  server.tool(
-    "retract_observation",
-    "RETRACT an observation you recorded by mistake, and heal the record. Pass the observation's " +
-    "`id` (returned by `record`). Edda deletes it and re-derives the affected fact from the " +
-    "observations that remain — so a wrong value you observed is un-observed and the claim reverts as " +
-    "if it had never happened; if it was the only observation for that fact, the fact is invalidated. " +
-    "Use this when you recorded the wrong thing (wrong value, wrong person, a test), NOT to represent a " +
-    "real change over time — a genuine change is a NEW `record`, which supersedes by recency.",
-    {
-      id: z.string().describe("The observation id to retract (from a prior `record` result)."),
-    },
-    async ({ id }) => {
-      try {
-        const r = await del(`/v2/observations/${encodeURIComponent(id)}`);
-        return { content: [{ type: "text", text:
-          `Observation retracted. The claim for ${r.property} was ${r.claim === "invalidated" ? "invalidated (no observations left)" : "re-derived from the remaining observations"}.` }] };
-      } catch (e) {
-        const msg = /observation_not_found/.test(e.message)
-          ? "No observation with that id in this workspace — check the id from the record result."
-          : `Couldn't retract the observation: ${e.message}`;
-        return { content: [{ type: "text", text: msg }] };
-      }
-    }
-  );
 
 
   server.tool(
@@ -956,24 +803,6 @@ export function createServer() {
     }
   );
 
-  server.tool(
-    "whoami",
-    "Report who this API key acts AS and who else is on the workspace — the agent's own identity in " +
-    "Edda. Returns your scope (a MEMBER key sees only that member's private content plus the shared " +
-    "graph; an ADMIN key sees all raw content) and the team roster with names and roles. Use it to " +
-    "understand whose view you have and to reference teammates. Emails show only for an admin key.",
-    {},
-    async () => {
-      const r = await get("/v2/workspace/members");
-      const scope = r.you?.scope === "admin"
-        ? "an ADMIN key — you see all raw content on this workspace"
-        : "a MEMBER key — you see only your own private content plus the shared graph";
-      const roster = (r.members || [])
-        .map(m => `  • ${m.name || "(unnamed)"} — ${m.role}${m.you ? " (you)" : ""}${m.email ? ` · ${m.email}` : ""}`)
-        .join("\n");
-      return { content: [{ type: "text", text: `You are ${scope}.\n\nWorkspace members (${r.count ?? 0}):\n${roster || "  (none)"}` }] };
-    }
-  );
 
 
   return server;