Project Guardian MCP

Part of the HeLa MCP Ecosystem — This server is HeLa Genome (hela-genome) — the State & Memory component of the HeLa cellular architecture. See the ecosystem docs for profiles, workflows, and multi-client setup.

A Model Context Protocol (MCP) server for persistent project memory, knowledge-graph operations, SQLite data access, runtime security checks, and guided project-management workflows. The current registry exposes 34 tools, 11 resources, and 27 prompts.

Table of Contents

• Features
  • Project Guardian Memory System
  • Streamlined Database Operations
  • Runtime Companion Integration
  • AI Guidance System
  • Advanced Features
  • Enterprise Features
• Requirements
• Installation
• Available Tools
  • Database Operations (7 tools)
  • Memory and Guidance Tools (11 tools)
  • Runtime Companion Tools (12 tools)
  • UI Tools (4 tools)
• AI Guidance System
  • Available Resources
  • Available Prompts
  • How AI Models Use Guidance
• Usage Examples
  • Project Guardian Setup
  • Project Management Workflow
  • Database Operations
• Configuration
  • Optional Runtime Services
  • For Cursor IDE
  • For Claude Desktop
• Project Structure
• Development
• License

Features

Project Guardian Memory System

• Knowledge Graph: Maintain project entities, relationships, and observations

• Entity Management: Projects, tasks, people, resources with rich metadata

• Relationship Mapping: Dependencies, ownership, blockers, and connections

• Observation Tracking: Contextual notes and progress updates

• Semantic Search: Fast, localized RAG matching via SQLite's native FTS5 extension (MATCH and bm25() ranking) across entity names, types, and observations

• Per-Project Memory: Each project gets its own memory.db. The server resolves the project root in this order: the GUARDIAN_PROJECT_ROOT environment variable, then the Git toplevel of its working directory, then $XDG_DATA_HOME/project-guardian as a shared fallback outside any Git repository

• Central Memory Mirror: Every memory write also syncs into one central database at ~/memory/memory.db, giving an aggregated, searchable map across all projects and a fallback when a project database is unavailable. Reads through read_graph and search_nodes merge both stores, with project entries taking precedence

• Daily Central Backups: On the first sync of each day, the central database is snapshotted to ~/memory/backup/ddmmyyyy_memory.db; the seven most recent backups are kept and older ones pruned automatically. On first run, a legacy ~/memory.db in the home directory is migrated into the new layout and used to seed the first backup

• On-Demand Pre-Commit Setup: Nothing is installed at startup. Call setup_pre_commit when you want a generated .pre-commit-config.yaml and Git hooks in the active project

• On-Demand Web UI: Launch a terminal-themed interactive node graph via start_ui (and close_ui/stop_ui to free the port) to visually pan, search, and explore the project state. Desktop-only with mobile gate (<768px overlay), always-visible entity browser, clustered amber orbs → expand to cyan per-observation, cursor-streamed GET /api/graph/stream?cursor=&limit=500 + react-window virtual list, >1k physics freeze.

Harness Session Bridge

• Read-only ingestion from 8 agent harnesses: opencode, kilocode, zed, delta, antigravity, cursor, vscode, codex. Sources are opened read-only (SQLite OPEN_READONLY, capped JSONL scans) — the bridge never writes to harness stores and never touches harness processes.
• What's harvested: session titles, summaries/previews, timestamps, project directories, models, message/step counts. Full transcripts and binaries are never ingested.
• Secret redaction first: API keys, tokens, bearer credentials, private keys, and password assignments are replaced with [REDACTED] before anything reaches the graph.
• Incremental + idempotent: per-session watermarks in a harness_sync table — re-runs only pick up new or updated sessions; dryRun previews without writing.
• Absent stores are honest: harnesses with no local store on the machine (e.g. Cursor/VS Code when not installed) report found: false instead of failing. Store paths are overridable via HARNESS_<ID>_PATH.

Streamlined Database Operations

• Two Stores, One Interface: Every project uses its own memory.db; all seven database tools can also address the central aggregate with database: "central"
• Core CRUD: Essential database operations (query, insert, update, delete)
• SQL Execution: Direct SQL query execution
• Data Transfer: Import/export CSV and JSON files
• 34 Tools Total: Seven database tools, ten memory tools, one guidance tool, twelve runtime companion tools, and four UI/stream tools (start_ui, close_ui, stop_ui, read_graph_stream)

Runtime Companion Integration

The repository includes six guardian-* AgentSkills and exposes their operational capabilities through typed MCP tools:

