get_vault

Instructions

Implementation Reference

• src/tools/get-vault.ts:6-40 (handler)

  Main tool handler implementation for get_vault - defines the schema with optional id, network, and address parameters, and contains the async handler logic that fetches vault data from the API and formats the response using formatVaultDetail.

  export function registerGetVault(server: McpServer) {
    server.tool(
      'get_vault',
      'Get detailed information about a specific DeFi vault including risk breakdown, recent events, and historical snapshots. Lookup by ID or by network + address.',
      {
        id: z.string().optional().describe('Vault ID (e.g. morpho-ethereum-0x...)'),
        network: z.string().optional().describe('Network slug (e.g. ethereum, base, arbitrum)'),
        address: z.string().optional().describe('Vault contract address (0x...)'),
      },
      async (params) => {
        let data: any;
  
        if (params.id) {
          const result = await apiGet<{ data: any }>(`/v1/vaults/${params.id}`);
          data = result.data;
        } else if (params.network && params.address) {
          const result = await apiGet<{ data: any }>(`/v1/vault/${params.network}/${params.address}`);
          data = result.data;
        } else {
          return {
            content: [
              {
                type: 'text' as const,
                text: 'Please provide either an `id` or both `network` and `address`.',
              },
            ],
            isError: true,
          };
        }
  
        const text = formatVaultDetail(data);
        return { content: [{ type: 'text' as const, text }] };
      }
    );
  }

• src/lib/formatters.ts:24-68 (helper)

  formatVaultDetail helper function that formats the vault detail response into markdown, including risk breakdown, recent events, and historical APR calculations from snapshots.

  export function formatVaultDetail(data: { vault: any; snapshots: any[]; events: any[] }): string {
    const { vault, snapshots, events } = data;
    const sections = [formatVaultSummary(vault)];
  
    const apr7d = computeAvgApr(snapshots, 7);
    const apr30d = computeAvgApr(snapshots, 30);
    if (apr7d != null || apr30d != null) {
      const parts = [`**APR (current):** ${formatPercent(vault.apr_net)}`];
      if (apr7d != null) parts.push(`**APR (7d avg):** ${formatPercent(apr7d)}`);
      if (apr30d != null) parts.push(`**APR (30d avg):** ${formatPercent(apr30d)}`);
      sections.push(parts.join(' | '));
    }
  
    if (vault.risk_vectors) {
      sections.push('\n### Risk Breakdown');
      const rv = vault.risk_vectors;
      if (rv.asset) sections.push(`- **Asset Composition:** ${rv.asset.score}/10`);
      if (rv.platform)
        sections.push(
          `- **Platform Code:** ${rv.platform.score}/10 (Lindy: ${rv.platform.details?.lindyScore ?? 'N/A'}, Audit: ${rv.platform.details?.auditScore ?? 'N/A'})`
        );
      if (rv.control)
        sections.push(
          `- **Governance:** ${rv.control.score}/10${rv.control.details?.timelock ? ` (Timelock: ${formatTimelock(rv.control.details.timelock)})` : ''}`
        );
    }
  
    const meta: string[] = [];
    if (vault.audit_status) meta.push(`Audit: ${vault.audit_status}`);
    if (vault.strategy_type) meta.push(`Strategy: ${vault.strategy_type}`);
    if (vault.deployment_timestamp)
      meta.push(`Deployed: ${new Date(vault.deployment_timestamp).toLocaleDateString()}`);
    if (meta.length) sections.push('\n### Metadata\n' + meta.join(' | '));
  
    if (events?.length) {
      sections.push('\n### Recent Events');
      for (const e of events.slice(0, 5)) {
        sections.push(
          `- **${e.event_type}** (${e.severity}): ${e.title} — ${new Date(e.occurred_at).toLocaleDateString()}`
        );
      }
    }
  
    return sections.join('\n');
  }

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

  Import statement for registerGetVault tool registration function.

  import { registerGetVault } from './tools/get-vault';

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

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

  registerGetVault(server);

• src/api-client.ts:3-19 (helper)

  apiGet helper function used by get_vault handler to make HTTP requests to the Philidor API endpoint.

  export async function apiGet<T = any>(path: string): Promise<T> {
    const res = await fetch(`${API_BASE}${path}`, {
      headers: { Accept: 'application/json' },
    });
    if (!res.ok) {
      let message: string;
      try {
        const json = (await res.json()) as Record<string, any>;
        message = json?.error?.message || json?.message || JSON.stringify(json);
      } catch {
        message = res.statusText || `HTTP ${res.status}`;
      }
      throw new Error(`API ${res.status}: ${message}`);
    }
    const json = await res.json();
    return json as T;
  }