Councly MCP Server

Instructions

Implementation Reference

• src/index.ts:182-194 (handler)

  Handler for the councly_status tool: parses the input using counclyStatusSchema, fetches the hearing status via CounclyClient.getHearingStatus(hearing_id), formats the result with formatHearingResult, and returns it as MCP text content.

  case 'councly_status': {
    const parsed = counclyStatusSchema.parse(args);
    const status = await client.getHearingStatus(parsed.hearing_id);
  
    return {
      content: [
        {
          type: 'text',
          text: formatHearingResult(status),
        },
      ],
    };
  }

• src/tools.ts:30-35 (schema)

  Zod schema definition for councly_status tool input validation, requiring a UUID hearing_id. Includes TypeScript type inference.

  export const counclyStatusSchema = z.object({
    hearing_id: z.string().uuid().describe('The hearing ID returned from councly_hearing'),
  });
  
  export type CounclyHearingInput = z.infer<typeof counclyHearingSchema>;
  export type CounclyStatusInput = z.infer<typeof counclyStatusSchema>;

• src/tools.ts:91-112 (registration)

  MCP tool registration/definition for councly_status, including name, description, and inputSchema used in listTools response.

    {
      name: 'councly_status',
      description: `Check the status of a council hearing.
  
  Returns:
  - For in-progress hearings: current phase and progress percentage
  - For completed hearings: verdict, trust score, and counsel summaries
  - For failed hearings: error message
  
  Use this to check on hearings created with wait=false, or to retrieve past hearing results.`,
      inputSchema: {
        type: 'object',
        properties: {
          hearing_id: {
            type: 'string',
            format: 'uuid',
            description: 'The hearing ID to check',
          },
        },
        required: ['hearing_id'],
      },
    },

• src/index.ts:52-107 (helper)

  Helper function to format hearing status into a readable Markdown string, used by both councly_hearing (when waiting) and councly_status tools.

  // Format hearing result for display
  function formatHearingResult(status: {
    hearingId: string;
    status: string;
    verdict?: string | null;
    trustScore?: number | null;
    totalCost?: number;
    counselSummaries?: Array<{
      seat: string;
      model: string;
      lastTurn: string;
    }>;
    progress?: number;
    error?: string;
  }): string {
    const lines: string[] = [];
  
    lines.push(`## Hearing ${status.hearingId}`);
    lines.push(`**Status:** ${status.status}`);
  
    if (status.status === 'completed' || status.status === 'early_stopped') {
      if (status.verdict) {
        lines.push('');
        lines.push('### Verdict');
        lines.push(status.verdict);
      }
  
      if (status.trustScore !== null && status.trustScore !== undefined) {
        lines.push('');
        lines.push(`**Trust Score:** ${status.trustScore}/100`);
      }
  
      if (status.counselSummaries && status.counselSummaries.length > 0) {
        lines.push('');
        lines.push('### Counsel Perspectives');
        for (const counsel of status.counselSummaries) {
          lines.push(`**${counsel.seat}** (${counsel.model}):`);
          lines.push(counsel.lastTurn);
          lines.push('');
        }
      }
  
      if (status.totalCost !== undefined) {
        lines.push(`**Cost:** ${status.totalCost} credits`);
      }
    } else if (status.status === 'failed') {
      lines.push(`**Error:** ${status.error || 'Unknown error'}`);
    } else {
      // In progress
      if (status.progress !== undefined) {
        lines.push(`**Progress:** ${status.progress}%`);
      }
    }
  
    return lines.join('\n');
  }