LODA API MCP Server

Instructions

Implementation Reference

• src/index.ts:510-530 (handler)

  The main handler function for the 'search_programs' tool. Validates input parameters, calls the LODA API client to perform the search, formats the results into MCP-compatible content (text summary and raw data), and returns the response.
  private async handleSearchPrograms(args: { q: string; limit?: number; skip?: number; shuffle?: boolean }) { const { q, limit, skip, shuffle } = args; if (!q || typeof q !== 'string') { throw new McpError(ErrorCode.InvalidParams, "q is required"); } const result = await this.apiClient.searchPrograms(q, limit, skip, shuffle); return { content: [ { type: "text", text: result.results.length === 0 ? 'No programs found.' : result.results.map((r: {id: string, name: string, keywords?: string[]}) => `${r.id}: ${r.name}` + (r.keywords && r.keywords.length ? ` [${r.keywords.join(', ')}]` : '') ).join('\n') + `\nTotal: ${result.total}` } ], ...result }; }
• src/index.ts:253-281 (schema)

  Tool definition including name, detailed description, and input schema (JSON Schema) for validation of parameters: q (required string), optional limit, skip, shuffle.
  { name: "search_programs", description: "Search for LODA programs using flexible criteria. Supports pagination.\n" + "\nSupported search criteria:\n" + "- Name: Matches tokens in the program name (case-insensitive).\n" + "- ID: Matches tokens in the program ID (e.g., A000045).\n" + "- Keywords: Include keywords by specifying them in the query (e.g., 'core easy'). Exclude keywords by prefixing with a minus sign (e.g., '-hard').\n" + "- Operation Types: Include operation types (opcodes) to match in the LODA program (e.g., `mov add`). Exclude operation types by prefixing with a minus sign (e.g., `-mul`).\n" + "- Submitter: Matches tokens in the submitter's name (case-insensitive).\n" + "- Advanced: All tokens in the query must be present in either the program name or submitter name. Keywords and operation types are handled as described above.\n" + "\nExample queries:\n" + "- 'Fibonacci core' (programs with 'Fibonacci' in the name and the 'core' keyword)\n" + "- 'A000045' (program with ID A000045)" + "- 'Alice' (programs submitted by Alice)\n" + "- '-hard' (exclude programs with the 'hard' keyword)\n" + "- 'bin' (include programs with 'bin' operations)\n", inputSchema: { type: "object", properties: { q: { type: "string", description: "Search query supporting keywords, properties, submitters, and advanced criteria. To require a keyword, include it; to exclude, prefix with '-' (e.g., -core)." }, limit: { type: "number", description: "Maximum number of results to return (pagination limit)", minimum: 1, maximum: 100 }, skip: { type: "number", description: "Number of items to skip before starting to collect the result set (pagination offset)", minimum: 0 }, shuffle: { type: "boolean", description: "If set to true, the search results will be shuffled randomly" } }, required: ["q"], additionalProperties: false } },
• src/index.ts:413-414 (registration)

  Registration of the 'search_programs' tool in the CallToolRequestSchema switch dispatcher, mapping the tool name to its handler function.
  case "search_programs": return this.handleSearchPrograms(safeArgs as { q: string; limit?: number; skip?: number; shuffle?: boolean });
• src/index.ts:147-154 (helper)

  API client helper method that constructs the search query parameters and makes the HTTP request to the LODA API endpoint /programs/search for fetching program search results.
  async searchPrograms(q: string, limit?: number, skip?: number, shuffle?: boolean): Promise<{ total: number; results: { id: string; name: string; keywords?: string[] }[] }> { const params = new URLSearchParams({ q }); if (limit !== undefined) params.append('limit', String(limit)); if (skip !== undefined) params.append('skip', String(skip)); if (shuffle !== undefined) params.append('shuffle', String(shuffle)); // The API returns { total, results: [{id, name, keywords?}] } return this.makeRequest(`/programs/search?${params.toString()}`); }