nonprofit-explorer-mcp-server: Instructions file for Claude Code

Developer Protocol

Server: nonprofit-explorer-mcp-server Version: 0.1.8 Framework: @cyanheads/mcp-ts-core ^0.12.3 Engines: Bun ≥1.3.0, Node ≥24.0.0 MCP SDK: @modelcontextprotocol/server ^2.0.0 Zod: ^4.4.3

Read the framework docs first: node_modules/@cyanheads/mcp-ts-core/CLAUDE.md contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.

Core Rules

• Logic throws, framework catches. Tool/resource handlers are pure — throw on failure, no try/catch. Plain Error is fine; the framework catches, classifies, and formats. Use error factories (notFound(), validationError(), etc.) when the error code matters.
• Use ctx.log for request-scoped logging. No console calls.
• Use ctx.state for tenant-scoped storage. Never access persistence directly.
• Need input the caller didn't supply? return ctx.requestInput(...) and read ctx.inputs when the handler is re-entered. Never await for user input mid-handler.
• Secrets in env vars only — never hardcoded.
• Close the loop on issues. When implementing work tracked by a GitHub issue, comment on the issue with what landed and close it. Do both — a comment without a close leaves stale issues open; a close without a comment leaves no record of what shipped. The comment is for future readers — state the concrete changes, not the conversation that produced them.

Patterns

Tool

import { tool, z } from '@cyanheads/mcp-ts-core';
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
import { getNonprofitExplorerService } from '@/services/nonprofit-explorer/nonprofit-explorer-service.js';

export const nonprofitSearch = tool('nonprofit_search', {
  title: 'Search Nonprofits',
  description: 'Search 1.8M+ IRS-recognized tax-exempt organizations by name, keyword, city, or phrase.',
  annotations: { readOnlyHint: true },
  input: z.object({
    query: z.string().describe('Keyword search string.'),
    state: z.string().length(2).optional().describe('Two-letter US state abbreviation.'),
    page: z.number().int().min(0).default(0).describe('Zero-indexed page number. 25 results per page.'),
  }),
  output: z.object({
    total_results: z.number().describe('Total matching orgs.'),
    organizations: z.array(z.object({
      ein: z.number().describe('EIN as integer.'),
      name: z.string().describe('Legal org name.'),
    })).describe('Matching organizations for the current page.'),
  }),
  enrichment: {
    notice: z.string().optional().describe('Present when the page carried no organizations.'),
  },
  errors: [
    {
      reason: 'upstream_error',
      code: JsonRpcErrorCode.ServiceUnavailable,
      when: 'ProPublica returns a 5xx or the request fails at the network layer',
      retryable: true,
      recovery: 'Wait a moment and retry.',
    },
  ],
  async handler(input, ctx) {
    const svc = getNonprofitExplorerService();
    const raw = await svc.search(input, ctx);
    const orgs = raw.organizations ?? [];
    // A zero-hit search succeeded — return an empty list plus a notice, never an error.
    if (orgs.length === 0) ctx.enrich.notice(`No organizations matched "${input.query}".`);
    return { total_results: raw.total_results ?? 0, organizations: orgs.map(o => ({ ein: o.ein, name: o.name ?? '' })) };
  },
  format: (result) => [{ type: 'text', text: result.organizations.map(o => `**${o.name}** (EIN: ${o.ein})`).join('\n') }],
});