saferagenticai-mcp

Servidor MCP de SaferAgenticAI

Sirve el framework SaferAgenticAI (criterios canónicos + capa de Patrones de Implementación) a asistentes de codificación mediante el Protocolo de Contexto de Modelo (MCP).

Disponible en

Publicado en los catálogos MCP canónicos: instálelo desde un cliente compatible con registros o mediante la CLI que se muestra a continuación:

• PyPI — saferagenticai-mcp
• Registro MCP Oficial — io.github.NellInc/saferagenticai-mcp

También se está distribuyendo en el ecosistema MCP más amplio: mcp.directory, mcpservers.org, PulseMCP (a través de la ingesta del registro) y mcp.so.

Instalación

Elija la opción que se ajuste a su configuración.

Opción 1 — uvx (la más rápida, sin venv manual)

Si tiene uv instalado, apunte su cliente MCP a:

uvx --from git+https://github.com/NellInc/saferagenticai-mcp saferagenticai-mcp

uv gestiona el aislamiento y almacena en caché la instalación. Funciona para líneas de configuración de un solo comando en ~/.claude/mcp.json.

Opción 2 — pipx (instalación global aislada)

pipx install "git+https://github.com/NellInc/saferagenticai-mcp"

Expone saferagenticai-mcp globalmente; se actualiza con pipx upgrade saferagenticai-mcp.

Opción 3 — venv manual (funciona sin conexión desde un checkout)

Homebrew / Python del sistema bloquea pip install directo bajo PEP 668, así que si ha clonado el repositorio y desea una instalación editable:

python3 -m venv research/mcp/.venv
research/mcp/.venv/bin/pip install -e research/mcp/server

Produce research/mcp/.venv/bin/saferagenticai-mcp. Los cambios en los YAML de patrones en el repositorio se detectan en vivo (modo editable).

Opción 4 — desde PyPI

pipx install saferagenticai-mcp
# or, with the modern uv toolchain:
uv tool install saferagenticai-mcp
# or plain pip:
pip install --user saferagenticai-mcp

Para reproducibilidad con trazabilidad de auditoría, fije la versión: pipx install saferagenticai-mcp==0.3.6. El paquete incluye criteria-v1.json + 238 YAML de patrones + 4 ejemplares

• operational_heuristics.yaml dentro de saferagenticai_mcp/_data/, por lo que una instalación desde wheel funciona sin necesidad de checkout del repositorio. (El wheel 0.3.0 es anterior a la extensión del corpus e incluye solo 214 patrones, sin heurísticas; 0.3.1 es la primera compilación completa).

Configuración (Claude Code)

Añada a ~/.claude/mcp.json (o a la configuración MCP de su IDE). Elija la variante que coincida con su opción de instalación.

Con uvx

{
  "mcpServers": {
    "saferagenticai": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/NellInc/saferagenticai-mcp",
        "saferagenticai-mcp"
      ]
    }
  }
}

Con pipx o venv manual

{
  "mcpServers": {
    "saferagenticai": {
      "command": "/absolute/path/to/saferagenticai-mcp"
    }
  }
}

Para un checkout con venv manual, la ruta absoluta es <repo>/research/mcp/.venv/bin/saferagenticai-mcp.

Reinicie Claude Code / su IDE después de editar. El servidor se cargará en la primera llamada a herramienta desde su asistente.

Herramientas (12 en total)

Herramienta	Entrada	Devuelve
list_suites	—	16 suites con títulos y recuentos de subobjetivos
get_requirement	id, include_pattern	un subobjetivo + su capa de Patrones; recurre a candidatos difusos si no hay coincidencia exacta
list_requirements	filtros de suite/tipo/content_type/confianza	lista de subobjetivos filtrada con señales de fiabilidad
search_patterns	query, limit, verbosity	coincidencias clasificadas ponderadas por campo con matched_in y (en modo completo) fragmentos + indicadores de confianza. Pesos de campo: título 10×, resumen 4×, sfr 3×, descripción 2×, cuerpo 1×
get_cross_references	id, include_inferred	adyacencias salientes
get_reverse_references	id	adyacencias entrantes (quién cita este patrón)
resolve_id	query	canoniza un id parcial, fragmento de slug o display_id; siempre devuelve candidatos
find_patterns_for_task	task, limit, verbosity	patrones principales agrupados por suite para una descripción de tarea; por defecto en modo compacto para triaje económico
list_unreviewed	limit	patrones sin reviewed_by, ordenados de menor confianza a mayor
review_stats	—	% de cobertura, por suite, por confianza; además, recuento de problemas de validación
list_operational_heuristics	suite_id?, query?	heurísticas operativas extraídas de despliegues de IA agéntica en producción, opcionalmente filtradas por suite o palabra clave
get_operational_heuristic	id	una heurística operativa por id (p. ej. OH::geoffrey-pattern); devuelve la entrada completa con principio, mapeo del framework, patrones de diseño y narrativa de descubrimiento

