@imboard.ai/mcp-server 0.1.0

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@imboard.ai/mcp-server",
+  "version": "0.1.0",
+  "description": "imboard MCP server — adapter over the public REST API",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "main": "./dist/index.cjs",
+  "bin": {
+    "imboard-mcp-server": "./dist/index.cjs"
+  },
+  "exports": {
+    ".": "./dist/index.cjs",
+    "./api-client": {
+      "import": "./src/api-client/imboardApiClient.ts",
+      "default": "./src/api-client/imboardApiClient.ts"
+    },
+    "./config": {
+      "import": "./src/config.ts",
+      "default": "./src/config.ts"
+    },
+    "./errors": {
+      "import": "./src/api-client/errors.ts",
+      "default": "./src/api-client/errors.ts"
+    }
+  },
+  "files": [
+    "dist/**/*.cjs",
+    "src/**/*.ts",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "imboard",
+    "ai",
+    "claude",
+    "board-management"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/imboard-ai/imboard-monorepo.git",
+    "directory": "main/packages/mcp-server"
+  },
+  "homepage": "https://github.com/imboard-ai/imboard-monorepo/tree/main/main/packages/mcp-server#readme",
+  "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/jest": "^0.2.39",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.5.0",
+    "cross-env": "^10.1.0",
+    "esbuild": "^0.27.2",
+    "eslint": "^9.39.2",
+    "jest": "^30.3.0",
+    "prettier": "^3.8.1",
+    "tsx": "^4.11.2",
+    "typescript": "^5.8.2"
+  }
+}

package/src/api-client/errors.ts

@@ -0,0 +1,42 @@
+/**
+ * Error types for the imboard API client.
+ * Maps the /api error envelope into a typed exception.
+ */
+
+export interface ApiErrorPayload {
+  code: string;
+  message: string;
+  status: number;
+  requestId: string | null;
+  details: unknown;
+}
+
+export class ImboardApiError extends Error {
+  readonly code: string;
+  readonly status: number;
+  readonly requestId: string | null;
+  readonly details: unknown;
+
+  constructor(payload: ApiErrorPayload) {
+    super(payload.message);
+    this.name = 'ImboardApiError';
+    this.code = payload.code;
+    this.status = payload.status;
+    this.requestId = payload.requestId;
+    this.details = payload.details;
+  }
+}
+
+export class ImboardApiTimeoutError extends Error {
+  constructor(timeoutMs: number) {
+    super(`Request timed out after ${timeoutMs}ms`);
+    this.name = 'ImboardApiTimeoutError';
+  }
+}
+
+export class ImboardApiNetworkError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ImboardApiNetworkError';
+  }
+}

package/src/api-client/imboardApiClient.ts

