search_works

Instructions

Implementation Reference

• src/tools/searchWorks.ts:4-41 (handler)

  The handler function that executes the search_works tool logic. It calls the OpenAlex API for /works endpoint, optionally summarizes results (limits authorships and concepts) based on 'view:summary' parameter, and returns formatted JSON response.

  export async function searchWorks(args: any) {
      const { view, ...searchArgs } = args;
      if (view === 'summary') {
          // Define the fields for the summary view
          searchArgs.select = 'id,doi,title,publication_year,type,cited_by_count,authorships,concepts,primary_location,open_access,best_oa_location';
          
          const data = await makeOpenAlexRequest("/works", searchArgs);
  
          // Process the results to create the summary
          const summarizedResults = data.results.map((work: Work) => {
              // Limit authorships
              if (work.authorships && work.authorships.length > 5) {
                  work.authorships = work.authorships.slice(0, 5);
              }
              // Limit concepts
              if (work.concepts && work.concepts.length > 3) {
                  // Assuming concepts are sorted by score, which is typical.
                  // If not, we might need to sort them first.
                  work.concepts = work.concepts.slice(0, 3);
              }
              return work;
          });
  
          return {
              content: [{
                  type: "text",
                  text: JSON.stringify({ ...data, results: summarizedResults }, null, 2)
              }]
          };
      } else {
          return {
              content: [{
                      type: "text",
                      text: JSON.stringify(await makeOpenAlexRequest("/works", args), null, 2)
                  }]
          };
      }
  }

• src/index.ts:58-76 (schema)

  Input schema definition for the search_works tool, specifying parameters like search, filter, sort, pagination, and view options.

  inputSchema: {
      type: "object",
      properties: {
          search: { type: "string", description: "Full-text search query" },
          filter: { type: "string", description: "Key:value OpenAlex filters. Supports entity attributes (e.g., 'publication_year', 'is_oa'), IDs, and convenience filters (e.g., 'title.search'). Example: 'is_oa:true,type:journal'" },
          sort: { type: "string", description: "Sort field with optional :desc (e.g., 'cited_by_count:desc')" },
          page: { type: "number", description: "Page number (max 10,000 results total)" },
          per_page: { type: "number", description: "Results per page (max 200)" },
          cursor: { type: "string", description: "Cursor for deep pagination (use '*' for first call)" },
          group_by: { type: "string", description: "Group results by field for faceting" },
          select: { type: "string", description: "Comma-separated list of fields to return" },
          sample: { type: "number", description: "Random sample size" },
          seed: { type: "number", description: "Random seed for reproducible sampling" },
          mailto: { type: "string", description: "Email for rate limits" },
          api_key: { type: "string", description: "Premium API key" },
          bearer_token: { type: "string", description: "Bearer token for authentication" },
          view: { type: "string", "enum": ["summary", "full"], description: "The view of the data to return. 'summary' returns a concise version, 'full' returns the complete object." }
      }
  }

• src/index.ts:55-77 (registration)

  Registration of the search_works tool in the ListTools response, including name, description, and schema.

  {
      name: "search_works",
      description: "Search scholarly works in OpenAlex",
      inputSchema: {
          type: "object",
          properties: {
              search: { type: "string", description: "Full-text search query" },
              filter: { type: "string", description: "Key:value OpenAlex filters. Supports entity attributes (e.g., 'publication_year', 'is_oa'), IDs, and convenience filters (e.g., 'title.search'). Example: 'is_oa:true,type:journal'" },
              sort: { type: "string", description: "Sort field with optional :desc (e.g., 'cited_by_count:desc')" },
              page: { type: "number", description: "Page number (max 10,000 results total)" },
              per_page: { type: "number", description: "Results per page (max 200)" },
              cursor: { type: "string", description: "Cursor for deep pagination (use '*' for first call)" },
              group_by: { type: "string", description: "Group results by field for faceting" },
              select: { type: "string", description: "Comma-separated list of fields to return" },
              sample: { type: "number", description: "Random sample size" },
              seed: { type: "number", description: "Random seed for reproducible sampling" },
              mailto: { type: "string", description: "Email for rate limits" },
              api_key: { type: "string", description: "Premium API key" },
              bearer_token: { type: "string", description: "Bearer token for authentication" },
              view: { type: "string", "enum": ["summary", "full"], description: "The view of the data to return. 'summary' returns a concise version, 'full' returns the complete object." }
          }
      }
  },

• src/index.ts:281-282 (registration)

  Dispatch/registration in the CallToolRequest handler switch statement that invokes the searchWorks handler.

  case "search_works":
      return await searchWorks(args);

• src/index.ts:22-22 (helper)

  Import statement that resolves to the searchWorks handler implementation.

  import { searchWorks } from "./tools/searchWorks.js";