OpenAlex MCP Server

Instructions

Implementation Reference

• src/tools/searchPublishers.ts:3-10 (handler)

  The main execution function for the search_publishers tool. It calls the OpenAlex /publishers endpoint via helper and returns formatted JSON response.
  export async function searchPublishers(args: any) { return { content: [{ type: "text", text: JSON.stringify(await makeOpenAlexRequest("/publishers", args), null, 2) }] }; }
• src/index.ts:165-181 (schema)

  Input schema defining parameters for the search_publishers tool (used in list_tools response).
  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., 'country_codes', 'hierarchy_level'), IDs, and convenience filters (e.g., 'display_name.search'). Example: 'country_codes:US,hierarchy_level:0'" }, sort: { type: "string", description: "Sort field with optional :desc" }, page: { type: "number", description: "Page number" }, per_page: { type: "number", description: "Results per page (max 200)" }, cursor: { type: "string", description: "Cursor for deep pagination" }, group_by: { type: "string", description: "Group results by field" }, select: { type: "string", description: "Fields to return" }, sample: { type: "number", description: "Random sample size" }, seed: { type: "number", description: "Random seed" }, mailto: { type: "string", description: "Email for rate limits" }, api_key: { type: "string", description: "Premium API key" } } }
• src/index.ts:291-292 (registration)

  Registration in the call_tool dispatcher switch statement, routing requests to the handler.
  case "search_publishers": return await searchPublishers(args);
• src/index.ts:162-182 (registration)

  Tool object in list_tools response registering the search_publishers tool with name, description, and schema.
  { name: "search_publishers", description: "Search publishers", 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., 'country_codes', 'hierarchy_level'), IDs, and convenience filters (e.g., 'display_name.search'). Example: 'country_codes:US,hierarchy_level:0'" }, sort: { type: "string", description: "Sort field with optional :desc" }, page: { type: "number", description: "Page number" }, per_page: { type: "number", description: "Results per page (max 200)" }, cursor: { type: "string", description: "Cursor for deep pagination" }, group_by: { type: "string", description: "Group results by field" }, select: { type: "string", description: "Fields to return" }, sample: { type: "number", description: "Random sample size" }, seed: { type: "number", description: "Random seed" }, mailto: { type: "string", description: "Email for rate limits" }, api_key: { type: "string", description: "Premium API key" } } } },
• src/utils.ts:22-61 (helper)

  Supporting utility that handles all HTTP requests to OpenAlex API, including query building, headers, auth, and error handling. Used by the search_publishers handler.
  export async function makeOpenAlexRequest(endpoint: string, params: OpenAlexQueryParams = {}): Promise<any> { const queryString = buildQueryString(params); const url = `${OPENALEX_BASE_URL}${endpoint}${queryString ? '?' + queryString : ''}`; try { // Build User-Agent with mailto for polite pool access let userAgent = 'OpenAlex-MCP-Server/1.0.0 (https://github.com/openalex-mcp-server)'; if (params.mailto) { userAgent += ` mailto:${params.mailto}`; } else { // Use environment variable for default email const defaultEmail = process.env.OPENALEX_DEFAULT_EMAIL || 'mcp-server@example.com'; userAgent += ` mailto:${defaultEmail}`; } // Build headers const headers: Record<string, string> = { 'Accept': 'application/json', 'User-Agent': userAgent }; // Add Bearer token - check parameter first, then environment variable const bearerToken = params.bearer_token || process.env.OPENALEX_BEARER_TOKEN; if (bearerToken) { headers['Authorization'] = `Bearer ${bearerToken}`; } const response = await axios.get(url, { headers, timeout: 30000 }); return response.data; } catch (error) { if (axios.isAxiosError(error)) { throw new Error(`OpenAlex API error: ${error.response?.status} - ${error.response?.statusText || error.message}`); } throw error; } }