Project Guardian MCP

Un servidor del Model Context Protocol (MCP) para memoria persistente de proyectos, operaciones de grafo de conocimiento, acceso a datos SQLite, comprobaciones de seguridad en tiempo de ejecución y flujos de trabajo guiados de gestión de proyectos. El registro actual expone 34 herramientas, 11 recursos y 27 prompts.

Tabla de Contenidos

• Características

  • Sistema de Memoria de Project Guardian

  • Operaciones de Base de Datos Optimizadas

  • Integración de Compañeros en Tiempo de Ejecución

  • Sistema de Guía de IA

  • Características Avanzadas

  • Características Empresariales

• Requisitos

• Instalación

• Herramientas Disponibles

  • Operaciones de Base de Datos (7 herramientas)

  • Herramientas de Memoria y Guía (11 herramientas)

  • Herramientas de Compañeros en Tiempo de Ejecución (12 herramientas)

  • Herramientas de UI (4 herramientas)

• Sistema de Guía de IA

  • Recursos Disponibles

  • Prompts Disponibles

  • Cómo Usan los Modelos de IA la Guía

• Ejemplos de Uso

  • Configuración de Project Guardian

  • Flujo de Trabajo de Gestión de Proyectos

  • Operaciones de Base de Datos

• Configuración

  • Servicios Opcionales en Tiempo de Ejecución

  • Para Cursor IDE

  • Para Claude Desktop

• Estructura del Proyecto

• Desarrollo

• Licencia

Related MCP server: Engram

Características

Sistema de Memoria de Project Guardian

• Grafo de Conocimiento: Mantiene entidades, relaciones y observaciones del proyecto

• Gestión de Entidades: Proyectos, tareas, personas y recursos con metadatos enriquecidos

• Mapeo de Relaciones: Dependencias, propiedad, bloqueos y conexiones

• Seguimiento de Observaciones: Notas contextuales y actualizaciones de progreso

• Búsqueda Semántica: Coincidencia RAG rápida y localizada mediante la extensión FTS5 nativa de SQLite (ranking MATCH y bm25()) en nombres, tipos y observaciones de entidades

• Memoria por Proyecto: Cada proyecto tiene su propio memory.db. El servidor resuelve la raíz del proyecto en este orden: la variable de entorno GUARDIAN_PROJECT_ROOT, luego el nivel superior de Git de su directorio de trabajo y, por último, $XDG_DATA_HOME/project-guardian como respaldo compartido fuera de cualquier repositorio Git

• Espejo Central de Memoria: Cada escritura de memoria también se sincroniza en una base de datos central en ~/memory/memory.db, lo que proporciona un mapa agregado y buscable de todos los proyectos y un respaldo cuando una base de datos de proyecto no está disponible. Las lecturas a través de read_graph y search_nodes combinan ambos almacenes, con prioridad para las entradas del proyecto

• Copias de Seguridad Centrales Diarias: En la primera sincronización de cada día, la base de datos central se captura en ~/memory/backup/ddmmyyyy_memory.db; se conservan las siete copias de seguridad más recientes y las más antiguas se eliminan automáticamente. En la primera ejecución, un ~/memory.db heredado en el directorio personal se migra a la nueva estructura y se utiliza para sembrar la primera copia de seguridad

• Configuración de Pre-Commit Bajo Demanda: No se instala nada al iniciar. Llama a setup_pre_commit cuando quieras un .pre-commit-config.yaml generado y hooks de Git en el proyecto activo

• Interfaz Web Bajo Demanda: Inicia un grafo de nodos interactivo con temática de terminal mediante start_ui (y close_ui/stop_ui para liberar el puerto) para desplazarte visualmente, buscar y explorar el estado del proyecto. Solo para escritorio con bloqueo móvil (superposición <768px), explorador de entidades siempre visible, orbes ámbar agrupados → se expanden a cian por observación, transmisión por cursor GET /api/graph/stream?cursor=&limit=500 + lista virtual react-window, congelación de física >1k.

Operaciones de Base de Datos Optimizadas

• Dos Almacenes, Una Interfaz: Cada proyecto usa su propio memory.db; las siete herramientas de base de datos también pueden dirigirse al agregado central con database: "central"

• CRUD Básico: Operaciones esenciales de base de datos (consultar, insertar, actualizar, eliminar)

• Ejecución de SQL: Ejecución directa de consultas SQL

• Transferencia de Datos: Importar/exportar archivos CSV y JSON

• 34 Herramientas en Total: Siete herramientas de base de datos, diez herramientas de memoria, una herramienta de guía, doce herramientas de compañeros en tiempo de ejecución y cuatro herramientas de UI/transmisión (start_ui, close_ui, stop_ui, read_graph_stream)

Integración de Compañeros en Tiempo de Ejecución

El repositorio incluye seis AgentSkills guardian-* y expone sus capacidades operativas a través de herramientas MCP tipadas:

Los AgentSkills proporcionan flujos de trabajo e instrucciones en el lado del host. El runtime MCP implementa las operaciones correspondientes directamente en TypeScript, excepto el escaneo de contenedores, que invoca a Trivy como proceso externo acotado. No se expone ninguna herramienta genérica de ejecución de scripts o shell.

Sistema de Guía de IA

• 11 Recursos: Plantillas, mejores prácticas, estado del proyecto y salud de las capacidades de los compañeros

• 27 Prompts: Flujos de trabajo predefinidos y completos para todos los aspectos de la gestión de proyectos

• Guía Experta: Instrucciones paso a paso para operaciones complejas

• Ayuda Contextual: Prompts adaptativos según las necesidades del usuario

