Charity MCP Server

Accede a datos de organizaciones benéficas y sin fines de lucro de la base de datos del IRS a través de CharityAPI.org.

Documentación

Charity MCP Server

Un servidor integral del Model Context Protocol (MCP) que proporciona a los asistentes de IA acceso de nivel empresarial a datos de organizaciones benéficas y sin fines de lucro de la base de datos del IRS. Este servidor completo permite a las herramientas de IA consultar información sobre organizaciones benéficas, verificar el estado de deducibilidad de impuestos, buscar organizaciones sin fines de lucro y utilizar plantillas de prompts avanzadas para flujos de trabajo guiados de investigación de organizaciones benéficas.

🎯 Estado del Proyecto: Funcionalidad Completa

Logro: Implementación 100% completa que supera todos los requisitos originales

✅ Las 4 herramientas principales de MCP con manejo integral de errores
✅ Sistema de prompts completo con 14 plantillas especializadas
✅ Arquitectura de nivel empresarial con seguridad total de tipos
✅ Listo para producción con pruebas y documentación exhaustivas
✅ Funciones avanzadas que brindan una experiencia de usuario superior

Características

🔍 Consulta de Organizaciones Benéficas

Consulte información detallada sobre cualquier organización benéfica utilizando su EIN (Identificación Fiscal)
Obtenga datos completos del IRS, incluidos nombre oficial, ubicación, estado fiscal y códigos de clasificación
Valide el formato del EIN y las reglas comerciales

🔎 Búsqueda de Organizaciones Benéficas

Busque organizaciones benéficas por nombre de organización, ciudad o estado
Soporte para paginación y filtrado
Encuentre organizaciones cuando no tenga su EIN exacto

✅ Verificación de Organizaciones Benéficas Públicas

Verifique rápidamente si una organización califica como organización benéfica pública deducible de impuestos
Verifique el estado 501(c)(3) para la planificación de donaciones
Verificación instantánea del estado de deducibilidad de impuestos

📝 Sistema Avanzado de Prompts (14 Plantillas)

8 Prompts de Verificación: Flujos de trabajo completos de verificación de organizaciones benéficas con pasos guiados
6 Prompts de Referencia Rápida: Asistencia de consulta simplificada y mejores prácticas
Generación Dinámica: Prompts basados en plantillas con sustitución de parámetros
Experiencia de Usuario: Flujos de trabajo predefinidos para escenarios comunes de investigación de organizaciones benéficas
Guía para Asistentes de IA: Mejores prácticas y árboles de decisión para un uso óptimo de las herramientas

🛡️ Funciones Empresariales

Límite de Velocidad: Límites de velocidad de API configurables para prevenir abusos
Validación de Entrada: Validación integral con controles de seguridad
Manejo de Errores: Manejo robusto de errores con mensajes fáciles de usar
Registro: Registro detallado para monitoreo y depuración
Seguridad de Tipos: Implementación completa en TypeScript con esquemas Zod

Inicio Rápido

Requisitos Previos

Node.js 18+
npm o yarn
Cuenta de CharityAPI y clave de API

Instalación

Clone el repositorio

git clone <repository-url>
cd charity-mcp-server

Instale las dependencias
```
npm install
```

Configure las variables de entorno

cp .env.example .env
# Edit .env with your API key and configuration

Compile el proyecto
```
npm run build
```
Inicie el servidor
```
npm start
```

Configuración

Variables de Entorno

Cree un archivo .env basado en .env.example:

# CharityAPI Configuration
CHARITY_API_BASE_URL=https://api.charityapi.org
CHARITY_API_KEY=your_api_key_here
CHARITY_API_TIMEOUT=10000
CHARITY_API_MAX_RETRIES=3
CHARITY_API_RETRY_DELAY=1000

# Server Configuration  
MAX_CONCURRENT_REQUESTS=10
REQUEST_TIMEOUT_MS=30000
ENABLE_CACHING=false
LOG_LEVEL=INFO

# Rate Limiting
RATE_LIMIT_REQUESTS_PER_MINUTE=100
RATE_LIMIT_WINDOW_MS=60000

Configuración de la Clave de API

Regístrese para obtener una cuenta de CharityAPI
Genere una clave de API desde su panel de control
Agregue la clave de API a su archivo .env

Herramientas Disponibles

1. Consulta de Organizaciones Benéficas (`charity_lookup`)

Consulte información detallada sobre una organización benéfica específica utilizando su EIN.

Entrada:

