Servidor MCP de PiQrypt

Pista de auditoría criptográfica para agentes de IA mediante el Protocolo de Contexto de Modelo (MCP)

Related MCP server: DCL Evaluator

🚀 ¿Qué es PiQrypt MCP?

El servidor MCP de PiQrypt proporciona acceso mediante el Protocolo de Contexto de Modelo a PiQrypt, la pista de auditoría criptográfica post-cuántica para agentes de IA.

Casos de uso:

• 🤖 Agentes de IA: Firman cada decisión con una prueba criptográfica

• 📊 Flujos de trabajo en n8n: Añaden una pista de auditoría a los flujos de automatización

• 🏦 Bots de trading: Cumplimiento con SEC/FINRA para trading automatizado

• 👥 Automatización de RR. HH.: Decisiones de contratación por IA que cumplen con el RGPD

• 🏥 IA en salud: Pista de auditoría HIPAA para decisiones médicas

📦 Instalación

Requisitos previos

1. Instalar piqrypt (obligatorio — Python 3.8+)

pip install piqrypt

El servidor MCP delega todas las operaciones criptográficas al paquete de Python piqrypt. Si no está instalado, el servidor devolverá un error claro en cada llamada a la herramienta.

2. Instalar el servidor MCP (Node.js 18+)

npm install -g @piqrypt/mcp-server

Instalar mediante npx (sin instalación global)

npx @piqrypt/mcp-server

Construir desde el código fuente

git clone https://github.com/piqrypt/piqrypt-mcp-server
cd piqrypt-mcp-server
npm install
npm run build

PIQRYPT_PYTHON — entorno de Python personalizado

Por defecto, el servidor utiliza python3 (Linux/Mac) o python (Windows). Si piqrypt está instalado en un entorno virtual, establece esta variable para apuntar al intérprete correcto:

Windows

set PIQRYPT_PYTHON=C:\path\to\venv\Scripts\python.exe

Linux / Mac

export PIQRYPT_PYTHON=/path/to/venv/bin/python

Para hacerlo persistente, añádelo a la configuración de tu cliente MCP:

{
  "mcpServers": {
    "piqrypt": {
      "command": "piqrypt-mcp-server",
      "args": [],
      "env": {
        "PIQRYPT_PYTHON": "/path/to/venv/bin/python"
      }
    }
  }
}

⚙️ Configuración

Claude Desktop

Añadir a ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "piqrypt": {
      "command": "piqrypt-mcp-server",
      "args": []
    }
  }
}

n8n (v1.88+)

1. Instalar la integración MCP de n8n

2. Añadir el servidor MCP de PiQrypt a la configuración

3. Usar en flujos de trabajo mediante el nodo MCP

Compatible con

Clientes MCP

Plataformas de automatización (mediante nodo MCP)

Qué puedes auditar con PiQrypt MCP

Cada llamada a la herramienta pasa por las mismas 4 operaciones: sellar, verificar, exportar, buscar. Esto es lo que significa en la práctica dependiendo de tu contexto:

Trading automatizado / finanzas Cualquier agente que envíe órdenes, reequilibre carteras o active transacciones puede sellar cada decisión antes de su ejecución. La cadena firmada es exportable para auditorías SEC/FINRA sin infraestructura adicional.

Automatización de RR. HH. y contratación Cualquier flujo de trabajo que evalúe candidatos, puntúe CVs o clasifique solicitantes puede sellar cada decisión. Proporciona una pista de auditoría conforme al Art. 22 del RGPD para la contratación asistida por IA: quién decidió qué, cuándo y qué datos se utilizaron (hash, nunca almacenados en bruto).

Canalizaciones de contenido y publicación Cualquier agente que redacte, apruebe o publique contenido puede sellar cada paso. Útil cuando varios agentes de IA colaboran y necesitas probar la atribución: qué agente escribió qué, y en qué orden.

DevOps y CI/CD Cualquier agente que active despliegues, fusione ramas o rote secretos puede sellar cada acción. Proporciona un registro a prueba de manipulaciones de los cambios de infraestructura realizados por agentes autónomos.

Salud e IA médica Cualquier agente de diagnóstico o triaje puede sellar cada recomendación. Proporciona una pista de auditoría conforme a HIPAA que vincula cada resultado de la IA con una identidad de agente verificable.

El patrón común en todos los casos:

[Agent makes decision]
↓
piqrypt_stamp_event    ← sign + chain
↓
[Agent executes action]
↓
piqrypt_export_audit   ← portable proof, verifiable
                          without PiQrypt installed

🛠️ Herramientas disponibles

1. piqrypt_stamp_event

Firma una decisión de IA con una prueba criptográfica.

Parámetros:

• agent_id (cadena, obligatorio): Identificador del agente

• payload (objeto, obligatorio): Datos de la decisión

• previous_hash (cadena, opcional): Hash del evento anterior para encadenar

Ejemplo:

const event = await mcp.call('piqrypt_stamp_event', {
  agent_id: 'trading_bot_v1',
  payload: {
    action: 'buy',
    symbol: 'AAPL',
    quantity: 100,
    price: 150.25
  }
});

Devuelve:

{
  "version": "AISS-1.0",
  "agent_id": "trading_bot_v1",
  "timestamp": 1739382400,
  "nonce": "uuid-...",
  "payload": { ... },
  "previous_hash": "sha256:...",
  "signature": "base64:..."
}

2. piqrypt_verify_chain

Verifica la integridad de la cadena de eventos.

Parámetros:

• events (matriz, obligatorio): Eventos a verificar

Ejemplo:

const result = await mcp.call('piqrypt_verify_chain', {
  events: [event1, event2, event3]
});

