@adrata/adrata-mcp 1.0.2 → 1.0.6

package/tools/work-hub/audit.js

@@ -8,17 +8,19 @@
  */
 
 const TERMINAL_STAGES = new Set(['production', 'deep backlog']);
-// Up Next is the deliberately unowned pull buffer. Triage/Aligning are capture
-// and grooming, where thin cards are allowed. Only these stages mean somebody
+// Backlog is thin capture, and Up Next is the deliberately unowned pull buffer.
+// These stages mean somebody
 // has actually taken a pass and therefore require both an end-to-end owner and
 // a current handler.
-const ACTIVE_STAGES = new Set(['in progress', 'staging qa1', 'staging qa2']);
+const ACTIVE_STAGES = new Set(['aligning', 'in progress', 'staging qa1', 'staging qa2']);
 // A card crossing the cut line into Up Next must be executable. Production is
 // included because historical evidence does not stop mattering after release.
 const EXECUTABLE_STAGES = new Set(['up next', ...ACTIVE_STAGES, 'production']);
 
 function normalized(value) {
-  return String(value ?? '').trim().toLowerCase();
+  return String(value ?? '')
+    .trim()
+    .toLowerCase();
 }
 
 function hoursSince(iso, nowMs) {
@@ -96,7 +98,8 @@ export function auditWorkHubBoards(boards, { now = new Date() } = {}) {
         } else if (item.criteria === undefined) {
           add('criteria_not_measured', 'This read did not include acceptance-criteria status.');
         }
-        if (!item.kind) add('missing_kind', 'The card is not classified as a story, bug, or chore.');
+        if (!item.kind)
+          add('missing_kind', 'The card is not classified as a story, bug, or chore.');
       }
       if (isActive && !item.assigneeUserId) {
         add('unowned_active_card', 'The card is active but has no end-to-end owner.');
@@ -107,7 +110,12 @@ export function auditWorkHubBoards(boards, { now = new Date() } = {}) {
 
       const staleAfter = column?.staleness?.staleAfterHours;
       const ageHours = hoursSince(item.enteredColumnAt, nowMs);
-      if (!isTerminal && Number.isFinite(staleAfter) && ageHours !== null && ageHours > staleAfter) {
+      if (
+        !isTerminal &&
+        Number.isFinite(staleAfter) &&
+        ageHours !== null &&
+        ageHours > staleAfter
+      ) {
         add(
           'stale_open_card',
           `The card has spent ${Math.floor(ageHours)}h in ${stage}; this column is stale after ${staleAfter}h.`
@@ -115,7 +123,9 @@ export function auditWorkHubBoards(boards, { now = new Date() } = {}) {
       }
     }
 
-    findings.push(...boardFindings.map((finding) => ({ boardId: board.id, boardName: board.name, ...finding })));
+    findings.push(
+      ...boardFindings.map((finding) => ({ boardId: board.id, boardName: board.name, ...finding }))
+    );
     perBoard.push({
       boardId: board.id,
       boardName: board.name,

package/toolsets/revenue/competitive-coverage.js

@@ -0,0 +1,164 @@
+/**
+ * Coverage for the two competitive-intelligence reads, both of which used to answer zero with
+ * no denominator and no statement of what they had actually asked.
+ *
+ * `get_competitor_intel` was documented as competitive intelligence FOR A NAMED COMPANY and
+ * sent `companyId` to a handler that took no query extractor at all: the parameter was
+ * discarded without error, and the workspace's whole competitor-definition list came back. So
+ * the tool returned the same answer for every company, and on an unpopulated workspace
+ * returned `count: 0`. A seller could not tell "no competitors at this account" from "we never
+ * scoped this to the account" from "ingest is broken".
+ *
+ * `list_customer_signals` passed its endpoint straight through and returned a bare `items: []`.
+ *
+ * The repo already knows how to do this — `get_installed_base` and `get_icp_distribution` carry
+ * coverage blocks saying in words that zero invoices means nothing has been ingested rather
+ * than zero spend, `check_inbox` checks provider connectivity before reporting no replies, and
+ * `describeCount` states a denominator or explains why it cannot. These two tools predate that
+ * discipline; this brings them forward.
+ *
+ * Kept separate from `server.js` so the composition can be tested: `server.js` auto-connects a
+ * transport on import and cannot be loaded by a unit test.
+ */
+
+import { describeCount } from '../spaces.js';
+
+/** The rows out of an API envelope, whatever shape it came in as. Null when it is not a list. */
+function rowsOf(payload) {
+  if (Array.isArray(payload)) return payload;
+  const data = payload?.data;
+  if (Array.isArray(data)) return data;
+  if (Array.isArray(data?.data)) return data.data;
+  return null;
+}
+
+/** The signal rows out of `SignalListResponse`, or null when the body was not a list. */
+function signalRows(payload) {
+  if (Array.isArray(payload?.items)) return payload.items;
+  return rowsOf(payload);
+}
+
+/** A count the API stated, as opposed to one we inferred from a truncated page. */
+function statedTotal(payload) {
+  const meta = payload?.meta ?? payload?.data?.meta;
+  const total = meta?.total ?? meta?.count;
+  return typeof total === 'number' ? total : null;
+}
+
+/**
+ * Compose the answer for one company from the workspace's competitor definitions and that
+ * company's mentions.
+ *
+ * The two halves have DIFFERENT SCOPES and saying so is most of the fix. Competitor
+ * definitions are a workspace-level configuration — the list of rivals this workspace tracks —
+ * and were previously returned as though they were an answer about the account. Mentions are
+ * the company-scoped evidence, and they live one route over.
+ *
+ * `mentionsUnavailable` is a third state again: a mentions read that FAILED must not be
+ * reported as a company with no mentions.
+ */
+export function composeCompetitorIntel({
+  companyId,
+  definitionsPayload,
+  mentionsPayload,
+  workspaceMentionsPayload,
+  mentionsUnavailable = false,
+}) {
+  const definitions = rowsOf(definitionsPayload);
+  const mentions = mentionsUnavailable ? null : rowsOf(mentionsPayload);
+  // The denominator: how many competitor mentions this workspace holds AT ALL. Without it
+  // "0 mentions" is indistinguishable from a store nothing has written to, which is the exact
+  // ambiguity a seller cannot resolve from the tool output.
+  const workspaceMentionTotal = mentionsUnavailable ? null : statedTotal(workspaceMentionsPayload);
+
+  const coverage = { companyId, scope: 'One company, read from two differently-scoped stores.' };
+
+  if (definitions === null) {
+    coverage.definitions =
+      'Could not read competitor definitions: the endpoint responded, but the body was not a collection. Treat this as a broken read, NOT as zero.';
+  } else if (definitions.length === 0) {
+    coverage.definitions =
+      'No competitors are defined for this workspace at all, so nothing can be attributed to any account. This is an UNCONFIGURED store, not evidence that this company faces no competition. Define competitors first (POST /api/v1/competitors).';
+  } else {
+    coverage.definitions = `${definitions.length} competitor definitions are configured. These are WORKSPACE-WIDE — they are the rivals this workspace tracks, not a finding about this company.`;
+  }
+
+  if (mentionsUnavailable) {
+    coverage.mentions =
+      'Could not read competitor mentions for this company. This is unknown, not zero — do not report that the account has no competitive activity.';
+  } else if (mentions === null) {
+    coverage.mentions =
+      'Could not read competitor mentions: the endpoint responded, but the body was not a collection. Treat this as a broken read, NOT as zero.';
+  } else {
+    coverage.mentions = describeCount({
+      found: statedTotal(mentionsPayload) ?? mentions.length,
+      of: workspaceMentionTotal ?? undefined,
+      noun: 'competitor mentions attributed to this company',
+      ofNoun: 'competitor mentions in this workspace',
+    });
+  }
+
+  return {
+    companyId,
+    competitorDefinitions: definitions ?? [],
+    mentionsForCompany: mentions ?? [],
+    coverage,
+  };
+}
+
+/**
+ * Attach a denominator, or an explanation of why there is none, to a customer-signal read.
+ *
+ * An empty `items` array is the ambiguous case and the only one worth spending a second
+ * request on: zero rows for these filters is a real answer if the store holds signals, and a
+ * completely different answer if the store has never been written to. `workspaceProbePayload`
+ * is that unfiltered probe, and is expected to be absent when there were rows to report.
+ */
+export function composeCustomerSignals({ payload, filtersApplied, workspaceProbePayload }) {
+  const items = signalRows(payload);
+  const named = Object.entries(filtersApplied ?? {})
+    .filter(([, v]) => v !== undefined && v !== null && v !== '')
+    .map(([k]) => k);
+  const filterNote = named.length
+    ? `Filters applied: ${named.join(', ')}.`
+    : 'No filters applied beyond the workspace scope.';
+
+  if (items === null) {
+    return {
+      ...payload,
+      coverage: {
+        signals:
+          'Could not read customer signals: the endpoint responded, but the body was not a collection. Treat this as a broken read, NOT as zero.',
+      },
+    };
+  }
+
+  if (items.length > 0) {
+    return {
+      ...payload,
+      coverage: { signals: describeCount({ found: items.length, noun: 'customer signals' }), filters: filterNote },
+    };
+  }
+
+  // `undefined` means the probe was not run; `null` means it ran and could not be read. Those
+  // are different sentences, and collapsing them would reintroduce the defect one level up.
+  const workspaceRows =
+    workspaceProbePayload === undefined ? undefined : signalRows(workspaceProbePayload);
+
+  let signals;
+  if (workspaceProbePayload === undefined) {
+    signals =
+      'Zero signals for these filters, and the workspace total was not checked, so this cannot distinguish an empty result from a store nothing has ever written to. Say so rather than reporting "none".';
+  } else if (workspaceRows === null) {
+    signals =
+      'Zero signals for these filters, and the workspace-wide probe could not be read. Treat this as unknown, NOT as zero.';
+  } else if (workspaceRows.length === 0) {
+    signals =
+      'The customer_signals store holds NO rows for this workspace at all — nothing has been ingested (webhook, manual log, or BYOK adapter). This is an unwritten store, not an absence of buying activity.';
+  } else {
+    signals =
+      'Zero signals match these filters, but the store does hold signals for this workspace. This is a real zero for the filters, not a failed read — try widening them.';
+  }
+
+  return { ...payload, coverage: { signals, filters: filterNote } };
+}

package/transport-http.js

@@ -18,12 +18,17 @@
 
 import http from 'node:http';
 import crypto from 'node:crypto';
+import { readFileSync } from 'node:fs';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { authenticate } from './access/auth.js';
 import { getCorsHeaders, isOriginAllowed, checkTransportSecurity, isIpAllowed, checkRateLimit, rateLimitResponse as buildRateLimitResponse } from './security.js';
 import { protectedResourceMetadata, validateTokenAudience } from './access/resource-metadata.js';
 
 const PROTECTED_RESOURCE_METADATA_PATH = '/.well-known/oauth-protected-resource';
+const PACKAGE_VERSION = JSON.parse(
+  readFileSync(new URL('./package.json', import.meta.url), 'utf8')
+).version;
+const BUILD_SHA = process.env.ADRATA_MCP_BUILD_SHA?.trim() || 'unknown';
 
 const PORT = parseInt(process.env.ADRATA_MCP_PORT || '3100', 10);
 const CORS_ORIGINS = process.env.ADRATA_MCP_CORS_ORIGINS || '*';
@@ -55,7 +60,7 @@ function parsePositiveInt(value, fallback) {
 // connect it to the server, and let the SDK assign a session ID.
 // ---------------------------------------------------------------------------
 
-/** @type {Map<string, { transport: StreamableHTTPServerTransport, principal: string, lastSeenAt: number }>} */
+/** @type {Map<string, { transport: StreamableHTTPServerTransport, server: import('@modelcontextprotocol/sdk/server/mcp.js').McpServer, principal: string, lastSeenAt: number }>} */
 const sessions = new Map();
 const validatedPrincipals = new Map();
 
@@ -72,7 +77,12 @@ async function validateHostedBearer(auth, token, principal) {
   if (cachedUntil > Date.now()) return true;
 
   const apiBase = auth.apiUrl || process.env.ADRATA_API_URL || 'https://api.adrata.com';
-  const validationPath = process.env.ADRATA_MCP_TOKEN_VALIDATION_PATH || '/api/v1/capabilities/workspace';
+  // The board capability inventory is an authenticated, read-only endpoint
+  // carried by every hosted MCP grant (`read:tasks`).  Do not use the legacy
+  // `/api/v1/capabilities/workspace` route here: that platform-capability
+  // surface is not implemented in the live API and returns 404, which made a
+  // correctly signed, audience-bound token look invalid at this boundary.
+  const validationPath = process.env.ADRATA_MCP_TOKEN_VALIDATION_PATH || '/api/v1/work-capabilities';
   const validationUrl = new URL(validationPath, apiBase);
 
   try {
@@ -262,11 +272,15 @@ function readBody(req, maxBytes = MAX_BODY_BYTES) {
 /**
  * Start the Streamable HTTP server and return a cleanup function.
  *
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} mcpServer
- *   The shared MCP server instance (same one used by stdio).
+ * @param {() => import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} createMcpServer
+ *   Factory for a fresh protocol instance per hosted session. The SDK owns one
+ *   transport per server instance and refuses a second connection.
  * @returns {Promise<http.Server>}
  */
-export async function startHttpTransport(mcpServer, options = {}) {
+export async function startHttpTransport(createMcpServer, options = {}) {
+  if (typeof createMcpServer !== 'function') {
+    throw new TypeError('Hosted MCP transport requires a server factory.');
+  }
   const runWithAuthContext = options.runWithAuthContext || ((auth, fn) => fn());
 
   const httpServer = http.createServer(async (req, res) => {
@@ -283,7 +297,11 @@ export async function startHttpTransport(mcpServer, options = {}) {
 
     if (pathname === '/health') {
       setCorsHeaders(res, req);
-      writeJson(res, 200, { status: 'ok' });
+      writeJson(res, 200, {
+        status: 'ok',
+        packageVersion: PACKAGE_VERSION,
+        buildSha: BUILD_SHA,
+      });
       return;
     }
 
@@ -417,8 +435,11 @@ export async function startHttpTransport(mcpServer, options = {}) {
           if (sid) sessions.delete(sid);
         };
 
-        // Connect the MCP server to this transport
-        await runWithAuthContext(auth, () => mcpServer.connect(transport));
+        // Each transport owns its protocol instance. Reusing one McpServer here
+        // makes the second client crash the whole process with "Already
+        // connected to a transport" and prevents concurrent hosted sessions.
+        const sessionServer = createMcpServer();
+        await runWithAuthContext(auth, () => sessionServer.connect(transport));
 
         // Handle the request (the SDK will set the session ID during init)
         await runWithAuthContext(auth, () => transport.handleRequest(req, res, body));
@@ -426,7 +447,7 @@ export async function startHttpTransport(mcpServer, options = {}) {
         // Store the session after initialization
         const sid = transport.sessionId;
         if (sid) {
-          sessions.set(sid, { transport, principal, lastSeenAt: Date.now() });
+          sessions.set(sid, { transport, server: sessionServer, principal, lastSeenAt: Date.now() });
         }
       } else if (sessionId && sessions.has(sessionId)) {
         // Existing session