branch_authority_status

Instructions

Implementation Reference

• src/mcp/tools/branchAuthority.ts:22-97 (handler)

  The registerBranchAuthorityTools function registers the 'branch_authority_status' MCP tool, which is the handler for querying constitutional branch authority, roster, and violations. It makes HTTP requests to the GIA Express API based on the action (status, roster, violations).

  export function registerBranchAuthorityTools(server: McpServer, engine: GovernanceEngine): void {
    server.tool(
      'branch_authority_status',
      'Colony Layer 4 — Separation of Powers. Query constitutional branch authority for users, view the full roster of authority holders, or inspect branch violations. Three branches: legislative (creates law), executive (executes law), judicial (interprets law).',
      {
        action: z.enum(['status', 'roster', 'violations']).describe(
          'Action: status = user\'s branches; roster = all holders; violations = violation log'
        ),
        user_id: z.string().optional().describe('User ID (required for status action)'),
        limit: z.number().min(1).max(200).optional().describe('Max results (default 50)'),
      },
      {
        title: 'Branch Authority (Separation of Powers)',
        readOnlyHint: true,
        idempotentHint: true,
        destructiveHint: false,
        openWorldHint: false,
      } as Record<string, unknown>,
      async (input) => {
        const apiBase = process.env.GIA_API_URL || 'http://localhost:3001';
        // GIA_INTERNAL_API_KEY = server-side name; GIA_API_KEY = MCP container name (same value)
        const apiKey = process.env.GIA_INTERNAL_API_KEY || process.env.GIA_API_KEY || '';
        const authHeaders = {
          'Authorization': `Bearer ${apiKey}`,
          'Content-Type': 'application/json',
        };
        let result: Record<string, unknown>;
  
        try {
          if (input.action === 'status') {
            if (!input.user_id) {
              result = { error: 'user_id required for status action' };
            } else {
              const resp = await fetch(`${apiBase}/api/branch/user/${encodeURIComponent(input.user_id)}`, { headers: authHeaders });
              if (!resp.ok) {
                const body = await resp.json() as Record<string, unknown>;
                result = { error: body.error || `HTTP ${resp.status}` };
              } else {
                result = await resp.json() as Record<string, unknown>;
              }
            }
          } else if (input.action === 'roster') {
            const resp = await fetch(`${apiBase}/api/branch/roster`, { headers: authHeaders });
            if (!resp.ok) {
              const body = await resp.json() as Record<string, unknown>;
              result = { error: body.error || `HTTP ${resp.status}` };
            } else {
              result = await resp.json() as Record<string, unknown>;
            }
          } else if (input.action === 'violations') {
            const limit = input.limit ?? 50;
            const resp = await fetch(`${apiBase}/api/branch/violations?limit=${limit}`, { headers: authHeaders });
            if (!resp.ok) {
              const body = await resp.json() as Record<string, unknown>;
              result = { error: body.error || `HTTP ${resp.status}` };
            } else {
              result = await resp.json() as Record<string, unknown>;
            }
          } else {
            result = { error: `Unknown action: ${input.action}` };
          }
        } catch (err: unknown) {
          result = {
            error: 'Failed to query branch authority — GIA Express API may be unreachable',
            detail: err instanceof Error ? err.message : String(err),
          };
        }
  
        // Telemetry
        engine.telemetryService.emitToolCall('branch_authority_status', `branch-${Date.now().toString(36)}`, 'INFORMATIONAL', true);
  
        return {
          content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
        };
      }
    );

• src/mcp/tools/branchAuthority.ts:26-32 (schema)

  Zod schema for the 'branch_authority_status' tool: action (enum: status, roster, violations), optional user_id, optional limit (1-200).

  {
    action: z.enum(['status', 'roster', 'violations']).describe(
      'Action: status = user\'s branches; roster = all holders; violations = violation log'
    ),
    user_id: z.string().optional().describe('User ID (required for status action)'),
    limit: z.number().min(1).max(200).optional().describe('Max results (default 50)'),
  },

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

  Registration entry in TOOL_REGISTRY for 'branch_authority_status' with tier 'tenant', linking to registerBranchAuthorityTools.

  { tier: 'tenant', register: registerBranchAuthorityTools, description: 'branch_authority_status (Colony Layer 4 — separation of powers)' },

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

  Import statement for the registerBranchAuthorityTools function from the branchAuthority module.

  import { registerBranchAuthorityTools } from './tools/branchAuthority.js';