Philidor MCP Server

Instructions

Implementation Reference

• src/tools/search-vaults.ts:6-60 (handler)

  Main implementation of search_vaults tool. Contains the registerSearchVaults function that defines the tool schema (lines 10-26) and the async handler (lines 27-58) which builds query parameters, calls the API, and formats the results for display.
  export function registerSearchVaults(server: McpServer) { server.tool( 'search_vaults', 'Search and filter DeFi vaults by chain, protocol, asset, risk tier, TVL, and more. Returns a paginated list with risk scores and APR.', { query: z .string() .optional() .describe('Search by vault name, symbol, asset, protocol, or curator'), chain: z.string().optional().describe('Filter by chain name (e.g. Ethereum, Base, Arbitrum)'), protocol: z .string() .optional() .describe('Filter by protocol ID (e.g. morpho, aave-v3, yearn-v3)'), asset: z.string().optional().describe('Filter by asset symbol (e.g. USDC, WETH)'), riskTier: z.string().optional().describe('Filter by risk tier: Prime, Core, or Edge'), minTvl: z.number().optional().describe('Minimum TVL in USD'), sortBy: z.string().optional().describe('Sort field: tvl_usd, apr_net, name, last_synced_at'), sortOrder: z.string().optional().describe('Sort order: asc or desc'), limit: z.number().optional().describe('Max results (default 10, max 50)'), }, async (params) => { const qs = buildQueryString({ search: params.query, chain: params.chain, protocol: params.protocol, asset: params.asset, riskTier: params.riskTier, minTvl: params.minTvl, sortBy: params.sortBy || 'tvl_usd', sortOrder: params.sortOrder || 'desc', limit: Math.min(params.limit || 10, 50), page: 1, }); const result = await apiGet<{ data: any[]; meta: any }>(`/v1/vaults${qs}`); const vaults = result.data; if (!vaults.length) { return { content: [ { type: 'text' as const, text: 'No vaults found matching the given criteria.' }, ], }; } const lines = vaults.map((v) => formatVaultSummary(v)); const summary = `Found ${result.meta.total} vaults (showing ${vaults.length}):\n\n` + lines.join('\n\n---\n\n'); return { content: [{ type: 'text' as const, text: summary }] }; } ); }
• src/server.ts:31-31 (registration)

  Tool registration - the search_vaults tool is registered with the MCP server by calling registerSearchVaults(server).
  registerSearchVaults(server);
• src/api-client.ts:21-30 (helper)

  Helper function buildQueryString that converts an object of parameters into a URL query string, used by search_vaults to construct API request parameters.
  export function buildQueryString( params: Record<string, string | number | boolean | undefined> ): string { const sp = new URLSearchParams(); for (const [key, value] of Object.entries(params)) { if (value !== undefined && value !== false) sp.set(key, String(value)); } const str = sp.toString(); return str ? `?${str}` : ''; }
• src/api-client.ts:3-19 (helper)

  Helper function apiGet that makes HTTP GET requests to the Philidor API endpoint, used by search_vaults to fetch vault data from /v1/vaults.
  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; }
• src/lib/formatters.ts:1-22 (helper)

  Helper function formatVaultSummary that formats a single vault object into a human-readable markdown summary with protocol, chain, asset, TVL, APR, and risk score information.
  export function formatVaultSummary(vault: any): string { const rs = vault.risk_score; const riskTier = vault.risk_tier || (rs != null && rs >= 8 ? 'Prime' : rs != null && rs >= 5 ? 'Core' : rs != null ? 'Edge' : 'N/A'); const score = vault.total_score ?? vault.risk_score ?? 'N/A'; return [ `## ${vault.name}`, `**Protocol:** ${vault.protocol_name} | **Chain:** ${vault.chain_name} | **Asset:** ${vault.asset_symbol || 'N/A'}`, `**TVL:** $${formatNumber(vault.tvl_usd)} | **APR:** ${formatPercent(vault.apr_net)}`, `**Risk Score:** ${score}/10 (${riskTier})`, vault.curator_name ? `**Curator:** ${vault.curator_name}` : null, ] .filter(Boolean) .join('\n'); }