list_boards

Instructions

Implementation Reference

• src/tools/boards.ts:18-24 (handler)

  The listBoards function: the actual handler that calls capsuleGet('/boards') to fetch paginated board data and returns it with a nextPage cursor.

  export async function listBoards(input: z.infer<typeof listBoardsSchema>) {
    const { data, nextPage } = await capsuleGet<{ boards: unknown[] }>("/boards", {
      page: input.page ?? 1,
      perPage: input.perPage ?? 100,
    });
    return { ...data, nextPage };
  }

• src/tools/boards.ts:16-16 (schema)

  listBoardsSchema: Zod schema defining the input — optional page and perPage pagination fields.

  export const listBoardsSchema = z.object({ ...paginationFields });

• src/server.ts:860-866 (registration)

  Tool registration for 'list_boards' in src/server.ts, calling registerTool with name, description, schema, and handler.

  registerTool(
    server,
    "list_boards",
    "List all project (case) boards defined in Capsule. A board is a grouping of stages that projects flow through — the project equivalent of an opportunity pipeline. Returns each board's id, name, and stages. Use this to discover boardId when creating a project, then pick a starting stage via list_stages. Like pipelines, boards are stable per account.",
    listBoardsSchema,
    listBoards,
  );

• src/server/register-tool.ts:39-59 (helper)

  registerTool helper function that wraps handler return values in MCP's text content response format.

  export function registerTool<Schema extends z.ZodObject<ZodRawShape>>(
    server: McpServer,
    name: string,
    description: string,
    schema: Schema,
    handler: (input: z.infer<Schema>) => Promise<unknown>,
  ): void {
    // Use the SDK config-form registerTool with the full Zod schema. The
    // deprecated shape overload rebuilds z.object(schema.shape), which drops
    // object-level refinements such as superRefine.
    const registerWithSchema = server.registerTool.bind(server) as (
      toolName: string,
      config: { description: string; inputSchema: Schema },
      callback: (input: z.infer<Schema>) => Promise<CallToolResult>,
    ) => void;
  
    registerWithSchema(name, { description, inputSchema: schema }, async (input) => {
      const result = await handler(input);
      return wrapAsText(result);
    });
  }

• src/capsule/client.ts:344-355 (helper)

  capsuleGet: the generic HTTP GET helper used by listBoards to call the Capsule CRM API with pagination.

  export async function capsuleGet<T>(path: string, params?: QueryParams): Promise<PagedResult<T>> {
    const token = getToken();
    const url = buildUrl(path, params);
    const { res, cleanup } = await doFetch(url, { headers: baseHeaders(token) });
    try {
      const data = await handleResponse<T>(res);
      const nextPage = parseNextPage(res.headers.get("Link"));
      return { data, nextPage };
    } finally {
      cleanup();
    }
  }