closecadence-mcp 0.1.0 → 0.2.1

package/README.md

@@ -4,11 +4,11 @@ Use your **Close Cadence** real-estate tools from your own Claude. This is a tin
 Claude (Desktop / Code) call your Close Cadence tools — listings, CMAs, social, follow-ups, flyers,
 photo enhancement — directly, in your saved voice, on your plan's credits.
 
-It's a thin client: it only forwards your authenticated requests to `closecadence.ai`. No tool logic or
+It's a thin client: it only forwards your authenticated requests to `tools.closecadence.com`. No tool logic or
 data lives in this package.
 
 ## Setup (about 1 minute)
-1. Get your key in the portal → **API key** (format `cck.cus_….…`).
+1. Get your key in the portal → **Use in Claude** (format `cck.cus_….…`).
 2. Add this to your Claude config (Claude Desktop → Settings → Developer → Edit Config):
 
 ```json
@@ -28,6 +28,7 @@ data lives in this package.
 - `cc_listing`, `cc_cma`, `cc_social`, `cc_email`, `cc_followup`, `cc_market_report`, `cc_open_house`, `cc_prospecting`, `cc_listing_presentation`
 - `cc_comps`, `cc_property` (property data) · `cc_flyer`, `cc_enhance` (media)
 - `cc_list_tools` (what's on your plan) · `cc_run` (any tool by id)
+- Partner-spec aliases (2026-06-23 connector spec): `generate_listing_doc` (= `cc_listing`), `generate_cma` (= `cc_cma`), `create_custom_video` (listing-tour **video script/storyboard**; rendered video pending Creatomate/HeyGen keys), `list_assets` (your recent generated outputs), `job_status` (poll an async job by id)
 
 If your membership lapses or you run out of credits, the tools say so clearly and point you to the portal.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "closecadence-mcp",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Use your Close Cadence real-estate tools from your own Claude (MCP server).",
   "type": "module",
   "bin": { "closecadence-mcp": "src/index.js" },

package/src/index.js

@@ -1,23 +1,57 @@
 #!/usr/bin/env node
 // Close Cadence MCP server — lets an agent's own Claude call the Close Cadence tools.
-// THIN CLIENT ONLY: it proxies authenticated calls to the licensed API at closecadence.ai. No business
+// THIN CLIENT ONLY: it proxies authenticated calls to the licensed API at tools.closecadence.com. No business
 // logic, prompts, or comp/CMA data live here (that's protected, server-side IP) — this just forwards the
 // agent's key + inputs and returns the result. Auth: env CC_API_KEY (cck.cus_xxx.yyy). stdio transport.
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
+import { writeFileSync, mkdirSync, readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
 
-const API = process.env.CC_API_BASE || 'https://closecadence.ai';
+const API = process.env.CC_API_BASE || 'https://tools.closecadence.com';
 const KEY = process.env.CC_API_KEY || '';
 
+// ---- Pillar 2: brand + market profiles travel with every job ----
+// The connector is the bridge, so it carries the realtor's brand_profile.json + market_profile.json to
+// the platform on EVERY tool call — outputs come back on-brand AND on-market without the agent having to
+// remember to attach them. Looked up (in order): CC_PROFILE_DIR, the CloseCadence data dir, the cwd.
+// Missing/oversized/invalid files are silently skipped (the server also has a per-member fallback copy).
+function ccDataDir() {
+  if (process.platform === 'win32') return join(process.env.APPDATA || join(homedir(), 'AppData', 'Roaming'), 'CloseCadence');
+  if (process.platform === 'darwin') return join(homedir(), 'Library', 'Application Support', 'CloseCadence');
+  return join(homedir(), '.config', 'CloseCadence');
+}
+function readJsonProfile(name) {
+  const dirs = [process.env.CC_PROFILE_DIR, ccDataDir(), process.cwd()].filter(Boolean);
+  for (const d of dirs) {
+    try {
+      const p = join(d, name);
+      if (!existsSync(p)) continue;
+      const raw = readFileSync(p, 'utf8');
+      if (raw.length > 96 * 1024) continue; // guard against an oversized file blowing the request
+      const obj = JSON.parse(raw);
+      if (obj && typeof obj === 'object') return obj;
+    } catch { /* unreadable / bad JSON -> skip */ }
+  }
+  return undefined;
+}
+function loadProfiles() {
+  const out = {};
+  const bp = readJsonProfile('brand_profile.json'); if (bp) out.brand_profile = bp;
+  const mp = readJsonProfile('market_profile.json'); if (mp) out.market_profile = mp;
+  return out;
+}
+
 const errText = (m) => ({ content: [{ type: 'text', text: m }], isError: true });
 
 // Turn an API response into MCP content, surfacing license/credit problems clearly.
 async function handle(r) {
   let j = {};
   try { j = await r.json(); } catch { /* non-JSON */ }
-  if (r.status === 401) return errText('Your Close Cadence membership isn’t active, or the key is invalid. Renew or rotate your key in the portal (closecadence.ai/portal → API key).');
-  if (r.status === 402) return errText((j && j.error) || 'You’re out of credits for this month. Top up at closecadence.ai/portal → Credits (or turn on auto-refill).');
+  if (r.status === 401) return errText('Your Close Cadence membership isn’t active, or the key is invalid. Renew or rotate your key in the portal (tools.closecadence.com/portal → Use in Claude).');
+  if (r.status === 402) return errText((j && j.error) || 'You’re out of credits for this month. Top up at tools.closecadence.com/portal → Credits (or turn on auto-refill).');
   if (r.status === 429) return errText((j && j.error) || 'Rate limited, or this key was flagged for use from too many places. Try again shortly, or rotate it in the portal.');
   if (r.status === 503) return errText((j && j.error) || 'This tool is being set up — check back shortly.');
   if (!r.ok || (j && j.error)) return errText((j && j.error) || ('Close Cadence error ' + r.status + '.'));
@@ -26,12 +60,12 @@ async function handle(r) {
 }
 
 function requireKey() {
-  return KEY ? null : errText('No CC_API_KEY set. Add your Close Cadence key (portal → API key) to the MCP config "env", e.g. { "CC_API_KEY": "cck...." }.');
+  return KEY ? null : errText('No CC_API_KEY set. Add your Close Cadence key (portal → Use in Claude) to the MCP config "env", e.g. { "CC_API_KEY": "cck...." }.');
 }
 async function callTool(tool, inputs) {
   const miss = requireKey(); if (miss) return miss;
   try {
-    const r = await fetch(API + '/api/tool', { method: 'POST', headers: { 'content-type': 'application/json', 'x-api-key': KEY }, body: JSON.stringify({ tool, inputs: inputs || {} }) });
+    const r = await fetch(API + '/api/tool', { method: 'POST', headers: { 'content-type': 'application/json', 'x-api-key': KEY }, body: JSON.stringify({ tool, inputs: inputs || {}, ...loadProfiles() }) });
     return await handle(r);
   } catch (e) { return errText('Could not reach Close Cadence: ' + String(e && e.message || e)); }
 }
@@ -42,6 +76,13 @@ async function callPath(path, body) {
     return await handle(r);
   } catch (e) { return errText('Could not reach Close Cadence: ' + String(e && e.message || e)); }
 }
+async function getPath(path) {
+  const miss = requireKey(); if (miss) return miss;
+  try {
+    const r = await fetch(API + path, { headers: { 'x-api-key': KEY } });
+    return await handle(r);
+  } catch (e) { return errText('Could not reach Close Cadence: ' + String(e && e.message || e)); }
+}
 
 const server = new McpServer({ name: 'closecadence', version: '0.1.0' });
 
@@ -57,6 +98,7 @@ const NAMED = [
   ['cc_open_house', 'open-house-kit', 'Open-house kit: social + email + neighbor invite + visitor follow-up.', 'address, details'],
   ['cc_prospecting', 'prospecting', 'Expired / FSBO outreach: letter + call script + texts.', 'type, context'],
   ['cc_listing_presentation', 'listing-presentation', 'Win-the-listing presentation content, slide by slide.', 'address, property, seller_goal, market, differentiators'],
+  ['cc_avatar_report', 'avatar-marketing-report', 'Two-presenter AI-avatar marketing report script from your numbers (Studio) — feeds the avatar video renderer.', 'agent_name, co_presenter, market, period, total_volume, sales_count, avg_price, top_sale, wins, focus'],
 ];
 for (const [name, id, desc, fields] of NAMED) {
   server.registerTool(
@@ -77,6 +119,12 @@ server.registerTool('cc_property', { title: 'cc_property', description: 'Propert
 server.registerTool('cc_flyer', { title: 'cc_flyer', description: 'Generate a "just listed" card / flyer image (readable text).', inputSchema: { prompt: z.string().optional(), headline: z.string().optional() } }, async (a) => callPath('/api/media/flyer', a));
 server.registerTool('cc_enhance', { title: 'cc_enhance', description: 'Enhance a listing photo (sky replacement / HDR / declutter).', inputSchema: { imageUrl: z.string().url() } }, async (a) => callPath('/api/media/enhance', a));
 
+// Avatar Studio (Studio tier): generate a branded talking-head marketing VIDEO or REEL in your own
+// voice from your numbers. Rendering is async — cc_avatar_render enqueues + returns a job id; poll
+// cc_avatar_status for the finished video url. Each render uses plan credits (video 500 / reel 120).
+server.registerTool('cc_avatar_render', { title: 'cc_avatar_render', description: 'Generate an on-brand AI-avatar marketing VIDEO or REEL in your voice from your numbers (Studio). Async — returns a job id; poll cc_avatar_status. Uses plan credits.', inputSchema: { kind: z.enum(['report', 'reel']).optional().describe('report (full) or reel (short)'), fmt: z.enum(['video', 'reel']).optional().describe('video = 16:9, reel = 9:16') } }, async ({ kind, fmt }) => callPath('/api/avatar/request', { kind: kind || 'report', fmt: fmt || (kind === 'reel' ? 'reel' : 'video') }));
+server.registerTool('cc_avatar_status', { title: 'cc_avatar_status', description: 'Check an avatar render job by id (or omit to list your recent renders). Returns status + the finished video url when ready.', inputSchema: { job: z.string().optional().describe('job id from cc_avatar_render') } }, async ({ job }) => getPath('/api/avatar/status' + (job ? ('?job=' + encodeURIComponent(job)) : '')));
+
 // Discovery + escape hatch.
 server.registerTool('cc_list_tools', { title: 'cc_list_tools', description: 'List every Close Cadence tool available to your plan.', inputSchema: {} }, async () => {
   const miss = requireKey(); if (miss) return miss;
@@ -85,4 +133,72 @@ server.registerTool('cc_list_tools', { title: 'cc_list_tools', description: 'Lis
 });
 server.registerTool('cc_run', { title: 'cc_run', description: 'Run ANY Close Cadence tool by id with an inputs object. Prefer the specific cc_* tools when one fits.', inputSchema: { tool: z.string().describe('Tool id, e.g. bio-builder'), inputs: z.record(z.any()).optional() } }, async ({ tool, inputs }) => callTool(tool, inputs));
 
+// Local-only: write the live Command Center dashboard board. No key/subscription needed — the dashboard
+// renders purely from this local file (the permanent asset) even if the AI subscription lapses. Stays on
+// the agent's device. Mirrors the desktop host's cc_save_board (board.json in the CloseCadence data dir).
+function boardPath() {
+  let dir;
+  if (process.platform === 'win32') dir = join(process.env.APPDATA || join(homedir(), 'AppData', 'Roaming'), 'CloseCadence');
+  else if (process.platform === 'darwin') dir = join(homedir(), 'Library', 'Application Support', 'CloseCadence');
+  else dir = join(homedir(), '.config', 'CloseCadence');
+  mkdirSync(dir, { recursive: true });
+  return join(dir, 'board.json');
+}
+server.registerTool('cc_save_board', {
+  title: 'cc_save_board',
+  description: "Update the agent's live Command Center dashboard. After reading their recent real-estate email, pass the full board object — it saves locally and the desktop dashboard refreshes. Stays on the agent's device. Core blocks: summary, transactions, tasks, email, signatures, notes, meta. Pillar-2/3 blocks the dashboard also renders: account { name, title, brokerage, photo_url, tier, tier_label, trial_ends, credits_remaining, credits_monthly, status } (pull from the cc account/credits endpoint so the identity + credits strip survive a lapse), assets [ { kind, title, status, status_detail, url, job_id, ts } ] (platform jobs — listing docs, videos, CMAs), roi { period_label, hours_saved, drafts_written, assets_produced, deals_tracked }, income, extra_panels.",
+  inputSchema: { board: z.record(z.any()).describe('The full board: { meta, summary, transactions, tasks, email, signatures, notes, income, account, assets, roi, extra_panels }.') },
+  annotations: { readOnlyHint: false, openWorldHint: false },
+}, async ({ board }) => {
+  try {
+    writeFileSync(boardPath(), JSON.stringify(board ?? {}));
+    return { content: [{ type: 'text', text: 'Board saved — it’ll refresh in the Close Cadence Command Center dashboard.' }] };
+  } catch (e) {
+    return errText('Couldn’t save the board: ' + String(e && e.message || e));
+  }
+});
+
+// ---- Partner-spec aliases (2026-06-23 Platform Connector Architecture spec, Morgahn Grey) ----
+// Thin, spec-named aliases over the EXISTING backend — additive, no breakage to the cc_* tools above.
+// Single source of truth: each entry maps a spec name -> the same backend a cc_* tool already uses, so
+// the mapping stays obvious and maintainable. Tool-engine aliases go to /api/tool (same id, same auth).
+const SPEC_TOOL_ALIASES = [
+  // spec_name              backend tool id   (same backend as)   description / inputs
+  ['generate_listing_doc', 'listing-engine', 'Full listing marketing package: MLS remarks, long description, social posts, hooks (same engine as cc_listing).', 'address, price, beds, baths, sqft, features'],
+  ['generate_cma', 'cma-narrative', 'CMA pricing narrative + objection handling from comps, for a seller (same engine as cc_cma; pair with cc_comps for real data).', 'address, comps, suggested_price, seller_expectation, market'],
+  // create_custom_video returns a production-ready VIDEO SCRIPT / STORYBOARD today (listing tour script).
+  // Rendered-video output (an actual .mp4 URL) is PENDING provider keys (Creatomate / HeyGen) — this tool
+  // does NOT return a video file or fake a URL; it returns the script the renderer will use once wired.
+  ['create_custom_video', 'listing-tour', 'Production-ready VIDEO SCRIPT / STORYBOARD for a listing tour (hook, room-by-room narration with shot cues, on-screen captions). NOTE: this currently returns the SCRIPT only — rendered video (an actual .mp4) is pending provider keys (Creatomate / HeyGen) and is NOT produced yet; no video URL is returned.', 'address, features, highlights, length, voice'],
+];
+for (const [name, id, desc, fields] of SPEC_TOOL_ALIASES) {
+  server.registerTool(
+    name,
+    {
+      title: name,
+      description: desc + ' Pass an `inputs` object with: ' + fields + '. Runs in your saved voice; uses plan credits.',
+      inputSchema: { inputs: z.record(z.any()).describe('Tool inputs — ' + fields) },
+      annotations: { readOnlyHint: false, openWorldHint: true },
+    },
+    async ({ inputs }) => callTool(id, inputs),
+  );
+}
+
+// Spec aliases over non-/api/tool backends (async job + asset list). Same auth (CC_API_KEY), same base URL.
+// list_assets -> GET /api/assets/list (the member's recent generated outputs from the Content Library).
+server.registerTool('list_assets', {
+  title: 'list_assets',
+  description: 'List your recent generated outputs (the Content Library) — newest first: { id, tool, title, fav, ts, result }. Matches the 2026-06-23 connector spec.',
+  inputSchema: {},
+  annotations: { readOnlyHint: true, openWorldHint: true },
+}, async () => getPath('/api/assets/list'));
+
+// job_status -> GET /api/job/<id> — poll a long-running async job (e.g. video render) until done/error.
+server.registerTool('job_status', {
+  title: 'job_status',
+  description: 'Check the status of an async Close Cadence job (e.g. a long-running video render) by its job id. Returns { status, result, error }. Matches the 2026-06-23 connector spec.',
+  inputSchema: { job_id: z.string().describe('The job id returned when the async job was submitted (e.g. job_….).') },
+  annotations: { readOnlyHint: true, openWorldHint: true },
+}, async ({ job_id }) => getPath('/api/job/' + encodeURIComponent(job_id)));
+
 await server.connect(new StdioServerTransport());