@imboard.ai/mcp-server 0.1.0 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imboard.ai/mcp-server",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "imboard MCP server — adapter over the public REST API",
   "type": "module",
   "license": "MIT",
@@ -51,33 +51,34 @@
   "bugs": {
     "url": "https://github.com/imboard-ai/imboard-monorepo/issues"
   },
-  "scripts": {
-    "build": "esbuild src/index.ts --bundle --platform=node --outdir=dist --out-extension:.js=.cjs --sourcemap --external:@modelcontextprotocol/sdk --external:zod --banner:js='#!/usr/bin/env node'",
-    "dev": "tsx watch src/index.ts",
-    "start": "node dist/index.cjs",
-    "lint": "eslint src/**/*.ts",
-    "format:check": "prettier --check \"src/**/*.ts\"",
-    "format:write": "prettier --write \"src/**/*.ts\"",
-    "typecheck": "tsc --noEmit",
-    "test": "cross-env NODE_OPTIONS='--experimental-vm-modules' jest --passWithNoTests --detectOpenHandles --forceExit --verbose --colors",
-    "prepack": "npm run build"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.1.12"
   },
   "devDependencies": {
     "@jest/globals": "^30.3.0",
-    "@swc/core": "^1.15.21",
+    "@swc/core": "^1.15.24",
     "@swc/jest": "^0.2.39",
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.6.0",
     "cross-env": "^10.1.0",
-    "esbuild": "^0.27.2",
-    "eslint": "^9.39.2",
+    "esbuild": "^0.28.0",
+    "eslint": "^10.2.0",
     "jest": "^30.3.0",
-    "prettier": "^3.8.1",
+    "prettier": "^3.8.2",
     "tsx": "^4.11.2",
-    "typescript": "^5.8.2"
+    "typescript": "^6.0.2"
+  },
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --outdir=dist --out-extension:.js=.cjs --sourcemap --external:@modelcontextprotocol/sdk --external:zod --banner:js='#!/usr/bin/env node'",
+    "build:extension": "node scripts/build-extension.mjs",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.cjs",
+    "lint": "eslint \"src/**/*.ts\" \"*.config.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "format:write": "prettier --write \"src/**/*.ts\"",
+    "typecheck": "tsc --noEmit -p tsconfig.typecheck.json",
+    "hygiene": "bash -c 'pnpm run typecheck && pnpm run lint' --",
+    "test": "cross-env NODE_OPTIONS='--experimental-vm-modules' jest --passWithNoTests --detectOpenHandles --forceExit --verbose --colors"
   }
-}
+}

package/src/api-client/imboardApiClient.ts

@@ -9,12 +9,30 @@ import { McpConfig } from '../config.js';
 import { logger } from '../utils/logging.js';
 import { ImboardApiError, ImboardApiTimeoutError, ImboardApiNetworkError } from './errors.js';
 
-const DEFAULT_TIMEOUT_MS = 30_000;
+// These endpoints answer in well under a second; a long timeout only delays
+// failure. 10s + the GET retry below recovers quickly on a fresh connection if a
+// socket stalls, instead of dragging a hung call through the full retry cycle.
+const DEFAULT_TIMEOUT_MS = 10_000;
 const MAX_RETRIES = 2;
 const RETRY_BASE_MS = 500;
 
+/**
+ * MCP user-resolution map (#978, propagated by #1247).
+ *
+ * Backend endpoints that contain `userId` references attach a top-level
+ * `users` map when called with `?include=users`, so MCP consumers can render
+ * names + positions without a separate user-lookup call.
+ */
+export interface UserMapEntry {
+  userId: string;
+  name: string;
+  positions: string[];
+}
+export type UserMap = Record<string, UserMapEntry>;
+
 export interface ApiSuccessResponse<T> {
   data: T;
+  users?: UserMap;
   requestId: string | null;
 }
 
