@opennous/mcp 0.11.1 → 0.18.0

package/package.json

@@ -1,7 +1,13 @@
 {
   "name": "@opennous/mcp",
-  "version": "0.11.1",
+  "version": "0.18.0",
   "description": "Nous MCP Server — Customer graph for GTM agents.",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NousC/nous.git",
+    "directory": "apps/mcp"
+  },
   "type": "module",
   "bin": {
     "nous-mcp": "src/index.js"

package/src/client.js

@@ -9,6 +9,9 @@
  */
 
 import { AsyncLocalStorage } from "node:async_hooks";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 
 // Resolve an env var defensively — Claude Code plugins use ${user_config.X}
 // substitution; when an optional userConfig field is left blank, the literal
@@ -32,15 +35,33 @@ export function runWithApiKey(apiKey, fn) {
   return apiKeyStore.run({ apiKey }, fn);
 }
 
+// Credential written by `nous login` (the browser device-auth flow). The CLI and
+// the MCP server share ~/.nous/config.json, so a user who runs the login command
+// gets a key the MCP picks up on the next call — no paste, no env var.
+function fileApiKey() {
+  try {
+    const dir = resolvedEnv("NOUS_CONFIG_DIR") || path.join(os.homedir(), ".nous");
+    const cfg = JSON.parse(fs.readFileSync(path.join(dir, "config.json"), "utf8"));
+    const k = cfg?.apiKey;
+    return k && !String(k).includes("${") ? k : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function currentApiKey() {
-  return apiKeyStore.getStore()?.apiKey ?? resolvedEnv("NOUS_API_KEY");
+  return apiKeyStore.getStore()?.apiKey ?? resolvedEnv("NOUS_API_KEY") ?? fileApiKey();
 }
 
-// stdio-only preflight: the env key must be present at startup.
+// stdio-only preflight. A key may come from the env OR from `nous login`'s
+// credential file. This is advisory — the server still starts without one so
+// the user can run the login command after installing the plugin, and the key
+// is resolved per-call.
 export function validateConfig() {
-  if (!resolvedEnv("NOUS_API_KEY")) {
+  if (!resolvedEnv("NOUS_API_KEY") && !fileApiKey()) {
     throw new Error(
-      "NOUS_API_KEY is required. Get yours at opennous.cloud → Settings → API Keys"
+      "No Nous API key found. Run the /nous-login command (or `npx @opennous/cli login`) to sign in, " +
+      "or set NOUS_API_KEY."
     );
   }
 }

package/src/index.js

@@ -17,7 +17,15 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { validateConfig } from "./client.js";
 import { createServer } from "./server.js";
 
-validateConfig();
+// Advisory only — don't hard-exit if there's no key yet. The user may install
+// the plugin and then run /nous-login; the server must already be running so the
+// key (resolved per-call from env or ~/.nous/config.json) is picked up without a
+// restart.
+try {
+  validateConfig();
+} catch (err) {
+  console.error(`[nous] ${err.message}`);
+}
 
 const server = createServer();
 const transport = new StdioServerTransport();

package/src/server.js

@@ -1,7 +1,7 @@
 /**
  * Nous MCP server factory.
  *
- * Builds an McpServer with the seven v2 tools registered. Both entrypoints use it:
+ * Builds an McpServer with the v2 tools registered. Both entrypoints use it:
  *   - index.js (stdio bin, published as @opennous/mcp) — one server, env-scoped key
  *   - http.js  (hosted, mcp.opennous.cloud)           — a fresh server per request,
  *                                                        key scoped via AsyncLocalStorage
@@ -18,13 +18,19 @@
  *   attention            — what needs your attention (accounts gone quiet, facts decayed)
  *   verify               — re-check a fact before acting on it
  *   get_gtm_profile      — the user's GTM profile (ICP, market, pricing, product, competitors)
+ *   update_gtm_profile   — write back a change to a GTM context section (evolve, keep history)
+ *   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_scoring_model  — build/rebuild the ICP scoring model from the recorded GTM context
  */
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { get, post } from "./client.js";
 
-export const SERVER_VERSION = "0.11.0";
+export const SERVER_VERSION = "0.18.0";
 
 // ─── helpers ──────────────────────────────────────────────────────────────────
 
@@ -50,8 +56,10 @@ export function createServer() {
     name: "nous",
     version: SERVER_VERSION,
     description:
-      "Nous — the context layer for GTM agents. Call get_context before drafting outreach or " +
-      "preparing for a meeting. Call record after every interaction, or whenever you learn something.",
+      "Nous — the context layer for GTM agents. Nous 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.",
     icons: [
       { src: "https://opennous.cloud/newlogoP.png", mimeType: "image/png", sizes: ["64x64"] },
     ],
@@ -115,6 +123,17 @@ export function createServer() {
         }
         lines.push("");
       }
+      if (ctx.documents?.length) {
+        // Meeting briefs / notes / transcripts kept on the contact — an overview
+        // (snippets only). To pull relevant content, use search_notes (semantic).
+        lines.push("DOCUMENTS (notes & meeting records — use search_notes to search their content):");
+        for (const d of ctx.documents) {
+          const when = d.date ? `  [${relAge(d.date)}]` : "";
+          lines.push(`  ${d.type.replace(/_/g, " ")}${d.title ? ` · ${d.title}` : ""}${when}`);
+          if (d.snippet) lines.push(`    ${d.snippet}`);
+        }
+        lines.push("");
+      }
       if (ctx.stakeholders?.length) {
         lines.push("STAKEHOLDERS:");
         for (const s of ctx.stakeholders) lines.push(`  ${s.name ?? "—"} — ${s.role ?? ""}`);
@@ -349,7 +368,17 @@ export function createServer() {
     const lines = [];
     for (const [cat, facts] of Object.entries(groups)) {
       lines.push(`${cat.toUpperCase()} (${facts.length}):`);
-      for (const f of facts) lines.push(`  ${f.content}  [${relAge(f.recorded_at)}]`);
+      for (const f of facts) {
+        // Flag AI-drafted facts (confidence < 1) and ones not confirmed in a long
+        // time, so the agent treats them as provisional and prefers fresh,
+        // user-confirmed facts when they conflict.
+        const ageDays = f.recorded_at ? Math.floor((Date.now() - new Date(f.recorded_at).getTime()) / 86400000) : 0;
+        const tags = [];
+        if (typeof f.confidence === "number" && f.confidence < 1) tags.push("inferred");
+        if (ageDays >= 90) tags.push("stale");
+        const tag = tags.length ? ` (${tags.join(", ")})` : "";
+        lines.push(`  ${f.content}${tag}  [${relAge(f.recorded_at)}]`);
+      }
       lines.push("");
     }
     return { content: [{ type: "text", text: lines.join("\n").trim() }] };
@@ -358,5 +387,248 @@ export function createServer() {
   // Legacy alias — keeps existing integrations calling get_workspace_facts working.
   server.tool("get_workspace_facts", gtmProfileDescription, gtmProfileSchema, gtmProfileHandler);
 
+  // ===========================================================================
+  // TOOL: update_gtm_profile  —  POST /v2/workspace/facts
+  // Write-back: the agent records a durable change to the user's OWN GTM profile
+  // and EVOLVES the matching belief (supersede + keep history) instead of piling
+  // up contradictions. This is the loop that keeps the context current as the
+  // company learns — pair it with get_gtm_profile.
+  // ===========================================================================
+  server.tool(
+    "update_gtm_profile",
+    "Keep a SECTION of the user's OWN GTM context current. Each section is a living file: ICP, " +
+    "Market, Product, Pricing, Competitors, Positioning (these feed the ICP scoring model), plus " +
+    "'GTM Motion' (how they sell — motion, RevOps, process) and 'Notes' (a running log for anything " +
+    "else durable about their GTM that doesn't fit the others). Use this whenever the user states or " +
+    "you learn a lasting change to how THEY go to market — repriced, moved upmarket, sharpened " +
+    "positioning, changed their motion, won a new segment, or a useful note about how they operate. " +
+    "This is NOT for facts about a prospect or account (use `record` for those). " +
+    "Rules: keep content short and current — a sentence or two, not an essay. In the default 'replace' " +
+    "mode the section EVOLVES (the old version is kept as history, never silently contradicted), so " +
+    "just write the section's current state. Use 'append' mode to log a Notes entry without replacing. " +
+    "Nous is the source of truth for the GTM context — write back here instead of keeping a local file.",
+    {
+      section: z.enum(["ICP", "Market", "Product", "Pricing", "Competitors", "Positioning", "GTM Motion", "Notes"])
+        .describe("Which section of the GTM context this updates."),
+      content: z.string().describe("The section's current content — short and current, not an essay."),
+      mode: z.enum(["replace", "append"]).optional()
+        .describe("'replace' (default) evolves the section and keeps the prior version as history. 'append' logs a new entry without replacing — the default for Notes."),
+      supersedes: z.string().optional()
+        .describe("Optional id of a specific existing fact to replace (overrides section matching)."),
+    },
+    async ({ section, content, mode, supersedes }) => {
+      const r = await post("/v2/workspace/facts", { section, content, mode, supersedes });
+      const verb = r.mode === "append" ? "Logged to" : r.superseded ? "Updated" : "Recorded";
+      return { content: [{ type: "text", text: `${verb} ${section}: ${content}` }] };
+    },
+  );
+
+  // ===========================================================================
+  // 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.
+  // ===========================================================================
+  server.tool(
+    "save_note",
+    "Save a note or document onto a person or company so it is kept on their record — a meeting " +
+    "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 " +
+    "(use `update_gtm_profile`). 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)."),
+      type: z.enum(["note", "meeting_brief", "transcript", "meeting_notes", "pre_meeting", "research"])
+        .optional().describe("What kind of document this is (default: note)."),
+      title: z.string().optional().describe("A short name, e.g. 'Pre-meeting brief — renewal' or 'Transcript — Jun 1'."),
+      date: z.string().optional().describe("The relevant date (e.g. the meeting date, ISO or plain). Defaults to now."),
+    },
+    async ({ focus, content, type, title, date }) => {
+      const r = await post("/v2/notes", { focus, content, type, title, date });
+      const label = title || (r.doc_type || "note").replace(/_/g, " ");
+      return { content: [{ type: "text", text: `Saved ${label} to ${focus}.` }] };
+    },
+  );
+
+  // ===========================================================================
+  // TOOL: search_notes  —  POST /v2/notes/search
+  // Semantic search over saved notes & documents (briefs, transcripts, notes).
+  // The retrieval counterpart to save_note — pull relevant document content
+  // instead of dumping whole documents into context.
+  // ===========================================================================
+  server.tool(
+    "search_notes",
+    "Semantically search the saved notes & documents (meeting briefs, transcripts, meeting notes) " +
+    "kept on contacts. Use this to pull relevant content from the record — e.g. 'what did we discuss " +
+    "about pricing', 'objections raised in past meetings', or to compare across a contact's meetings. " +
+    "Pass `focus` to restrict to one person/company, or omit it to search across everyone. Returns the " +
+    "matching documents (type, title, date, similarity, snippet); get the full body with get_account.",
+    {
+      question: z.string().describe("Natural-language query to match against document content."),
+      focus: z.string().optional().describe("Optional — restrict to one person/company (email, LinkedIn URL, domain, or entity UUID)."),
+      limit: z.number().optional().describe("Max documents to return (default 8)."),
+    },
+    async ({ question, focus, limit }) => {
+      const r = await post("/v2/notes/search", { question, focus, limit });
+      if (!r.documents?.length) {
+        return { content: [{ type: "text", text: `No saved documents matched "${question}".` }] };
+      }
+      const lines = [`Documents matching "${question}":`, ""];
+      for (const d of r.documents) {
+        const when = d.date ? `  [${relAge(d.date)}]` : "";
+        lines.push(`  ${d.type.replace(/_/g, " ")}${d.title ? ` · ${d.title}` : ""}  (${pct(d.similarity)})${when}`);
+        if (d.snippet) lines.push(`    ${d.snippet}`);
+        lines.push(`    (entity_id: ${d.entity_id})`);
+      }
+      return { content: [{ type: "text", text: lines.join("\n").trim() }] };
+    },
+  );
+
+  // ===========================================================================
+  // TOOL: get_workspace_status  —  GET /v2/workspace/status
+  // The "one main call." Nous is operated by the agent, so the agent needs to
+  // know the state of the workspace: is it onboarded, is the GTM playbook 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 — and what to set up next. Nous is " +
+    "operated by you, the agent, not by a human clicking through the app: call this at the start of " +
+    "a session to learn whether the workspace is onboarded, whether the GTM playbook (ICP model) is " +
+    "built, which integrations are connected, whether CRM sync is configured, and whether webhooks/" +
+    "triggers are live. Returns a ranked NEXT STEPS list — walk the user through whatever is missing " +
+    "(onboard them with set_workspace_profile, build the playbook with update_gtm_profile, connect " +
+    "their tools). Use this before offering to set anything up.",
+    {},
+    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}` : ""}`);
+      lines.push("");
+
+      const mark = (b) => (b ? "✓" : "✗");
+      lines.push("SETUP:");
+      lines.push(`  ${mark(setup.onboarding?.done)} Onboarding${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)` : ""}`);
+      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 ?? {};
+      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)`);
+
+      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",
+    "Onboard the workspace, or update its basic profile. Nous is set up by you, the agent, in " +
+    "conversation — not by the user clicking through a wizard. Ask the user for their company name, " +
+    "their website, whether they sell a SERVICE or SOFTWARE, and a sentence describing their ideal " +
+    "customer, then write them here. This seeds the GTM context and the ICP scoring model. Call " +
+    "get_workspace_status first to see what's already set; send only the fields you're setting or " +
+    "changing. After this, the next step is usually the GTM playbook (update_gtm_profile).",
+    {
+      name: z.string().optional().describe("The user's company / workspace name."),
+      website: z.string().optional().describe("The company website (used to seed the GTM context)."),
+      business_type: z.enum(["service", "software"]).optional()
+        .describe("Whether they sell a service or software — sets the CRM's buyer terminology and default signup stage."),
+      plan_model: z.enum(["free_plan", "free_trial", "both", "paid_only"]).optional()
+        .describe("For software only: how they package (free plan, free trial, both, or paid only)."),
+      default_signup_stage: z.string().optional()
+        .describe("The pipeline stage a brand-new signup lands in (e.g. 'Lead', 'Free User'). Defaults sensibly from business_type."),
+      icp: z.string().optional()
+        .describe("A sentence or two describing their ideal customer — seeds the ICP scoring model."),
+    },
+    async ({ name, website, business_type, plan_model, default_signup_stage, icp }) => {
+      const r = await post("/v2/workspace/onboarding", { name, website, business_type, plan_model, default_signup_stage, icp });
+      const w = r.workspace ?? {};
+      const set = [
+        w.name && `name=${w.name}`,
+        w.website && `site=${w.website}`,
+        w.business_type && `type=${w.business_type}`,
+        icp && "ICP recorded",
+      ].filter(Boolean);
+      return { content: [{ type: "text", text:
+        `Workspace profile saved.${set.length ? ` ${set.join(" · ")}.` : ""}\n` +
+        `Next: call get_workspace_status to see what to set up next (usually the GTM playbook).` }] };
+    }
+  );
+
+  // ===========================================================================
+  // TOOL: build_scoring_model  —  POST /v2/workspace/scoring-model
+  // The second half of building the GTM playbook. The agent records the GTM
+  // context with update_gtm_profile, 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 (or rebuild) the user's ICP scoring model from the GTM context they've recorded. This is " +
+    "the second half of setting up the GTM playbook: first record the ICP and how they sell with " +
+    "update_gtm_profile, then call this to translate that context into a weighted set of scoring " +
+    "signals so accounts get scored for fit. If a model already exists it is left alone unless you " +
+    "pass force:true (use that when the GTM context has changed and the model should be rebuilt). If " +
+    "it reports no GTM context yet, record some with update_gtm_profile first, then call this again.",
+    {
+      force: z.boolean().optional()
+        .describe("Rebuild the model even if one already exists — use when the GTM context has changed."),
+    },
+    async ({ force }) => {
+      try {
+        const r = await post("/v2/workspace/scoring-model", { force: force === true });
+        const signals = r.signals ?? [];
+        const lines = [`Built the ICP scoring model — ${signals.length} signal${signals.length === 1 ? "" : "s"}:`];
+        for (const s of signals) lines.push(`  • ${s.label ?? s.key} (weight ${s.weight})`);
+        lines.push("", "Accounts will now be scored for fit. Check it on the GTM Context page.");
+        return { content: [{ type: "text", text: lines.join("\n").trim() }] };
+      } catch (e) {
+        // Surface the actionable cases (no context yet / model already exists) as
+        // guidance rather than a raw error, so the agent knows what to do next.
+        const msg = String(e?.message ?? e);
+        if (msg.includes("no_gtm_context")) {
+          return { content: [{ type: "text", text:
+            "No GTM context recorded yet. Record the ICP and how they sell with update_gtm_profile first, then build the model." }] };
+        }
+        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." }] };
+        }
+        throw e;
+      }
+    }
+  );
+
   return server;
 }