Conclave MCP

Instructions

Implementation Reference

• server.py:340-372 (handler)

  The conclave_estimate tool handler function that estimates costs for conclave queries. Takes a question string and optional tier parameter, estimates token count from question length, and returns formatted cost breakdown for quick/ranked/full query types.

  @mcp.tool()
  async def conclave_estimate(question: str, tier: Optional[str] = None) -> str:
      """Estimate cost for a conclave query before running it.
  
      Provides approximate cost breakdown for quick/ranked/full query types.
  
      Args:
          question: The question (used to estimate token count)
          tier: Which tier to estimate - "quick", "ranked", "full" (default: all)
  
      Returns:
          Cost estimates for each query type
      """
      # Rough token estimate (4 chars per token)
      query_tokens = len(question) // 4 + 50
  
      tiers_to_estimate = [tier] if tier in ("quick", "ranked", "full") else ["quick", "ranked", "full"]
  
      estimates = {}
      for t in tiers_to_estimate:
          estimates[t] = estimate_cost(query_tokens, tier=t)
  
      output = "## Cost Estimates\n\n"
      for t, est in estimates.items():
          output += f"### {t.title()}\n"
          output += f"- Stage 1: ${est['stage1']:.4f}\n"
          output += f"- Stage 2: ${est['stage2']:.4f}\n"
          output += f"- Stage 3: ${est['stage3']:.4f}\n"
          output += f"- **Total: ${est['total']:.4f}**\n\n"
  
      output += f"_Estimates based on ~{query_tokens} input tokens. Actual costs may vary._"
  
      return output

• config.py:243-312 (helper)

  Helper function that calculates cost estimates for council queries. Takes query_tokens, tier, models, and chairman parameters, and returns a dict with cost breakdown for stage1, stage2, stage3, and total. Uses MODEL_COSTS dictionary for per-model pricing data.

  def estimate_cost(
      query_tokens: int,
      tier: str = "full",
      models: list[str] = None,
      chairman: str = None,
  ) -> dict:
      """
      Estimate cost for a council query.
  
      Args:
          query_tokens: Approximate tokens in the query
          tier: "quick" (stage 1), "ranked" (stage 1+2), or "full" (all stages)
          models: Council models to use (defaults to COUNCIL_MODELS)
          chairman: Chairman model (defaults to current chairman)
  
      Returns:
          Dict with cost breakdown and total
      """
      models = models or COUNCIL_MODELS
      chairman = chairman or get_current_chairman()
  
      def get_cost(model: str) -> tuple[float, float]:
          return MODEL_COSTS.get(model, DEFAULT_MODEL_COST)
  
      # Rough estimates for response sizes
      avg_response_tokens = 500
      ranking_tokens = 300
      synthesis_tokens = 800
  
      cost_breakdown = {
          "stage1": 0.0,
          "stage2": 0.0,
          "stage3": 0.0,
          "total": 0.0,
      }
  
      # Stage 1: Each model gets query, produces response
      for model in models:
          input_cost, output_cost = get_cost(model)
          cost_breakdown["stage1"] += (
              (query_tokens / 1000) * input_cost +
              (avg_response_tokens / 1000) * output_cost
          )
  
      if tier in ["ranked", "full"]:
          # Stage 2: Each model evaluates all responses
          eval_input_tokens = query_tokens + (avg_response_tokens * len(models))
          for model in models:
              input_cost, output_cost = get_cost(model)
              cost_breakdown["stage2"] += (
                  (eval_input_tokens / 1000) * input_cost +
                  (ranking_tokens / 1000) * output_cost
              )
  
      if tier == "full":
          # Stage 3: Chairman synthesizes everything
          synthesis_input = query_tokens + (avg_response_tokens * len(models)) + (ranking_tokens * len(models))
          input_cost, output_cost = get_cost(chairman)
          cost_breakdown["stage3"] = (
              (synthesis_input / 1000) * input_cost +
              (synthesis_tokens / 1000) * output_cost
          )
  
      cost_breakdown["total"] = sum([
          cost_breakdown["stage1"],
          cost_breakdown["stage2"],
          cost_breakdown["stage3"],
      ])
  
      return cost_breakdown

• server.py:340-340 (registration)

  The @mcp.tool() decorator registers the conclave_estimate function as an MCP tool with the FastMCP server instance.

  @mcp.tool()