@adrata/adrata-mcp 1.0.0 → 1.0.2

package/toolsets/spaces.js

@@ -0,0 +1,628 @@
+/**
+ * Space tools for the Adrata MCP server — the nine surfaces a person now
+ * chooses between, made reachable by an agent.
+ *
+ * # Why this file exists
+ *
+ * The app grew a two-step chooser at `/spaces` over nine spaces in three
+ * families (Demand: Story, Market, Sell · Supply: Build, Design, Service ·
+ * Company: People, Finance, Cloud). Six of those nine read data this server
+ * had no tool for. An agent could not answer "how healthy are our customers",
+ * "what content do we have", "what is actually connected", or even "which
+ * spaces does this workspace have" — questions a person answers by clicking
+ * once.
+ *
+ * The gap was not that the endpoints were secret. It was that reaching them
+ * required `adrata_api_request` with a hand-written path, which is the raw
+ * bridge this server's typed tools exist to replace: no shape, no denominator,
+ * no idea which of several endpoints a surface actually joins. `/service`
+ * reads `expansion/health` AND `companies`; `/market` derives its segments
+ * from four collections at once. A tool that knows the join is the difference
+ * between an agent answering the question and an agent guessing at it.
+ *
+ * # Every tool here is a READ
+ *
+ * Deliberately. The nine spaces introduced no new write endpoints — they are
+ * projections over records that already have governed write tools (a deal is
+ * still written through the opportunity tools, a task through the action
+ * tools). Adding ungoverned writes here to "complete" a space would recreate
+ * exactly the defect the `governedWrite` docblock in ../api-bridge.js was
+ * written to close. When a space does grow a write, it routes through
+ * `governedWrite` like everything else.
+ *
+ * # Never a confident zero
+ *
+ * Every count in this file carries its denominator or its basis. A tool that
+ * answers `0` with nothing beside it is indistinguishable from a broken
+ * integration, an empty workspace, and a renamed column — and that ambiguity
+ * has already cost this codebase a real investigation. So `get_customer_health`
+ * says "15 of 150 accounts scored" rather than "15", `list_content_files` says
+ * whether the store is empty or absent, and any count derived from a list the
+ * server truncated says so rather than reporting the page size as the total.
+ */
+
+/**
+ * The nine spaces, their families, and where each one's data actually lives.
+ *
+ * Kept as data rather than prose because two questions get asked constantly —
+ * "what are the spaces" and "which tool reads this one" — and a table answers
+ * both without the agent reading source. `dataSource: null` is meaningful, not
+ * missing: it records a space that HAS no server-side data, which is a real
+ * answer and a very different thing from one whose endpoint is unknown.
+ */
+export const SPACES = [
+  {
+    id: 'story',
+    family: 'demand',
+    route: '/story',
+    reads: ['/api/v1/knowledge/files'],
+    tool: 'list_content_files',
+  },
+  {
+    id: 'market',
+    family: 'demand',
+    route: '/market',
+    reads: [
+      '/api/v1/icp-profiles',
+      '/api/v1/companies',
+      '/api/v1/opportunities',
+      '/api/v1/campaigns',
+    ],
+    tool: 'get_market_overview',
+  },
+  {
+    id: 'sell',
+    family: 'demand',
+    route: '/opportunities',
+    reads: ['/api/v1/opportunities', '/api/v1/pipeline-stages'],
+    tool: 'search_opportunities / get_pipeline_board',
+  },
+  {
+    id: 'build',
+    family: 'supply',
+    route: '/board',
+    reads: ['/api/v1/work-boards', '/api/v1/work-items', '/api/v1/work-scopes'],
+    tool: 'list_work_boards / list_work_scopes',
+  },
+  {
+    id: 'design',
+    family: 'supply',
+    route: '/design',
+    reads: [],
+    dataSource: null,
+    tool: null,
+    unreachable:
+      'Design canvases are stored in the browser\'s localStorage on ONE device (key prefix adrata.starfield.design.<workspaceId>). There is no endpoint, no row, and no sync — so no agent, CLI, or second browser can read them, and this is a property of the feature rather than a missing tool. Reaching them would require the canvas to be persisted server-side first.',
+  },
+  {
+    id: 'service',
+    family: 'supply',
+    route: '/service',
+    reads: ['/api/v1/expansion/health', '/api/v1/companies'],
+    tool: 'get_customer_health',
+  },
+  {
+    id: 'people',
+    family: 'company',
+    route: '/people',
+    reads: ['/api/v1/people'],
+    tool: 'search_people',
+  },
+  {
+    id: 'finance',
+    family: 'company',
+    route: '/finance',
+    reads: ['/api/v1/opportunities', '/api/v1/usage/limits'],
+    tool: 'get_finance_overview',
+  },
+  {
+    id: 'cloud',
+    family: 'company',
+    route: '/cloud',
+    reads: ['/api/v1/providers/workspace-connectors', '/api/v1/oauth/email/providers'],
+    tool: 'list_workspace_connectors',
+  },
+];
+
+export const SPACE_FAMILIES = ['demand', 'supply', 'company'];
+
+/**
+ * Read a list payload without inventing a total.
+ *
+ * The API returns collections in several shapes (`{data: []}`, `{items: []}`,
+ * a bare array) and SOMETIMES a separate total. Guessing wrong yields the
+ * worst possible answer — a plausible number that is really the page size — so
+ * this returns the rows it actually found plus whether a server-side total was
+ * present, and the callers say "N returned" instead of "N exist" when it was
+ * not.
+ */
+export function readCollection(payload) {
+  const rows = Array.isArray(payload)
+    ? payload
+    : Array.isArray(payload?.data)
+      ? payload.data
+      : Array.isArray(payload?.items)
+        ? payload.items
+        : Array.isArray(payload?.results)
+          ? payload.results
+          : null;
+
+  const total =
+    typeof payload?.total === 'number'
+      ? payload.total
+      : typeof payload?.count === 'number'
+        ? payload.count
+        : typeof payload?.pagination?.total === 'number'
+          ? payload.pagination.total
+          : null;
+
+  return {
+    rows: rows ?? [],
+    // `shapeRecognized:false` is why a caller can tell "the workspace has none"
+    // from "the response was not a collection at all" — the second is a bug
+    // report, the first is an answer.
+    shapeRecognized: rows !== null,
+    total,
+  };
+}
+
+/**
+ * Turn a count into a sentence that cannot be mistaken for a broken read.
+ *
+ * This is the single most reused thing in the file. `0` alone is ambiguous;
+ * "0 of 150 accounts have a health score" is an answer, and "the response was
+ * not a collection" is a defect the agent should report rather than average
+ * into a summary.
+ */
+export function describeCount({ found, of, noun, ofNoun, shapeRecognized = true, truncated = false }) {
+  if (!shapeRecognized) {
+    return `Could not read ${noun}: the endpoint responded, but the body was not a collection. Treat this as a broken read, NOT as zero.`;
+  }
+  const base =
+    typeof of === 'number'
+      ? `${found} of ${of} ${ofNoun ?? noun}`
+      : `${found} ${noun}${truncated ? ' (page limit reached — more exist)' : ''}`;
+  if (found === 0 && typeof of === 'number' && of > 0) {
+    return `${base}. The store is reachable and genuinely empty for this workspace — this is a real zero, not a failed read.`;
+  }
+  if (found === 0) {
+    return `${base}. Zero rows AND no denominator available, so this cannot distinguish an empty workspace from an undeployed store — say so rather than reporting "none".`;
+  }
+  return base;
+}
+
+export function registerSpaceTools(server, { z, api, ok }) {
+  // ---------------------------------------------------------------- spaces
+  server.tool(
+    'list_spaces',
+    `The nine spaces this workspace is organised into, in their three families (Demand: Story, Market, Sell · Supply: Build, Design, Service · Company: People, Finance, Cloud), each with the endpoints it reads and the tool that reads them.
+
+Start here when a request names a surface rather than a record — "what's in Service", "show me the Story space" — because the space-to-data mapping is not guessable: /service joins customer health to companies, /market derives segments from four collections, and /design has no server-side data AT ALL (canvases live in one browser's localStorage, so nothing can read them remotely — the tool reports that as an unreachable surface rather than an empty one).
+
+Entitlements are fetched when available, so this distinguishes "the workspace does not have this space" from "the space is empty".`,
+    {
+      family: z
+        .enum(['demand', 'supply', 'company'])
+        .optional()
+        .describe('Limit to one family. Omit for all nine spaces.'),
+    },
+    async ({ family }) => {
+      const spaces = family ? SPACES.filter((s) => s.family === family) : SPACES;
+
+      // Entitlements are advisory here: the space list is a property of the
+      // product, so a failed entitlement read must NOT empty it. It degrades
+      // to "unknown" and says so.
+      let entitlements = null;
+      let entitlementsError = null;
+      try {
+        const raw = await api('GET', '/api/v1/entitlements');
+        entitlements = readCollection(raw).shapeRecognized ? readCollection(raw).rows : raw;
+      } catch (err) {
+        entitlementsError = String(err?.message || err);
+      }
+
+      return ok({
+        spaces: spaces.map((s) => ({
+          ...s,
+          reachableByAgent: s.tool !== null,
+        })),
+        count: describeCount({
+          found: spaces.length,
+          of: SPACES.length,
+          noun: 'spaces',
+          ofNoun: 'spaces',
+        }),
+        unreachable: SPACES.filter((s) => s.tool === null).map((s) => ({
+          space: s.id,
+          why: s.unreachable,
+        })),
+        entitlements:
+          entitlementsError === null
+            ? entitlements
+            : {
+                unavailable: true,
+                error: entitlementsError,
+                note: 'Entitlements could not be read, so "which spaces does this workspace have" is UNKNOWN — not "none". The nine spaces above are the product\'s shape, not a statement about this workspace\'s grants.',
+              },
+      });
+    }
+  );
+
+  // --------------------------------------------------------------- service
+  server.tool(
+    'get_customer_health',
+    `Customer health scores — the Service space. Every scored account with its health score, risk band, and the signals behind it, joined to the company record so the answer names accounts rather than ids.
+
+Reports coverage as "N of M accounts scored", because the number that matters in a health review is usually the accounts with NO score — an unscored account is invisible risk, and a tool that returned only the scored ones would hide exactly the accounts a CSM needs to hear about.`,
+    {
+      limit: z.number().optional().describe('Max scored accounts to return (default 50).'),
+      riskOnly: z
+        .boolean()
+        .optional()
+        .describe('Return only accounts in a declining or at-risk band.'),
+    },
+    async ({ limit = 50, riskOnly = false }) => {
+      const healthRaw = await api('GET', '/api/v1/expansion/health', {
+        params: { limit },
+      });
+      const health = readCollection(healthRaw);
+
+      // The denominator. Without it "15 scored accounts" is unfalsifiable —
+      // it could be full coverage of a 15-account book or 10% of a 150-account
+      // one, and those call for opposite actions.
+      let companyTotal = null;
+      let companyTotalError = null;
+      try {
+        const companiesRaw = await api('GET', '/api/v1/companies', { params: { limit: 1 } });
+        const companies = readCollection(companiesRaw);
+        companyTotal = companies.total;
+        if (companyTotal === null) {
+          companyTotalError =
+            'The companies endpoint returned no server-side total, so coverage cannot be stated as a fraction.';
+        }
+      } catch (err) {
+        companyTotalError = String(err?.message || err);
+      }
+
+      const rows = riskOnly
+        ? health.rows.filter((r) => {
+            const band = String(r?.riskBand ?? r?.risk_band ?? r?.status ?? '').toLowerCase();
+            return band.includes('risk') || band.includes('declin') || band.includes('red');
+          })
+        : health.rows;
+
+      return ok({
+        accounts: rows,
+        coverage: describeCount({
+          found: health.rows.length,
+          of: companyTotal,
+          noun: 'accounts with a health score',
+          ofNoun: 'companies',
+          shapeRecognized: health.shapeRecognized,
+        }),
+        ...(companyTotalError
+          ? {
+              coverageCaveat: `Denominator unavailable: ${companyTotalError} Report the scored count WITHOUT implying it is complete.`,
+            }
+          : {}),
+        ...(riskOnly
+          ? {
+              filtered: describeCount({
+                found: rows.length,
+                of: health.rows.length,
+                noun: 'at-risk accounts',
+                ofNoun: 'scored accounts',
+              }),
+            }
+          : {}),
+      });
+    }
+  );
+
+  // ----------------------------------------------------------------- story
+  server.tool(
+    'list_content_files',
+    `Content files — the Story space. Everything the workspace has written or uploaded as narrative material, with type, owner, and linkage.
+
+This is the CONTENT store, not the account wiki: use search_knowledge for wiki pages about an account, and this for the assets themselves.`,
+    {
+      limit: z.number().optional().describe('Max files to return (default 100).'),
+      includeDeleted: z.boolean().optional().describe('Include soft-deleted files (default false).'),
+    },
+    async ({ limit = 100, includeDeleted = false }) => {
+      const raw = await api('GET', '/api/v1/knowledge/files', {
+        params: { limit, isDeleted: includeDeleted ? undefined : false },
+      });
+      const files = readCollection(raw);
+      return ok({
+        files: files.rows,
+        count: describeCount({
+          found: files.rows.length,
+          of: files.total,
+          noun: 'content files',
+          shapeRecognized: files.shapeRecognized,
+          truncated: files.total === null && files.rows.length === limit,
+        }),
+      });
+    }
+  );
+
+  // ---------------------------------------------------------------- market
+  server.tool(
+    'get_market_overview',
+    `The Market space: ICP profiles, the campaigns running against them, and how the company book distributes across them.
+
+The app derives its segments CLIENT-SIDE from four collections at once, so an agent hitting any single endpoint sees a fragment of what the page shows. This tool performs the same join and reports each part's own count, so a partial answer is visible AS partial rather than silently thin.`,
+    {
+      limit: z.number().optional().describe('Max companies to sample for the distribution (default 250).'),
+    },
+    async ({ limit = 250 }) => {
+      const parts = {};
+      const errors = {};
+
+      // Each read is independent: one failing endpoint must degrade its own
+      // section, never blank the overview and never quietly contribute a zero
+      // to a total.
+      for (const [key, path, params] of [
+        ['icpProfiles', '/api/v1/icp-profiles', {}],
+        ['campaigns', '/api/v1/campaigns', { limit: 100 }],
+        ['companies', '/api/v1/companies', { limit }],
+        ['opportunities', '/api/v1/opportunities', { limit: 250 }],
+      ]) {
+        try {
+          const raw = await api('GET', path, { params });
+          parts[key] = readCollection(raw);
+        } catch (err) {
+          errors[key] = String(err?.message || err);
+        }
+      }
+
+      const summary = {};
+      for (const [key, coll] of Object.entries(parts)) {
+        summary[key] = describeCount({
+          found: coll.rows.length,
+          of: coll.total,
+          noun: key,
+          shapeRecognized: coll.shapeRecognized,
+          truncated: coll.total === null && coll.rows.length >= (key === 'companies' ? limit : 100),
+        });
+      }
+
+      return ok({
+        icpProfiles: parts.icpProfiles?.rows ?? [],
+        campaigns: parts.campaigns?.rows ?? [],
+        companySample: parts.companies?.rows?.length ?? 0,
+        counts: summary,
+        ...(Object.keys(errors).length
+          ? {
+              partial: true,
+              failedReads: errors,
+              warning:
+                'One or more of the four collections failed to read. The sections that failed are MISSING, not empty — do not present this as a complete market picture.',
+            }
+          : {}),
+      });
+    }
+  );
+
+  // --------------------------------------------------------------- finance
+  server.tool(
+    'get_finance_overview',
+    `The Finance space: booked and open pipeline value alongside the workspace's plan usage and limits.
+
+Money figures are summed from the opportunities actually returned, and the tool says how many that was — a total computed from a truncated page is the classic way a revenue number comes out confidently wrong.`,
+    {},
+    async () => {
+      const parts = {};
+      const errors = {};
+      for (const [key, path, params] of [
+        ['opportunities', '/api/v1/opportunities', { limit: 500, scope: 'all' }],
+        ['usage', '/api/v1/usage/limits', {}],
+      ]) {
+        try {
+          parts[key] = await api('GET', path, { params });
+        } catch (err) {
+          errors[key] = String(err?.message || err);
+        }
+      }
+
+      const opps = parts.opportunities ? readCollection(parts.opportunities) : null;
+      let openValue = null;
+      let openCount = null;
+      if (opps?.shapeRecognized) {
+        const open = opps.rows.filter((o) => {
+          const s = String(o?.status ?? o?.stage ?? '').toLowerCase();
+          return !s.includes('won') && !s.includes('lost') && !s.includes('closed');
+        });
+        openCount = open.length;
+        openValue = open.reduce((sum, o) => sum + (Number(o?.value ?? o?.amount ?? 0) || 0), 0);
+      }
+
+      return ok({
+        openPipelineValue: openValue,
+        openDeals:
+          openCount === null
+            ? 'unavailable — opportunities did not read as a collection'
+            : describeCount({
+                found: openCount,
+                of: opps.rows.length,
+                noun: 'open deals',
+                ofNoun: 'opportunities returned',
+              }),
+        basis:
+          opps === null
+            ? 'No opportunities were read, so no money figure is stated. This is NOT $0.'
+            : describeCount({
+                found: opps.rows.length,
+                of: opps.total,
+                noun: 'opportunities summed',
+                shapeRecognized: opps.shapeRecognized,
+                truncated: opps.total === null && opps.rows.length >= 500,
+              }),
+        usage: parts.usage ?? { unavailable: errors.usage },
+        ...(Object.keys(errors).length ? { failedReads: errors } : {}),
+      });
+    }
+  );
+
+  // ----------------------------------------------------------------- cloud
+  server.tool(
+    'list_workspace_connectors',
+    `The Cloud space: what is ACTUALLY connected in this workspace — the connector registry joined to the live OAuth grants — not the catalogue of what could be connected.
+
+That distinction is the whole point of the tool. list_provider_catalog answers "what does Adrata integrate with"; this answers "what does THIS workspace have wired up, and is the grant still good". A connector present in the registry with no matching grant is a broken integration wearing a connected badge, and the tool surfaces that pairing explicitly.`,
+    {},
+    async () => {
+      const parts = {};
+      const errors = {};
+      for (const [key, path] of [
+        ['connectors', '/api/v1/providers/workspace-connectors'],
+        ['emailGrants', '/api/v1/oauth/email/providers'],
+      ]) {
+        try {
+          parts[key] = readCollection(await api('GET', path));
+        } catch (err) {
+          errors[key] = String(err?.message || err);
+        }
+      }
+
+      return ok({
+        connectors: parts.connectors?.rows ?? [],
+        emailGrants: parts.emailGrants?.rows ?? [],
+        counts: {
+          connectors: parts.connectors
+            ? describeCount({
+                found: parts.connectors.rows.length,
+                of: parts.connectors.total,
+                noun: 'workspace connectors',
+                shapeRecognized: parts.connectors.shapeRecognized,
+              })
+            : `unavailable: ${errors.connectors}`,
+          emailGrants: parts.emailGrants
+            ? describeCount({
+                found: parts.emailGrants.rows.length,
+                of: parts.emailGrants.total,
+                noun: 'connected email accounts',
+                shapeRecognized: parts.emailGrants.shapeRecognized,
+              })
+            : `unavailable: ${errors.emailGrants}`,
+        },
+        ...(Object.keys(errors).length
+          ? {
+              partial: true,
+              failedReads: errors,
+              warning:
+                'A side of the join failed. "Nothing connected" CANNOT be concluded from this response — one of the two sources did not answer.',
+            }
+          : {}),
+      });
+    }
+  );
+
+  // -------------------------------------------------------------- calendar
+  server.tool(
+    'get_calendar_agenda',
+    `The agenda a person sees on /calendar — events in a date window with their attendees and organizer, from the desktop read model (GET /api/v2/events/calendar).
+
+Deliberately the v2 path, not /api/v1/events: the calendar page reads v2 and gets attendees and organizer resolved, where the v1 list returns the bare event. An agent briefing someone on their day needs to know WHO is in the room, so this reads the same model the person is looking at.`,
+    {
+      start: z.string().describe('ISO date/time for the start of the window, e.g. 2026-08-20T00:00:00Z'),
+      end: z.string().describe('ISO date/time for the end of the window.'),
+    },
+    async ({ start, end }) => {
+      const raw = await api('GET', '/api/v2/events/calendar', { params: { start, end } });
+      const events = readCollection(raw);
+      return ok({
+        window: { start, end },
+        events: events.rows,
+        count: describeCount({
+          found: events.rows.length,
+          of: events.total,
+          noun: 'events in this window',
+          shapeRecognized: events.shapeRecognized,
+        }),
+        note:
+          events.shapeRecognized && events.rows.length === 0
+            ? 'An empty window is a real answer — the calendar read succeeded and there is nothing scheduled between these times. Check the window before concluding the calendar is disconnected.'
+            : undefined,
+      });
+    }
+  );
+
+  // -------------------------------------------------------------- pipeline
+  server.tool(
+    'get_pipeline_board',
+    `The Deals list as the /opportunities page assembles it: every pipeline stage in order, with the deals sitting in each one.
+
+search_opportunities returns deals as a flat list; this returns the BOARD, so "what is stuck in negotiation" and "which stage is empty" are answerable. An empty stage is reported as an empty stage rather than omitted — a missing column and a column with no deals mean very different things to a forecast.`,
+    {
+      limit: z.number().optional().describe('Max deals to place on the board (default 250).'),
+    },
+    async ({ limit = 250 }) => {
+      const parts = {};
+      const errors = {};
+      for (const [key, path, params] of [
+        ['stages', '/api/v1/pipeline-stages', { limit: 100 }],
+        ['opportunities', '/api/v1/opportunities', { limit }],
+      ]) {
+        try {
+          parts[key] = readCollection(await api('GET', path, { params }));
+        } catch (err) {
+          errors[key] = String(err?.message || err);
+        }
+      }
+
+      if (!parts.stages || !parts.opportunities) {
+        return ok({
+          unavailable: true,
+          failedReads: errors,
+          warning:
+            'The board needs BOTH stages and deals. One side failed, so no board is returned — an agent must not infer an empty pipeline from this.',
+        });
+      }
+
+      const byStage = new Map();
+      for (const stage of parts.stages.rows) {
+        const id = stage?.id ?? stage?.stageId ?? stage?.name;
+        byStage.set(String(id), { stage, deals: [] });
+      }
+      let unplaced = 0;
+      for (const deal of parts.opportunities.rows) {
+        const key = String(deal?.stageId ?? deal?.stage_id ?? deal?.stage ?? '');
+        const bucket = byStage.get(key);
+        if (bucket) bucket.deals.push(deal);
+        else unplaced += 1;
+      }
+
+      return ok({
+        board: [...byStage.values()].map(({ stage, deals }) => ({
+          stage,
+          dealCount: deals.length,
+          deals,
+        })),
+        counts: {
+          stages: describeCount({
+            found: parts.stages.rows.length,
+            of: parts.stages.total,
+            noun: 'pipeline stages',
+            shapeRecognized: parts.stages.shapeRecognized,
+          }),
+          deals: describeCount({
+            found: parts.opportunities.rows.length,
+            of: parts.opportunities.total,
+            noun: 'deals placed on the board',
+            shapeRecognized: parts.opportunities.shapeRecognized,
+            truncated: parts.opportunities.total === null && parts.opportunities.rows.length >= limit,
+          }),
+        },
+        // Deals whose stage id matches no known stage would otherwise vanish
+        // from the board and quietly shrink the pipeline total.
+        ...(unplaced > 0
+          ? {
+              unplacedDeals: `${unplaced} of ${parts.opportunities.rows.length} deals reference a stage that is not in the stage list. They are NOT on the board above, so the board's deal count is short by that many.`,
+            }
+          : {}),
+      });
+    }
+  );
+}