@opennous/mcp 0.46.0 → 0.48.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opennous/mcp",
-  "version": "0.46.0",
+  "version": "0.48.0",
   "description": "Nous — the Context Graph for AI Agents.",
   "license": "Apache-2.0",
   "repository": {

package/src/http.js

@@ -3,7 +3,7 @@
 /**
  * Nous MCP Server — hosted, multi-tenant HTTP entrypoint (mcp.opennous.cloud).
  *
- * Serves the same seven tools (server.js) over the MCP Streamable HTTP transport,
+ * Serves the same tool set (server.js) over the MCP Streamable HTTP transport,
  * so cloud clients that cannot launch a local process — n8n cloud above all —
  * can connect by pasting one URL plus their workspace API key.
  *

package/src/server.js

@@ -10,34 +10,24 @@
  * sees raw rows — it gets engineered, epistemics-tagged context. It never
  * "updates" — it records observations; Nous derives.
  *
- * Tools:
- *   get_context          — engineered context for a task (draft_email, follow_up, ...) + ICP fit score
- *   get_account          — the full account record: every claim + the timeline + ICP fit score
- *   merge_contacts       — fold two duplicate records for the same person into one (lossless, reversible)
- *   record               — record what happened / what you learned (observe, never update)
- *   query                — retrieve + summarise a corpus of activity across many people
- *   attention            — what needs your attention (accounts gone quiet, facts decayed)
- *   verify               — re-check a fact before acting on it
- *   get_foundation         — read the user's own rules: voice, outreach, icp, positioning
- *   save_note            — attach a note/document (meeting brief, transcript, prep) to a contact
- *   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_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, …)
- *   configure_crm_sync   — set CRM sync rules (auto-sync, create policy, hygiene cadence)
- *   sync_crm_now         — run an immediate incremental/full CRM pull (don't wait for the daily cron)
- *   get_routing_preferences — Claude Code routing prefs to default GTM to Nous (write to CLAUDE.md)
+ * Tools, by group (the authoritative live catalog is `node scripts/list-tools.mjs`):
+ *   READ    get_context · get_account · verify · query · attention · get_action_items ·
+ *           pipeline · pipeline_intelligence · campaign_performance · score ·
+ *           search_notes · get_foundation · get_insights
+ *   WRITE   record · record_signal · save_note · propose_vault_file · merge_contacts ·
+ *           sync_foundation
+ *   ACT     send_linkedin_message
+ *   CORRECT retract_observation · delete_note
+ *   RUN     get_workspace_status · set_workspace_profile · build_icp_model · train_icp_model ·
+ *           sync_icp · export_icp_model · connect_integration · configure_crm_sync ·
+ *           sync_crm_now · scrape_engagers · get_routing_preferences
  */
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { get, post } from "./client.js";
+import { get, post, del } from "./client.js";
 
-export const SERVER_VERSION = "0.42.0";
+export const SERVER_VERSION = "0.48.0";
 
 // ─── helpers ──────────────────────────────────────────────────────────────────
 
@@ -508,7 +498,7 @@ export function createServer() {
     "Retrieve and summarise activity across many people. Three 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 evaluating stage'.\n" +
+    "'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 " +
@@ -679,19 +669,31 @@ export function createServer() {
       const camps = r.campaigns || [];
       if (!camps.length) return { content: [{ type: "text", text: "No campaign replies logged yet." }] };
       const t = r.totals || {};
-      const pct = (n) => `${Math.round((n || 0) * 100)}%`;
+      const pct = (n) => n == null ? "—" : `${Math.round(n * 100)}%`;
       const lines = camps.map(c => {
+        const cap = c.captured || {};
+        const pt = c.provider_totals, pr = c.provider_rates;
         const tiers = c.tier_of_positive || {};
         const good = (tiers.tier_1 || 0) + (tiers.tier_2 || 0);
-        const conv = `${c.conversions || 0} client${c.conversions === 1 ? "" : "s"}${c.median_days_to_client != null ? ` (avg ${c.median_days_to_client}d to close)` : ""}${c.in_progress ? `, ${c.in_progress} in evaluation` : ""}`;
-        const steps = (c.steps || []).map(s => `      step ${s.step ?? "—"}: ${s.positive}/${s.replies} positive (${pct(s.positive_rate)})`).join("\n");
+        const funnel = pt
+          ? `      funnel: ${pt.sent ?? "?"} sent → ${pt.contacted ?? "?"} contacted → ${pt.replies ?? "?"} replies (${pct(pr?.reply_rate)}) → ${pt.opportunities ?? "?"} opportunities (${pct(pr?.opportunity_rate)})`
+          : `      funnel: (no provider analytics yet)`;
+        const conv = `${c.conversions || 0} client${c.conversions === 1 ? "" : "s"}${c.median_days_to_client != null ? ` (avg ${c.median_days_to_client}d)` : ""}${c.in_progress ? `, ${c.in_progress} in evaluation` : ""}`;
+        const steps = (c.steps || []).map(s => {
+          const subj = s.subject ? ` — "${s.subject}"` : "";
+          return `      step ${s.step ?? "—"}${subj}: ${s.positive}/${s.replies} positive (${pct(s.positive_rate)})`;
+        }).join("\n");
+        const obj = (c.top_objections || []).length
+          ? `\n      objections/pains: ${c.top_objections.slice(0, 4).map(o => `“${String(o).slice(0, 90)}”`).join("; ")}`
+          : "";
         return `  ${c.campaign_name || c.campaign_id}\n` +
-          `      ${c.replies} replies — ${c.positive} positive (${pct(c.positive_rate)}), ${c.neutral} neutral, ${c.negative} negative\n` +
+          funnel + "\n" +
+          `      captured sample: ${cap.replies} replies — ${cap.positive} positive (${pct(cap.positive_rate)}), ${cap.neutral} neutral, ${cap.negative} negative\n` +
           `      converted: ${conv}\n` +
-          `      positive repliers: avg ICP ${c.avg_icp_of_positive ?? "?"}, ${good} tier-1/2 of ${c.positive}` +
-          (steps ? `\n${steps}` : "");
+          `      positive repliers: avg ICP ${c.avg_icp_of_positive ?? "?"}, ${good} tier-1/2 of ${cap.positive}` +
+          (steps ? `\n${steps}` : "") + obj;
       });
-      const head = `Campaign performance (${t.conversions || 0} clients, ${t.positive || 0}/${t.replies || 0} replies positive, ${pct(t.positive_rate)}):`;
+      const head = `Campaign performance (${t.conversions || 0} clients · ${t.sent || 0} sent · ${t.positive || 0}/${t.replies || 0} captured replies positive):`;
       return { content: [{ type: "text", text: `${head}\n${lines.join("\n")}` }] };
     }
   );
@@ -712,11 +714,28 @@ export function createServer() {
       const r = await get("/v2/pipeline/intelligence", {});
       const pct = (n) => n == null ? "—" : `${Math.round(n * 100)}%`;
       const cc = r.current_stage_counts || {};
-      const order = ["identified", "aware", "connected", "interested", "evaluating", "client", "lost", "disqualified", "churned"];
-      const dist = order.filter(s => cc[s]).map(s => `${s} ${cc[s]}`).join(" · ") || "no staged accounts";
+      // The funnel, lowest → highest, then the terminals. SOURCE OF TRUTH:
+      // PIPELINE_LADDER + TERMINAL_STAGES in packages/core/src/pipeline.ts. This
+      // package publishes standalone and has no @nous/core dependency, so the
+      // list is copied here. Keep it in step with core.
+      const order = [
+        "identified", "connected", "interested", "meeting_booked",
+        "discovery", "demo", "negotiation", "closed_won",
+        "closed_lost", "disqualified", "churned",
+      ];
+      // Ladder order first, then any stage the API sent that this copy doesn't
+      // know about. The old list had no proposal, negotiation or demo in it and
+      // the filter silently dropped everything it missed, so late-funnel accounts
+      // disappeared from the distribution entirely. A stage must never vanish
+      // just because a copy of the list went stale.
+      const byStage = (obj, keep) => [
+        ...order.filter(s => keep(obj[s])),
+        ...Object.keys(obj).filter(s => !order.includes(s) && keep(obj[s])),
+      ];
+      const dist = byStage(cc, v => !!v).map(s => `${s} ${cc[s]}`).join(" · ") || "no staged accounts";
       const conv = (r.stage_conversion || []).map(c => `      ${c.from} → ${c.to}: ${pct(c.rate)} (${c.reached_to}/${c.reached_from})`).join("\n");
       const dis = r.median_days_in_stage || {};
-      const inStage = order.filter(s => dis[s] != null).map(s => `${s} ${dis[s]}d`).join(" · ");
+      const inStage = byStage(dis, v => v != null).map(s => `${s} ${dis[s]}d`).join(" · ");
       const text = `Pipeline (${r.accounts || 0} accounts, ${r.clients || 0} clients):\n` +
         `  now: ${dist}\n` +
         `  median days to client: ${r.median_days_to_client ?? "— (no wins yet)"}\n` +
@@ -726,6 +745,43 @@ export function createServer() {
     }
   );
 
+  // ===========================================================================
+  // TOOL: pipeline  —  GET /v2/pipeline/portfolio
+  // The whole account portfolio in one call: health/band, ICP fit, stage,
+  // days-quiet, open flags, open objections, live competitors, engagement trend,
+  // multi-threading. The "reason over my whole book" tool.
+  // ===========================================================================
+  server.tool(
+    "pipeline",
+    "The whole ACCOUNT PORTFOLIO in one call — every in-touch account with its deal health + band, " +
+    "ICP fit, pipeline stage, days-quiet, open re-engagement flags, open-objection count, live competitors, " +
+    "engagement trend (rising/steady/cooling/cold), and multi-threading, plus a stage-count breakdown. Use " +
+    "for any portfolio question: 'which accounts are cooling', 'who should I re-engage', 'where is competitive " +
+    "risk highest', 'what's slipping', 'great-fit deals gone cold', 'analyze my pipeline'. Reason over the list.",
+    { limit: z.number().optional().describe("Cap on accounts returned (default: all, most-actionable first)") },
+    async (input) => {
+      const r = await get("/v2/pipeline/portfolio", input.limit ? { limit: input.limit } : {});
+      const stages = Object.entries(r.stage_counts || {}).map(([s, n]) => `${s} ${n}`).join(" · ");
+      const rows = (r.accounts || []).slice(0, input.limit || 60).map(a => {
+        const bits = [
+          a.name,
+          `health ${a.health ?? "—"} (${a.band})`,
+          a.icp != null ? `ICP ${a.icp}` : null,
+          `stage ${a.stage}`,
+          a.days_quiet != null ? `quiet ${a.days_quiet}d` : null,
+          `engagement ${a.engagement_trend}`,
+          a.single_threaded ? "single-threaded" : `${a.engaged_contacts}/${a.total_contacts} engaged`,
+          a.open_objections ? `${a.open_objections} open objection${a.open_objections === 1 ? "" : "s"}` : null,
+          a.competitors?.length ? `competitors: ${a.competitors.join(", ")}` : null,
+          a.flags?.length ? `flags: ${a.flags.join(", ")}` : null,
+        ].filter(Boolean);
+        return `  • ${bits.join(" — ")}`;
+      }).join("\n");
+      const text = `Portfolio (${r.total || 0} in-touch accounts). By stage: ${stages || "—"}\n${rows || "  (none)"}`;
+      return { content: [{ type: "text", text }] };
+    }
+  );
+
   // ===========================================================================
   // TOOL: get_action_items  —  GET /v2/action-items
   // Commitments extracted from meetings/emails — what you owe each account.
@@ -798,10 +854,6 @@ export function createServer() {
     }
   );
 