• Base de Conocimiento: Sabiduría integral de gestión de proyectos

Características Avanzadas

• Validación de Esquemas: Validación integral de entradas con esquemas Zod

• Gestión de Errores: Mensajes de error detallados y manejo elegante de fallos

• Gestión de Conexiones: Caché LRU acotada de 20 conexiones con WAL + synchronous=NORMAL + cache_size=-64000 + journal_size_limit=67108864 + temp_store=MEMORY + busy_timeout=5000, VACUUM mensual (POST /api/vacuum) y limpieza al apagar

• Integración de Archivos: Las importaciones CSV y SQL se transmiten; las escrituras CSV usan ensamblaje de cadenas acotado

• Límites de Resultados y Paginación: SELECT sin procesar ilimitado con tope de 10 000 filas; read_graph/readStore por defecto 5000 con ?limit=&offset=, read_graph_stream cursor 500/página mediante GET /api/graph/stream?cursor=&limit=& + POST /api/vacuum, search_nodes acotado a 100 (RRF híbrido k=60)

Características Empresariales

• TypeScript: Totalmente tipado con gestión integral de errores

• Validación de Entradas: Validación de esquema Zod para todos los parámetros

• Recuperación de Errores: Manejo elegante de errores con mensajes de error detallados

• Gestión de Recursos: Limpieza automática de conexiones y recursos

• Pruebas: Diez suites de Jest con 93 pruebas superadas (WAL + paginación + close_ui + read_graph_stream + e2e-vector híbrido)

Requisitos

• Node.js: >= 18.0.0

• npm: Última versión estable

• SQLite3: Se instala automáticamente como dependencia

• Redis: Opcional; solo se requiere para las herramientas cache_* a través de REDIS_URL

• Trivy: Opcional; solo se requiere para scan_container_image

Instalación

1. Clona el repositorio:

git clone https://github.com/1999AZZAR/project-guardian-mcp-server.git
cd project-guardian-mcp-server

2. Instala las dependencias:

npm install

3. Compila el proyecto: Elige entre compilación de desarrollo o de producción:

Para desarrollo (incluye mapas de origen y compilación completa de TypeScript):

npm run build

Para producción (crea un paquete optimizado y minificado):

npm run build:prod

4. Ejecuta la suite de pruebas:

npm test

5. Inicia el servidor:

npm start

Actualización Tras Cambios

Cuando descargues nuevas actualizaciones o modifiques el código, debes recompilar el servidor y reiniciar tu cliente MCP (Cursor, Claude Desktop, etc.) para que los cambios surtan efecto:

1. Descarga el código más reciente: git pull

2. Instala las nuevas dependencias (si las hay): npm install

3. Recompila el paquete: npm run build:prod

4. Importante: Reinicia tu IDE o la conexión MCP para que el cliente pueda obtener las herramientas y prompts recién actualizados.

Herramientas Disponibles

Este servidor MCP proporciona actualmente 34 herramientas:

Operaciones de Base de Datos (7 herramientas)

Todas las herramientas de base de datos aceptan un selector database opcional: project (predeterminado) apunta al memory.db del proyecto activo, central apunta al agregado central en ~/memory/memory.db.

execute_sql - Ejecutar Consulta SQL

Ejecuta consultas SQL sin procesar en la base de datos de memoria seleccionada.

Parámetros:

• query (obligatorio): Cadena de consulta SQL

• parameters (opcional): Matriz de parámetros de consulta

• database (opcional): "project" o "central", predeterminado "project"

query_data - Consultar Datos de Tabla

Consulta tablas de memoria con filtrado y paginación.

Parámetros:

• table (obligatorio): Nombre de la tabla

• conditions (opcional): Objeto de condiciones WHERE

• limit (opcional): Número máximo de filas a devolver

• offset (opcional): Número de filas a omitir

• orderBy (opcional): Columna por la que ordenar

• orderDirection (opcional): Dirección de ordenación ("ASC" o "DESC")

• database (opcional): "project" o "central", predeterminado "project"

insert_data - Insertar Registros

Inserta registros en una tabla de memoria.

Parámetros:

• table (obligatorio): Nombre de la tabla

• records (obligatorio): Matriz de objetos de registro a insertar

• database (opcional): "project" o "central", predeterminado "project"

update_data - Actualizar Registros

Actualiza registros en una tabla de memoria.

Parámetros:

• table (obligatorio): Nombre de la tabla

• conditions (obligatorio): Condiciones WHERE para los registros a actualizar

• updates (obligatorio): Campos a actualizar

• database (opcional): "project" o "central", predeterminado "project"

delete_data - Eliminar Registros

Elimina registros de una tabla de memoria.

Parámetros:

• table (obligatorio): Nombre de la tabla

• conditions (obligatorio): Condiciones WHERE para los registros a eliminar

• database (opcional): "project" o "central", predeterminado "project"

import_data - Importar Datos

Importa datos desde un archivo CSV o JSON a una tabla de memoria.

Parámetros:

• table (obligatorio): Nombre de la tabla de destino

• filePath (obligatorio): Ruta al archivo de origen

• format (opcional): Formato de archivo ("csv" o "json")

• options (opcional): Opciones de importación (delimiter, hasHeader)

• database (opcional): "project" o "central", predeterminado "project"

export_data - Exportar Datos

Exporta datos de una tabla de memoria a un archivo CSV o JSON.

Parámetros:

• table (obligatorio): Nombre de la tabla de origen

• filePath (obligatorio): Ruta del archivo de salida

• format (opcional): Formato de salida ("csv" o "json")

