search_funders

Instructions

Implementation Reference

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

  The main handler function for the 'search_funders' tool. It invokes the makeOpenAlexRequest helper with the '/funders' endpoint and the provided arguments, then formats the JSON response as text content.

  export async function searchFunders(args: any) {
      return {
          content: [{
                  type: "text",
                  text: JSON.stringify(await makeOpenAlexRequest("/funders", args), null, 2)
              }]
      };
  }

• src/index.ts:186-202 (schema)

  Input schema for the 'search_funders' tool, defining the expected parameters such as search query, filters, pagination options, and API credentials.

  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_code', 'grants_count'), IDs, and convenience filters (e.g., 'display_name.search'). Example: 'country_code:DE,grants_count:>10'" },
          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:183-203 (registration)

  Registration of the 'search_funders' tool in the ListTools response, including name, description, and input schema.

  {
      name: "search_funders",
      description: "Search funders",
      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_code', 'grants_count'), IDs, and convenience filters (e.g., 'display_name.search'). Example: 'country_code:DE,grants_count:>10'" },
              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:293-294 (registration)

  Dispatch case in the CallToolRequest handler that routes calls to the searchFunders handler function.

  case "search_funders":
      return await searchFunders(args);

• src/utils.ts:22-61 (helper)

  Core helper utility that constructs and makes HTTP requests to the OpenAlex API endpoints, handling query parameters, headers, authentication, and errors. Used by the search_funders 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;
      }
  }