Daraja MCP

Integra aplicaciones de IA con la API Daraja de Safaricom para una interacción fluida con los servicios de M-Pesa.

GitHub
14
Prueba este MCPPatrocinado

Documentación

Daraja MCP

🚨 Aviso Importante: Repositorio Movido

Este proyecto se ha movido a un nuevo repositorio. Si buscas contribuir o acceder a la última versión, visita:

https://github.com/paylinkmcp/paylink

Un servidor de Protocolo de Contexto de Modelo (MCP) diseñado para integrar aplicaciones de IA con la API Daraja de Safaricom, permitiendo una interacción fluida con los servicios de M-Pesa.

⚠️ Advertencia: No Listo para Producción

Este proyecto se encuentra actualmente en desarrollo y no se recomienda para uso en producción. Está diseñado para:

  • Aprendizaje y experimentación
  • Entornos de desarrollo y pruebas
  • Implementaciones de prueba de concepto

Para uso en producción, asegúrate de:

  • Pruebas de seguridad exhaustivas
  • Manejo adecuado de errores
  • Implementación completa de todas las funciones planificadas
  • Cumplimiento de los requisitos de producción de Safaricom

¿Qué es un Servidor MCP?

Los servidores MCP (Protocolo de Contexto de Modelo) proporcionan capacidades para que los LLM interactúen con sistemas externos. Los servidores MCP pueden proporcionar tres tipos principales de capacidades:

  • Recursos: Datos similares a archivos que pueden ser leídos por los clientes (como respuestas de API)
  • Herramientas: Funciones que pueden ser llamadas por el LLM (con aprobación del usuario)
  • Prompts: Plantillas preescritas que ayudan a los usuarios a realizar tareas específicas

Daraja MCP aprovecha específicamente esta arquitectura para conectar sistemas de IA con la API Daraja M-Pesa de Safaricom.

Descripción General

Daraja MCP es un puente entre la IA, fintech y M-Pesa, haciendo que la automatización financiera impulsada por IA sea accesible y eficiente. Al estandarizar la conexión entre LLM (Modelos de Lenguaje de Gran Escala) y transacciones financieras, Daraja MCP permite que las aplicaciones impulsadas por IA procesen pagos, recuperen datos de transacciones y automaticen flujos de trabajo financieros sin esfuerzo.

Capacidades Clave

  • ✅ Transacciones M-Pesa Impulsadas por IA – Permiten a los LLM manejar pagos B2C, C2B y B2B
  • ✅ Integración Estandarizada – MCP garantiza compatibilidad con múltiples herramientas de IA
  • ✅ Seguro y Escalable – Implementa autenticación OAuth y soporta manejo de transacciones a nivel empresarial
  • ✅ Automatización Flexible – Los agentes de IA pueden consultar saldos de cuentas, generar facturas y automatizar la conciliación

Requisitos

  • Python 3.12
  • Credenciales de la API Daraja de Safaricom (Consumer Key y Secret)

Instalación

Paso 1: Configuración de tu Entorno

  1. Instalar el Administrador de Paquetes uv

    Para Mac/Linux:

    curl -LsSf https://astral.sh/uv/install.sh | sh

    Para Windows (PowerShell):

    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

  2. Clonar el Repositorio

    git clone https://github.com/jameskanyiri/DarajaMCP.git
cd DarajaMCP

  3. Crear y Activar un Entorno Virtual

    uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

    ✅ Salida Esperada: El prompt de tu terminal debería cambiar, indicando que el entorno virtual está activado.

  4. Instalar Dependencias

    uv sync

Paso 2: Configuración de Variables de Entorno

  1. Copia el archivo de entorno de ejemplo:

    cp .env.example .env

  2. Actualiza el archivo .env con tus credenciales reales y valores de configuración.

Nota: Para desarrollo, usa el entorno sandbox. Cambia a la URL de producción cuando estés listo.

Uso

Pruebas con Claude Desktop

  1. Instalar Claude Desktop

    • Descarga e instala la última versión desde Claude Desktop
    • Asegúrate de estar ejecutando la última versión

  2. Configurar Claude Desktop

    • Abre tu archivo de configuración de Claude Desktop:

      # On MacOS/Linux
code ~/Library/Application\ Support/Claude/claude_desktop_config.json

# On Windows
code %APPDATA%\Claude\claude_desktop_config.json

    • Crea el archivo si no existe

  3. Agregar Configuración del Servidor Elige una de las siguientes configuraciones:

    Formato Recomendado por Anthropic

    {
  "mcpServers": {
    "daraja": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/DarajaMCP",
        "run",
        "main.py"
      ]
    }
  }
}

    Configuración Funcional (Probada)

    {
  "mcpServers": {
    "DarajaMCP": {
      "command": "/ABSOLUTE/PATH/TO/PARENT/.local/bin/uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/DarajaMCP",
        "run",
        "main.py"
      ]
    }
  }
}

    Nota:

    • Reemplaza /ABSOLUTE/PATH/TO/PARENT con tu ruta real
    • Para encontrar la ruta completa a uv, ejecuta:
    # On MacOS/Linux
