Councly MCP Server

Instructions

Implementation Reference

• src/index.ts:139-180 (handler)

  Main execution handler for the councly_hearing tool within the MCP CallToolRequestSchema handler. Parses input with schema, creates hearing via API client, optionally polls for completion, formats result, and returns MCP response.
  case 'councly_hearing': { const parsed = counclyHearingSchema.parse(args); // Create the hearing const hearing = await client.createHearing({ subject: parsed.subject, preset: parsed.preset, workflow: parsed.workflow, }); // If not waiting, return immediately if (!parsed.wait) { return { content: [ { type: 'text', text: `Hearing created: ${hearing.hearingId}\nStatus: ${hearing.status}\nPreset: ${hearing.preset}\nCost: ${hearing.cost.credits} credits\n\nUse councly_status to check progress.`, }, ], }; } // Wait for completion const status = await client.waitForCompletion(hearing.hearingId, { timeoutMs: parsed.timeout_seconds * 1000, onProgress: (s) => { // Progress updates could be logged if needed if (s.progress !== undefined) { process.stderr.write(`\rProgress: ${s.progress}%`); } }, }); return { content: [ { type: 'text', text: formatHearingResult(status), }, ], }; }
• src/tools.ts:12-28 (schema)

  Zod input schema definition for councly_hearing tool parameters.
  export const counclyHearingSchema = z.object({ subject: z.string().min(10).max(10000).describe( 'The topic or question to discuss. Should be clear and specific. For code review, include the code. For decisions, include context and constraints.' ), preset: z.enum(['balanced', 'fast', 'coding', 'coding_plus']).optional().default('balanced').describe( 'Model preset to use. balanced (9 credits) - general purpose, fast (6 credits) - quick responses, coding (14 credits) - code-focused, coding_plus (17 credits) - enhanced with 4 counsels' ), workflow: z.enum(['auto', 'discussion', 'review', 'brainstorming']).optional().default('auto').describe( 'Workflow type. auto - system chooses best fit, discussion - debate format, review - code/document review, brainstorming - idea generation' ), wait: z.boolean().optional().default(true).describe( 'Whether to wait for completion. If true, polls until hearing finishes. If false, returns immediately with hearing ID.' ), timeout_seconds: z.number().min(30).max(600).optional().default(300).describe( 'Maximum seconds to wait for completion (only used if wait=true). Default 300 (5 minutes).' ), });
• src/tools.ts:41-90 (registration)

  MCP tool definition object for councly_hearing, including name, description, and JSON schema, part of TOOL_DEFINITIONS array used for listTools response.
  { name: 'councly_hearing', description: `Create a council hearing where multiple LLMs (Claude, GPT, Gemini, Grok) debate a topic and a moderator synthesizes the verdict. Use cases: - Code review: Get diverse perspectives on code quality, architecture, security - Technical decisions: Compare approaches, weigh trade-offs - Problem solving: Generate and evaluate multiple solutions - Brainstorming: Explore ideas from different angles The hearing runs asynchronously. By default, this tool waits for completion and returns the verdict. Set wait=false to get the hearing ID immediately and check status later with councly_status. Cost: Varies by preset (6-17 credits). Check councly.ai for current pricing.`, inputSchema: { type: 'object', properties: { subject: { type: 'string', description: 'The topic or question to discuss. Be specific and include relevant context.', minLength: 10, maxLength: 10000, }, preset: { type: 'string', enum: ['balanced', 'fast', 'coding', 'coding_plus'], default: 'balanced', description: 'Model preset: balanced (9 credits), fast (6 credits), coding (14 credits), coding_plus (17 credits, 4 counsels)', }, workflow: { type: 'string', enum: ['auto', 'discussion', 'review', 'brainstorming'], default: 'auto', description: 'Workflow type for the hearing', }, wait: { type: 'boolean', default: true, description: 'Wait for completion (true) or return immediately (false)', }, timeout_seconds: { type: 'number', default: 300, minimum: 30, maximum: 600, description: 'Max wait time in seconds (if wait=true)', }, }, required: ['subject'], }, },
• src/api-client.ts:144-151 (helper)

  CounclyClient method to create a hearing by making POST request to /api/v1/mcp/council endpoint.
  async createHearing(request: CreateHearingRequest): Promise<CreateHearingResponse> { const headers: Record<string, string> = {}; if (request.idempotencyKey) { headers['Idempotency-Key'] = request.idempotencyKey; } return this.request<CreateHearingResponse>('POST', '/council', request, headers); }
• src/api-client.ts:185-225 (helper)

  CounclyClient helper to poll getHearingStatus until completion or timeout, with optional progress callback.
  async waitForCompletion( hearingId: string, options: { pollIntervalMs?: number; timeoutMs?: number; onProgress?: (status: HearingStatusResponse) => void; } = {} ): Promise<HearingStatusResponse> { const { pollIntervalMs = 5000, timeoutMs = 300000, // 5 minutes default onProgress, } = options; const startTime = Date.now(); while (true) { const status = await this.getHearingStatus(hearingId); if (onProgress) { onProgress(status); } // Terminal states if (['completed', 'failed', 'early_stopped'].includes(status.status)) { return status; } // Timeout check if (Date.now() - startTime > timeoutMs) { throw new CounclyApiError( 'TIMEOUT', `Hearing did not complete within ${timeoutMs / 1000} seconds`, 408 ); } // Wait before next poll await new Promise((resolve) => setTimeout(resolve, pollIntervalMs)); } }