search_by_category

Retrieve academic papers from arXiv by specifying a category, sorting options, and pagination parameters. Supports filtering by relevance, submission, or update date.

Instructions

Search for papers in a specific arXiv category

Input Schema

TableJSON Schema

Name	Required	Description
`category`	Yes	arXiv category (e.g., cs.AI, physics.optics)
`max_results`	No	Maximum number of results to return (max 2000)
`sort_by`	No	Sort by: relevance, lastUpdatedDate, submittedDate
`sort_order`	No	Sort order: ascending or descending
`start`	No	Starting index for pagination (0-based)

Implementation Reference

src/index.ts:347-381 (handler)

The main handler function that implements the search_by_category tool logic. It constructs arXiv API search parameters using the provided category and optional pagination/sorting options, queries the arXiv API, processes the response, and returns the results.

private async searchByCategory(args: SearchByCategoryArgs) {
  const searchParams: SearchParams = {
    search_query: `cat:${args.category}`,
  };
  
  // Add pagination
  if (args.start !== undefined) {
    searchParams.start = args.start;
  }
  
  if (args.max_results !== undefined) {
    searchParams.max_results = Math.min(args.max_results, 2000); // API limit
  } else {
    searchParams.max_results = 10; // Default
  }
  
  // Add sorting
  if (args.sort_by) {
    searchParams.sortBy = args.sort_by;
  }
  
  if (args.sort_order) {
    searchParams.sortOrder = args.sort_order;
  }
  
  const response = await this.queryArxiv(searchParams);
  return {
    content: [
      {
        type: 'text',
        text: JSON.stringify(response, null, 2),
      },
    ],
  };
}

src/index.ts:50-56 (schema)

TypeScript interface defining the input arguments for the searchByCategory handler.

interface SearchByCategoryArgs {
  category: string;
  start?: number;
  max_results?: number;
  sort_by?: string;
  sort_order?: string;
}

src/index.ts:170-200 (registration)

MCP tool registration in the ListTools response, including name, description, and JSON input schema.

  name: 'search_by_category',
  description: 'Search for papers in a specific arXiv category',
  inputSchema: {
    type: 'object',
    properties: {
      category: {
        type: 'string',
        description: 'arXiv category (e.g., cs.AI, physics.optics)',
      },
      start: {
        type: 'number',
        description: 'Starting index for pagination (0-based)',
      },
      max_results: {
        type: 'number',
        description: 'Maximum number of results to return (max 2000)',
      },
      sort_by: {
        type: 'string',
        description: 'Sort by: relevance, lastUpdatedDate, submittedDate',
        enum: ['relevance', 'lastUpdatedDate', 'submittedDate'],
      },
      sort_order: {
        type: 'string',
        description: 'Sort order: ascending or descending',
        enum: ['ascending', 'descending'],
      },
    },
    required: ['category'],
  },
},

src/index.ts:231-238 (registration)

Dispatcher case in CallToolRequest handler that validates input and invokes the searchByCategory method.

case 'search_by_category':
  if (!request.params.arguments || typeof request.params.arguments.category !== 'string') {
    throw new McpError(
      ErrorCode.InvalidParams,
      'Missing or invalid category parameter'
    );
  }
  return await this.searchByCategory(request.params.arguments as unknown as SearchByCategoryArgs);

arXiv MCP Server