• conditions (opcional): Condiciones WHERE para filtrar la exportación

• options (opcional): Opciones de exportación (delimiter, includeHeader)

• database (opcional): "project" o "central", por defecto "project"

Herramientas de memoria y guía (11 herramientas)

initialize_memory - Inicializar el sistema de memoria

Configura el esquema y las tablas de la base de datos de memoria del proyecto.

Parámetros: Ninguno

create_entity - Crear entidades de proyecto

Crea entidades en el grafo de conocimiento del proyecto (admite individual o por lotes).

Parámetros:

• entities (obligatorio): Matriz de objetos de entidad

  • name: Nombre de la entidad

  • entityType: Tipo (project, task, person, resource)

  • observations: Matriz de notas sobre la entidad

create_relation - Crear relaciones entre entidades

Crea relaciones entre entidades del proyecto (admite individual o por lotes).

Parámetros:

• relations (obligatorio): Matriz de objetos de relación

  • from: Nombre de la entidad de origen

  • to: Nombre de la entidad de destino

  • relationType: Tipo de relación (depends_on, blocks, owns, etc.)

add_observation - Añadir observaciones a entidades

Añade observaciones/notas a las entidades del proyecto (admite individual o por lotes).

Parámetros:

• observations (obligatorio): Matriz de objetos de observación

  • entityName: Nombre de la entidad de destino

  • contents: Matriz de cadenas de observación para añadir

delete_entity - Eliminar entidades del proyecto

Elimina entidades y sus relaciones de la memoria del proyecto (admite individual o por lotes).

Parámetros:

• entityNames (obligatorio): Matriz de nombres de entidad para eliminar

delete_observation - Eliminar observaciones de entidades

Elimina observaciones específicas de las entidades (admite individual o por lotes).

Parámetros:

• deletions (obligatorio): Matriz de objetos de eliminación

  • entityName: Nombre de la entidad de destino

  • observations: Matriz de cadenas de observación para eliminar

delete_relation - Eliminar relaciones entre entidades

Elimina relaciones entre entidades del proyecto (admite individual o por lotes).

Parámetros:

• relations (obligatorio): Matriz de objetos de relación para eliminar

  • from: Nombre de la entidad de origen

  • to: Nombre de la entidad de destino

  • relationType: Tipo de relación para eliminar

read_graph - Leer el grafo de conocimiento del proyecto

Recupera el grafo de conocimiento completo, fusionando la base de datos del proyecto activo con el agregado central. Las entradas del proyecto prevalecen sobre las entradas centrales con el mismo nombre. Admite paginación.

Parámetros:

• database (opcional): "project" (por defecto, combinado), "central" (solo central)

• limit (opcional, 1-10000, por defecto 5000): Máximo de entidades/relaciones a devolver, ORDER BY updated_at DESC

• offset (opcional, 0+): Filas a omitir

search_nodes - Buscar en el conocimiento del proyecto

Busca entidades y relaciones que coincidan con una consulta en nombres, tipos y contenido, tanto en la base de datos del proyecto como en el agregado central. Utiliza la clasificación FTS5 MATCH + bm25().

Parámetros:

• query (obligatorio): Término de búsqueda

• limit (opcional, 1-100, por defecto 20): Máximo de entidades clasificadas a devolver

open_node - Obtener detalles de la entidad

Recupera información detallada sobre las entidades del proyecto (admite individual o por lotes).

Parámetros:

• names (obligatorio): Matriz de nombres de entidad para recuperar

get_project_guidance - Acceder a la guía de IA

Invoca un marco de guía de proyecto para recibir instrucciones especializadas y listas de verificación para flujos de trabajo específicos. Esto permite que la IA obtenga y siga de forma autónoma los protocolos establecidos de gestión de proyectos.

Parámetros:

• guidance_name (obligatorio): Nombre de la guía (p. ej., project-setup, sprint-planning)

• arguments (opcional): Argumentos requeridos por el marco de guía específico

Herramientas complementarias de tiempo de ejecución (12 herramientas)

sync_central_memory

Copia el grafo de conocimiento del proyecto activo en la base de datos de memoria central (~/memory/memory.db por defecto, se puede sobrescribir con GUARDIAN_CENTRAL_DB). Las entidades se insertan o actualizan (upsert) y las relaciones se deduplican, de modo que la base de datos central acumula un mapa buscable de todos los proyectos. Cada escritura de memoria también se sincroniza automáticamente; llama a esta herramienta para forzar una sincronización bajo demanda. La primera sincronización de cada día también crea una instantánea de la base de datos central y elimina las copias de seguridad antiguas más allá de las siete más recientes.

set_project_root

Cambia la base de datos de memoria del proyecto activo a la ruta absoluta del proyecto indicada. Úsalo al inicio de la sesión cuando el servidor se haya lanzado fuera del directorio del proyecto, para que la memoria se escriba en el proyecto en lugar de en la base de datos compartida de respaldo.

• path (obligatorio): Ruta absoluta a la raíz del proyecto. Dentro de un repositorio Git, se utiliza el nivel superior (toplevel).

setup_pre_commit

Crea un .pre-commit-config.yaml en la raíz del proyecto activo e instala los hooks de Git, bajo demanda. Requiere que pre-commit esté instalado. Las entradas .gitignore generadas son intencionadamente amplias: junto a memory.db, el bloque ignora directorios locales de herramientas comunes como .claude/, .vscode/, .idea/, .gemini/ y .cursor/, además de los archivos .env. Las entradas ya presentes en .gitignore nunca se duplican. El servidor nunca hace nada de esto automáticamente al iniciarse.