@@ -26,6 +44,7 @@ export interface ApiCollectionMeta {
 export interface ApiCollectionResponse<T> {
   data: T[];
   meta: ApiCollectionMeta;
+  users?: UserMap;
   requestId: string | null;
 }
 
@@ -46,10 +65,24 @@ export class ImboardApiClient {
     return this.request<T>('GET', path, undefined, params);
   }
 
-  async getCollection<T>(path: string, params?: Record<string, string>): Promise<ApiCollectionResponse<T>> {
+  async getCollection<T>(
+    path: string,
+    params?: Record<string, string>
+  ): Promise<ApiCollectionResponse<T>> {
     return this.requestCollection<T>('GET', path, params);
   }
 
+  /**
+   * GET a legacy non-enveloped endpoint and return the parsed body as-is,
+   * with no `{ data }` unwrapping. `get()` now also tolerates bare bodies, so
+   * this is mostly for callers that want the raw shape without the
+   * `{ data, users, requestId }` wrapper. Still goes through timeout + GET-retry.
+   */
+  async getRaw<T>(path: string, params?: Record<string, string>): Promise<T> {
+    const response = await this.executeWithRetry('GET', path, undefined, params);
+    return (await response.json()) as T;
+  }
+
   async post<T>(path: string, body?: unknown): Promise<ApiSuccessResponse<T>> {
     return this.request<T>('POST', path, body);
   }
@@ -70,24 +103,33 @@ export class ImboardApiClient {
     method: HttpMethod,
     path: string,
     body?: unknown,
-    params?: Record<string, string>,
+    params?: Record<string, string>
   ): Promise<ApiSuccessResponse<T>> {
     const response = await this.executeWithRetry(method, path, body, params);
     const requestId = response.headers.get('x-request-id');
-    const json = await response.json() as Record<string, unknown>;
+    const json = (await response.json()) as Record<string, unknown>;
 
-    if (!json || typeof json !== 'object' || !('data' in json)) {
+    if (json === null || typeof json !== 'object') {
       throw new ImboardApiError({
         code: 'INTERNAL_ERROR',
-        message: 'Response body missing "data" field',
+        message: 'Response body is not a JSON object',
         status: response.status,
         requestId,
         details: null,
       });
     }
 
+    // Most v1 routes wrap payloads as `{ data, meta, users }`, but several legacy
+    // routes return a bare object (e.g. historical-metrics `{ boardId, metrics }`,
+    // board-feedback `{ messages }`, document search `{ documentIds, meta }`).
+    // Tolerate both: use `data` when enveloped, otherwise pass the whole body
+    // through. Without this, every non-enveloped tool failed with a confusing
+    // "Response body missing data field" error.
+    const hasEnvelope = 'data' in json;
+
     return {
-      data: json.data as T,
+      data: (hasEnvelope ? json.data : json) as T,
+      users: 'users' in json ? (json.users as UserMap) : undefined,
       requestId,
     };
   }
@@ -95,11 +137,11 @@ export class ImboardApiClient {
   private async requestCollection<T>(
     method: HttpMethod,
     path: string,
-    params?: Record<string, string>,
+    params?: Record<string, string>
   ): Promise<ApiCollectionResponse<T>> {
     const response = await this.executeWithRetry(method, path, undefined, params);
     const requestId = response.headers.get('x-request-id');
-    const json = await response.json() as Record<string, unknown>;
+    const json = (await response.json()) as Record<string, unknown>;
 
     if (!json || typeof json !== 'object' || !('data' in json) || !('meta' in json)) {
       throw new ImboardApiError({
@@ -114,6 +156,7 @@ export class ImboardApiClient {
     return {
       data: json.data as T[],
       meta: json.meta as ApiCollectionMeta,
+      users: 'users' in json ? (json.users as UserMap) : undefined,
       requestId,
     };
   }
@@ -122,7 +165,7 @@ export class ImboardApiClient {
     method: HttpMethod,
     path: string,
     body?: unknown,
-    params?: Record<string, string>,
+    params?: Record<string, string>
   ): Promise<Response> {
     const url = this.buildUrl(path, params);
     // Conservative: only retry GET. PUT/DELETE are technically idempotent
@@ -135,7 +178,9 @@ export class ImboardApiClient {
     for (let attempt = 0; attempt < maxAttempts; attempt++) {
       if (attempt > 0) {
         const delayMs = RETRY_BASE_MS * Math.pow(2, attempt - 1);
-        logger.info(`Retrying ${method} ${path} (attempt ${attempt + 1}/${maxAttempts})`, { delayMs });
+        logger.info(`Retrying ${method} ${path} (attempt ${attempt + 1}/${maxAttempts})`, {
+          delayMs,
+        });
         await sleep(delayMs);
       }
 
@@ -160,7 +205,9 @@ export class ImboardApiClient {
 
         // Retry on 5xx for idempotent requests
         if (isIdempotent && response.status >= 500 && attempt < maxAttempts - 1) {
-          logger.warn(`Server error ${response.status} on ${method} ${path}, will retry`, { requestId });
+          logger.warn(`Server error ${response.status} on ${method} ${path}, will retry`, {
+            requestId,
+          });
           lastError = apiError;
           continue;
         }
@@ -195,8 +242,8 @@ export class ImboardApiClient {
     const timer = setTimeout(() => controller.abort(), this.timeoutMs);
 
     const headers: Record<string, string> = {
-      'Authorization': `Bearer ${this.token}`,
-      'Accept': 'application/json',
+      Authorization: `Bearer ${this.token}`,
+      Accept: 'application/json',
     };
 
     if (body !== undefined) {

package/src/server.ts

@@ -16,10 +16,14 @@ import { registerNotificationTools } from './tools/notifications.tools.js';
 import { registerActionItemTools } from './tools/action-items.tools.js';
 import { registerUserTools } from './tools/user.tools.js';
 import { registerSupportingTools } from './tools/supporting.tools.js';
+import { registerRogueKpiTools } from './tools/rogue-kpis.tools.js';
+import { registerPersonaDossierTools } from './tools/persona-dossiers.tools.js';
+import { registerKnowledgeGraphTools } from './tools/knowledge-graph.tools.js';
+import { registerKgAdvisoryTools } from './tools/kg-advisory.tools.js';
 import { registerDocsResources } from './resources/docs.resources.js';
 
 const SERVER_NAME = 'imboard-mcp-server';
-const SERVER_VERSION = '0.1.0';
+const SERVER_VERSION = '0.1.3';
 
 export function createServer(config: McpConfig): McpServer {
   logger.info(`Creating ${SERVER_NAME} v${SERVER_VERSION}`);
@@ -45,6 +49,10 @@ export function createServer(config: McpConfig): McpServer {
   registerActionItemTools(server, api);
   registerUserTools(server, api);
   registerSupportingTools(server, api);
+  registerRogueKpiTools(server, api);
+  registerPersonaDossierTools(server, api);
+  registerKnowledgeGraphTools(server, api);
+  registerKgAdvisoryTools(server, api);
 
   registerDocsResources(server);
 

package/src/tools/dashboards.tools.ts

@@ -1,31 +1,42 @@
-import { boardIdParam, resourceIdParam, paginationParams, buildQueryParams, formatResult, handleToolError, RegisterToolsFn } from './shared.js';
+import {
+  boardIdParam,
+  resourceIdParam,
+  paginationParams,
+  buildQueryParams,
+  formatResult,
+  handleToolError,
+  RegisterToolsFn,
+} from './shared.js';
 
 export const registerDashboardTools: RegisterToolsFn = (server, client) => {
   server.tool(
     'list_report_dashboards',
-    'Lists dashboards under a specific report. Dashboards are nested under reports in imboard\'s domain model.',
+    "Lists dashboards under a specific report. Dashboards are nested under reports in imboard's domain model. Includes a top-level `users` map resolving any userId references in the response (e.g. createdByUserId).",
     {
       boardId: boardIdParam,
-      reportId: resourceIdParam.describe('The report ID (required — dashboards are nested under reports)'),
+      reportId: resourceIdParam.describe(
+        'The report ID (required — dashboards are nested under reports)'
+      ),
       ...paginationParams,
     },
     async ({ boardId, reportId, ...rest }) => {
       try {
         const params = buildQueryParams(rest, []);
+        params.include = 'users';
         const result = await client.getCollection(
           `/api/boards/${boardId}/reports/${reportId}/dashboards`,
-          params,
+          params
         );
-        return formatResult({ data: result.data, meta: result.meta });
+        return formatResult({ data: result.data, meta: result.meta, users: result.users });
       } catch (error) {
         return handleToolError(error);
       }
-    },
+    }
   );
 
   server.tool(
     'get_dashboard',
-    'Returns details for a specific dashboard including type, title, and associated report.',
+    'Returns details for a specific dashboard including type, title, and associated report. Includes a top-level `users` map resolving any userId references in the response.',
     {
       boardId: boardIdParam,
       reportId: resourceIdParam.describe('The report ID'),
@@ -35,11 +46,12 @@ export const registerDashboardTools: RegisterToolsFn = (server, client) => {
       try {
         const result = await client.get(
           `/api/boards/${boardId}/reports/${reportId}/dashboards/${dashboardId}`,
+          { include: 'users' }
         );
-        return formatResult({ data: result.data });
+        return formatResult({ data: result.data, users: result.users });
       } catch (error) {
         return handleToolError(error);
       }
-    },
+    }
   );
 };

package/src/tools/documents.tools.ts

@@ -1,46 +1,55 @@
 import { z } from 'zod';
-import { boardIdParam, resourceIdParam, paginationParams, buildQueryParams, formatResult, handleToolError, RegisterToolsFn } from './shared.js';
+import {
+  boardIdParam,
+  resourceIdParam,
+  paginationParams,
+  buildQueryParams,
+  formatResult,
+  handleToolError,
+  RegisterToolsFn,
+} from './shared.js';
 
 export const registerDocumentTools: RegisterToolsFn = (server, client) => {
   server.tool(
     'list_board_documents',
-    'Lists document metadata for a board. Supports filtering by meeting or document type. Does not provide file download in V1.',
+    'Lists document metadata for a board. Supports filtering by meeting or document type. Does not provide file download in V1. Includes a top-level `users` map resolving any userId references in the response (e.g. createdByUserId).',
     {
       boardId: boardIdParam,
       ...paginationParams,
       meetingId: z.string().optional().describe('Filter by meeting ID'),
-      documentType: z.string().optional().describe('Filter by document type (e.g. boardResolutions, minutesOfMeetings, capTable)'),
+      documentType: z
+        .string()
+        .optional()
+        .describe('Filter by document type (e.g. boardResolutions, minutesOfMeetings, capTable)'),
     },
     async ({ boardId, ...rest }) => {
       try {
         const params = buildQueryParams(rest, ['meetingId', 'documentType']);
-        const result = await client.getCollection(
-          `/api/boards/${boardId}/documents`,
-          params,
-        );
-        return formatResult({ data: result.data, meta: result.meta });
+        params.include = 'users';
+        const result = await client.getCollection(`/api/boards/${boardId}/documents`, params);
+        return formatResult({ data: result.data, meta: result.meta, users: result.users });
       } catch (error) {
         return handleToolError(error);
       }
-    },
+    }
   );
 
   server.tool(
     'get_document',
-    'Returns metadata for a specific document including title, type, and associated meeting. Does not provide file download in V1.',
+    'Returns metadata for a specific document including title, type, and associated meeting. Does not provide file download in V1. Includes a top-level `users` map resolving any userId references in the response.',
     {
       boardId: boardIdParam,
       documentId: resourceIdParam.describe('The document ID'),
     },
     async ({ boardId, documentId }) => {
       try {
-        const result = await client.get(
-          `/api/boards/${boardId}/documents/${documentId}`,
-        );
-        return formatResult({ data: result.data });
+        const result = await client.get(`/api/boards/${boardId}/documents/${documentId}`, {
+          include: 'users',
+        });
+        return formatResult({ data: result.data, users: result.users });
       } catch (error) {
         return handleToolError(error);
       }
-    },
+    }
   );
 };

package/src/tools/kg-advisory.tools.ts

@@ -0,0 +1,110 @@
+/**
+ * KG governance advisory MCP tools (#978).
+ *
+ * Read-only surface (3 tools): list advisories, list runs, run a review pass.
+ * Mutation tools (dismiss/snooze/reopen/config-edit) are NOT exposed in v1 —
+ * those should remain explicit user actions through the UI for proper
+ * attribution.
+ *
+ * `get_governance_advisories` enriches the response with a `users` map (name
+ * + positions) so agent consumers don't need to re-resolve user IDs.
+ */
+
+import { z } from 'zod';
+import { boardIdParam, formatResult, handleToolError, RegisterToolsFn } from './shared.js';
+
+const ruleTypeEnum = z.enum([
+  'stale_commitment',
+  'dropped_topic',
+  'governance_coverage_gap',
+  'narrative_drift',
+  'unanswered_director_question',
+  'orphan_decision',
+  'textual_contradiction',
+]);
+
+const statusEnum = z.enum(['open', 'dismissed', 'resolved', 'snoozed']);
+
+export const registerKgAdvisoryTools: RegisterToolsFn = (server, client) => {
+  server.tool(
+    'get_governance_advisories',
+    'List KG governance advisories for a board. Returns all statuses by default (consumer groups by status). Filter via status, ruleType, or limit. Includes a top-level `users` map resolving any userId references in the response (owner, raisedBy, dismissedBy).',
+    {
+      boardId: boardIdParam,
+      status: statusEnum
+        .optional()
+        .describe('Filter to a single status. Default: all statuses returned.'),
+      ruleType: ruleTypeEnum.optional().describe('Filter to a single rule type.'),
+      limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(200)
+        .optional()
+        .describe('Max advisories to return (default 100).'),
+    },
+    async ({ boardId, status, ruleType, limit }) => {
+      try {
+        const params: Record<string, string> = { include: 'users' };
+        if (status) params.status = status;
+        if (ruleType) params.ruleType = ruleType;
+        if (limit !== undefined) params.limit = String(limit);
+        const response = await client.get(
+          `/api/boards/${boardId}/knowledge-graph/governance-advisory`,
+          params
+        );
+        return formatResult(response.data);
+      } catch (error) {
+        return handleToolError(error);
+      }
+    }
+  );
+
+  server.tool(
+    'get_governance_advisory_runs',
+    'List recent KG governance advisory review runs for a board (paginated, newest first). Audit/retro surface — see when runs fired, who triggered them, and finding counts per rule.',
+    {
+      boardId: boardIdParam,
+      limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe('Max runs to return (default 10).'),
+    },
+    async ({ boardId, limit }) => {
+      try {
+        const params: Record<string, string> = {};
+        if (limit !== undefined) params.limit = String(limit);
+        const response = await client.get(
+          `/api/boards/${boardId}/knowledge-graph/governance-advisory/runs`,
+          params
+        );
+        return formatResult(response.data);
+      } catch (error) {
+        return handleToolError(error);
+      }
+    }
+  );
+
+  server.tool(
+    'run_governance_advisory_review',
+    'Trigger a KG governance advisory review pass for a board. Returns the review ID. A 60s soft check returns the in-flight review if one already started in the last minute.',
+    {
+      boardId: boardIdParam,
+      reason: z.string().optional().describe('Free-text reason for triggering this run.'),
+    },
+    async ({ boardId, reason }) => {
+      try {
+        const response = await client.post(
+          `/api/boards/${boardId}/knowledge-graph/governance-advisory/run`,
+          { reason, source: 'mcp_tool' }
+        );
+        return formatResult(response.data);
+      } catch (error) {
+        return handleToolError(error);
+      }
+    }
+  );
+};

package/src/tools/knowledge-graph.tools.ts

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+import { boardIdParam, formatResult, handleToolError, RegisterToolsFn } from './shared.js';
+
+export const registerKnowledgeGraphTools: RegisterToolsFn = (server, client) => {
+  server.tool(
+    'get_board_prep_brief',
+    'Get a full board preparation brief from the knowledge graph: open contradictions, unanswered director questions, approved decisions pending follow-up, governance coverage gaps, dropped topics, director question patterns, and narrative drift. Requires board admin or internal management role.',
+    {
+      boardId: boardIdParam,
+    },
+    async ({ boardId }) => {
+      try {
+        const response = await client.get(`/api/boards/${boardId}/kg/prep-brief`);
+        return formatResult({ data: response.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    }
+  );
+
+  server.tool(
+    'get_knowledge_graph_summary',
+    'Get knowledge graph index stats for a board: node counts by type, edge count, health metrics (open contradictions, open questions, stale commitments), governance coverage gaps, dropped topics, compiled summary, and recent ingestion history. Requires board admin or internal management role.',
+    {
+      boardId: boardIdParam,
+    },
+    async ({ boardId }) => {
+      try {
+        const response = await client.get(`/api/boards/${boardId}/kg/summary`);
+        return formatResult({ data: response.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    }
+  );
+
+  server.tool(
+    'get_open_items',
+    'Get open items from the knowledge graph. Filter by type: "contradictions" (conflicting data across sources), "questions" (unanswered or deferred director questions), or "commitments" (approved/proposed decisions pending follow-up). Omit type to get all. Requires board admin or internal management role.',
+    {
+      boardId: boardIdParam,
+      type: z
+        .enum(['contradictions', 'questions', 'commitments'])
+        .optional()
+        .describe(
+          'Filter by item type: contradictions, questions, or commitments. Omit to get all types.'
+        ),
+    },
+    async ({ boardId, type }) => {
+      try {
+        const params: Record<string, string> = {};
+        if (type) params.type = type;
+        const response = await client.get(`/api/boards/${boardId}/kg/open-items`, params);
+        return formatResult({ data: response.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    }
+  );
+
+  server.tool(
+    'query_knowledge_graph',
+    'Ask a natural language question against the board knowledge graph. The system retrieves relevant graph data (contradictions, decisions, questions, topics, themes, KPI mentions) and synthesizes an answer using an LLM. Requires board admin or internal management role.',
+    {
+      boardId: boardIdParam,
+      question: z
+        .string()
+        .max(2000)
+        .describe(
+          'The natural language question to ask about the board knowledge graph (max 2000 chars)'
+        ),
+    },
+    async ({ boardId, question }) => {
+      try {
+        const response = await client.post(`/api/boards/${boardId}/kg/query`, { question });
+        return formatResult({ data: response.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    }
+  );
+};