Philidor MCP Server

Instructions

Implementation Reference

• src/tools/explain-risk-score.ts:5-17 (handler)

  Tool registration and handler function that defines the explain_risk_score tool, validates input using Zod schema, and calls formatRiskScoreExplanation to generate the response.

  export function registerExplainRiskScore(server: McpServer) {
    server.tool(
      'explain_risk_score',
      'Explain what a Philidor risk score means, including the tier (Prime/Core/Edge), how it is calculated, and what the thresholds are.',
      {
        score: z.number().min(0).max(10).describe('Risk score (0-10) to explain'),
      },
      async (params) => {
        const text = formatRiskScoreExplanation(params.score);
        return { content: [{ type: 'text' as const, text }] };
      }
    );
  }

• src/tools/explain-risk-score.ts:10-11 (schema)

  Input schema definition using Zod: requires a score parameter (number, min 0, max 10) representing the risk score to explain.

    score: z.number().min(0).max(10).describe('Risk score (0-10) to explain'),
  },

• src/lib/formatters.ts:198-229 (helper)

  Core implementation logic that determines the risk tier (Prime/Core/Edge) based on score thresholds and generates detailed explanation including calculation methodology and tier definitions.

  export function formatRiskScoreExplanation(score: number): string {
    let tier: string, meaning: string;
    if (score >= 8) {
      tier = 'Prime';
      meaning =
        'This is a high-safety vault. It typically features mature code (>2 years), multiple independent audits, and safe governance (long timelocks or immutable contracts).';
    } else if (score >= 5) {
      tier = 'Core';
      meaning =
        'This is a moderate-safety vault. It is likely audited but may be newer or have more flexible governance (shorter timelocks).';
    } else {
      tier = 'Edge';
      meaning =
        'This is a higher-risk vault. It may be unaudited, very new, have instant admin powers, or recent security incidents.';
    }
  
    return [
      `## Risk Score: ${score}/10 — ${tier} Tier`,
      `\n${meaning}`,
      '\n### How the Score is Calculated',
      'The score is a weighted average of three risk vectors:',
      '- **Asset Composition (40%)**: Quality of underlying assets and collateral',
      '- **Platform Code (40%)**: Code maturity (Lindy effect), audit density, dependency risk, incident history',
      '- **Governance (20%)**: Admin controls, timelock duration, immutability',
      '\n### Tier Thresholds',
      '- **Prime (8.0-10.0)**: Highest safety — institutional-grade',
      '- **Core (5.0-7.9)**: Moderate safety — suitable with monitoring',
      '- **Edge (0.0-4.9)**: Higher risk — requires careful due diligence',
      '\n### Hard Disqualifications',
      'A vault is capped at Edge tier if: no audit exists for the protocol version, or the platform score is 0.',
    ].join('\n');
  }

• src/server.ts:12-12 (registration)

  Import statement for registerExplainRiskScore function from the tools module.

  import { registerExplainRiskScore } from './tools/explain-risk-score';

• src/server.ts:39-39 (registration)

  Registration call that registers the explain_risk_score tool with the MCP server instance.

  registerExplainRiskScore(server);