@opennous/mcp 0.16.0 → 0.19.0

package/package.json

@@ -1,7 +1,13 @@
 {
   "name": "@opennous/mcp",
-  "version": "0.16.0",
+  "version": "0.19.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

@@ -21,13 +21,20 @@
  *   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
+ *   connect_integration  — connect a key-based integration (Apollo, Prospeo, HubSpot, …)
+ *   configure_crm_sync   — set CRM sync rules (auto-sync, create policy, hygiene cadence)
+ *   set_trigger          — create an outbound event trigger (webhook); list_triggers reads them
+ *   list_triggers        — list the workspace's event triggers + available events
  */
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { get, post } from "./client.js";
 
-export const SERVER_VERSION = "0.16.0";
+export const SERVER_VERSION = "0.19.0";
 
 // ─── helpers ──────────────────────────────────────────────────────────────────
 
@@ -53,8 +60,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"] },
     ],
@@ -485,5 +494,271 @@ export function createServer() {
     },
   );
 
+  // ===========================================================================
+  // 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;
+      }
+    }
+  );
+
+  // ===========================================================================
+  // TOOL: connect_integration  —  POST /v2/workspace/integrations
+  // The agent connects a KEY-BASED integration for the user (no clicking through
+  // the Integrations page). OAuth providers still need a browser, so this is
+  // limited to providers that authenticate with an API key/token.
+  // ===========================================================================
+  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.",
+    {
+      provider: z.string().describe("Provider name, lowercase — e.g. 'apollo', 'prospeo', 'instantly', 'hubspot', 'pipedrive', 'attio'."),
+      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."),
+    },
+    async ({ provider, credentials, name }) => {
+      try {
+        const r = await post("/v2/workspace/integrations", { provider, credentials, name });
+        return { content: [{ type: "text", text: `Connected ${r.connection?.provider ?? provider}.${r.message ? ` ${r.message}` : ""}` }] };
+      } catch (e) {
+        const msg = String(e?.message ?? e);
+        if (msg.includes("oauth_provider")) {
+          return { content: [{ type: "text", text: `${provider} uses a browser sign-in, so it can't be connected with a key. Tell the user to connect it on the Integrations page.` }] };
+        }
+        if (msg.includes("invalid_credentials")) {
+          return { content: [{ type: "text", text: `Those credentials didn't verify for ${provider}. Ask the user to double-check the key and try again.` }] };
+        }
+        if (msg.includes("unknown_provider")) {
+          return { content: [{ type: "text", text: `No provider named "${provider}". Ask the user which tool they mean.` }] };
+        }
+        throw e;
+      }
+    }
+  );
+
+  // ===========================================================================
+  // TOOL: configure_crm_sync  —  POST /v2/workspace/crm-sync
+  // The agent sets the CRM sync rules — the same options as the CRM Sync page.
+  // The CRM must already be connected (OAuth connect stays a human step).
+  // ===========================================================================
+  server.tool(
+    "configure_crm_sync",
+    "Configure how Nous keeps a connected CRM in sync — the same settings as the CRM Sync page. The " +
+    "CRM must already be connected (HubSpot/Pipedrive/Attio). Set any of: auto-sync (daily pull), " +
+    "push of touchpoints, the create policy (when a new record is auto-created and the ICP-fit " +
+    "threshold), and the hygiene cadence. Only send the fields you want to change. If it reports the " +
+    "CRM isn't connected, tell the user to connect it on the Integrations page first.",
+    {
+      provider: z.enum(["hubspot", "pipedrive", "attio"]).describe("Which connected CRM to configure."),
+      autoSync: z.boolean().optional().describe("Pull contacts/companies/deals daily."),
+      pushActivities: z.boolean().optional().describe("Push touchpoints (meetings, replies, proposals) back to the CRM."),
+      createInCrm: z.boolean().optional().describe("Auto-create new records in the CRM when they earn it."),
+      createTrigger: z.enum(["any_reply_or_meeting", "positive_reply_or_meeting", "meeting_only", "interested_stage"]).optional()
+        .describe("What earns a new record."),
+      createRequireIcpFit: z.boolean().optional().describe("Require an ICP-fit score before creating a record."),
+      createIcpThreshold: z.number().optional().describe("Minimum ICP-fit score to create (0-100)."),
+      hygieneEnabled: z.boolean().optional().describe("Run scheduled hygiene reconciliation."),
+      hygieneCadence: z.enum(["weekly", "monthly"]).optional().describe("How often hygiene runs."),
+    },
+    async (args) => {
+      try {
+        const r = await post("/v2/workspace/crm-sync", args);
+        const c = r.config ?? {};
+        return { content: [{ type: "text", text:
+          `CRM sync configured for ${args.provider}. auto-sync ${c.auto_sync ? "on" : "off"}, ` +
+          `create ${c.create_in_crm ? `on (${c.create_trigger}${c.create_require_icp_fit ? `, ICP ≥ ${c.create_icp_threshold}` : ""})` : "off"}, ` +
+          `hygiene ${c.hygiene_enabled ? c.hygiene_cadence : "off"}.` }] };
+      } catch (e) {
+        const msg = String(e?.message ?? e);
+        if (msg.includes("crm_not_connected")) {
+          return { content: [{ type: "text", text: `${args.provider} isn't connected yet. Tell the user to connect it on the Integrations page, then configure sync.` }] };
+        }
+        throw e;
+      }
+    }
+  );
+
+  // ===========================================================================
+  // TOOL: set_trigger / list_triggers  —  /v2/workspace/triggers
+  // Outbound event triggers (webhooks) — wire the user's stack to fire when the
+  // record changes.
+  // ===========================================================================
+  server.tool(
+    "set_trigger",
+    "Create an outbound event trigger (a webhook) so an external tool is notified when something " +
+    "happens in the workspace — e.g. a new contact, a reply, a meeting booked. Pass the destination " +
+    "URL and which events to fire on. Call list_triggers first to see the available event names.",
+    {
+      url: z.string().describe("The destination URL the event is POSTed to."),
+      events: z.array(z.string()).describe("Event names to fire on (see list_triggers for the catalog)."),
+      name: z.string().optional().describe("Optional label for the trigger."),
+    },
+    async ({ url, events, name }) => {
+      try {
+        const r = await post("/v2/workspace/triggers", { url, events, name });
+        return { content: [{ type: "text", text: `Trigger created for ${events.join(", ")} → ${url}.` }] };
+      } catch (e) {
+        const msg = String(e?.message ?? e);
+        return { content: [{ type: "text", text: `Couldn't create the trigger: ${msg}. Call list_triggers to see valid event names.` }] };
+      }
+    }
+  );
+  server.tool(
+    "list_triggers",
+    "List the workspace's outbound event triggers (webhooks) and the catalog of available event names.",
+    {},
+    async () => {
+      const r = await get("/v2/workspace/triggers");
+      const lines = [];
+      if (r.triggers?.length) {
+        lines.push(`TRIGGERS (${r.triggers.length}):`);
+        for (const t of r.triggers) lines.push(`  ${t.name || "(unnamed)"} → ${t.url}  [${(t.events || []).join(", ")}]`);
+      } else {
+        lines.push("No triggers set up yet.");
+      }
+      if (r.available_events?.length) {
+        lines.push("", `AVAILABLE EVENTS: ${r.available_events.join(", ")}`);
+      }
+      return { content: [{ type: "text", text: lines.join("\n").trim() }] };
+    }
+  );
+
   return server;
 }