Devuelve:

{
  "valid": true,
  "events_count": 3,
  "chain_hash": "sha256:...",
  "errors": []
}

3. piqrypt_export_audit

Exporta la pista de auditoría para cumplimiento normativo.

Parámetros:

• agent_id (cadena, obligatorio): Agente a exportar

• certified (booleano): Solicitar certificación de PiQrypt

• output_format (cadena): json o pqz

Ejemplo:

const audit = await mcp.call('piqrypt_export_audit', {
  agent_id: 'trading_bot_v1',
  certified: true,
  output_format: 'json'
});

4. piqrypt_search_events

Búsqueda rápida mediante índice SQLite.

Parámetros:

• event_type (cadena, opcional): Filtrar por tipo

• from_timestamp (número, opcional): Hora de inicio

• to_timestamp (número, opcional): Hora de finalización

• limit (número): Resultados máximos (por defecto: 100)

Ejemplo:

const trades = await mcp.call('piqrypt_search_events', {
  event_type: 'trade_executed',
  from_timestamp: 1739300000,
  limit: 50
});

📊 Panel de control Vigil (opcional, gratuito)

Cada evento sellado es visible en Vigil: el panel de control de monitorización local de PiQrypt.

Nota: Vigil no se inicia automáticamente con el servidor MCP. Debes iniciarlo por separado antes de abrir el panel de control.

piqrypt vigil
# → http://localhost:8421

El nivel gratuito incluye: salud de la cadena, puntuación de riesgo VRS, historial de 7 días, alertas CRÍTICAS. Actualiza a Pro para obtener historial de 90 días, gobernanza TrustGate y firmas post-cuánticas.

🗑️ Gestión de agentes

Los agentes se crean automáticamente en el primer sello. Para ver y eliminar agentes:

1. Inicia Vigil: piqrypt vigil

2. Abre http://localhost:8421

3. Ve a la vista All Agents

4. Selecciona los agentes a eliminar → haz clic en ✕ Delete selected

5. Confirma: Vigil vuelve a la pantalla de bienvenida cuando no quedan agentes

Los agentes se almacenan en ~/.piqrypt/agents/ en tu máquina. Eliminar un agente elimina sus claves y su historial de eventos permanentemente.

🔒 Modelo de seguridad

Aislamiento de procesos

┌─────────────────────────────────────┐
│  MCP Client (any MCP-compatible client)     │
│  ↓ JSON-RPC over stdio              │
├─────────────────────────────────────┤
│  MCP Server (TypeScript/Node.js)    │  ← No crypto here
│  ↓ subprocess call                  │
├─────────────────────────────────────┤
│  Python Bridge (bridge.py)          │
│  ↓ invokes CLI                      │
├─────────────────────────────────────┤
│  PiQrypt CLI (Python)               │
│  ↓ uses                             │
├─────────────────────────────────────┤
│  Core Crypto (aiss package)         │  ← All crypto here
│  • Ed25519 / Dilithium3             │
│  • RFC 8785 canonical JSON          │
│  • Hash chains                      │
└─────────────────────────────────────┘

Garantías

✅ Las claves privadas nunca se exponen a la capa MCP ✅ Toda la criptografía en Python (Ed25519, Dilithium3) ✅ Misma seguridad que la CLI (aislamiento de procesos) ✅ Conforme a RFC AISS-1.1 (salida idéntica) ✅ Validación de entrada antes de la llamada al subproceso

📚 Ejemplos

Bot de trading (n8n)

[Webhook: price alert] 
    ↓
[AI Decision: buy/sell?]
    ↓
[PiQrypt MCP: stamp decision]  ← Audit trail
    ↓
[Execute trade API]
    ↓
[Database: store proof]

Automatización de RR. HH.

[Upload CV]
    ↓
[AI Agent: evaluate candidate]
    ↓
[PiQrypt MCP: stamp evaluation]  ← GDPR compliance
    ↓
[Email HR team]

🧪 Pruebas

# Build
npm run build

# Test bridge
python3 src/python/bridge.py stamp '{"agent_id":"test","payload":{"action":"test"}}'

# Test MCP server (manual)
node dist/index.js
# Then send MCP request via stdin

🔧 Solución de problemas

Error: piqrypt is not installed in this Python environment

El intérprete de Python utilizado por el servidor MCP no puede encontrar el paquete piqrypt.

Solución:

pip install piqrypt

Si piqrypt está instalado en un entorno virtual y no en el Python del sistema, establece PIQRYPT_PYTHON para que apunte al intérprete correcto:

# Linux / Mac
export PIQRYPT_PYTHON=/path/to/venv/bin/python

# Windows
set PIQRYPT_PYTHON=C:\path\to\venv\Scripts\python.exe

Para verificar qué Python utilizará el servidor:

# Linux / Mac
$PIQRYPT_PYTHON -c "import aiss; print('ok')"

# Windows
%PIQRYPT_PYTHON% -c "import aiss; print('ok')"

📖 Documentación

• Guía de configuración de MCP

• Referencia de herramientas

• Integración con n8n

• Modelo de seguridad

• Cumplimiento RFC

🤝 Contribución

¡Agradecemos las contribuciones! Consulta CONTRIBUTING.md.

📄 Licencia

Servidor MCP → Licencia MIT - ver LICENSE Núcleo de PiQrypt → nivel gratuito + niveles comerciales

🔗 Enlaces

• Núcleo de PiQrypt: https://github.com/piqrypt/piqrypt

• Protocolo MCP: https://modelcontextprotocol.io

• n8n: https://n8n.io

• Documentación: https://docs.piqrypt.com

Creado con ❤️ por PiQrypt Inc.