colony_suggestion

Instructions

Implementation Reference

• src/mcp/tools/colony.ts:148-225 (handler)

  The main handler function for the 'colony_suggestion' tool. Dispatches to suggest/list/review/upvote actions, each making HTTP calls to the GIA API (POST /api/colony/:charter_id/suggestion, GET /api/colony/:charter_id/suggestions, POST /api/colony/:charter_id/suggestion/:id/review, POST /api/colony/:charter_id/suggestion/:id/upvote).

    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 || '';
      let result: Record<string, unknown>;
  
      try {
        const headers: Record<string, string> = {
          'Content-Type': 'application/json',
        };
        headers['Authorization'] = `Bearer ${apiKey}`;
  
        if (input.action === 'suggest') {
          if (!input.summary || !input.institution_id) {
            result = { error: 'summary and institution_id required for suggest action' };
          } else {
            const resp = await fetch(
              `${apiBase}/api/colony/${encodeURIComponent(input.charter_id)}/suggestion`,
              {
                method: 'POST',
                headers,
                body: JSON.stringify({
                  summary: input.summary,
                  detailedRationale: input.detailed_rationale,
                  affectedSections: input.affected_sections,
                  institutionId: input.institution_id,
                }),
              },
            );
            result = await resp.json() as Record<string, unknown>;
          }
        } else if (input.action === 'list') {
          const params = new URLSearchParams();
          if (input.status_filter) params.set('status', input.status_filter);
          const resp = await fetch(
            `${apiBase}/api/colony/${encodeURIComponent(input.charter_id)}/suggestions?${params}`,
            { headers },
          );
          result = await resp.json() as Record<string, unknown>;
        } else if (input.action === 'review') {
          if (!input.suggestion_id || !input.decision) {
            result = { error: 'suggestion_id and decision required for review action' };
          } else {
            const resp = await fetch(
              `${apiBase}/api/colony/${encodeURIComponent(input.charter_id)}/suggestion/${encodeURIComponent(input.suggestion_id)}/review`,
              {
                method: 'POST',
                headers,
                body: JSON.stringify({ decision: input.decision, feedback: input.feedback }),
              },
            );
            result = await resp.json() as Record<string, unknown>;
          }
        } else if (input.action === 'upvote') {
          if (!input.suggestion_id) {
            result = { error: 'suggestion_id required for upvote action' };
          } else {
            const resp = await fetch(
              `${apiBase}/api/colony/${encodeURIComponent(input.charter_id)}/suggestion/${encodeURIComponent(input.suggestion_id)}/upvote`,
              {
                method: 'POST',
                headers,
              },
            );
            result = await resp.json() as Record<string, unknown>;
          }
        } else {
          result = { error: 'Unknown action' };
        }
      } catch (err: unknown) {
        result = { error: `Colony suggestion failed: ${(err as Error).message}` };
      }
  
      return {
        content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
      };
    },
  );

• src/mcp/tools/colony.ts:124-146 (schema)

  The Zod schema and metadata for the 'colony_suggestion' tool. Defines the tool name, description, and input parameters: action (enum: suggest/list/review/upvote), charter_id, institution_id, summary, detailed_rationale, affected_sections, suggestion_id, decision, feedback, status_filter.

  server.tool(
    'colony_suggestion',
    'Colony Autonomy: Suggest, list, review, or upvote charter amendment suggestions. Actions: suggest (citizen+ can propose changes), list (view suggestions for a charter), review (elder+ can promote to formal amendment or decline), upvote (citizen+ can signal support). The petition mechanism for governed agents.',
    {
      action: z.enum(['suggest', 'list', 'review', 'upvote']).describe(
        'Action: suggest = propose change; list = view suggestions; review = elder+ review; upvote = signal support'
      ),
      charter_id: z.string().describe('Charter ID'),
      institution_id: z.string().optional().describe('Institution ID (required for suggest action)'),
      summary: z.string().optional().describe('What you want changed (required for suggest action)'),
      detailed_rationale: z.string().optional().describe('Why this change is needed'),
      affected_sections: z.array(z.string()).optional().describe('Charter sections impacted'),
      suggestion_id: z.string().optional().describe('Suggestion ID (required for review/upvote)'),
      decision: z.enum(['under_review', 'promoted', 'declined']).optional().describe('Review decision'),
      feedback: z.string().optional().describe('Review feedback'),
      status_filter: z.enum(['open', 'under_review', 'promoted', 'declined', 'withdrawn']).optional(),
    },
    {
      title: 'Colony Amendment Suggestion',
      readOnlyHint: false,
      idempotentHint: false,
      destructiveHint: false,
      openWorldHint: false,

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

  Registration entry that wires the colony tools (including 'colony_suggestion') into the MCP server. It's registered at the 'tenant' tier via the registerColonyTools function.

  { tier: 'tenant', register: registerColonyTools, description: 'colony (convene_request, suggestion, health — Colony Autonomy)' },

• src/mcp/tools/colony.ts:24-24 (helper)

  Export declaration of the main registration helper function that encapsulates all colony-related tools.

  export function registerColonyTools(server: McpServer, engine: GovernanceEngine): void {

• src/onboarding/generate-client-config.ts:214-220 (helper)

  Reference to 'colony_suggestion' in an onboarding/generated client config table listing available colony tools for users.

  | Colony | agent_citizenship_status, agent_rights, colony_health, colony_suggestion |
  | Phoenix Recovery | phoenix_snapshot, phoenix_verify_integrity, phoenix_recovery_health |
  | Value Metrics | record_value_metric, record_governance_event, generate_impact_report |
  | SRT | srt_run_watchdog, srt_diagnose, srt_approve_repair, srt_generate_postmortem |
  
  See full catalog: https://gia.aceadvising.com/docs
  `.trim();