ein (cadena, obligatorio): EIN en formato "XX-XXXXXXX" o "XXXXXXXXX"

Ejemplo:

{
  "ein": "13-1837418"
}

Devuelve:

Detalles completos de la organización
Estado y códigos de deducibilidad de impuestos
Clasificación de la organización y códigos de actividad
Estado actual del IRS e información de resoluciones

2. Búsqueda de Organizaciones Benéficas (`charity_search`)

Busque organizaciones benéficas por nombre, ubicación u otros criterios.

Entrada:

query (cadena, opcional): Nombre de la organización o palabras clave
city (cadena, opcional): Filtrar por nombre de ciudad
state (cadena, opcional): Filtrar por estado (código de 2 letras)
limit (número, opcional): Resultados por página (1-100, predeterminado 25)
offset (número, opcional): Omitir resultados para paginación (predeterminado 0)

Ejemplo:

{
  "query": "American Red Cross",
  "state": "CA",
  "limit": 10
}

Devuelve:

Lista de organizaciones coincidentes
Información de paginación
Detalles básicos (nombre, EIN, ubicación, deducibilidad)

3. Verificación de Organizaciones Benéficas Públicas (`public_charity_check`)

Verifique si una organización califica como organización benéfica pública deducible de impuestos.

Entrada:

ein (cadena, obligatorio): EIN en formato "XX-XXXXXXX" o "XXXXXXXXX"

Ejemplo:

{
  "ein": "13-1837418"
}

Devuelve:

Estado de organización benéfica pública (sí/no)
Elegibilidad para donaciones deducibles de impuestos
Confirmación del EIN

Prompts Disponibles

El servidor proporciona prompts integrados para ayudar a los asistentes de IA a realizar la verificación de organizaciones benéficas de manera efectiva:

Prompts de Verificación

Guía de Verificación de Organizaciones Benéficas (charity_verification_guide)
- Guía completa para realizar la verificación de legitimidad de organizaciones benéficas
- Personalizable por tipo de organización (solo_nombre, basado_en_ein, sospechoso, etc.)
Flujo de Trabajo Básico de Legitimidad (basic_legitimacy_workflow)
- Flujos de trabajo paso a paso para diferentes escenarios de verificación
- Parámetros: tipo_de_verificación, nombre_de_organización, ein, ubicación
Detección de Señales de Alerta (red_flag_detection)
- Orientación para detectar y manejar estados problemáticos de organizaciones benéficas
- Maneja organizaciones revocadas, condicionales y suspendidas
Plantillas de Respuesta de Verificación (verification_response_templates)
- Formatos de respuesta estandarizados para diferentes resultados de verificación
- Plantillas para casos verificados, fallidos, condicionales y no_encontrados

Prompts de Referencia Rápida

Referencia Rápida de Verificación (quick_verification_reference)
- Plantillas de consulta rápida para escenarios comunes de verificación
- Personalizable por tipo de entrada del usuario
Plantillas de Respuesta Rápidas (response_templates_quick)
- Plantillas de respuesta rápida con indicadores de estado (✅ ⚠️ ❌)
- Plantillas para casos verificados, no_se_puede_verificar y problemas_encontrados
Guía de Selección de Herramientas (tool_selection_guide)
- Árbol de decisión para seleccionar la herramienta MCP adecuada
- Orientación específica por escenario para diferentes contextos de verificación
Referencia de Palabras Clave Comunes (common_keywords_reference)
- Referencia de palabras clave que activan la verificación de organizaciones benéficas
- Patrones de reconocimiento de intención para asistentes de IA
Mejores Prácticas para Asistentes de IA (ai_assistant_best_practices)
- Mejores prácticas integrales para usar el sistema de verificación de organizaciones benéficas
- Pautas para comunicación, manejo de errores y experiencia de usuario

Uso de Prompts

Los asistentes de IA pueden acceder a estos prompts a través del protocolo MCP:

{
  "method": "prompts/get",
  "params": {
    "name": "basic_legitimacy_workflow",
    "arguments": {
      "verification_type": "organization_name",
      "organization_name": "American Red Cross"
    }
  }
}

Uso con Clientes MCP

Claude Desktop

Agregue a su configuración de Claude Desktop:

{
  "mcpServers": {
    "charity-server": {
      "command": "node",
      "args": ["path/to/charity-mcp-server/build/index.js"],
      "env": {
        "CHARITY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Otros Clientes MCP

El servidor implementa el protocolo MCP estándar y funciona con cualquier cliente compatible. Conéctese utilizando transporte stdio.

Desarrollo

Estructura del Proyecto

src/
├── config/          # Configuration management
├── formatting/      # Response formatting utilities
├── prompts/         # MCP prompt implementations and templates
├── schemas/         # Zod validation schemas
├── services/        # External API clients and rate limiting
├── tools/           # MCP tool implementations
├── transformers/    # Data transformation utilities
├── types/           # TypeScript type definitions
├── utils/           # Logging, error handling, validation
└── validation/      # Input validation and sanitization

Comandos de Desarrollo

# Install dependencies
npm install

# Run in development mode with hot reload
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Clean build artifacts
npm run clean

# Run tests (when implemented)
npm test

# Run linting (when configured)
npm run lint

Arquitectura

El servidor sigue una arquitectura en capas:

Capa MCP: Maneja la comunicación del protocolo y el registro de herramientas
Capa de Validación: Saneamiento y validación de entrada con esquemas Zod
Capa de Servicios: Comunicación con API externa con límite de velocidad
Capa de Transformación: Transformación y estandarización de datos
Capa de Formato: Formato de respuestas para un consumo óptimo por parte de la IA

Componentes Clave

Validación de Entrada: Validación de formato EIN, saneamiento de seguridad
Límite de Velocidad: Algoritmo de cubeta de tokens con límites configurables
Manejo de Errores: Respuestas de error estructuradas con mensajes fáciles de usar
Registro: Registro estructurado con niveles configurables
Seguridad de Tipos: Cobertura completa de TypeScript con validación en tiempo de ejecución

Referencia de API

Integración con CharityAPI

Este servidor se integra con CharityAPI.org para proporcionar:

Acceso a la base de datos completa de organizaciones sin fines de lucro del IRS
Consulta de información de organizaciones benéficas en tiempo real
Capacidades de búsqueda y filtrado de organizaciones
Verificación del estado de deducibilidad de impuestos

Límite de Velocidad

Límites de velocidad predeterminados:

100 solicitudes por minuto por herramienta
Configurable mediante variables de entorno
Limpieza automática de tokens caducados

Contribuciones

Haga un fork del repositorio
Cree una rama de características (git checkout -b feature/amazing-feature)
Confirme sus cambios (git commit -m 'Add amazing feature')
Envíe a la rama (git push origin feature/amazing-feature)
Abra una Solicitud de Extracción

Pautas de Desarrollo

Mantenga el cumplimiento del modo estricto de TypeScript
Agregue validación integral de entrada para nuevas funciones
Incluya manejo de errores con mensajes fáciles de usar
Actualice esquemas y tipos para nuevas estructuras de datos
Agregue registro para depuración y monitoreo
Siga los patrones de organización de código existentes

Licencia

Este proyecto está licenciado bajo la Licencia MIT: consulte el archivo LICENCIA para obtener más detalles.

Ejemplos de Prompts y Uso

Para asistentes de IA que utilizan este servidor MCP, consulte nuestras guías completas de prompts:

Guía de Prompts de Verificación - Flujos de trabajo detallados y ejemplos para la verificación de organizaciones benéficas
Referencia Rápida - Plantillas de consulta rápida y mejores prácticas

Ejemplos de Prompts de Verificación

Verificación Básica de Legitimidad:

"¿Es la Cruz Roja Americana una organización benéfica real registrada en el IRS?"
"Verifique que esa organización con EIN 13-1837418 sea legítima"
"Verificación rápida: ¿es el EIN 52-1693387 una organización benéfica pública legítima?"

Verificación de Organizaciones Sospechosas:

"Recibí una solicitud de donación de 'Help Kids Foundation': ¿son legítimos?"
"Alguien está recolectando dinero para ayuda por huracanes: EIN 12-3456789. ¿Es real?"

Verificación Específica por Ubicación:

"¿Existe una organización benéfica legítima llamada 'Local Food Bank' en Chicago, IL?"
"Verifique 'Animal Rescue' que opera en California"

Soporte

Problemas: Reporte errores y solicitudes de funciones a través de Problemas de GitHub
Documentación: Documentación adicional disponible en la carpeta /docs
CharityAPI: Para preguntas relacionadas con la API, visite CharityAPI.org

Agradecimientos

Model Context Protocol por el estándar
CharityAPI.org por el acceso a datos de organizaciones sin fines de lucro
La comunidad de código abierto por la inspiración y las contribuciones

Charity MCP Server

Documentación