Fuentes de datos

• Framework normativo: framework/catalog/, cargado a través de la proyección generada assessor/src/data/criteria-v1.json
• Capa de patrones: research/mcp/suites/<SUITE>/<pattern_id>.yaml (238 archivos)
• Ejemplares: research/mcp/exemplars/*.yaml (respaldo para cuatro subobjetivos ancla)
• Heurísticas operativas: research/mcp/operational_heuristics.yaml (14 heurísticas)

Al iniciar, el servidor carga ambos y construye un índice en memoria claveado por pattern_id. También se admiten búsquedas display_id, pero pueden resolverse a múltiples subobjetivos (variantes subrayadas).

Prueba rápida (sin MCP instalado)

python3 -c "
from saferagenticai_mcp.framework_loader import load_framework
idx = load_framework()
print(f'{len(idx.subgoals)} subgoals, {sum(1 for s in idx.subgoals.values() if s.has_pattern)} with patterns')
"

Versionado

• Framework canónico: sigue el campo version de criteria-v1.json.
• Capa de patrones: v1-draft mientras este directorio se está poblando; v1 una vez revisado.
• Servidor: versionado semántico. La versión actual es 0.3.6 (framework 1.3-draft, corpus completo de 238 patrones y heurísticas operativas incluidas). Fije explícitamente para reproducibilidad de auditoría.

Lo que ya está integrado

• Recarga en caliente — el servidor recorre el árbol de fuentes en cada llamada a herramienta; los cambios aparecen sin reiniciar.
• Validación en carga — campos obligatorios, enum de content_type, enum de confianza. Los patrones inválidos registran WARNINGs pero no detienen el servidor.
• find_patterns_for_task — tarea en lenguaje natural → patrones principales agrupados por suite. Elimina la necesidad de un índice de embeddings separado a la escala actual.
• Índice de referencias cruzadas inverso — construido en carga, consultado por get_reverse_references.

No implementado

• Autenticación / transporte remoto (solo stdio).
• Búsqueda semántica basada en embeddings — la puntuación de palabras clave ponderadas por campo es suficiente con 238 patrones; los embeddings valdrían la pena a 10× esta escala.
• Herramienta de escritura mark_reviewed — deliberadamente no añadida. Las ediciones de revisión de Fase 3 pasan directamente por el YAML (editor + git diff = auditable); el MCP permanece de solo lectura.

La arquitectura agéntica nativa más amplia propone operaciones de orientación compuesta, paquete de contexto, espacio de trabajo, planificación, acción y verificación. Explícitamente no forman parte de la interfaz 0.3.6 actual. Consulte ../../architecture/README.md para el objetivo y el plan de compatibilidad.

El catálogo autoritativo mapea los identificadores y slugs MCP actuales a IDs de requisitos permanentes. El servidor 0.3.6 conserva su interfaz de doce herramientas, carga la instantánea empaquetada generada, valida saai.catalog.v1 e informa el hash compartido de la instantánea.

Licencia

Este servidor (el código en este directorio) está licenciado MIT — consulte LICENSE.

El contenido del framework de seguridad que sirve (los patrones, criterios canónicos y heurísticas operativas incluidos bajo saferagenticai_mcp/_data/) forma parte del framework SaferAgenticAI, publicado bajo CC-BY-4.0 en la raíz del repositorio. Atribución: Nell Watson y la Comunidad de Práctica de Seguridad de IA Agéntica.