board_list_institutions

Instructions

Implementation Reference

• src/mcp/tools/institution.ts:114-144 (handler)

  The handler for board_list_institutions tool. Calls GET /api/institution, maps results, returns list of institutions with IDs needed for further board operations.

  server.tool(
    'board_list_institutions',
    'List all institutions in the GIA Governed Organizational Architecture. Each institution is a governed body (e.g. Architecture Review Board, Federal AI Board) with its own charter hierarchy. Returns institution IDs needed to convene sessions.',
    {},
    { title: 'List Institutions', readOnlyHint: true, idempotentHint: true, destructiveHint: false, openWorldHint: false },
    async () => {
      try {
        const data = await apiCall('/api/institution', 'GET') as any;
        const institutions = (data.institutions || data || []) as any[];
  
        return {
          content: [{ type: 'text' as const, text: JSON.stringify({
            count: institutions.length,
            institutions: institutions.map((i: any) => ({
              institution_id:       i.institution_id,
              name:                 i.name,
              description:          i.description,
              status:               i.status,
              compliance_frameworks: i.compliance_frameworks,
              created_at:           i.created_at,
            })),
            next_step: institutions.length > 0
              ? `Call board_list_charters with institution_id from above to see committees`
              : `Call board_install_kit to install a prebuilt institution template`,
          }, null, 2) }],
        };
      } catch (err: unknown) {
        return boardErrorResponse(err);
      }
    }
  );

• src/mcp/tools/institution.ts:117-117 (schema)

  Input schema for board_list_institutions — empty object (no parameters needed).

  {},

• src/mcp/tools/institution.ts:109-144 (registration)

  Registration of board_list_institutions via server.tool() call, along with all other board tools.

  export function registerInstitutionTools(server: McpServer): void {
  
    // =========================================================================
    // board_list_institutions — list all governed institutions
    // =========================================================================
    server.tool(
      'board_list_institutions',
      'List all institutions in the GIA Governed Organizational Architecture. Each institution is a governed body (e.g. Architecture Review Board, Federal AI Board) with its own charter hierarchy. Returns institution IDs needed to convene sessions.',
      {},
      { title: 'List Institutions', readOnlyHint: true, idempotentHint: true, destructiveHint: false, openWorldHint: false },
      async () => {
        try {
          const data = await apiCall('/api/institution', 'GET') as any;
          const institutions = (data.institutions || data || []) as any[];
  
          return {
            content: [{ type: 'text' as const, text: JSON.stringify({
              count: institutions.length,
              institutions: institutions.map((i: any) => ({
                institution_id:       i.institution_id,
                name:                 i.name,
                description:          i.description,
                status:               i.status,
                compliance_frameworks: i.compliance_frameworks,
                created_at:           i.created_at,
              })),
              next_step: institutions.length > 0
                ? `Call board_list_charters with institution_id from above to see committees`
                : `Call board_install_kit to install a prebuilt institution template`,
            }, null, 2) }],
          };
        } catch (err: unknown) {
          return boardErrorResponse(err);
        }
      }
    );

• src/mcp/server.ts:109-109 (registration)

  Registration entry point — registerInstitutionTools is called as a TENANT-tier tool from the MCP server's TOOL_REGISTRY.

  { tier: 'tenant', register: (server, _engine) => registerInstitutionTools(server), description: 'board (list_institutions, list_charters, convene_session, get_session, install_kit)' },

• src/mcp/tools/institution.ts:54-90 (helper)

  apiCall helper used by the handler to make HTTP requests to the GIA Express API backend.

  async function apiCall(path: string, method: string, body?: unknown): Promise<unknown> {
    const headers: Record<string, string> = { 'Content-Type': 'application/json' };
    if (API_KEY) headers['Authorization'] = `Bearer ${API_KEY}`;
  
    let res: Response;
    try {
      res = await fetch(`${API_BASE}${path}`, {
        method,
        headers,
        body: body ? JSON.stringify(body) : undefined,
      });
    } catch (err: unknown) {
      // Network-level failure: server down, DNS fail, connection refused
      const msg = err instanceof Error ? err.message : 'Unknown network error';
      const envDiag = [
        `GIA_API_URL: ${process.env.GIA_API_URL ? 'set' : 'NOT SET (using default: http://localhost:3001)'}`,
        `GIA_API_KEY: ${process.env.GIA_API_KEY ? 'set' : 'NOT SET'}`,
        `GIA_SERVER_URL: ${process.env.GIA_SERVER_URL ? 'set' : 'NOT SET'}`,
      ].join(', ');
      throw new BoardApiError(
        null, path,
        `Board API unavailable at ${API_BASE}. Check that the Express server is running. Env: ${envDiag}. (${msg})`,
        `API ${method} ${path} → network error: ${msg}`,
      );
    }
  
    if (!res.ok) {
      const errText = await res.text().catch(() => 'Unknown error');
      throw new BoardApiError(
        res.status, path,
        `Board API returned ${res.status} for ${method} ${path}. ${res.status === 503 ? 'Server may be restarting — retry in 30 seconds.' : errText.slice(0, 200)}`,
        `API ${method} ${path} → ${res.status}: ${errText.slice(0, 300)}`,
      );
    }
  
    return res.json();
  }