search_sequences

Instructions

Implementation Reference

• src/index.ts:465-485 (handler)

  MCP tool handler for 'search_sequences'. Validates input, delegates to apiClient.searchSequences, formats results as MCP content block listing sequences with total count.

  private async handleSearchSequences(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.searchSequences(q, limit, skip, shuffle);
    return {
      content: [
        {
          type: "text",
          text: result.results.length === 0 ?
            'No sequences 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:369-379 (schema)

  JSON schema defining the input parameters for the search_sequences tool: required 'q' string, optional limit (1-100), skip (>=0), shuffle (bool).

  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:352-380 (registration)

  Registration of the 'search_sequences' tool in the MCP ListTools handler, including name, detailed description of search capabilities, and input schema.

  {
    name: "search_sequences",
    description:
      "Search for integer sequences using flexible criteria. Supports pagination.\n" +
      "\nSupported search criteria:\n" +
      "- Name: Matches tokens in the sequence name (case-insensitive).\n" +
      "- ID: Matches tokens in the sequence 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) of the corresponding LODA program (e.g., `mov add`). Exclude operation types by prefixing with a minus sign (e.g., `-mul`).\n" +
      "- Author: Matches tokens in the author names (case-insensitive).\n" +
      "- Submitter: Matches tokens in the submitter names of the corresponding LODA programs (case-insensitive).\n" +
      "- Advanced: All tokens in the query must be present in either the sequence name, author name, or submitter name. Keywords are handled as described above.\n" +
      "\nExample queries:\n" +
      "- 'Fibonacci core' (sequences with 'Fibonacci' in the name and the 'core' keyword)\n" +
      "- 'A000045' (sequence with ID A000045)" +
      "- 'Alice' (sequences authored by Alice or with programs submitted by Alice)\n" +
      "- '-hard' (exclude sequences with the 'hard' keyword)\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:134-141 (helper)

  API client helper method that builds query parameters for sequence search and invokes the generic makeRequest to fetch from LODA API /sequences/search endpoint.

  async searchSequences(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(`/sequences/search?${params.toString()}`);
  }

• src/index.ts:425-426 (registration)

  Dispatcher switch case in CallToolRequest handler that routes 'search_sequences' calls to the handleSearchSequences method.

  case "search_sequences":
    return this.handleSearchSequences(safeArgs as { q: string; limit?: number; skip?: number; shuffle?: boolean });