@opennous/mcp 0.42.0 → 0.44.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opennous/mcp",
-  "version": "0.42.0",
+  "version": "0.44.0",
   "description": "Nous — the Context Graph for AI Agents.",
   "license": "AGPL-3.0-only",
   "repository": {

package/src/server.js

@@ -23,8 +23,8 @@
  *   search_notes         — semantic search over saved notes & documents
  *   get_workspace_status — what's set up in this workspace + a ranked next_steps list (call first)
  *   set_workspace_profile— agent-driven onboarding: set the workspace's name, site, type, ICP
- *   build_scoring_model  — build/rebuild the ICP scoring model from the recorded GTM context
- *   record_closed_deals  — build the ICP model from real closed-won/lost deals (contrastive lift)
+ *   build_icp_model  — build/rebuild the ICP scoring model from the recorded GTM context
+ *   train_icp_model  — build the ICP model from real closed-won/lost deals (contrastive lift)
  *   sync_icp              — sync the user's EXISTING ICP/positioning files into Nous (file → graph)
  *   export_icp_model        — get the learned ICP model as a block to write back into their ICP file (graph → file)
  *   connect_integration  — connect a key-based integration (Apollo, Prospeo, HubSpot, …)
@@ -34,7 +34,7 @@
  *   list_triggers        — list the workspace's event triggers + available events
  *   get_routing_preferences — Claude Code routing prefs to default GTM to Nous (write to CLAUDE.md)
  *   lead_list_operations — the operations trail of a lead list (imports/enrich/push/replies), filterable
- *   coverage             — pre-spend coverage: exact per-lead check (identifiers) or attribute estimate (title/keyword)
+ *   get_coverage         — pre-spend coverage: exact per-lead check (identifiers) or attribute estimate (title/keyword)
  *   enrich_leads         — find missing emails for a lead list (two-step: dry-run cost preview, then confirm)
  *   verify_leads         — validate email deliverability for a lead list (two-step preview, then confirm)
  */
@@ -89,9 +89,9 @@ const pct     = (c) => `${Math.round((c ?? 0) * 100)}%`;
 // Gong/Granola). Returned by get_routing_preferences; the agent writes it into
 // the user's CLAUDE.md (Claude Code) or the user pastes it into claude.ai org
 // preferences. Mirrors the Install page's "short" version.
-const ROUTING_PREFERENCES = `# Nous is this workspace's customer graph
+const ROUTING_PREFERENCES = `# Nous is this workspace's GTM context graph
 
-Nous is our customer graph for GTM. It resolves every person, conversation, and
+Nous is our context graph for GTM. It resolves every person, conversation, and
 touchpoint across our GTM tool stack into one account record, with each fact's
 confidence and freshness, the full interaction timeline, a 0-100 ICP fit score on
 every account, plus our own ICP, positioning, and pricing. Agents read engineered
@@ -249,11 +249,27 @@ export function createServer() {
     "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 " +
-    "confidence and freshness, plus the recent activity timeline. Pass an email or entity UUID. " +
-    "For a task-specific, ranked view, prefer get_context.",
-    { id: z.string().describe("Email address or entity UUID") },
-    async ({ id }) => {
-      const rec = await get(`/v2/accounts/${encodeURIComponent(id)}`);
+    "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.",
+    {
+      id: z.string().describe("Email address or entity UUID"),
+      intent: z
+        .enum(["meeting_prep", "call_prep", "account_review", "follow_up", "draft_email"])
+        .optional()
+        .describe(
+          "What you're about to do. Shapes how much of their history comes back: a meeting brief wants " +
+          "the conversation in detail, an email draft wants one hook. Defaults to account_review.",
+        ),
+    },
+    async ({ id, intent }) => {
+      // Ask for the RANKED record, not the raw one.
+      //
+      // The timeline this tool used to print was chronological and contentless —
+      // "3d ago  email_sent" — which tells an agent that something happened and
+      // nothing about what. Ranked activity carries the source and the substance,
+      // so the model reads what was actually said instead of a list of event names.
+      const q = new URLSearchParams({ intent: intent ?? "account_review", compress: "1" });
+      const rec = await get(`/v2/accounts/${encodeURIComponent(id)}?${q}`);
       const lines = [`${rec.type} · ${rec.entity_id}`, ""];
 
       if (rec.icp) {
@@ -275,13 +291,37 @@ export function createServer() {
         }
         lines.push("");
       }
-      const obs = rec.recent_observations ?? [];
-      if (obs.length) {
+      // What they actually said and did — the most telling first, each with the
+      // system it came from, so a claim in the answer can always be traced back.
+      const activity = rec.key_activity ?? [];
+      if (activity.length) {
+        lines.push(`WHAT HAPPENED (${activity.length} most telling):`);
+        for (const a of activity) {
+          const when = a.when ? relAge(a.when) : "";
+          const head = `  ${a.what}${a.source ? ` · ${a.source}` : ""}${when ? ` · ${when}` : ""}`;
+          lines.push(a.detail ? `${head}\n      ${a.detail}` : head);
+        }
+        lines.push("");
+      }
+
+      // Say what was left out, and why. An agent that is handed 18 of 300
+      // interactions and does not know it will happily conclude that nothing else
+      // ever happened.
+      const sum = rec.activity_summary;
+      if (sum?.note) lines.push(sum.note);
+      else if (sum?.total_observations) {
+        lines.push(`${sum.total_observations} interactions on record.`);
+      }
+
+      // Fall back to the raw timeline if an older API didn't rank anything.
+      if (!activity.length && rec.recent_observations?.length) {
+        const obs = rec.recent_observations;
         lines.push(`TIMELINE (${obs.length}):`);
         for (const o of obs.slice(0, 30)) {
           lines.push(`  ${whenLabel(o.property, o.observed_at)}  ${fmtType(o.property)}`);
         }
       }
+
       return { content: [{ type: "text", text: lines.join("\n").trim() }] };
     }
   );
@@ -507,9 +547,15 @@ export function createServer() {
         return { content: [{ type: "text", text: "Nothing needs attention right now." }] };
       }
       // Upcoming meetings carry a `when` — render the absolute local date+time.
+      //
+      // Each item also names where it came from: the calendar holding the call, the
+      // transcript the promise was captured from. An agent that can cite the call
+      // someone made a promise ON is making an argument; one that just asserts the
+      // promise is asking to be trusted.
       const lines = r.items.map(it => {
         const when = it.when ? `${fmtWhen(it.when)} — ` : "";
-        return `  ${when}${it.entity_name ?? it.entity_id} — ${it.what}\n      → ${it.suggested_action}`;
+        const from = it.source ? `  [${it.source}]` : "";
+        return `  ${when}${it.entity_name ?? it.entity_id} — ${it.what}${from}\n      → ${it.suggested_action}`;
       });
       return { content: [{ type: "text", text: `Needs attention (${r.items.length}):\n${lines.join("\n")}` }] };
     }
@@ -638,6 +684,11 @@ export function createServer() {
     "whenever you edit a policy file in the repo (e.g. references/voice.md, outreach rules), passing the " +
     "file's new content and its path, so Nous mirrors it and every other agent obeys the same rules. An " +
     "edited playbook file that isn't synced is silently inert — other agents keep reading the old rules. " +
+    "MIRROR, DO NOT REWRITE: when the user already has a playbook file, sync it AS-IS. Their file is the " +
+    "author and Nous is the mirror — always pass file_path so the next sync knows where an in-app edit " +
+    "lands. 'Improving' their wording on the way through means the copy in Nous silently disagrees with " +
+    "the copy in their repo, and they will trust neither. If a file looks wrong, SAY SO; don't fix it in " +
+    "transit. " +
     "(For the ICP/context files specifically, sync_icp is the sync — use that one.)",
     syncPlaybookSchema, syncPlaybookHandler);
 
@@ -752,7 +803,19 @@ export function createServer() {
 
       const mark = (b) => (b ? "✓" : "✗");
       lines.push("SETUP:");
-      lines.push(`  ${mark(setup.onboarding?.done)} Onboarding${setup.onboarding?.done ? "" : ` — missing ${(setup.onboarding?.missing ?? []).join(", ") || "details"}`}`);
+      // The ICP first, because it IS the gate — a workspace without one is not set up, no
+      // matter how many integrations are green. If it's mirrored from a file in their repo,
+      // say so and say where: that file is the author, and editing anything else is a way of
+      // losing their work on the next sync.
+      const icp = setup.icp ?? {};
+      lines.push(
+        `  ${mark(icp.done)} ICP${icp.done
+          ? (icp.source === "claude_code" && icp.file_path
+              ? ` — mirrored from ${icp.file_path} (their repo is the author; edit the FILE, then sync)`
+              : " — authored in Nous")
+          : " — MISSING. The workspace is not set up until this exists. Scan their repo before you ask them anything."}`
+      );
+      lines.push(`  ${mark(setup.onboarding?.done)} Profile${setup.onboarding?.done ? "" : ` — missing ${(setup.onboarding?.missing ?? []).join(", ") || "details"}`}`);
       lines.push(`  ${mark(setup.gtm_playbook?.done)} GTM playbook${setup.gtm_playbook?.model ? " (scoring model live)" : ""}${setup.gtm_playbook?.stale_facts ? ` · ${setup.gtm_playbook.stale_facts} stale fact(s)` : ""}`);
       if (setup.icp_sync) {
         const sy = setup.icp_sync;
@@ -842,14 +905,14 @@ export function createServer() {
   );
 
   // ===========================================================================
-  // TOOL: build_scoring_model  —  POST /v2/workspace/scoring-model
+  // TOOL: build_icp_model  —  POST /v2/workspace/scoring-model
   // The second half of building the GTM playbook. The agent syncs the GTM context
   // from the user's files with sync_icp, then calls this to turn it into a weighted
   // ICP scoring model. After this, accounts get scored for fit and
   // get_workspace_status shows the playbook as done.
   // ===========================================================================
   server.tool(
-    "build_scoring_model",
+    "build_icp_model",
     "Build (or rebuild) the user's ICP scoring model from their synced GTM context. This is " +
     "the second half of setting up the GTM playbook: first sync the user's ICP/positioning/pricing " +
     "files with sync_icp, then call this to translate that context into a weighted set of scoring " +
@@ -858,7 +921,7 @@ export function createServer() {
     "pass force:true (use that when the context files have changed and the model should be rebuilt). If " +
     "it reports no GTM context yet, sync the user's context files with sync_icp first, then call this again. " +
     "STRONGER than this tool: if the user can name a few closed-WON and closed-LOST customer domains, " +
-    "call record_closed_deals instead (or as well) — it trains the model on real outcomes via " +
+    "call train_icp_model instead (or as well) — it trains the model on real outcomes via " +
     "contrastive lift, which beats a model inferred from a description.",
     {
       force: z.boolean().optional()
@@ -882,7 +945,7 @@ export function createServer() {
         }
         if (msg.includes("model_exists")) {
           return { content: [{ type: "text", text:
-            "A scoring model already exists. Call build_scoring_model again with force:true to rebuild it from the current GTM context." }] };
+            "A scoring model already exists. Call build_icp_model again with force:true to rebuild it from the current GTM context." }] };
         }
         throw e;
       }
@@ -890,11 +953,11 @@ export function createServer() {
   );
 
   // ===========================================================================
-  // TOOL: record_closed_deals  —  POST /v2/workspace/closed-deals
+  // TOOL: train_icp_model  —  POST /v2/workspace/closed-deals
   // Build the ICP model from REAL outcomes via contrastive lift (won vs lost).
   // ===========================================================================
   server.tool(
-    "record_closed_deals",
+    "train_icp_model",
     "Build (or sharpen) the ICP scoring model from the user's REAL closed deals. Pass closed-WON " +
     "customer domains and closed-LOST domains; Nous enriches each, links the contacts you already " +
     "have there, and runs contrastive lift (what's true of winners but not losers) to discover the " +
@@ -986,7 +1049,7 @@ export function createServer() {
         const sig = r.signals ?? [];
         if (r.model_status === "created" && sig.length) {
           lines.push("", `Built the ICP scoring model — ${sig.length} signal${sig.length === 1 ? "" : "s"}.`);
-          lines.push("Next: if the user can name a few closed-won + closed-lost domains, call record_closed_deals to sharpen it on real outcomes, then call export_icp_model to write the learned model back into their ICP file.");
+          lines.push("Next: if the user can name a few closed-won + closed-lost domains, call train_icp_model to sharpen it on real outcomes, then call export_icp_model to write the learned model back into their ICP file.");
         } else if (r.model_status === "no_icp_memory") {
           lines.push("", "Synced, but there wasn't enough ICP content to build a scoring model — make sure the ICP section has real content.");
         } else {
@@ -1019,7 +1082,7 @@ export function createServer() {
     "calibration gap) as a ready-to-write markdown block, and write it back into the user's own ICP " +
     "file. This is the payoff of the symbiosis: their file keeps the words, Nous keeps the model, and " +
     "this writes the model under their words. CLAUDE CODE flow: call this after sync_icp or after " +
-    "record_closed_deals, then with your file tools open `target_path`, and if the file already has a " +
+    "train_icp_model, then with your file tools open `target_path`, and if the file already has a " +
     "block between '<!-- nous:icp start -->' and '<!-- nous:icp end -->' REPLACE that whole block with " +
     "the returned `block`; if not, append the returned `block` (e.g. replacing a '## [To refine]' " +
     "placeholder). Never edit inside the markers by hand — this tool regenerates them. Everything " +
@@ -1030,11 +1093,11 @@ export function createServer() {
       if (!r.has_model) {
         return { content: [{ type: "text", text:
           "No ICP scoring model yet. Sync the user's ICP file with sync_icp first (or build one with " +
-          "build_scoring_model / record_closed_deals), then call this to write it back." }] };
+          "build_icp_model / train_icp_model), then call this to write it back." }] };
       }
       const note = r.has_outcomes
         ? "This model is trained on real closed deals (lift + calibration shown)."
-        : "This model is seeded from the ICP only — add closed deals with record_closed_deals to sharpen it.";
+        : "This model is seeded from the ICP only — add closed deals with train_icp_model to sharpen it.";
       return { content: [{ type: "text", text:
         `Write the block below into ${r.target_path} with your file editor — replace any existing block ` +
         `between the nous:icp markers, or append it if there's none (create the file/section if absent). ` +
@@ -1253,14 +1316,14 @@ export function createServer() {
   );
 
   // ===========================================================================
-  // TOOL: coverage  —  POST /v2/dedup (exact) | GET /v2/people/coverage (estimate)
+  // TOOL: get_coverage  —  POST /v2/dedup (exact) | GET /v2/people/coverage (estimate)
   // "What do I already have?" before spending on a list elsewhere. One tool, two
   // modes: pass identifiers for an EXACT per-lead net-new/re-enrich/reuse check
   // (the pre-spend gate), or a title/keyword for a rough attribute ESTIMATE.
   // (Replaces the former check_leads + lead_coverage tools.)
   // ===========================================================================
   server.tool(
-    "coverage",
+    "get_coverage",
     "(Nous Cloud only) Check what you ALREADY have before spending on a list elsewhere (Apollo, Sales Navigator, Clay). " +
     "Two modes:\n" +
     "  • EXACT — pass candidate identifiers (emails / linkedin_urls / domains, free in any tool's " +