-  // get_gtm_profile removed: the user's GTM lives in their files, mirrored into
-  // the graph as foundations (get_foundation) plus the learned ICP model. Read
-  // get_foundation for the user's own rules, ICP, and positioning.
-
   // ===========================================================================
   // TOOLS: get_foundation / sync_foundation  —  the POLICY layer (vs. facts).
   // Foundations are versioned rule-docs that GOVERN agent behavior: voice, outreach,
@@ -889,12 +941,6 @@ export function createServer() {
     "category to list all four.",
     getInsightsSchema, getInsightsHandler);
 
-  // The GTM context is no longer written through a dedicated MCP tool. In the file
-  // symbiosis model the user's own files (context/icp.md, positioning.md, …) are
-  // the source of truth: the agent edits those with its own file tools and calls
-  // `sync_icp` to sync them into the graph (and `export_icp_model` to write the learned
-  // model back). The shared POST /v2/workspace/facts route still backs that import.
-
   // ===========================================================================
   // TOOL: save_note  —  POST /v2/notes
   // Attach a long-form artifact to a CONTACT: a meeting brief you wrote, a
@@ -928,6 +974,36 @@ export function createServer() {
     },
   );
 
+  // ===========================================================================
+  // TOOL: propose_vault_file  —  POST /v2/personal/propose
+  // Propose a markdown file into the member's PERSONAL vault. It lands in their
+  // inbox as a proposal — the member approves it before it is filed into a folder
+  // or synced to their Git. This is how an agent contributes to a member's own
+  // notes (thoughts, decisions, briefs, content) without writing anything without
+  // consent. Distinct from `save_note` (which attaches a document to a CONTACT's
+  // record) — this is the member's private vault, not an account.
+  // ===========================================================================
+  server.tool(
+    "propose_vault_file",
+    "Propose a markdown file into the member's personal vault (their private notes, not an " +
+    "account). It lands in their INBOX as a proposal — the member approves it before it's filed " +
+    "into a folder and synced to their Git; nothing is written without their approval. Use this to " +
+    "draft a thought, a decision record, a brief, or content for the member to review and keep. " +
+    "Pick the destination folder. This is NOT for notes on a contact (use save_note) and NOT for the " +
+    "GTM profile (use sync_icp).",
+    {
+      folder: z.enum(["inbox", "thoughts", "decisions", "projects", "briefs", "content", "company"])
+        .describe("Where it files once approved. ROUTING: briefs = a one-off account or meeting brief, filed FLAT (no subfolder). projects = ongoing recurring analysis by area (with a subfolder): pipeline/funnel review -> projects, subfolder 'pipeline'; campaign analysis -> projects, subfolder 'campaigns'; an initiative -> projects, subfolder = its name. content = anything to publish/send (post, newsletter, outbound copy, market/research write-up). decisions = a decision. thoughts = a loose idea. company = the company's own context. Don't pick 'inbox' — that's where it lands to await approval."),
+      name: z.string().describe("The file name, ending in .md, for what it is plus the date, e.g. 'Pipeline Review — 2026-08-12.md'."),
+      content: z.string().describe("The full markdown content of the file."),
+      subfolder: z.string().optional().describe("REQUIRED for 'projects' — the area: 'pipeline', 'campaigns', or the initiative name. Leave empty for 'briefs' (flat) and other folders."),
+    },
+    async ({ folder, name, content, subfolder }) => {
+      await post("/v2/personal/propose", { folder, name, content, subfolder });
+      return { content: [{ type: "text", text: `Proposed "${name}" into ${folder}. It's waiting in the member's inbox for approval.` }] };
+    },
+  );
+
   // ===========================================================================
   // TOOL: search_notes  —  POST /v2/notes/search
   // Semantic search over saved notes & documents (briefs, transcripts, notes).