| Companion | Runtime role | MCP surface | | --- | --- | --- | | guardian-memory | Persistent entities, relations, and observations | Ten memory tools | | guardian-session | Active-task, bug, blocker, and recent-change summaries | get_session_context | | guardian-tracker | Bounded Git diff and untracked-file analysis | analyze_git_changes | | guardian-wall | Untrusted-text normalization and prompt-injection detection | inspect_untrusted_text | | guardian-security | Secret scanning and Trivy image scanning | scan_project_secrets, scan_container_image | | guardian-cache | Optional namespaced Redis storage | Four cache_* tools |

AgentSkills provide host-side workflows and instructions. The MCP runtime implements the corresponding operations directly in TypeScript, except container scanning, which invokes Trivy as a bounded external process. No generic script or shell execution tool is exposed.

AI Guidance System

• 11 Resources: Templates, best practices, project status, and companion capability health
• 27 Prompts: Comprehensive pre-built workflows for all aspects of project management
• Expert Guidance: Step-by-step instructions for complex operations
• Contextual Help: Adaptive prompts based on user needs
• Knowledge Base: Comprehensive project management wisdom

Advanced Features

• Schema Validation: Comprehensive input validation with Zod schemas
• Error Handling: Detailed error messages and graceful failure handling
• Connection Management: Bounded 20-connection LRU cache with WAL + synchronous=NORMAL + cache_size=-64000 + journal_size_limit=67108864 + temp_store=MEMORY + busy_timeout=5000, monthly VACUUM (POST /api/vacuum) and shutdown cleanup
• File Integration: CSV and SQL imports are streamed; CSV writes use bounded string assembly
• Result Limits & Pagination: Unbounded raw SELECT capped at 10,000 rows; read_graph/readStore default 5000 with ?limit=&offset=, read_graph_stream cursor 500/page via GET /api/graph/stream?cursor=&limit=& + POST /api/vacuum, search_nodes capped 100 (hybrid RRF k=60)

Enterprise Features

• TypeScript: Fully typed with comprehensive error handling
• Input Validation: Zod schema validation for all parameters
• Error Recovery: Graceful error handling with detailed error messages
• Resource Management: Automatic cleanup of connections and resources
• Testing: Ten Jest suites with 93 passing tests (WAL + pagination + close_ui + read_graph_stream + e2e-vector hybrid)

Requirements

• Node.js: >= 18.0.0
• npm: Latest stable version
• SQLite3: Automatically installed as dependency
• Redis: Optional; required only for cache_* tools through REDIS_URL
• Trivy: Optional; required only for scan_container_image

Installation

1. Clone the repository:

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

2. Install dependencies:

npm install

3. Build the project: Choose between development or production build:

For development (includes source maps and full TypeScript compilation):

npm run build

For production (creates an optimized, minified bundle):

npm run build:prod

4. Run the test suite:

npm test

5. Start the server:

npm start

Updating After Changes

When you pull new updates or modify the code, you must rebuild the server and restart your MCP client (Cursor, Claude Desktop, etc.) for the changes to take effect:

1. Pull the latest code: git pull
2. Install new dependencies (if any): npm install
3. Rebuild the bundle: npm run build:prod
4. Important: Restart your IDE or the MCP connection so the client can fetch the newly updated tools and prompts.

Available Tools

This MCP server currently provides 34 tools:

Database Operations (7 tools)

All database tools accept an optional database selector: project (default) targets the active project's memory.db, central targets the central aggregate at ~/memory/memory.db.

execute_sql - Execute SQL Query

Execute raw SQL queries on the selected memory database.

Parameters:

• query (required): SQL query string
• parameters (optional): Query parameters array
• database (optional): "project" or "central", default "project"

query_data - Query Table Data

Query memory tables with filtering and pagination.

Parameters:

• table (required): Table name
• conditions (optional): WHERE conditions object
• limit (optional): Maximum rows to return
• offset (optional): Number of rows to skip
• orderBy (optional): Column to sort by
• orderDirection (optional): Sort direction ("ASC" or "DESC")
• database (optional): "project" or "central", default "project"

insert_data - Insert Records

Insert records into a memory table.

Parameters:

• table (required): Table name
• records (required): Array of record objects to insert
• database (optional): "project" or "central", default "project"

update_data - Update Records

Update records in a memory table.

Parameters:

• table (required): Table name
• conditions (required): WHERE conditions for records to update
• updates (required): Fields to updat