@edda-business/mcp 0.56.0 → 0.58.0

package/package.json

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

package/src/server.js

@@ -13,7 +13,7 @@
  * Tools, by group (v0.56 — consolidated, Cerebras-style):
  *   RETRIEVE  search (unified, scope=all|company|personal|notes) · get_context ·
  *             get_account · who_knows · query · attention · verify
- *   WRITE     save_note · save_to_vault · propose_company_file
+ *   WRITE     save_note · save_to_vault · update_vault_file · propose_company_file
  *   FIX       merge_contacts (action=merge|split)
  *   RUN       list_integrations · connect_integration
  *
@@ -26,7 +26,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { get, post, del } from "./client.js";
 
-export const SERVER_VERSION = "0.56.0";
+export const SERVER_VERSION = "0.58.0";
 
 // ─── helpers ──────────────────────────────────────────────────────────────────
 
@@ -91,13 +91,12 @@ export function createServer() {
   server.tool(
     "get_context",
     "Get engineered context for a specific task about a person or company. Pass their email (or " +
-    "entity id) and the intent. Returns a focused, ranked context block: the facts that matter for " +
-    "that task — each with a confidence and a freshness — the durable FACTS we've learned about them " +
-    "(their atomic memory: budget, authority, pain, stack, plans), the recent timeline, the buying-group " +
-    "stakeholders, open predictions, and the account's ICP fit score (0-100 + why). Call this before " +
-    "drafting outreach, preparing for a meeting, " +
-    "or making any decision about a person. A fact's freshness tells you whether to trust it: 'fresh' " +
-    "act on it, 'suspect'/'expired' verify first.",
+    "entity id) and the intent. Returns a focused, ranked context block: the durable FACTS we've " +
+    "learned about them (each with a confidence and a freshness), the recent timeline, the other " +
+    "people at their company and how they relate, and the relevant notes and records. Call this before " +
+    "a meeting or any decision about a person or company, so you act on what we actually know rather " +
+    "than generic guesses. A fact's freshness tells you whether to trust it: 'fresh' 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(["follow_up", "meeting_prep", "call_prep", "account_review"])
@@ -131,11 +130,6 @@ export function createServer() {
         }
         lines.push("");
       }
-      if (ctx.workspace?.length) {
-        lines.push("YOUR CONTEXT (ICP / product / positioning):");
-        for (const w of ctx.workspace) lines.push(`  ${w.property}: ${fmtVal(w.value)}`);
-        lines.push("");
-      }
       if (ctx.timeline?.length) {
         lines.push("TIMELINE:");
         for (const t of ctx.timeline) {
@@ -157,23 +151,18 @@ export function createServer() {
         lines.push("");
       }
       if (ctx.stakeholders?.length) {
-        // The buying committee as a STRUCTURE: who's at the account, their role,
-        // whether we've engaged them, and how they relate — so the agent works the
-        // whole committee, not one person.
+        // The people connected to this company and how they relate — the local map, so
+        // the agent sees the whole picture, not one person in isolation.
         const c = ctx.committee;
-        lines.push(c?.company ? `BUYING COMMITTEE — ${c.company}:` : "STAKEHOLDERS:");
+        lines.push(c?.company ? `PEOPLE AT ${c.company}:` : "RELATED PEOPLE:");
         for (const s of ctx.stakeholders) {
           if (s.role === "company") continue; // the company is the header
           const bits = [];
-          if (s.committee_role && s.committee_role !== "contact") bits.push(s.committee_role.replace(/_/g, " "));
           if (s.role) bits.push(s.role);
-          bits.push(s.engaged ? "engaged" : "not yet engaged");
           if (s.confirmed === false) bits.push("mentioned, unconfirmed");
           const rel = s.relationships?.length ? ` — ${s.relationships.join("; ")}` : "";
-          lines.push(`  ${s.name ?? "—"} (${bits.join(", ")})${rel}`);
+          lines.push(`  ${s.name ?? "—"}${bits.length ? ` (${bits.join(", ")})` : ""}${rel}`);
         }
-        if (c?.champion) lines.push(`  champion: ${c.champion}`);
-        if (c?.gaps?.length) for (const g of c.gaps) lines.push(`  ⚠ ${g}`);
         lines.push("");
       }
       return {
@@ -188,8 +177,8 @@ export function createServer() {
   // ===========================================================================
   server.tool(
     "get_account",
-    "Get the full account record for a person or company — the durable FACTS we've learned about them " +
-    "(their atomic memory: budget, authority, pain, stack, plans), every attribute (claim) with its " +
+    "Get the full record for a person or company — the durable FACTS we've learned about them (their " +
+    "role, company, history, and anything else worth remembering), every attribute (claim) with its " +
     "confidence and freshness, plus what they actually SAID and did, ranked by how much it tells you. " +
     "Pass an email or entity UUID, and the intent you're working toward so the record is shaped for it.",
     {
@@ -243,23 +232,18 @@ export function createServer() {
         }
         lines.push("");
       }
-      // The buying committee — who else is at the account, their role, whether we've
-      // engaged them, and how they relate. Same structure get_context surfaces.
+      // The people connected to this company and how they relate. Same structure get_context surfaces.
       if (rec.stakeholders?.length) {
         const c = rec.committee;
-        lines.push(c?.company ? `BUYING COMMITTEE — ${c.company}:` : "STAKEHOLDERS:");
+        lines.push(c?.company ? `PEOPLE AT ${c.company}:` : "RELATED PEOPLE:");
         for (const s of rec.stakeholders) {
           if (s.role === "company") continue;
           const bits = [];
-          if (s.committee_role && s.committee_role !== "contact") bits.push(s.committee_role.replace(/_/g, " "));
           if (s.role) bits.push(s.role);
-          bits.push(s.engaged ? "engaged" : "not yet engaged");
           if (s.confirmed === false) bits.push("mentioned, unconfirmed");
           const rel = s.relationships?.length ? ` — ${s.relationships.join("; ")}` : "";
-          lines.push(`  ${s.name ?? "—"} (${bits.join(", ")})${rel}`);
+          lines.push(`  ${s.name ?? "—"}${bits.length ? ` (${bits.join(", ")})` : ""}${rel}`);
         }
-        if (c?.champion) lines.push(`  champion: ${c.champion}`);
-        if (c?.gaps?.length) for (const g of c.gaps) lines.push(`  ⚠ ${g}`);
         lines.push("");
       }
       const claims = Object.values(rec.claims ?? {});
@@ -421,22 +405,21 @@ export function createServer() {
   // ===========================================================================
   server.tool(
     "query",
-    "Retrieve and summarise activity across many people. Three powers:\n" +
+    "Retrieve and summarise activity across many people and companies. Powers:\n" +
     "  1. return:'entities' groups results by person/company (one row per entity, ranked by " +
-    "most-recent matching activity). Use for 'hottest leads', 'who replied this week', " +
-    "'who's in the negotiation stage'.\n" +
-    "  2. `without` subtracts entities — 'sent in 5d MINUS replied in 5d' = 'no-reply leads'. " +
-    "'activity in 30d MINUS activity in 5d' = 'cooled leads'.\n" +
-    "  3. rollups.by_value appears when scope.kind='state' — counts entities by current value " +
-    "(use scope.property='stage' for funnel reports).\n" +
+    "most-recent matching activity). Use for 'who we talked to this week', 'who replied recently'.\n" +
+    "  2. `without` subtracts entities — 'sent in 5d MINUS replied in 5d' = 'wrote to, no reply back'. " +
+    "'activity in 30d MINUS activity in 5d' = 'people who've gone quiet'.\n" +
+    "  3. rollups.by_value appears when scope.kind='state' — counts entities by a current value " +
+    "(scope.property='<state property>').\n" +
     "  4. Scheduled meetings/calls are events with property 'interaction.meeting_scheduled' and a " +
     "future-dated `when`. For 'what's booked today/this week', set property:'interaction.meeting_scheduled' " +
     "with from/to bounding the day or week (since_days only looks backward and can't reach them), and " +
     "order:'asc' to list soonest-first. Meeting rows render the absolute date and time.\n" +
-    "  5. scope.facts:true + question searches the FACTS corpus (durable atomic facts about accounts) " +
-    "instead of activity — cross-account semantic fact search like 'which accounts want off Clay' or " +
-    "'who is hiring'. return:'entities' gives the single best-matching fact per account. (A single " +
-    "account's facts already come back inline with get_account.)",
+    "  5. scope.facts:true + question searches the FACTS corpus (durable facts about people/companies) " +
+    "instead of activity — cross-record semantic fact search like 'who is hiring' or 'who mentioned " +
+    "switching tools'. return:'entities' gives the single best-matching fact per record. (A single " +
+    "record's facts already come back inline with get_account.)",
     {
       scope: z.object({
         kind: z.enum(["event", "state"]).optional(),
@@ -448,7 +431,7 @@ export function createServer() {
         to: z.string().optional().describe("ISO timestamp — only activity at/before this (absolute upper bound). Combine from+to for a window; future-dated for upcoming meetings"),
         order: z.enum(["asc", "desc"]).optional().describe("observed_at order (default desc, newest first). Use 'asc' for an upcoming-meeting schedule (soonest first)"),
         limit: z.number().optional().describe("max items (default 50, cap 200)"),
-        facts: z.boolean().optional().describe("search the FACTS corpus (durable atomic facts about accounts) instead of activity. Needs `question` — a cross-account semantic fact search, e.g. 'which accounts want off Clay'. return:'entities' = the best matching fact per account."),
+        facts: z.boolean().optional().describe("search the FACTS corpus (durable facts about people/companies) instead of activity. Needs `question` — a cross-record semantic fact search, e.g. 'who is hiring'. return:'entities' = the best matching fact per record."),
       }).describe("Corpus filter"),
       without: z.object({
         kind: z.enum(["event", "state"]).optional(),
@@ -537,12 +520,12 @@ export function createServer() {
   // ===========================================================================
   server.tool(
     "verify",
-    "Re-check a specific fact before you act on it — e.g. an email or a deal stage that looks stale " +
+    "Re-check a specific fact before you act on it — e.g. an email or a job title that looks stale " +
     "in get_context. Pass the person/company and the property name. Returns the fact re-derived from " +
     "current evidence, and tells you whether it is still unverified.",
     {
       focus: z.string().describe("Email, LinkedIn URL, entity UUID, or name"),
-      property: z.string().describe("The fact to re-check — e.g. 'email', 'job_title', 'pipeline_stage'"),
+      property: z.string().describe("The fact to re-check — e.g. 'email', 'job_title', 'company'"),
     },
     async ({ focus, property }) => {
       const r = await post("/v2/verify", { focus, property });
@@ -610,7 +593,7 @@ export function createServer() {
     },
     async ({ folder, name, content, subfolder }) => {
       const r = await post("/v2/personal/files", { folder, name, content, subfolder });
-      return { content: [{ type: "text", text: `Saved "${name}" to your ${r?.folder || folder} vault — it's searchable now.` }] };
+      return { content: [{ type: "text", text: `"${name}" is waiting in your Inbox to approve — once you do, it files into ${r?.folder || folder}.` }] };
     },
   );
 
@@ -761,14 +744,13 @@ export function createServer() {
   // ===========================================================================
   server.tool(
     "connect_integration",
-    "Connect a key-based integration for the user — an enrichment, CRM, or sequencer provider that " +
-    "authenticates with an API key or token (e.g. Apollo, Prospeo, Instantly, HubSpot private-app " +
-    "token, Pipedrive, Attio, Smartlead, HeyReach). Ask the user for the provider's API key, then " +
-    "call this; it verifies the credentials before saving. Providers that use a browser sign-in " +
-    "(OAuth, e.g. Gmail) can't be connected this way — for those, point the user to the Integrations " +
-    "page. After connecting an enrichment provider, the account record starts filling in.",
+    "Connect a data source that feeds the knowledge base — a provider that authenticates with an API " +
+    "key or token. Ask the user for the provider's key, then call this; it verifies the credentials " +
+    "before saving. Providers that use a browser sign-in (OAuth, e.g. Gmail or calendar) can't be " +
+    "connected this way — for those, point the user to the Integrations page. Once connected, the " +
+    "source starts feeding the knowledge base.",
     {
-      provider: z.string().describe("Provider name, lowercase — e.g. 'apollo', 'prospeo', 'instantly', 'hubspot', 'pipedrive', 'attio'."),
+      provider: z.string().describe("Provider name, lowercase."),
       credentials: z.record(z.string()).describe("The provider's credentials as key/value, e.g. { api_key: '...' } or { access_token: '...' }."),
       name: z.string().optional().describe("Optional label for the connection."),
     },
@@ -800,13 +782,14 @@ export function createServer() {
   // ===========================================================================
   server.tool(
     "save_to_vault",
-    "Save a file into the MEMBER'S OWN private knowledge vault, in a folder they name " +
-    "(inbox, projects, decisions, companies, people, resources, archive, thoughts). Use it when the " +
-    "member asks you to keep or file something for them — 'save this to projects', 'put this PDF in " +
-    "resources'. Pass markdown/text as `content`, OR a PDF/DOCX as base64 in `file` (it's extracted to " +
-    "text automatically and stored so they can search it later). PRIVATE to the member — nothing is " +
-    "shared until they promote it to their department. NOT the shared company vault (use " +
-    "propose_company_file), NOT a note on a contact (use save_note).",
+    "Save a file into the MEMBER'S OWN private knowledge vault. It lands in their INBOX for review " +
+    "with the target folder you name remembered (inbox, projects, decisions, companies, people, " +
+    "resources, archive, thoughts); the member approves it in the app, which files it into that folder " +
+    "and makes it searchable. Nothing enters their knowledge without their approval. Use it when the " +
+    "member asks you to keep or file something — 'save this to resources', 'put this PDF in projects'. " +
+    "Pass markdown/text as `content`, OR a PDF/DOCX as base64 in `file` (extracted to text automatically). " +
+    "PRIVATE to the member. NOT the shared company vault (use propose_company_file), NOT a note on a " +
+    "contact (use save_note).",
     {
       folder: z.string().describe("The vault folder: inbox | projects | decisions | companies | people | resources | archive | thoughts."),
       name: z.string().describe("The file name, e.g. 'Q3 Plan.md' or 'vendor-contract.pdf'."),
@@ -818,7 +801,7 @@ export function createServer() {
     async ({ folder, name, content, file, mime, subfolder }) => {
       try {
         const r = await post("/v2/personal/files", { folder, name, content, file_base64: file, mime, subfolder });
-        return { content: [{ type: "text", text: `Saved "${name}" to your ${r?.folder || folder} vault — it's searchable now.` }] };
+        return { content: [{ type: "text", text: `"${name}" is waiting in your Inbox to approve — once you do, it files into ${r?.folder || folder} and becomes searchable.` }] };
       } catch (e) {
         const msg = String(e?.message || e);
         if (msg.includes("no_text_extracted")) return { content: [{ type: "text", text: `Couldn't read any text from that file — a scanned/image-only PDF has no extractable text. Text, markdown, or a text-based PDF/DOCX works.` }] };
@@ -828,6 +811,40 @@ export function createServer() {
     }
   );
 
+  // ===========================================================================
+  // TOOL: update_vault_file  —  POST /v2/personal/files/update
+  // Edit an existing personal file. Snapshots the old content to version history,
+  // then replaces/appends + re-embeds. save_to_vault is for NEW files (→ Inbox);
+  // this edits one that's already live.
+  // ===========================================================================
+  server.tool(
+    "update_vault_file",
+    "Edit an EXISTING file in the member's own vault — revise it or append to it. Identify the file by " +
+    "`file_id` (from a search or save result) or by `path` ('folder/[subfolder/]name.md'). The previous " +
+    "content is saved to version history FIRST (never lost), then your new content replaces it — or is added " +
+    "to the end with append:true — and the file is re-embedded; the member sees a fresh 'updated' time. Use " +
+    "this to keep a living document current: a rolling brief, a spec, a running log. For a NEW file use " +
+    "save_to_vault (which lands in the Inbox for approval); this edits one that already exists and is live.",
+    {
+      file_id: z.string().optional().describe("The file's id (from a search/save result). Provide this OR path."),
+      path: z.string().optional().describe("The file's vault path, e.g. 'resources/Edda Architecture.md'. Provide this OR file_id."),
+      content: z.string().describe("The new markdown content. Replaces the file's content unless append is true."),
+      append: z.boolean().optional().describe("If true, append this to the end of the file instead of replacing it."),
+    },
+    async ({ file_id, path, content, append }) => {
+      try {
+        const r = await post("/v2/personal/files/update", { file_id, path, content, append });
+        return { content: [{ type: "text", text: r?.note || "Updated the file." }] };
+      } catch (e) {
+        const msg = String(e?.message || e);
+        if (msg.includes("not_found")) return { content: [{ type: "text", text: "Couldn't find that file — check the file_id or path (folder/name.md)." }] };
+        if (msg.includes("file_id_or_path_required")) return { content: [{ type: "text", text: "Tell me which file to edit — pass file_id or path." }] };
+        if (msg.includes("content_required")) return { content: [{ type: "text", text: "Give me the new content to write." }] };
+        throw e;
+      }
+    }
+  );
+
   server.tool(
     "list_integrations",
     "List the integrations connected to this workspace (Gmail, HubSpot, Apollo, Instantly, LinkedIn, …) " +