Charity MCP Server

Instructions

Search parameters:
- query: Organization name or keywords
- city: Filter by city name
- state: Filter by state (2-letter code like 'CA', 'NY')

Returns a list of matching organizations with basic information including:
- Organization name and EIN
- Location (city, state)
- Deductibility status

Use this tool to find organizations when you don't have their exact EIN.

Implementation Reference

• src/tools/charity-search.ts:48-144 (handler)

  The handler function that implements the core logic of the 'charity-search' tool: input validation, rate limiting, API call to charityAPIClient.searchCharities, response formatting, and error handling.

  export async function handleCharitySearch(args: unknown): Promise<CallToolResult> {
    try {
      logger.debug("Charity search requested", { args });
  
      // Validate input
      const input = CharitySearchInputSchema.parse(args);
      logger.debug("Input validated", { input });
  
      // Ensure at least one search parameter is provided
      if (!input.query && !input.city && !input.state) {
        return {
          content: [
            {
              type: "text",
              text: "At least one search parameter must be provided.",
            } as TextContent,
          ],
          isError: true,
        };
      }
  
      // Check rate limit
      if (!(await rateLimiter.checkRateLimit('charity_search'))) {
        const resetTime = rateLimiter.getResetTime('charity_search');
        const resetDate = new Date(resetTime).toISOString();
        
        return {
          content: [
            {
              type: "text",
              text: `Rate limit exceeded for charity search. Please try again after ${resetDate}.`,
            } as TextContent,
          ],
          isError: true,
        };
      }
  
      // Prepare API parameters
      const apiParams = {
        q: input.query,
        city: input.city,
        state: input.state,
      };
  
      // Make API call
      logger.info("Searching charities", { params: apiParams });
      const response = await charityAPIClient.searchCharities(apiParams);
      
      if (!response.data) {
        throw new CharityAPIError("No data returned from CharityAPI", 404);
      }
  
      // Format response
      const results = Array.isArray(response.data) ? response.data : [];
  
      const output: CharitySearchOutput = {
        results: results.map(charity => ({
          ein: charity.ein,
          name: charity.name,
          city: charity.city,
          state: charity.state,
          deductibilityCode: charity.deductibilityCode,
        })),
      };
  
      // Create formatted text response
      const formattedText = formatCharitySearchResponse(output, input);
  
      logger.info("Charity search completed successfully", { 
        resultCount: output.results.length,
        searchParams: apiParams 
      });
  
      return {
        content: [
          {
            type: "text",
            text: formattedText,
          } as TextContent,
        ],
      };
  
    } catch (error) {
      logger.error("Charity search failed", { args, error });
      
      const mcpError = handleMCPError(error);
      return {
        content: [
          {
            type: "text",
            text: mcpError.message,
          } as TextContent,
        ],
        isError: true,
      };
    }
  }

• src/schemas/charity-schemas.ts:29-46 (schema)

  Zod schema used for runtime validation of charity-search tool inputs in the handler.

  export const CharitySearchInputSchema = z.object({
    query: z.string()
      .min(3, "Search query cannot be empty")
      .max(200, "Search query cannot exceed 200 characters")
      .optional(),
    city: z.string()
      .optional()
      .transform((val) => val === "" ? undefined : val)
      .refine((val) => val === undefined || (val.length <= 100), 
        "City name cannot exceed 100 characters"),
    state: z.string()
      .optional()
      .transform((val) => val === "" ? undefined : val)
      .transform((val) => val?.toUpperCase())
      .refine((val) => val === undefined || (val.length === 2 && /^[A-Za-z]{2}$/.test(val)), 
        "State must be a 2-letter abbreviation (e.g., CA, ca, NY, ny)"),
  });

• src/tools/charity-search.ts:7-46 (registration)

  Tool definition object including name, description, and input schema, exported and used for registration in tools/index.ts.

  export const CHARITY_SEARCH_TOOL = {
    name: "charity-search",
    description: `
      Search for charities and nonprofit organizations in the IRS database.
      You can search by organization name, location, or combine multiple criteria.
      
      Search parameters:
      - query: Organization name or keywords
      - city: Filter by city name
      - state: Filter by state (2-letter code like 'CA', 'NY')
      
      Returns a list of matching organizations with basic information including:
      - Organization name and EIN
      - Location (city, state)
      - Deductibility status
      
      Use this tool to find organizations when you don't have their exact EIN.
    `.trim(),
    inputSchema: {
      type: "object" as const,
      properties: {
        query: {
          type: "string",
          description: "Search term for organization name or keywords",
          maxLength: 200,
        },
        city: {
          type: "string",
          description: "Filter by city name (optional)",
          maxLength: 100,
        },
        state: {
          type: "string",
          description: "Filter by state using 2-letter abbreviation like 'CA' or 'NY' (optional)",
          pattern: "^[A-Z]{2}$",
        },
      },
      required: [],
    },
  };

• src/tools/index.ts:22-41 (registration)

  Registration of tool call handler in registerAllTools function, dispatching 'charity-search' calls to handleCharitySearch.

  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    const { name, arguments: args } = request.params;
  
    switch (name) {
      case CHARITY_LOOKUP_TOOL.name:
        return await handleCharityLookup(args);
      
      case PUBLIC_CHARITY_CHECK_TOOL.name:
        return await handlePublicCharityCheck(args);
      
      case CHARITY_SEARCH_TOOL.name:
        return await handleCharitySearch(args);
      
      case LIST_ORGANIZATIONS_TOOL.name:
        return await handleListOrganizations(args);
      
      default:
        throw new Error(`Unknown tool: ${name}`);
    }
  });

• src/tools/charity-search.ts:146-185 (helper)

  Helper function to format the charity search results into a markdown response string.

  function formatCharitySearchResponse(output: CharitySearchOutput, input: CharitySearchInput): string {
    const { results } = output;
    
    let response = `# Charity Search Results\n\n`;
    
    // Search summary
    const searchCriteria = [];
    if (input.query) searchCriteria.push(`Query: "${input.query}"`);
    if (input.city) searchCriteria.push(`City: ${input.city}`);
    if (input.state) searchCriteria.push(`State: ${input.state}`);
    
    response += `**Search Criteria:** ${searchCriteria.join(', ')}\n`;
    response += `**Results:** ${results.length} organizations found\n\n`;
  
    if (results.length === 0) {
      response += `No organizations found matching your search criteria. Try:\n`;
      response += `- Broadening your search terms\n`;
      response += `- Checking spelling of organization name or location\n`;
      response += `- Using fewer filters\n`;
      return response;
    }
  
    // Results listing
    results.forEach((charity, index) => {
      response += `## ${index + 1}. ${charity.name}\n`;
      response += `**EIN:** ${charity.ein}\n`;
      
      if (charity.city || charity.state) {
        response += `**Location:** ${[charity.city, charity.state].filter(Boolean).join(', ')}\n`;
      }
      
      if (charity.deductibilityCode) {
        response += `**Deductibility Code:** ${charity.deductibilityCode}\n`;
      }
      
      response += `\n`;
    });
  
    return response;
  }