@@ -0,0 +1,256 @@
+/**
+ * Authenticated HTTP client for calling the imboard /api endpoints.
+ *
+ * Uses Node.js built-in fetch. All MCP tools call through this client —
+ * it handles auth, timeout, retry (GET only), and response normalization.
+ */
+
+import { McpConfig } from '../config.js';
+import { logger } from '../utils/logging.js';
+import { ImboardApiError, ImboardApiTimeoutError, ImboardApiNetworkError } from './errors.js';
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_RETRIES = 2;
+const RETRY_BASE_MS = 500;
+
+export interface ApiSuccessResponse<T> {
+  data: T;
+  requestId: string | null;
+}
+
+export interface ApiCollectionMeta {
+  nextCursor: string | null;
+  hasMore: boolean;
+}
+
+export interface ApiCollectionResponse<T> {
+  data: T[];
+  meta: ApiCollectionMeta;
+  requestId: string | null;
+}
+
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+export class ImboardApiClient {
+  private readonly baseUrl: string;
+  private readonly token: string;
+  private readonly timeoutMs: number;
+
+  constructor(config: McpConfig, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    this.baseUrl = config.apiBaseUrl.replace(/\/+$/, '');
+    this.token = config.apiToken;
+    this.timeoutMs = timeoutMs;
+  }
+
+  async get<T>(path: string, params?: Record<string, string>): Promise<ApiSuccessResponse<T>> {
+    return this.request<T>('GET', path, undefined, params);
+  }
+
+  async getCollection<T>(path: string, params?: Record<string, string>): Promise<ApiCollectionResponse<T>> {
+    return this.requestCollection<T>('GET', path, params);
+  }
+
+  async post<T>(path: string, body?: unknown): Promise<ApiSuccessResponse<T>> {
+    return this.request<T>('POST', path, body);
+  }
+
+  async put<T>(path: string, body?: unknown): Promise<ApiSuccessResponse<T>> {
+    return this.request<T>('PUT', path, body);
+  }
+
+  async patch<T>(path: string, body?: unknown): Promise<ApiSuccessResponse<T>> {
+    return this.request<T>('PATCH', path, body);
+  }
+
+  async delete<T>(path: string): Promise<ApiSuccessResponse<T>> {
+    return this.request<T>('DELETE', path);
+  }
+
+  private async request<T>(
+    method: HttpMethod,
+    path: string,
+    body?: unknown,
+    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>;
+
+    if (!json || typeof json !== 'object' || !('data' in json)) {
+      throw new ImboardApiError({
+        code: 'INTERNAL_ERROR',
+        message: 'Response body missing "data" field',
+        status: response.status,
+        requestId,
+        details: null,
+      });
+    }
+
+    return {
+      data: json.data as T,
+      requestId,
+    };
+  }
+
+  private async requestCollection<T>(
+    method: HttpMethod,
+    path: 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>;
+
+    if (!json || typeof json !== 'object' || !('data' in json) || !('meta' in json)) {
+      throw new ImboardApiError({
+        code: 'INTERNAL_ERROR',
+        message: 'Response body missing "data" or "meta" field',
+        status: response.status,
+        requestId,
+        details: null,
+      });
+    }
+
+    return {
+      data: json.data as T[],
+      meta: json.meta as ApiCollectionMeta,
+      requestId,
+    };
+  }
+
+  private async executeWithRetry(
+    method: HttpMethod,
+    path: string,
+    body?: unknown,
+    params?: Record<string, string>,
+  ): Promise<Response> {
+    const url = this.buildUrl(path, params);
+    // Conservative: only retry GET. PUT/DELETE are technically idempotent
+    // but we avoid retrying writes to prevent confusing side effects.
+    const isIdempotent = method === 'GET';
+    const maxAttempts = isIdempotent ? MAX_RETRIES + 1 : 1;
+
+    let lastError: Error | undefined;
+
+    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 });
+        await sleep(delayMs);
+      }
+
+      try {
+        const response = await this.executeSingle(method, url, body);
+
+        if (response.ok) {
+          return response;
+        }
+
+        // Parse error envelope
+        const errorBody = await this.tryParseErrorBody(response);
+        const requestId = response.headers.get('x-request-id');
+
+        const apiError = new ImboardApiError({
+          code: errorBody?.code ?? 'INTERNAL_ERROR',
+          message: errorBody?.message ?? `HTTP ${response.status}`,
+          status: response.status,
+          requestId,
+          details: errorBody?.details ?? null,
+        });
+
+        // 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 });
+          lastError = apiError;
+          continue;
+        }
+
+        throw apiError;
+      } catch (error) {
+        if (error instanceof ImboardApiError) {
+          throw error;
+        }
+
+        if (error instanceof ImboardApiTimeoutError || error instanceof ImboardApiNetworkError) {
+          if (isIdempotent && attempt < maxAttempts - 1) {
+            lastError = error;
+            continue;
+          }
+          throw error;
+        }
+
+        // Unexpected error
+        throw new ImboardApiNetworkError(
+          error instanceof Error ? error.message : 'Unknown network error'
+        );
+      }
+    }
+
+    // All retries exhausted
+    throw lastError ?? new ImboardApiNetworkError('All retries exhausted');
+  }
+
+  private async executeSingle(method: HttpMethod, url: string, body?: unknown): Promise<Response> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    const headers: Record<string, string> = {
+      'Authorization': `Bearer ${this.token}`,
+      'Accept': 'application/json',
+    };
+
+    if (body !== undefined) {
+      headers['Content-Type'] = 'application/json';
+    }
+
+    try {
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      });
+      return response;
+    } catch (error) {
+      if (error instanceof DOMException && error.name === 'AbortError') {
+        throw new ImboardApiTimeoutError(this.timeoutMs);
+      }
+      throw new ImboardApiNetworkError(
+        error instanceof Error ? error.message : 'Network request failed'
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  private buildUrl(path: string, params?: Record<string, string>): string {
+    const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+    const url = new URL(`${this.baseUrl}${normalizedPath}`);
+
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        url.searchParams.set(key, value);
+      }
+    }
+
+    return url.toString();
+  }
+
+  private async tryParseErrorBody(
+    response: Response
+  ): Promise<{ code: string; message: string; details: unknown } | undefined> {
+    try {
+      const text = await response.text();
+      const json = JSON.parse(text) as {
+        error?: { code: string; message: string; details: unknown };
+      };
+      return json.error;
+    } catch {
+      return undefined;
+    }
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/config.ts

@@ -0,0 +1,62 @@
+export interface McpConfig {
+  apiBaseUrl: string;
+  apiToken: string;
+}
+
+export class ConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ConfigError';
+  }
+}
+
+export function loadConfig(): McpConfig {
+  const errors: string[] = [];
+
+  const apiBaseUrl = process.env.IMBOARD_API_BASE_URL?.trim();
+  const apiToken = process.env.IMBOARD_API_TOKEN?.trim();
+
+  if (!apiBaseUrl) {
+    errors.push('IMBOARD_API_BASE_URL is required');
+  }
+
+  if (!apiToken) {
+    errors.push('IMBOARD_API_TOKEN is required');
+  }
+
+  if (apiBaseUrl && !isValidUrl(apiBaseUrl)) {
+    errors.push(`IMBOARD_API_BASE_URL is not a valid URL: ${apiBaseUrl}`);
+  }
+
+  if (apiBaseUrl && isValidUrl(apiBaseUrl) && isPrivateAddress(apiBaseUrl)) {
+    errors.push('IMBOARD_API_BASE_URL must not point to a private/internal address');
+  }
+
+  if (errors.length > 0) {
+    throw new ConfigError(
+      `Configuration errors:\n  - ${errors.join('\n  - ')}`
+    );
+  }
+
+  return {
+    apiBaseUrl: apiBaseUrl!,
+    apiToken: apiToken!,
+  };
+}
+
+function isValidUrl(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return url.protocol === 'http:' || url.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+const PRIVATE_HOSTNAMES = ['localhost', '127.0.0.1', '0.0.0.0', '169.254.169.254', '[::1]'];
+const PRIVATE_IP_PATTERN = /^(10\.|172\.(1[6-9]|2\d|3[01])\.|192\.168\.)/;
+
+function isPrivateAddress(value: string): boolean {
+  const { hostname } = new URL(value);
+  return PRIVATE_HOSTNAMES.includes(hostname) || PRIVATE_IP_PATTERN.test(hostname);
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { loadConfig, ConfigError } from './config.js';
+import { createServer } from './server.js';
+import { logger, setLogLevel } from './utils/logging.js';
+
+async function main(): Promise<void> {
+  if (process.env.LOG_LEVEL) {
+    setLogLevel(process.env.LOG_LEVEL as 'debug' | 'info' | 'warn' | 'error');
+  }
+
+  logger.info('Starting imboard MCP server...');
+
+  const config = loadConfig();
+  logger.info('Configuration loaded', { apiBaseUrl: config.apiBaseUrl });
+
+  const server = createServer(config);
+  const transport = new StdioServerTransport();
+
+  await server.connect(transport);
+  logger.info('MCP server connected via stdio transport');
+}
+
+main().catch((err: unknown) => {
+  if (err instanceof ConfigError) {
+    logger.error(err.message);
+    process.exit(1);
+  }
+  logger.error('Fatal error during startup', {
+    error: err instanceof Error ? err.message : String(err),
+  });
+  process.exit(1);
+});

package/src/resources/docs.resources.ts

@@ -0,0 +1,97 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { logger } from '../utils/logging.js';
+
+const DOCS_BASE_URL = 'https://docs.imboard.ai';
+
+interface DocResource {
+  uri: string;
+  name: string;
+  description: string;
+  mimeType: string;
+}
+
+const STATIC_RESOURCES: DocResource[] = [
+  {
+    uri: `${DOCS_BASE_URL}/openapi.json`,
+    name: 'OpenAPI Specification',
+    description:
+      'Complete OpenAPI 3.1 spec for the imboard REST API — all endpoints, schemas, and examples',
+    mimeType: 'application/json',
+  },
+  {
+    uri: `${DOCS_BASE_URL}/llms.txt`,
+    name: 'LLMs.txt Index',
+    description:
+      'Structured index of all documentation pages — optimized for LLM consumption',
+    mimeType: 'text/plain',
+  },
+  {
+    uri: `${DOCS_BASE_URL}/llms-full.txt`,
+    name: 'Full Documentation (LLM)',
+    description:
+      'Complete documentation content in a single text file — all guides, references, and examples',
+    mimeType: 'text/plain',
+  },
+  {
+    uri: `${DOCS_BASE_URL}/api/schemas`,
+    name: 'Schema Index',
+    description:
+      'JSON index of all resource schemas (board, meeting, document, report, dashboard)',
+    mimeType: 'application/json',
+  },
+  {
+    uri: `${DOCS_BASE_URL}/api/recipes`,
+    name: 'Recipe Index',
+    description:
+      'JSON index of available dossier recipes (financial-update, sales-pipeline-update)',
+    mimeType: 'application/json',
+  },
+];
+
+export function registerDocsResources(server: McpServer): void {
+  for (const resource of STATIC_RESOURCES) {
+    server.resource(resource.name, resource.uri, {
+      description: resource.description,
+      mimeType: resource.mimeType,
+    }, async () => {
+      try {
+        const response = await fetch(resource.uri);
+        if (!response.ok) {
+          return {
+            contents: [
+              {
+                uri: resource.uri,
+                mimeType: 'text/plain',
+                text: `Failed to fetch ${resource.uri}: ${response.status} ${response.statusText}`,
+              },
+            ],
+          };
+        }
+
+        const text = await response.text();
+        return {
+          contents: [
+            {
+              uri: resource.uri,
+              mimeType: resource.mimeType,
+              text,
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          contents: [
+            {
+              uri: resource.uri,
+              mimeType: 'text/plain',
+              text: `Error fetching ${resource.uri}: ${message}`,
+            },
+          ],
+        };
+      }
+    });
+  }
+
+  logger.info(`Registered ${STATIC_RESOURCES.length} docs resources`);
+}

package/src/server.ts

@@ -0,0 +1,54 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpConfig } from './config.js';
+import { ImboardApiClient } from './api-client/imboardApiClient.js';
+import { registerGetMeTool } from './tools/getMe.tool.js';
+import { registerBoardsTools } from './tools/boards.tools.js';
+import { registerMemberTools } from './tools/members.tools.js';
+import { registerMeetingTools } from './tools/meetings.tools.js';
+import { logger } from './utils/logging.js';
+import { registerDocumentTools } from './tools/documents.tools.js';
+import { registerDocumentWriteTools } from './tools/documents-write.tools.js';
+import { registerReportTools } from './tools/reports.tools.js';
+import { registerDashboardTools } from './tools/dashboards.tools.js';
+import { registerSlotTools } from './tools/slots.tools.js';
+import { registerInviteTools } from './tools/invites.tools.js';
+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 { registerDocsResources } from './resources/docs.resources.js';
+
+const SERVER_NAME = 'imboard-mcp-server';
+const SERVER_VERSION = '0.1.0';
+
+export function createServer(config: McpConfig): McpServer {
+  logger.info(`Creating ${SERVER_NAME} v${SERVER_VERSION}`);
+
+  const server = new McpServer({
+    name: SERVER_NAME,
+    version: SERVER_VERSION,
+  });
+
+  const api = new ImboardApiClient(config);
+
+  registerGetMeTool(server, api);
+  registerBoardsTools(server, api);
+  registerMemberTools(server, api);
+  registerMeetingTools(server, api);
+  registerDocumentTools(server, api);
+  registerDocumentWriteTools(server, api);
+  registerReportTools(server, api);
+  registerDashboardTools(server, api);
+  registerSlotTools(server, api);
+  registerInviteTools(server, api);
+  registerNotificationTools(server, api);
+  registerActionItemTools(server, api);
+  registerUserTools(server, api);
+  registerSupportingTools(server, api);
+
+  registerDocsResources(server);
+
+  logger.info('All tools and resources registered');
+
+  return server;
+}

package/src/tools/action-items.tools.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import { resourceIdParam, formatResult, handleToolError, RegisterToolsFn } from './shared.js';
+
+export const registerActionItemTools: RegisterToolsFn = (server, client) => {
+  server.tool(
+    'list_my_action_items',
+    'Lists action items assigned to the authenticated user across all boards.',
+    {
+      includeCompleted: z.enum(['true', 'false']).optional().describe('Include completed items (default: false)'),
+      status: z.string().optional().describe('Filter by status (open, in_progress, completed, cancelled)'),
+    },
+    async ({ includeCompleted, status }) => {
+      try {
+        const params: Record<string, string> = {};
+        if (includeCompleted !== undefined) params.includeCompleted = includeCompleted;
+        if (status !== undefined) params.status = status;
+        const response = await client.get('/api/action-items/my', params);
+        return formatResult({ data: response.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+
+  server.tool(
+    'update_action_item_status',
+    'Updates an action item status (in_progress, completed, cancelled).',
+    {
+      actionItemId: resourceIdParam.describe('The action item ID'),
+      status: z.string().describe('New status (open, in_progress, completed, cancelled)'),
+    },
+    async ({ actionItemId, status }) => {
+      try {
+        const response = await client.patch(`/api/action-items/${actionItemId}/status`, { status });
+        return formatResult({ data: response.data });
+      } catch (error) {
+        return handleToolError(error);
+      }
+    },
+  );
+};