chain_of_reasoning

Instructions

Implementation Reference

• src/mcp/tools/chain-of-reasoning.ts:55-137 (handler)

  The handler function executed when the chain_of_reasoning tool is called. It constructs API URLs based on scope (session/agent/time_range) and format (summary/full/dag/export), fetches data from the Chain of Reasoning backend API, and returns the results with error handling.

    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 || '';
  
      try {
        let url: string;
        const params = new URLSearchParams();
  
        if (input.scope === 'session') {
          if (!input.session_id) {
            return { content: [{ type: 'text' as const, text: JSON.stringify({ error: 'session_id required when scope = "session"' }) }] };
          }
  
          if (input.format === 'dag') {
            url = `${apiBase}/api/chain-of-reasoning/session/${input.session_id}/dag`;
          } else if (input.format === 'export') {
            url = `${apiBase}/api/chain-of-reasoning/session/${input.session_id}/export`;
          } else {
            url = `${apiBase}/api/chain-of-reasoning/session/${input.session_id}`;
          }
        } else if (input.scope === 'agent') {
          if (!input.agent_id) {
            return { content: [{ type: 'text' as const, text: JSON.stringify({ error: 'agent_id required when scope = "agent"' }) }] };
          }
          url = `${apiBase}/api/chain-of-reasoning/agent/${encodeURIComponent(input.agent_id)}`;
          if (input.start) params.set('start', input.start);
          if (input.end) params.set('end', input.end);
          if (input.limit) params.set('limit', String(input.limit));
        } else {
          url = `${apiBase}/api/chain-of-reasoning/time-range`;
          if (input.start) params.set('start', input.start);
          if (input.end) params.set('end', input.end);
          if (input.limit) params.set('limit', String(input.limit));
        }
  
        const queryString = params.toString();
        const fullUrl = queryString ? `${url}?${queryString}` : url;
  
        const resp = await fetch(fullUrl, {
          headers: {
            'Authorization': `Bearer ${apiKey}`,
            'Content-Type': 'application/json',
          },
        });
  
        if (!resp.ok) {
          const body = await resp.text();
          return {
            content: [{ type: 'text' as const, text: JSON.stringify({
              error: `Chain of Reasoning query failed (HTTP ${resp.status})`,
              detail: body,
            }) }],
          };
        }
  
        const data = await resp.json() as Record<string, unknown>;
  
        // For summary format, strip the full links array to reduce token usage
        if (input.format === 'summary' && data.links) {
          const links = data.links as Array<Record<string, unknown>>;
          data.linksPreview = links.slice(0, 5).map(l => ({
            operation: l.operation,
            timestamp: l.timestamp,
            actor: l.actor,
            maiLevel: l.maiLevel,
          }));
          delete data.links;
        }
  
        return {
          content: [{ type: 'text' as const, text: JSON.stringify(data, null, 2) }],
        };
      } catch (err: unknown) {
        return {
          content: [{ type: 'text' as const, text: JSON.stringify({
            error: 'Chain of Reasoning query failed',
            detail: (err as Error).message,
          }) }],
        };
      }
    },
  );

• src/mcp/tools/chain-of-reasoning.ts:25-47 (schema)

  Zod schema defining the tool's input parameters: scope (session/agent/time_range), session_id, agent_id, start, end, format (summary/full/dag/export), and limit. Also includes metadata hints (readOnly, idempotent).

  {
    scope: z.enum(['session', 'agent', 'time_range']).describe(
      'What to query: "session" for a specific committee session, "agent" for an agent over time, "time_range" for all activity in a period.'
    ),
    session_id: z.string().optional().describe(
      'Committee session ID (required when scope = "session"). Format: cs-{uuid}'
    ),
    agent_id: z.string().optional().describe(
      'Agent ID (required when scope = "agent"). Can be a user ID or model name.'
    ),
    start: z.string().optional().describe(
      'Start of time range (ISO 8601). Default: 7 days ago.'
    ),
    end: z.string().optional().describe(
      'End of time range (ISO 8601). Default: now.'
    ),
    format: z.enum(['summary', 'full', 'dag', 'export']).default('summary').describe(
      'Response format: "summary" = stats only, "full" = all links, "dag" = causal graph with edges, "export" = EU AI Act compliance artifact.'
    ),
    limit: z.number().int().min(1).max(500).optional().describe(
      'Maximum number of links to return (default: 100, max: 500). Only applies to "full" format.'
    ),
  },

• src/mcp/tools/chain-of-reasoning.ts:21-23 (registration)

  The registerChainOfReasoningTools function that registers the tool with the MCP server via server.tool('chain_of_reasoning', ...).

  export function registerChainOfReasoningTools(server: McpServer, _engine: GovernanceEngine): void {
    server.tool(
      'chain_of_reasoning',

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

  Registration entry in the TOOL_REGISTRY array that maps chain_of_reasoning to the 'tenant' visibility tier, meaning it's accessible to paying customers but not public.

  { tier: 'tenant', register: registerChainOfReasoningTools, description: 'chain_of_reasoning (Governed Cognition provenance trail)' },