@imboard.ai/mcp-server 0.1.0

package/src/tools/notifications.tools.ts

@@ -0,0 +1,47 @@
+import { resourceIdParam, formatResult, handleToolError, RegisterToolsFn } from './shared.js';
+
+export const registerNotificationTools: RegisterToolsFn = (server, client) => {
+  server.tool(
+    'list_notifications',
+    'Lists notifications for the authenticated user.',
+    {},
+    async () => {
+      try {
+        const response = await client.get('/api/notification/');
+        return formatResult({ data: response.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+
+  server.tool(
+    'mark_all_notifications_read',
+    'Marks all notifications as read.',
+    {},
+    async () => {
+      try {
+        const response = await client.put('/api/notification/read/all');
+        return formatResult({ data: response.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+
+  server.tool(
+    'mark_notification_read',
+    'Marks a single notification as read.',
+    {
+      notificationId: resourceIdParam.describe('The notification ID'),
+    },
+    async ({ notificationId }) => {
+      try {
+        const response = await client.put(`/api/notification/read/${notificationId}`);
+        return formatResult({ data: response.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+};

package/src/tools/reports.tools.ts

@@ -0,0 +1,414 @@
+import { z } from 'zod';
+import { boardIdParam, resourceIdParam, paginationParams, buildQueryParams, formatResult, handleToolError, RegisterToolsFn } from './shared.js';
+
+export const registerReportTools: RegisterToolsFn = (server, client) => {
+  server.tool(
+    'list_board_reports',
+    'Lists reports for a board. Supports filtering by status.',
+    {
+      boardId: boardIdParam,
+      ...paginationParams,
+      status: z.enum(['draft', 'publishedForReview', 'finalized', 'archived', 'ongoing']).optional()
+        .describe('Filter by report status'),
+    },
+    async ({ boardId, ...rest }) => {
+      try {
+        const params = buildQueryParams(rest, ['status']);
+        const result = await client.getCollection(
+          `/api/boards/${boardId}/reports`,
+          params,
+        );
+        return formatResult({ data: result.data, meta: result.meta });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+
+  server.tool(
+    'get_report',
+    'Returns details for a specific board report including title, status, and publication date.',
+    {
+      boardId: boardIdParam,
+      reportId: resourceIdParam.describe('The report ID'),
+    },
+    async ({ boardId, reportId }) => {
+      try {
+        const result = await client.get(
+          `/api/boards/${boardId}/reports/${reportId}`,
+        );
+        return formatResult({ data: result.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+
+  server.tool(
+    'create_report',
+    'Creates a new report for a board.',
+    {
+      boardId: boardIdParam,
+      name: z.string().describe('Report name'),
+      description: z.string().optional().describe('Report description'),
+      meetingIds: z.array(z.string()).optional().describe('Meeting IDs to associate with'),
+      periodStart: z.string().optional().describe('Period start date (YYYY-MM-DD)'),
+      periodEnd: z.string().optional().describe('Period end date (YYYY-MM-DD)'),
+    },
+    async ({ boardId, name, description, meetingIds, periodStart, periodEnd }) => {
+      try {
+        const body: Record<string, unknown> = { name };
+        if (description !== undefined) body.description = description;
+        if (meetingIds !== undefined) body.meetingIds = meetingIds;
+        if (periodStart !== undefined) body.periodStart = periodStart;
+        if (periodEnd !== undefined) body.periodEnd = periodEnd;
+        const result = await client.post(`/api/reports/${boardId}`, body);
+        return formatResult({ data: result.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+
+  server.tool(
+    'update_report',
+    'Updates report details (name, description, status, period dates).',
+    {
+      boardId: boardIdParam,
+      reportId: resourceIdParam.describe('The report ID'),
+      name: z.string().optional().describe('Report name'),
+      description: z.string().optional().describe('Report description'),
+      status: z.string().optional().describe('Report status'),
+      meetingIds: z.array(z.string()).optional().describe('Meeting IDs to associate with'),
+      periodStart: z.string().optional().describe('Period start date (YYYY-MM-DD)'),
+      periodEnd: z.string().optional().describe('Period end date (YYYY-MM-DD)'),
+    },
+    async ({ boardId, reportId, name, description, status, meetingIds, periodStart, periodEnd }) => {
+      try {
+        const body: Record<string, unknown> = {};
+        if (name !== undefined) body.name = name;
+        if (description !== undefined) body.description = description;
+        if (status !== undefined) body.status = status;
+        if (meetingIds !== undefined) body.meetingIds = meetingIds;
+        if (periodStart !== undefined) body.periodStart = periodStart;
+        if (periodEnd !== undefined) body.periodEnd = periodEnd;
+        const result = await client.put(`/api/reports/${boardId}/${reportId}`, body);
+        return formatResult({ data: result.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+
+  server.tool(
+    'promote_report_status',
+    'Promotes report status (draft -> review -> published).',
+    {
+      boardId: boardIdParam,
+      reportId: resourceIdParam.describe('The report ID'),
+      status: z.string().describe('Target status (e.g. publishedForReview, finalized)'),
+    },
+    async ({ boardId, reportId, status }) => {
+      try {
+        const result = await client.put(`/api/reports/${boardId}/${reportId}/promote`, { status });
+        return formatResult({ data: result.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+
+  server.tool(
+    'create_followup_report',
+    'Creates a follow-up report from an existing report, copying dashboards and settings.',
+    {
+      boardId: boardIdParam,
+      reportId: resourceIdParam.describe('The source report ID'),
+      name: z.string().describe('Name for the follow-up report'),
+      description: z.string().optional().describe('Report description'),
+      meetingIds: z.array(z.string()).optional().describe('Meeting IDs to associate with'),
+      periodStart: z.string().optional().describe('Period start date (YYYY-MM-DD)'),
+      periodEnd: z.string().optional().describe('Period end date (YYYY-MM-DD)'),
+    },
+    async ({ boardId, reportId, name, description, meetingIds, periodStart, periodEnd }) => {
+      try {
+        const body: Record<string, unknown> = { name };
+        if (description !== undefined) body.description = description;
+        if (meetingIds !== undefined) body.meetingIds = meetingIds;
+        if (periodStart !== undefined) body.periodStart = periodStart;
+        if (periodEnd !== undefined) body.periodEnd = periodEnd;
+        const result = await client.post(`/api/reports/${boardId}/${reportId}/followup`, body);
+        return formatResult({ data: result.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+
+  server.tool(
+    'create_dashboard',
+    'Creates a custom dashboard in a report.',
+    {
+      boardId: boardIdParam,
+      reportId: resourceIdParam.describe('The report ID'),
+      customName: z.string().describe('Dashboard name (1-100 characters)'),
+      displayOrder: z.number().optional().describe('Display order position'),
+    },
+    async ({ boardId, reportId, customName, displayOrder }) => {
+      try {
+        const body: Record<string, unknown> = { customName };
+        if (displayOrder !== undefined) body.displayOrder = displayOrder;
+        const result = await client.post(`/api/reports/${boardId}/${reportId}/dashboards`, body);
+        return formatResult({ data: result.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+
+  server.tool(
+    'create_dashboard_version',
+    'Creates a new version of a dashboard with updated content.',
+    {
+      boardId: boardIdParam,
+      reportId: resourceIdParam.describe('The report ID'),
+      dashboardId: resourceIdParam.describe('The dashboard ID'),
+      content: z.record(z.string(), z.unknown()).describe('Dashboard content object (must include _type field)'),
+      notes: z.array(z.string()).optional().describe('Version notes'),
+    },
+    async ({ boardId, reportId, dashboardId, content, notes }) => {
+      try {
+        const body: Record<string, unknown> = { content };
+        if (notes !== undefined) body.notes = notes;
+        const result = await client.post(
+          `/api/reports/${boardId}/${reportId}/dashboards/${dashboardId}/versions`,
+          body,
+        );
+        return formatResult({ data: result.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+
+  server.tool(
+    'update_dashboard_review_status',
+    'Updates the review status of a dashboard.',
+    {
+      boardId: boardIdParam,
+      reportId: resourceIdParam.describe('The report ID'),
+      dashboardId: resourceIdParam.describe('The dashboard ID'),
+      newStatus: z.string().describe('New review status'),
+    },
+    async ({ boardId, reportId, dashboardId, newStatus }) => {
+      try {
+        const result = await client.put(
+          `/api/reports/${boardId}/${reportId}/dashboards/${dashboardId}/review-status`,
+          { newStatus },
+        );
+        return formatResult({ data: result.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+
+  server.tool(
+    'get_dashboard_chat',
+    'Gets discussion comments on a dashboard.',
+    {
+      boardId: boardIdParam,
+      reportId: resourceIdParam.describe('The report ID'),
+      dashboardId: resourceIdParam.describe('The dashboard ID'),
+      chatType: z.enum(['internal', 'boardFeedback']).optional().describe('Chat type filter'),
+    },
+    async ({ boardId, reportId, dashboardId, chatType }) => {
+      try {
+        const params: Record<string, string> = {};
+        if (chatType !== undefined) params.chatType = chatType;
+        const result = await client.get(
+          `/api/reports/${boardId}/${reportId}/dashboards/${dashboardId}/chat`,
+          params,
+        );
+        return formatResult({ data: result.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+
+  server.tool(
+    'post_dashboard_chat',
+    'Posts a comment on a dashboard.',
+    {
+      boardId: boardIdParam,
+      reportId: resourceIdParam.describe('The report ID'),
+      dashboardId: resourceIdParam.describe('The dashboard ID'),
+      message: z.string().describe('Comment text (1-5000 characters)'),
+      chatType: z.enum(['internal', 'boardFeedback']).describe('Chat type: internal or boardFeedback'),
+      recipientId: z.string().optional().describe('Recipient user ID (for directed feedback)'),
+    },
+    async ({ boardId, reportId, dashboardId, message, chatType, recipientId }) => {
+      try {
+        const body: Record<string, unknown> = { message, chatType };
+        if (recipientId !== undefined) body.recipientId = recipientId;
+        const result = await client.post(
+          `/api/reports/${boardId}/${reportId}/dashboards/${dashboardId}/chat`,
+          body,
+        );
+        return formatResult({ data: result.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+
+  server.tool(
+    'get_board_feedback',
+    'Gets board-level feedback on a report.',
+    {
+      boardId: boardIdParam,
+      reportId: resourceIdParam.describe('The report ID'),
+      recipientId: z.string().optional().describe('Filter by recipient user ID'),
+    },
+    async ({ boardId, reportId, recipientId }) => {
+      try {
+        const params: Record<string, string> = {};
+        if (recipientId !== undefined) params.recipientId = recipientId;
+        const result = await client.get(
+          `/api/reports/${boardId}/${reportId}/board-feedback`,
+          params,
+        );
+        return formatResult({ data: result.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+
+  server.tool(
+    'post_board_feedback',
+    'Posts board-level feedback on a report.',
+    {
+      boardId: boardIdParam,
+      reportId: resourceIdParam.describe('The report ID'),
+      message: z.string().describe('Feedback text (1-5000 characters)'),
+      recipientId: resourceIdParam.describe('Recipient user ID'),
+    },
+    async ({ boardId, reportId, message, recipientId }) => {
+      try {
+        const result = await client.post(
+          `/api/reports/${boardId}/${reportId}/board-feedback`,
+          { message, recipientId },
+        );
+        return formatResult({ data: result.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+
+  server.tool(
+    'trigger_report_audit',
+    'Triggers an AI audit of a report.',
+    {
+      boardId: boardIdParam,
+      reportId: resourceIdParam.describe('The report ID'),
+      includeAiAnalysis: z.boolean().optional().describe('Include AI analysis (default: true)'),
+    },
+    async ({ boardId, reportId, includeAiAnalysis }) => {
+      try {
+        const body: Record<string, unknown> = {};
+        if (includeAiAnalysis !== undefined) body.includeAiAnalysis = includeAiAnalysis;
+        const result = await client.post(`/api/reports/${boardId}/${reportId}/audit`, body);
+        return formatResult({ data: result.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+
+  server.tool(
+    'list_report_audits',
+    'Lists audit history for a report.',
+    {
+      boardId: boardIdParam,
+      reportId: resourceIdParam.describe('The report ID'),
+    },
+    async ({ boardId, reportId }) => {
+      try {
+        const result = await client.get(`/api/reports/${boardId}/${reportId}/audits`);
+        return formatResult({ data: result.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+
+  server.tool(
+    'get_report_audit',
+    'Gets details of a specific report audit.',
+    {
+      boardId: boardIdParam,
+      reportId: resourceIdParam.describe('The report ID'),
+      auditId: resourceIdParam.describe('The audit ID'),
+    },
+    async ({ boardId, reportId, auditId }) => {
+      try {
+        const result = await client.get(`/api/reports/${boardId}/${reportId}/audits/${auditId}`);
+        return formatResult({ data: result.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+
+  server.tool(
+    'get_historical_metrics',
+    'Gets historical KPI data for a board. Supports filtering by period type, date range, and number of periods.',
+    {
+      boardId: boardIdParam,
+      periodType: z.enum(['monthly', 'quarterly', 'yearly']).optional().describe('Period type (default: monthly)'),
+      periods: z.number().int().min(1).max(48).optional().describe('Number of periods (1-48)'),
+      startDate: z.string().optional().describe('Start date (ISO 8601)'),
+      endDate: z.string().optional().describe('End date (ISO 8601)'),
+      includeDerived: z.boolean().optional().describe('Include derived metrics'),
+    },
+    async ({ boardId, periodType, periods, startDate, endDate, includeDerived }) => {
+      try {
+        const params: Record<string, string> = {};
+        if (periodType !== undefined) params.periodType = periodType;
+        if (periods !== undefined) params.periods = String(periods);
+        if (startDate !== undefined) params.startDate = startDate;
+        if (endDate !== undefined) params.endDate = endDate;
+        if (includeDerived !== undefined) params.includeDerived = String(includeDerived);
+        const result = await client.get(`/api/boards/${boardId}/historical-metrics`, params);
+        return formatResult({ data: result.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+
+  server.tool(
+    'get_metrics_comparison',
+    'Compares metrics across time periods for a board.',
+    {
+      boardId: boardIdParam,
+      metric: z.string().describe('Metric key to compare'),
+      basePeriod: z.string().describe('Base period (e.g. 2025-01)'),
+      comparisonPeriod: z.string().describe('Comparison period (e.g. 2025-02)'),
+      periodType: z.enum(['monthly', 'quarterly', 'yearly']).optional().describe('Period type'),
+    },
+    async ({ boardId, metric, basePeriod, comparisonPeriod, periodType }) => {
+      try {
+        const params: Record<string, string> = { metric, basePeriod, comparisonPeriod };
+        if (periodType !== undefined) params.periodType = periodType;
+        const result = await client.get(`/api/boards/${boardId}/metrics-comparison`, params);
+        return formatResult({ data: result.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+};

package/src/tools/shared.ts

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ImboardApiClient } from '../api-client/imboardApiClient.js';
+import { ImboardApiError, ImboardApiTimeoutError, ImboardApiNetworkError } from '../api-client/errors.js';
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { logger } from '../utils/logging.js';
+
+// --- Shared params & types ---
+
+/** Reusable Zod schema for MongoDB ObjectId path parameters — prevents path traversal. */
+const objectIdSchema = z.string().regex(/^[a-f0-9]{24}$/, 'Must be a 24-character hex ID');
+
+export const boardIdParam = objectIdSchema.describe('The board ID');
+export const resourceIdParam = objectIdSchema;
+
+export const paginationParams = {
+  limit: z.number().int().min(1).max(100).optional().describe('Number of results per page (1-100, default 25)'),
+  cursor: z.string().optional().describe('Pagination cursor from a previous response'),
+  sort: z.enum(['updatedAt']).optional().describe('Sort field (default: updatedAt)'),
+  order: z.enum(['asc', 'desc']).optional().describe('Sort order (default: desc)'),
+};
+
+export type RegisterToolsFn = (server: McpServer, client: ImboardApiClient) => void;
+
+export function buildQueryParams(
+  args: Record<string, unknown>,
+  filterKeys: string[],
+): Record<string, string> {
+  const params: Record<string, string> = {};
+
+  for (const key of ['limit', 'cursor', 'sort', 'order', ...filterKeys]) {
+    const value = args[key];
+    if (value !== undefined && value !== null) {
+      params[key] = String(value);
+    }
+  }
+
+  return params;
+}
+
+export function formatResult(data: unknown): CallToolResult {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+  };
+}
+
+// --- Unified error handling ---
+
+function errorResult(code: string, message: string, extra?: Record<string, unknown>): CallToolResult {
+  const payload: Record<string, unknown> = { error: code, message, ...extra };
+  return {
+    isError: true,
+    content: [{ type: 'text', text: JSON.stringify(payload) }],
+  };
+}
+
+export function handleToolError(error: unknown): CallToolResult {
+  if (error instanceof ImboardApiError) {
+    logger.warn(`API error: ${error.code} ${error.status}`, { requestId: error.requestId });
+    const message = error.status >= 500 ? 'Internal server error' : error.message;
+    const extra: Record<string, unknown> = { status: error.status };
+    if (error.requestId) extra.requestId = error.requestId;
+    if (error.details !== undefined && error.details !== null) extra.details = error.details;
+    return errorResult(error.code, message, extra);
+  }
+
+  if (error instanceof ImboardApiTimeoutError) {
+    logger.warn(`API timeout: ${error.message}`);
+    return errorResult('TIMEOUT', error.message);
+  }
+
+  if (error instanceof ImboardApiNetworkError) {
+    logger.warn(`Network error: ${error.message}`);
+    return errorResult('NETWORK_ERROR', error.message);
+  }
+
+  logger.error('Unexpected tool error', {
+    error: error instanceof Error ? error.message : String(error),
+    stack: error instanceof Error ? error.stack : undefined,
+  });
+  return errorResult('INTERNAL_ERROR', 'An unexpected error occurred');
+}

package/src/tools/slots.tools.ts

@@ -0,0 +1,115 @@
+import { z } from 'zod';
+import { boardIdParam, resourceIdParam, formatResult, handleToolError, RegisterToolsFn } from './shared.js';
+
+export const registerSlotTools: RegisterToolsFn = (server, client) => {
+  server.tool(
+    'list_meeting_slots',
+    'Lists proposed time slots with vote tallies for a meeting. Each slot has feedbacks showing how each member voted.',
+    {
+      boardId: boardIdParam,
+      meetingId: resourceIdParam.describe('The meeting ID'),
+    },
+    async ({ boardId, meetingId }) => {
+      try {
+        const result = await client.getCollection(
+          `/api/boards/${boardId}/meetings/${meetingId}/slots`,
+        );
+        return formatResult({ data: result.data, meta: result.meta });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+
+  server.tool(
+    'create_meeting_slot',
+    'Proposes a new time slot for a meeting. The creator is automatically marked as "ok". All other board members start as "didNotVote".',
+    {
+      boardId: boardIdParam,
+      meetingId: resourceIdParam.describe('The meeting ID'),
+      startTime: z.string().describe('Proposed start time as ISO-8601 UTC string (e.g. "2025-07-15T14:00:00.000Z")'),
+      timezone: z.string().describe('IANA timezone for display (e.g. "America/New_York")'),
+      durationInMinutes: z.number().int().min(15).max(180).optional().describe('Duration in minutes (15-180, default 120)'),
+    },
+    async ({ boardId, meetingId, startTime, timezone, durationInMinutes }) => {
+      try {
+        const body: Record<string, unknown> = { startTime, timezone };
+        if (durationInMinutes !== undefined) body.durationInMinutes = durationInMinutes;
+
+        const result = await client.post(
+          `/api/boards/${boardId}/meetings/${meetingId}/slots`,
+          body,
+        );
+        return formatResult({ data: result.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+
+  server.tool(
+    'vote_on_slot',
+    'Casts or updates the authenticated user\'s vote on a proposed meeting time slot.',
+    {
+      boardId: boardIdParam,
+      meetingId: resourceIdParam.describe('The meeting ID'),
+      slotId: resourceIdParam.describe('The proposed slot ID'),
+      vote: z.enum(['ok', 'challenging', 'cant']).describe('Vote: "ok" (can attend), "challenging" (maybe), "cant" (cannot attend)'),
+      comment: z.string().max(500).optional().describe('Optional comment explaining the vote'),
+    },
+    async ({ boardId, meetingId, slotId, vote, comment }) => {
+      try {
+        const body: Record<string, unknown> = { vote };
+        if (comment !== undefined) body.comment = comment;
+
+        const result = await client.put(
+          `/api/boards/${boardId}/meetings/${meetingId}/slots/${slotId}/vote`,
+          body,
+        );
+        return formatResult({ data: result.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+
+  server.tool(
+    'delete_meeting_slot',
+    'Removes a proposed time slot from a meeting.',
+    {
+      boardId: boardIdParam,
+      meetingId: resourceIdParam.describe('The meeting ID'),
+      slotId: resourceIdParam.describe('The proposed slot ID'),
+    },
+    async ({ boardId, meetingId, slotId }) => {
+      try {
+        const result = await client.delete(
+          `/api/boards/${boardId}/meetings/${meetingId}/slots/${slotId}`,
+        );
+        return formatResult({ data: result.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+
+  server.tool(
+    'confirm_meeting_slot',
+    'Confirms a proposed slot as the meeting\'s scheduled time. Copies the slot\'s start time, duration, and timezone to the meeting.',
+    {
+      boardId: boardIdParam,
+      meetingId: resourceIdParam.describe('The meeting ID'),
+      slotId: resourceIdParam.describe('The proposed slot ID to confirm'),
+    },
+    async ({ boardId, meetingId, slotId }) => {
+      try {
+        const result = await client.post(
+          `/api/boards/${boardId}/meetings/${meetingId}/slots/${slotId}/confirm`,
+        );
+        return formatResult({ data: result.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+};