which uv

# On Windows
where uv

  4. Verificar Configuración

    • Guarda el archivo de configuración
    • Reinicia Claude Desktop
    • Busca el ícono de martillo 🔨 en la interfaz
    • Haz clic en él para ver las herramientas disponibles:
      • generate_access_token
      • stk_push (Implementación Futura)
      • query_transaction_status (Implementación Futura)
      • b2c_payment (Implementación Futura)
      • account_balance (Implementación Futura)

Herramientas y Prompts

Herramientas de Pago

stk_push

Inicia una solicitud de push STK de M-Pesa para solicitar al cliente que autorice un pago en su dispositivo móvil.

Entradas:

  • amount (int): El monto a pagar
  • phone_number (int): El número de teléfono del cliente

Devuelve: Respuesta de la API M-PESA en formato JSON

generate_qr_code

Genera un código QR para una solicitud de pago que los clientes pueden escanear para realizar pagos.

Entradas:

  • merchant_name (str): Nombre de la empresa/Nombre del comerciante M-Pesa
  • transaction_reference_no (str): Número de referencia de la transacción
  • amount (int): El monto total de la venta/transacción
  • transaction_type (Literal["BG", "WA", "PB", "SM", "SB"]): Tipo de transacción
  • credit_party_identifier (str): Identificador de la Parte Acreditada (Número de Móvil, Número de Negocio, Till de Agente, Paybill o Compra de Bienes del Comerciante)

Devuelve: Respuesta de la API M-PESA en formato JSON que contiene los datos del código QR

Prompts de Pago

stk_push_prompt

Genera un prompt para iniciar una solicitud de pago push STK de M-Pesa.

Entradas:

  • phone_number (str): El número de teléfono del cliente
  • amount (int): El monto a pagar
  • purpose (str): El propósito del pago

Devuelve: Cadena de prompt formateada para solicitud push STK

generate_qr_code_prompt

Genera un prompt para crear una solicitud de pago con código QR de M-Pesa.

Entradas:

  • merchant_name (str): Nombre del comerciante/negocio
  • amount (int): Monto a pagar
  • transaction_type (str): Tipo de transacción (BG para Compra de Bienes, WA para Billetera, PB para Paybill, SM para Enviar Dinero, SB para Enviar a Negocio)
  • identifier (str): El identificador del destinatario (número de till, paybill, número de teléfono)
  • reference (str, opcional): Número de referencia de la transacción. Si no se proporciona, se usará un valor predeterminado.

Devuelve: Cadena de prompt formateada para generación de código QR

Herramientas de Procesamiento de Documentos

create_source

Crea un conector desde la fuente de datos al servidor no estructurado para procesamiento.

Entradas:

  • connector_name (str): El nombre del conector de origen a crear

Devuelve: Detalles del conector de origen, incluidos nombre e ID

create_destination

Crea un conector desde el servidor no estructurado al destino para almacenamiento de datos.

Entradas:

  • connector_name (str): El nombre del conector de destino a crear

Devuelve: Detalles del conector de destino, incluidos nombre e ID

create_workflow

Crea un flujo de trabajo para procesar datos desde el conector de origen al conector de destino.

Entradas:

  • workflow_name (str): El nombre del flujo de trabajo a crear
  • source_id (str): El ID del conector de origen
  • destination_id (str): El ID del conector de destino

Devuelve: Detalles del flujo de trabajo, incluidos nombre, ID, estado, tipo, orígenes, destinos y programación

run_workflow

Ejecuta un flujo de trabajo.

Entradas:

  • workflow_id (str): El ID del flujo de trabajo a ejecutar

Devuelve: Estado de ejecución del flujo de trabajo

get_workflow_details

Obtén información detallada sobre un flujo de trabajo.

Entradas:

  • workflow_id (str): El ID del flujo de trabajo del que obtener detalles

Devuelve: Detalles del flujo de trabajo, incluidos nombre, ID y estado

fetch_documents

Recupera documentos analizados durante la ejecución del flujo de trabajo.

Entradas: Ninguna

Devuelve: Lista de documentos analizados

Prompts

create_and_run_workflow_prompt

Genera un prompt para crear y ejecutar un flujo de trabajo para procesamiento de documentos.

Entradas:

  • user_input (str): Los requisitos de procesamiento del usuario

Devuelve: Prompt formateado para la creación y ejecución del flujo de trabajo

Ejemplo:

# Example usage
prompt = await create_and_run_workflow_prompt(
    user_input="Process all PDF invoices from the invoices folder and store them in the processed folder"
)
# Returns: "The user wants to achieve Process all PDF invoices from the invoices folder and store them in the processed folder. Assist them by creating a source connector and a destination connector, then setting up the workflow and executing it."

Recursos

Actualmente, no hay recursos disponibles.

Licencia

MIT License

Agradecimientos

  • A Safaricom por proporcionar la API Daraja
  • A Anthropic por el marco MCP
  • A los contribuyentes del proyecto

Contacto

Para cualquier consulta, abre un issue en el repositorio de GitHub.