@@ -1474,6 +1550,108 @@ export function createServer() {
     }
   );
 
+  // ===========================================================================
+  // TOOL: send_linkedin_message — the ACT layer. An OUTWARD ACTION: it goes out
+  // through Unipile immediately, it is not a draft. The agent should read the
+  // 'voice'/'outreach' foundations first and `record` the touch after. Derives the
+  // workspace from the API key and runs on the workspace's connected LinkedIn
+  // account. POST /api/linkedin/send-message (verifyAuthEither).
+  // ===========================================================================
+  server.tool(
+    "send_linkedin_message",
+    "SEND a LinkedIn direct message for real, right now, from the workspace's connected LinkedIn " +
+    "account. This is an OUTWARD ACTION, not a draft — it reaches the person the moment you call it, so " +
+    "only send a message the user has approved. Address it one of three ways: `linkedin_url` (their " +
+    "profile URL) or `linkedin_member_id` to start a new conversation, or `chat_id` to REPLY inside an " +
+    "existing thread. It returns the thread's `chat_id` — keep it so the next reply stays in the same " +
+    "thread. Best practice: read the 'voice' and 'outreach' foundations first so the message obeys the " +
+    "user's rules, and `record` the touch afterward so the graph stays current. Requires a connected " +
+    "LinkedIn account (Integrations); it says so if none is connected.",
+    {
+      text: z.string().min(1).describe("The message body to send."),
+      linkedin_url: z.string().optional().describe("The recipient's LinkedIn profile URL. Provide this OR linkedin_member_id (to start a new chat), OR chat_id (to reply in an existing thread)."),
+      linkedin_member_id: z.string().optional().describe("The recipient's LinkedIn member id, if you have it instead of a profile URL."),
+      chat_id: z.string().optional().describe("An existing conversation's chat_id — pass it to reply in-thread instead of opening a new chat."),
+    },
+    async ({ text, linkedin_url, linkedin_member_id, chat_id }) => {
+      if (!linkedin_url && !linkedin_member_id && !chat_id) {
+        return { content: [{ type: "text", text:
+          "Tell me who to message: pass linkedin_url or linkedin_member_id to start a new chat, or chat_id to reply in an existing thread." }] };
+      }
+      try {
+        const r = await post("/api/linkedin/send-message", { text, linkedin_url, linkedin_member_id, chat_id });
+        return { content: [{ type: "text", text:
+          `Message sent over LinkedIn.${r.chat_id ? ` Thread chat_id: ${r.chat_id} (reuse it to reply in-thread).` : ""}` }] };
+      } catch (e) {
+        const msg =
+          /linkedin_not_connected/.test(e.message)
+            ? "No LinkedIn account is connected. Tell the user to connect LinkedIn in Integrations first."
+          : /auth_required/.test(e.message)
+            ? "This API key isn't scoped to a workspace, or LinkedIn isn't connected."
+          : /missing_params/.test(e.message)
+            ? "Couldn't tell who to message — provide linkedin_url, linkedin_member_id, or chat_id."
+            : `Couldn't send the message: ${e.message}`;
+        return { content: [{ type: "text", text: msg }] };
+      }
+    }
+  );
+
+  // ===========================================================================
+  // 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`). Nous 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(
+    "delete_note",
+    "DELETE a note saved by mistake. Pass the note's `id` (returned by `save_note`). It's removed from " +
+    "search and context immediately; the timeline stays reconstructable. Only touches notes — it will " +
+    "refuse an id that isn't a note. Use this for a note saved in error; to CHANGE a note, save a new " +
+    "one instead.",
+    {
+      id: z.string().describe("The note id to delete (from a prior `save_note` result)."),
+    },
+    async ({ id }) => {
+      try {
+        const r = await del(`/v2/notes/${encodeURIComponent(id)}`);
+        return { content: [{ type: "text", text:
+          r.status === "already_deleted" ? "That note was already deleted." : "Note deleted — it's out of search and context now." }] };
+      } catch (e) {
+        const msg = /note_not_found/.test(e.message)
+          ? "No note with that id in this workspace — check the id from the save_note result."
+          : /not_a_note/.test(e.message)
+          ? "That id isn't a note, so it can't be deleted here. Only save_note notes can be deleted this way."
+          : `Couldn't delete the note: ${e.message}`;
+        return { content: [{ type: "text", text: msg }] };
+      }
+    }
+  );
+
   // ===========================================================================
   // TOOL: get_routing_preferences
   // The routing preferences that make THIS agent default to Nous for GTM. The