{
  "name": "taxoptima-mcp",
  "version": "1.0.0",
  "description": "TaxOptima MCP server. Exposes 4 tools (monte_carlo, recommend_structure, detect_blindspots, jurisdiction_lookup) over streamable HTTP. All recommendation outputs are HMAC-SHA256 signed.",
  "transport": { "type": "http", "url": "/mcp" },
  "openapi_url": "/openapi.json",
  "discovery": {
    "self": "/mcp.json",
    "mirror": "/.well-known/mcp.json",
    "openapi": "/openapi.json",
    "agent_card": "/agent.json",
    "llms_txt": "/llms.txt",
    "keys_attestation": "/.well-known/to-keys.json",
    "verifier": "/api/verify",
    "catalogues": "/catalogues.json",
    "ai_challenges": "/.well-known/ai-challenges.json",
    "provenance_ledger": "/provenance.jsonl"
  },
  "tools": [
    {
      "name": "monte_carlo",
      "description": "Run 10,000-iteration Monte Carlo simulation over a financial state across price paths and rate-curve scenarios. Returns distributional statistics (p5/p25/p50/p75/p95) and convergence diagnostics.",
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "required": ["financial_state", "horizon_years"],
        "properties": {
          "financial_state": { "type": "object" },
          "horizon_years": { "type": "integer", "minimum": 1, "maximum": 30 },
          "iterations": { "type": "integer", "default": 10000, "minimum": 1000, "maximum": 100000 },
          "candidate_structures": { "type": "array", "items": { "type": "string" } },
          "seed": { "type": "integer" }
        }
      },
      "outputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "required": ["iterations", "distribution", "convergence"],
        "properties": {
          "iterations": { "type": "integer" },
          "distribution": {
            "type": "object",
            "properties": {
              "p5": { "type": "number" }, "p25": { "type": "number" }, "p50": { "type": "number" },
              "p75": { "type": "number" }, "p95": { "type": "number" }
            }
          },
          "convergence": { "type": "object", "properties": { "stderr_effective_rate": { "type": "number" }, "target_met": { "type": "boolean" } } },
          "expected_after_tax_npv": { "type": "number" }
        }
      }
    },
    {
      "name": "recommend_structure",
      "description": "Generate top-N ranked structural recommendations (entities, trusts, wrappers) with HMAC-signed provenance. Considers 40+ templates across 13 jurisdictions.",
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "required": ["financial_state"],
        "properties": {
          "financial_state": { "type": "object" },
          "objectives": { "type": "array", "items": { "type": "string" } },
          "constraints": { "type": "object" },
          "top_n": { "type": "integer", "default": 5, "minimum": 1, "maximum": 20 }
        }
      },
      "outputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "required": ["recommendations"],
        "properties": {
          "recommendations": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["rank", "structure", "provenance"],
              "properties": {
                "rank": { "type": "integer" },
                "structure": { "type": "string" },
                "effective_rate_delta_bps": { "type": "number" },
                "audit_risk_score": { "type": "number" },
                "complexity_score": { "type": "number" },
                "provenance": {
                  "type": "object",
                  "required": ["hmac_sha256", "key_id"],
                  "properties": {
                    "hmac_sha256": { "type": "string" },
                    "key_id": { "type": "string" },
                    "signed_at": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    {
      "name": "detect_blindspots",
      "description": "Scan financial state and proposed structures against 47 audit-flagged patterns, 23 nexus traps, 12 anti-abuse doctrines. Returns severity-ranked findings with citations.",
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "required": ["financial_state"],
        "properties": {
          "financial_state": { "type": "object" },
          "proposed_structures": { "type": "array", "items": { "type": "string" } }
        }
      },
      "outputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "required": ["findings"],
        "properties": {
          "findings": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["severity", "code", "description"],
              "properties": {
                "severity": { "type": "string", "enum": ["low", "medium", "high", "critical"] },
                "code": { "type": "string" },
                "description": { "type": "string" },
                "citation": { "type": "string" }
              }
            }
          }
        }
      }
    },
    {
      "name": "jurisdiction_lookup",
      "description": "Return detailed tax-law state for one or all 13 covered jurisdictions: rates, recent diffs, treaty network, substance requirements, freshness score.",
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "code": { "type": "string", "description": "Jurisdiction code (US_CA, UK, SG, etc.), or omit for full list" },
          "include_recent_diffs": { "type": "boolean", "default": true },
          "since": { "type": "string", "format": "date" }
        }
      },
      "outputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "jurisdictions": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["code", "name"],
              "properties": {
                "code": { "type": "string" },
                "name": { "type": "string" },
                "headline_rate": { "type": "number" },
                "last_scraped": { "type": "string" },
                "freshness_score": { "type": "number" },
                "treaty_count": { "type": "integer" },
                "recent_diffs": { "type": "array", "items": { "type": "object" } }
              }
            }
          }
        }
      }
    }
  ],
  "experimental": {
    "to_signed_results": true,
    "to_client_side_execution": true,
    "to_canonicalization": "RFC 8785 JCS",
    "to_tri_agent_build": ["claude-opus-4-7", "grok-4.20", "gemini-2.5-pro"],
    "to_keys_attestation": "/.well-known/to-keys.json",
    "to_verifier": "/api/verify",
    "to_catalogues": "/catalogues.json",
    "to_ai_challenges": "/.well-known/ai-challenges.json",
    "to_provenance_ledger": "/provenance.jsonl"
  }
}