search_programs

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()}`);
  }