get_session_context

Resume las tareas activas, los errores abiertos, los cambios recientes, los bloqueadores y la siguiente acción sugerida directamente desde el grafo de conocimiento.

• limit (opcional, 1-50, por defecto 10): Máximo de entradas por grupo de resultados.

analyze_git_changes

Devuelve las rutas modificadas exactas y legibles por máquina desde Git, incluyendo renombrados y, opcionalmente, archivos sin seguimiento.

• commit (opcional): Analiza un commit contra su padre.

• since (opcional, por defecto 1): Analiza los cambios desde hace N commits o una fecha de Git.

• includeUntracked (opcional, por defecto true): Incluye archivos sin seguimiento para el análisis del árbol de trabajo.

• maxFiles (opcional, 1-500, por defecto 100): Limita las rutas devueltas.

• commit y un valor personalizado de since son mutuamente excluyentes.

inspect_untrusted_text

Normaliza hasta 256 KiB de texto no confiable y detecta formato oculto, anulaciones de instrucciones, suplantación de roles, HTML/CSS oculto, marcado de exfiltración remota y contenido codificado similar a instrucciones.

• text (obligatorio): Contenido externo o no confiable.

• La detección es heurística. El texto normalizado devuelto sigue siendo datos no confiables.

scan_project_secrets

Escanea un archivo o directorio relativo al espacio de trabajo en busca de posibles credenciales codificadas. Los resultados contienen solo el tipo, la ruta relativa del archivo y el número de línea; los valores coincidentes nunca se devuelven.

• path (opcional, por defecto .): Destino de escaneo relativo al espacio de trabajo.

• exclude (opcional): Nombres de directorio adicionales para omitir.

• maxFindings (opcional, 1-500, por defecto 100): Limita los hallazgos.

• Se rechazan rutas absolutas, traversal, rutas inexistentes y escapes de enlaces simbólicos.

scan_container_image

Ejecuta un escaneo de Trivy con límite de tiempo y devuelve resúmenes acotados de vulnerabilidades HIGH/CRITICAL.

• image (obligatorio): Referencia de imagen de contenedor.

• maxFindings (opcional, 1-500, por defecto 100): Limita los hallazgos.

• Requiere Trivy. Se rechazan los valores de imagen que comiencen con -, contengan espacios en blanco o contengan caracteres de control.

Herramientas de caché Redis

• cache_get: Lee una clave mema:<category>:<name>.

• cache_set: Almacena un valor de hasta 512 KiB con ttlSeconds opcional de 1 a 604800.

• cache_delete: Elimina una clave con espacio de nombres.

• cache_scan: Escanea con cursor un patrón mema:* con un recuento limitado.

Las rutas de escaneo del proyecto están restringidas al espacio de trabajo Git actual. Las herramientas Redis se conectan de forma diferida y devuelven un error de no disponibilidad cuando REDIS_URL no está definido. El escaneo de contenedores permanece no disponible hasta que Trivy esté instalado. Lee project-guardian://companions/catalog para conocer el estado actual de las capacidades.

Herramientas de UI (4 herramientas)

start_ui

Inicia el servidor de la interfaz web de Project Guardian bajo demanda para explorar visualmente el grafo de conocimiento en tu navegador. Encuentra automáticamente un puerto libre (por defecto 3000, prueba 3001… en caso de colisión) y devuelve la URL HTTP local. La interfaz sirve el grafo de fuerzas con temática CRT desde ui/dist con una ruta estática de respaldo correcta (ui/dist → MCPservers/.../ui/dist).

• Parámetros: Ninguno

• Devuelve: UI Server successfully started on http://localhost:<port>

• Características: Solo escritorio (puerta móvil en <768px), navegador de entidades siempre visible, orbes de observación (ámbar agrupados → expandir a cian), paginación ?limit=&offset= en /api/graph/*.

close_ui / stop_ui

Detiene el servidor de la interfaz web si está en ejecución y libera el puerto.

• Parámetros: Ninguno

• Devuelve: UI Server stopped

• stop_ui es un alias de close_ui.

Sistema de guía de IA

Project Guardian MCP incluye recursos y prompts completos para ayudar a los modelos de IA a utilizar eficazmente el conjunto de herramientas para la gestión de proyectos.

Recursos disponibles

Project Guardian proporciona 11 recursos clave que los modelos de IA pueden leer para comprender conceptos de gestión de proyectos, acceder al estado de las capacidades y obtener información integral del proyecto:

project-guardian://templates/entity-types

Tipos de entidad estándar para la gestión de proyectos con ejemplos y pautas de uso.

project-guardian://templates/relationship-types

Tipos de relación comunes entre entidades del proyecto con ejemplos prácticos.

project-guardian://templates/project-workflows

Flujos de trabajo estándar para usar las herramientas de Project Guardian en diferentes escenarios.

project-guardian://templates/best-practices

Guía completa de mejores prácticas para una gestión eficaz del conocimiento del proyecto.

project-guardian://status/current-graph

Estado actual del grafo de conocimiento del proyecto con estadísticas resumidas.

project-guardian://cache/recent-activities

Actividades de gestión de proyectos realizadas recientemente y actualizaciones para el seguimiento del progreso.

project-guardian://cache/workflow-templates

Plantillas de flujo de trabajo de uso frecuente con ejemplos y orientación de implementación.

project-guardian://metrics/project-stats

Resumen estadístico de entidades, relaciones y actividades del proyecto con métricas de salud.

project-guardian://cache/team-members

Información almacenada en caché sobre los miembros del equipo del proyecto y sus roles dentro de la organización.

project-guardian://status/recent-changes

Adiciones, actualizaciones y modificaciones recientes del grafo de conocimiento para auditoría y monitoreo.

project-guardian://companions/catalog

Enumera los seis companions, sus herramientas MCP, los requisitos externos y su disponibilidad actual.

Prompts disponibles

Project Guardian ofrece 27 prompts que cubren configuración de proyectos, planificación, calidad, operaciones y flujos de trabajo de incidentes:

Gestión de proyectos principal

project-setup - Inicialización del proyecto

Argumentos:

• project_name (obligatorio): Nombre del proyecto

• team_members (opcional): Lista de miembros del equipo separada por comas

Proporciona orientación paso a paso para configurar una nueva estructura de proyecto con entidades y relaciones apropiadas.

sprint-planning - Planificación de sprint

Argumentos:

• sprint_name (obligatorio): Nombre/número del sprint

• duration_days (opcional): Duración del sprint en días

Guía a través de una planificación de sprint integral que incluye desglose de tareas, dependencias y planificación de capacidad.

progress-update - Seguimiento del progreso

Argumentos:

• task_name (obligatorio): Nombre de la tarea a actualizar

• progress_notes (obligatorio): Descripción de la actualización del progreso

Proceso estructurado para actualizar el progreso de las tareas y gestionar las dependencias.

retrospective - Retrospectiva del proyecto

Argumentos:

• time_period (obligatorio): Período de tiempo que se está revisando (p. ej., "último sprint", "Q1")

Proceso de retrospectiva integral que incluye análisis de datos, identificación de patrones y creación de acciones de mejora.

Gestión de calidad y procesos

code-review - Proceso de revisión de código

Argumentos:

• pull_request_title (obligatorio): Título del pull request que se está revisando

• reviewer_name (opcional): Nombre del revisor

Proceso estructurado de revisión de código con listas de verificación técnicas, documentación de incidencias y flujos de trabajo de aprobación.

bug-tracking - Gestión de errores

Argumentos:

• bug_description (obligatorio): Descripción del error o problema

• severity_level (opcional): Gravedad: Critical, High, Medium o Low

Flujo de trabajo completo de seguimiento de errores, desde el descubrimiento hasta la resolución, con análisis de impacto y comunicación con las partes interesadas.

technical-debt-assessment - Análisis de Deuda Técnica

Argumentos:

• component_name (obligatorio): Nombre del componente o base de código que se está evaluando

• assessment_scope (opcional): Alcance de la evaluación (file, module, system)

Identificación exhaustiva de deuda técnica, priorización y planificación de remediación.

Gestión de Lanzamientos y Despliegues

release-planning - Planificación de Lanzamientos

Argumentos:

• release_version (obligatorio): Número de versión para el lanzamiento (p. ej., "v2.1.0")

• release_date (opcional): Fecha objetivo de lanzamiento

Proceso completo de planificación de lanzamientos, incluidos controles de calidad, evaluación de riesgos y coordinación del despliegue.

Gestión de Riesgos y Cambios

risk-assessment - Gestión de Riesgos

Argumentos:

• risk_description (obligatorio): Descripción del riesgo

• impact_level (opcional): Impacto: High, Medium o Low

Flujo de trabajo completo para documentar riesgos, identificar impactos y desarrollar estrategias de mitigación.

change-management - Control de Cambios

Argumentos:

• change_description (obligatorio): Descripción del cambio propuesto

• impact_assessment (opcional): Evaluación de impacto: High, Medium o Low

Proceso estructurado de gestión de cambios con análisis de impacto, flujos de aprobación y seguimiento de la implementación.

Gestión de Equipos y Recursos

team-productivity - Análisis de Productividad

Argumentos:

• timeframe (obligatorio): Período de tiempo a analizar (week, month, quarter)

• focus_area (opcional): Área en la que centrarse (velocity, quality, collaboration)

Evaluación de la productividad del equipo con métricas de rendimiento, análisis de causa raíz y planificación de mejoras.

resource-allocation - Planificación de Recursos

Argumentos:

• resource_type (obligatorio): Tipo de recurso (human, infrastructure, budget)

• planning_horizon (opcional): Horizonte de planificación (sprint, quarter, year)

Optimización de la asignación de recursos con planificación de capacidad, análisis de brechas y seguimiento de utilización.

Documentación y Comunicación

stakeholder-communication - Gestión de Comunicación

Argumentos:

• communication_type (obligatorio): Tipo de comunicación (status_update, issue_alert, milestone_reached)

• audience (opcional): Público objetivo (team, management, client, all)

Planificación y ejecución de la comunicación con las partes interesadas, con estrategias específicas para cada audiencia y seguimiento de la eficacia.

documentation-management - Actualizaciones de Documentación

Argumentos:

• documentation_type (obligatorio): Tipo de documentación (api, user_guide, technical_spec)

• update_reason (opcional): Motivo de la actualización de documentación

Proceso de mantenimiento de documentación con planificación de contenido, flujos de revisión y coordinación de publicación.

Gestión de Requisitos y Planificación

requirements-gathering - Recopilación de Requisitos

Argumentos:

• requirement_type (obligatorio): Tipo de requisitos (functional, non-functional, business, technical)

• stakeholders (opcional): Lista de partes interesadas clave separadas por comas

Guía a través de un proceso exhaustivo de recopilación de requisitos con gestión de partes interesadas y categorización de requisitos.

user-story-management - Gestión de Historias de Usuario

Argumentos:

• feature_name (obligatorio): Nombre de la funcionalidad o épica

• user_role (opcional): Rol de usuario principal (p. ej., "customer", "admin", "developer")

Proceso estructurado para crear, gestionar y priorizar historias de usuario con criterios de aceptación y dependencias.

Gestión de Calidad y Técnica

testing-strategy - Desarrollo de Estrategia de Pruebas

Argumentos:

• application_type (obligatorio): Tipo de aplicación (web, mobile, api, desktop)

• criticality_level (opcional): Criticidad empresarial (critical, high, medium, low)

Desarrollo de una estrategia de pruebas exhaustiva que incluye pruebas automatizadas, controles de calidad y pruebas basadas en riesgos.

security-assessment - Evaluación de Seguridad

Argumentos:

• assessment_scope (obligatorio): Alcance de la evaluación de seguridad (application, infrastructure, data)

• compliance_requirements (opcional): Estándares de cumplimiento (GDPR, HIPAA, SOC2, etc.)

Marco de evaluación de seguridad con gestión de vulnerabilidades, verificación de cumplimiento e implementación de controles de seguridad.

performance-optimization - Optimización de Rendimiento

Argumentos:

• performance_metric (obligatorio): Métrica principal a optimizar (response_time, throughput, resource_usage)

• optimization_goal (opcional): Objetivo de rendimiento específico o porcentaje de mejora

Configuración de monitorización de rendimiento, identificación de cuellos de botella e implementación de optimizaciones con monitorización continua.

ci-cd-setup - Configuración de Pipeline CI/CD

Argumentos:

• pipeline_type (obligatorio): Tipo de pipeline (build, test, deploy, full_ci_cd)

• target_platform (opcional): Destino de despliegue (aws, azure, gcp, kubernetes, heroku)

Configuración completa de pipeline CI/CD, incluidos controles de calidad, procedimientos de reversión e integración de seguridad.

architecture-review - Revisión de Arquitectura

Argumentos:

• architecture_type (obligatorio): Tipo de arquitectura (microservices, monolithic, serverless, hybrid)

• review_focus (opcional): Área de enfoque principal (scalability, security, maintainability, performance)

Marco de evaluación arquitectónica con análisis de patrones de diseño, evaluación de la pila tecnológica y recomendaciones de mejora.

Gestión de Conocimiento y Equipos

knowledge-transfer - Transferencia de Conocimiento

Argumentos:

• knowledge_domain (obligatorio): Dominio de conocimiento (technical, process, business)

• transfer_recipients (opcional): Quién necesita recibir el conocimiento (team, individual, department)

Planificación y ejecución de la transferencia de conocimiento con gestión de sesiones, documentación y validación de la eficacia.

vendor-management - Gestión de Proveedores

Argumentos:

• vendor_type (obligatorio): Tipo de servicio de proveedor (cloud, development, consulting, infrastructure)

• contract_value (opcional): Rango de valor del contrato (small, medium, large, enterprise)

Gestión de relaciones con proveedores, incluido el seguimiento de contratos, la monitorización del rendimiento y la optimización de costes.

Gestión de Incidentes y Crisis

incident-response - Respuesta a Incidentes

Argumentos:

• incident_severity (obligatorio): Nivel de gravedad (critical, high, medium, low)

• incident_type (opcional): Tipo de incidente (security, performance, functionality, availability)

Marco de respuesta a incidentes con contención, recuperación, análisis de causa raíz y revisión posterior al incidente.

Gestión Financiera y de Recursos

cost-management - Gestión de Costes

Argumentos:

• cost_category (obligatorio): Categoría de coste principal (infrastructure, personnel, tools, licenses)

• budget_constraint (opcional): Nivel de restricción presupuestaria (strict, flexible, unlimited)

Monitorización de costes, estrategias de optimización y gestión presupuestaria con previsión e informes.

Gestión de Clientes e Innovación

customer-feedback - Gestión de Comentarios de Clientes

Argumentos:

• feedback_channel (obligatorio): Canal de comentarios principal (survey, support, reviews, analytics)

• feedback_focus (opcional): Área de enfoque (usability, features, performance, support)

Recopilación de comentarios de clientes, análisis y planificación de acciones con ciclos de mejora continua.

innovation-planning - Planificación de Innovación

Argumentos:

• innovation_type (obligatorio): Tipo de innovación (product, process, technology, business_model)

• risk_tolerance (opcional): Nivel de tolerancia al riesgo (conservative, moderate, aggressive)

Marco de gestión de la innovación con generación de ideas, experimentación y medición del éxito.

Cómo usan los modelos de IA la guía

1. Descubrimiento: Enumera los recursos y prompts disponibles para comprender las capacidades

2. Aprendizaje: Lee los recursos relevantes para comprender los conceptos de gestión de proyectos

3. Planificación: Utiliza los prompts adecuados para flujos de trabajo complejos

4. Ejecución: Sigue la guía estructurada para usar las herramientas de forma eficaz

5. Verificación: Comprueba los resultados e itera según sea necesario Este sistema de guía garantiza que los modelos de IA puedan ofrecer asistencia experta en gestión de proyectos utilizando el conjunto de herramientas de Project Guardian.

Protocolo de Comportamiento (Reglas del Sistema)

Cada respuesta de prompts/get de este servidor MCP incluye un Protocolo de Comportamiento compartido como mensaje del sistema (implementado en src/prompts/behavioral-protocol.ts). Este protocolo exige:

• Código mínimo, listo para producción y autodocumentado, con un enfoque de seguridad primero.

• Sin palabras de moda, emojis innecesarios ni relleno; respuestas directas y técnicamente precisas.

• Profundidad de respuesta adaptativa según la solicitud del usuario (respuestas rápidas frente a desgloses complejos).

• Uso coherente de mejores prácticas validadas para sistemas, programación, UI/UX y diseño.

Los clientes que integren este servidor MCP deben tratar el primer mensaje del sistema como las reglas que rigen cualquier modelo posterior que utilice estos prompts.

Ejemplos de Uso

Configuración de Project Guardian

// Initialize the project memory system
const initResult = await mcpClient.callTool('initialize_memory', {});

// Create your first project entities
const entityResult = await mcpClient.callTool('create_entity', {
  entities: [
    {
      name: 'web_platform',
      entityType: 'project',
      observations: ['Main web application platform', 'React + Node.js stack', 'Q2 2024 delivery']
    },
    {
      name: 'user_authentication',
      entityType: 'feature',
      observations: ['OAuth2 implementation', 'Google/GitHub providers', 'JWT tokens']
    }
  ]
});

// Establish project relationships
const relationResult = await mcpClient.callTool('create_relation', {
  relations: [
    {
      from: 'user_authentication',
      to: 'web_platform',
      relationType: 'part_of'
    }
  ]
});

Flujo de Trabajo de Gestión de Proyectos

// Add progress observations
await mcpClient.callTool('add_observation', {
  observations: [
    {
      entityName: 'user_authentication',
      contents: [
        'Completed OAuth2 setup for Google provider',
        'JWT implementation finished',
        'Unit tests passing at 95% coverage'
      ]
    }
  ]
});

// Search project knowledge
const searchResult = await mcpClient.callTool('search_nodes', {
  query: 'authentication'
});

// Read entire project knowledge graph
const graphResult = await mcpClient.callTool('read_graph', {});

// Get detailed entity information
const entityDetails = await mcpClient.callTool('open_node', {
  names: ['user_authentication', 'web_platform']
});

Operaciones de Base de Datos

// Execute custom SQL queries
const sqlResult = await mcpClient.callTool('execute_sql', {
  query: 'SELECT * FROM entities WHERE entity_type = ?',
  parameters: ['project']
});

// Query project data
const queryResult = await mcpClient.callTool('query_data', {
  table: 'entities',
  conditions: { entity_type: 'task' },
  limit: 10
});

// Import/export data
const importResult = await mcpClient.callTool('import_data', {
  table: 'project_data',
  filePath: './project_backup.csv',
  format: 'csv'
});

Configuración

Variables de Entorno

El servidor lee estas variables al iniciarse:

Los clientes MCP lanzan servidores con su propio directorio de trabajo, que a menudo es su carpeta de inicio en lugar del proyecto que está editando. En esa situación, la detección de Git no puede encontrar el proyecto y cada sesión escribe en la base de datos de respaldo compartida. Hay dos formas de solucionarlo:

1. Establezca GUARDIAN_PROJECT_ROOT en la configuración MCP del proyecto (consulte los ejemplos de clientes a continuación).

2. Llame a la herramienta set_project_root con la ruta absoluta del proyecto al inicio de la sesión; no se necesitan cambios de configuración. El cambio se aplica al servidor en ejecución; establezca la variable de entorno si desea que se aplique automáticamente a todas las sesiones futuras.

Servicios de Ejecución Opcionales

Redis es opcional y nunca se contacta durante el arranque. Configúralo solo cuando se necesiten las herramientas de caché:

{
  "env": {
    "REDIS_URL": "redis://localhost:6379/0"
  }
}

Trivy se localiza en PATH cuando se llama a scan_container_image. La ausencia de Redis o Trivy solo afecta a sus herramientas asociadas; las herramientas de memory, database, guidance, session, Git, wall y project-secret siguen disponibles.

El catálogo del companion informa de available, optional o unavailable para cada capacidad de runtime. El servidor usa transporte stdio y no expone un listener HTTP.

Para Cursor IDE

Añade este servidor a tu configuración MCP de Cursor (~/.cursor/mcp.json). Sustituye el valor de GUARDIAN_PROJECT_ROOT por el proyecto al que pertenece esta configuración:

{
  "mcpServers": {
    "project-guardian": {
      "command": "node",
      "args": ["/path/to/project-guardian-mcp-server/dist/index.js"],
      "env": {
        "GUARDIAN_PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

Para Claude Desktop

Añade este servidor a tu configuración de Claude Desktop (claude_desktop_config.json), siguiendo el mismo patrón:

{
  "mcpServers": {
    "project-guardian": {
      "command": "node",
      "args": ["/path/to/project-guardian-mcp-server/dist/index.js"],
      "env": {
        "GUARDIAN_PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

Estructura del proyecto

project-guardian-mcp-server/
├── src/
│   ├── index.ts              # Main entry point
│   ├── server.ts             # MCP server orchestrator
│   ├── memory-manager.ts     # Knowledge graph and FTS5 RAG semantic search
│   ├── sqlite-manager.ts     # Database operations and connection management
│   ├── import-export.ts      # CSV/JSON data import and export functionality
│   ├── ui-manager.ts         # On-Demand Web UI server and port finder
│   ├── types.ts              # TypeScript type definitions and schemas
│   ├── handlers/
│   │   └── request-handlers.ts # Central tool execution dispatcher
│   ├── tools/
│   │   ├── tool-registry.ts     # Tool definitions and listing
│   │   ├── database-tools.ts    # Database operation tool schemas
│   │   ├── memory-tools.ts      # Memory management tool schemas
│   │   ├── guidance-tools.ts    # Guidance tool schema
│   │   └── runtime-tools.ts     # Companion runtime tool schemas
│   ├── runtime/
│   │   ├── path-guard.ts        # Workspace path containment
│   │   └── runtime-capabilities.ts # Native companion implementations
│   ├── resources/
│   │   ├── resource-registry.ts  # Resource definitions and handlers
│   │   ├── resource-definitions.ts # Static resource metadata
│   │   ├── resource-handlers.ts   # Dynamic resource content generation
│   │   └── companion-catalog.ts   # Companion capability health
│   └── prompts/
│       ├── prompt-registry.ts       # Prompt definitions and handlers
│       ├── prompt-definitions.ts    # Static prompt metadata
│       ├── prompt-handlers.ts       # Dynamic prompt content generation
│       └── behavioral-protocol.ts   # Shared Behavioral Protocol system prompt
├── ui/                       # On-Demand Web UI frontend (Vite/React)
│   ├── src/
│   │   ├── App.tsx           # Main CRT-themed node graph visualization
│   │   ├── main.tsx          # React DOM entry point
│   │   └── index.css         # Styling, CRT scanlines, and CSS variables
│   └── vite.config.ts        # Vite build configuration
├── __tests__/                # Comprehensive test suite
│   ├── tool-registry.test.ts
│   ├── resource-registry.test.ts
│   ├── prompt-registry.test.ts
│   ├── request-handlers.test.ts
│   ├── runtime-capabilities.test.ts
│   ├── import-export.test.ts
│   ├── sqlite-manager.test.ts
│   └── bug-fixes.test.ts
├── skills/                   # Six distributable guardian-* AgentSkills
├── dist/                     # Ignored production build output
├── memory.db                 # Ignored local SQLite state, created on first run
├── package.json              # Project dependencies and scripts
├── package.prod.json         # Production-only dependencies for smaller bundle
├── tsconfig.json            # TypeScript configuration
├── jest.config.js           # Test configuration
└── README.md                # This documentation

Componentes clave

• server.ts: ciclo de vida del servidor MCP, transporte, handlers y coordinación del apagado

• handlers/request-handlers.ts: despachador central que enruta las llamadas a herramientas hacia los gestores adecuados

• tools/: sistema de definición y registro de herramientas (34 herramientas en total)

  • tool-registry.ts: lista todas las herramientas disponibles (7 DB + 10 memory + 1 guidance + 12 runtime + 3 UI)

  • database-tools.ts: esquemas de operaciones de base de datos (7 herramientas)

  • memory-tools.ts: esquemas de gestión de memoria (10 herramientas)

  • guidance-tools.ts: esquema de la herramienta de guía autónoma (1 herramienta)

  • runtime-tools.ts: esquemas tipados de capacidades del companion (12 herramientas)

• runtime/: guards de workspace e implementaciones del runtime companion

• resources/: sistema de gestión de recursos (11 recursos en total)

  • resource-registry.ts: listado de recursos y servicio de contenido

  • resource-definitions.ts: metadatos estáticos de recursos

  • resource-handlers.ts: generación dinámica de contenido

• prompts/: sistema de gestión de prompts (27 prompts en total)

  • prompt-registry.ts: listado de prompts y servicio de contenido

  • prompt-definitions.ts: metadatos estáticos de prompts

  • prompt-handlers.ts: generación dinámica de prompts con contexto

  • behavioral-protocol.ts: mensaje de sistema del Behavioral Protocol centralizado utilizado por todos los prompts

• memory-manager.ts: operaciones de grafo de conocimiento para entidades, relaciones y observaciones

• sqlite-manager.ts: abstracción de base de datos con caché de conexiones acotada y gestión de esquemas

• import-export.ts: utilidades de transferencia de datos CSV, JSON y SQL

• types.ts: esquemas Zod para la validación de entradas y la seguridad de tipos de TypeScript

• skills/: flujos de trabajo, scripts, referencias y recursos del lado del agente para los seis paquetes companion

Estado local

memory.db y sus sidecars memory.db-* son estado de runtime y Git los ignora. Cada proyecto mantiene su propia base de datos en su raíz de proyecto resuelta (consulta Variables de Entorno); los proyectos fuera de cualquier repositorio Git sin una raíz explícita comparten la base de datos de respaldo en $XDG_DATA_HOME/project-guardian. Además, cada escritura de memoria se replica en la base de datos central en ~/memory/memory.db, que es una fusión entre proyectos: eliminar una entidad en un proyecto no la elimina de la copia central, así que trata la base de datos central como un agregado consultable y no como una copia de seguridad por proyecto. Las instantáneas diarias se guardan en ~/memory/backup/. Un clon comienza sin memoria de proyecto; el servidor crea la base de datos y el esquema localmente en la primera ejecución. Haz una copia de seguridad o exporta la memoria explícitamente cuando deba trasladarse entre máquinas. Nunca hagas commit de la base de datos porque las observaciones pueden contener contexto privado del proyecto.

Las herramientas de database (execute_sql, query_data, insert_data, update_data, delete_data, import_data, export_data) aceptan un selector database: project (predeterminado) apunta a la base de datos del proyecto activo, central apunta al agregado.

Desarrollo

1. Clona el repositorio:

git clone https://github.com/1999AZZAR/project-guardian-mcp-server.git
cd project-guardian-mcp-server

2. Instala las dependencias:

npm install

3. Compila el proyecto: Para desarrollo activo (con vigilancia de archivos):

npm run dev

Para una compilación estándar:

npm run build

Para una compilación optimizada para producción:

npm run build:prod

4. Ejecuta los tests:

npm test

5. Inicia el servidor:

npm start

Licencia

MIT License: consulta el archivo LICENSE para más detalles.