Project Guardian MCP

一个用于持久化项目记忆、知识图谱操作、SQLite 数据访问、运行时安全检查以及引导式项目管理工作流的 Model Context Protocol（MCP）服务器。当前注册表公开了 34 个工具、11 个资源和 27 个提示词。

目录

• 功能特性

  • Project Guardian 记忆系统

  • 简化的数据库操作

  • 运行时伴生集成

  • AI 引导系统

  • 高级特性

  • 企业级特性

• 环境要求

• 安装

• 可用工具

  • 数据库操作（7 个工具）

  • 记忆与引导工具（11 个工具）

  • 运行时伴生工具（12 个工具）

  • UI 工具（4 个工具）

• AI 引导系统

  • 可用资源

  • 可用提示词

  • AI 模型如何使用引导

• 使用示例

  • Project Guardian 设置

  • 项目管理工作流

  • 数据库操作

• 配置

  • 可选运行时服务

  • 适用于 Cursor IDE

  • 适用于 Claude Desktop

• 项目结构

• 开发

• 许可证

Related MCP server: Engram

功能特性

Project Guardian 记忆系统

• 知识图谱：维护项目实体、关系和观察记录

• 实体管理：项目、任务、人员、资源，附带丰富的元数据

• 关系映射：依赖、归属、阻塞项和连接

• 观察跟踪：上下文备注和进度更新

• 语义搜索：通过 SQLite 原生的 FTS5 扩展（MATCH 和 bm25() 排序）在实体名称、类型和观察记录之间进行快速、本地化的 RAG 匹配

• 项目独立记忆：每个项目都有自己的 memory.db。服务器按以下顺序解析项目根目录：GUARDIAN_PROJECT_ROOT 环境变量，然后是工作目录的 Git 顶层目录，最后是 $XDG_DATA_HOME/project-guardian，作为任何 Git 仓库之外的共享回退位置

• 中央记忆镜像：每次记忆写入也会同步到位于 ~/memory/memory.db 的中央数据库，提供跨所有项目的聚合、可搜索地图，并在项目数据库不可用时作为回退。通过 read_graph 和 search_nodes 的读取会合并两个存储，项目条目优先

• 每日中央备份：每天首次同步时，中央数据库会被快照到 ~/memory/backup/ddmmyyyy_memory.db；保留最近七个备份，并自动清理更早的备份。首次运行时，主目录中的旧版 ~/memory.db 会被迁移到新布局，并用于生成第一个备份

• 按需 Pre-Commit 设置：启动时不会安装任何内容。当你希望在当前项目中生成 .pre-commit-config.yaml 和 Git 钩子时，调用 setup_pre_commit

• 按需 Web UI：通过 start_ui（以及 close_ui/stop_ui 释放端口）启动一个终端主题的交互式节点图，以可视化方式平移、搜索和探索项目状态。仅限桌面端，带移动端门控（<768px 遮罩层）、始终可见的实体浏览器、聚类的琥珀色圆球 → 展开为每个观察记录的青色圆球、游标流式 GET /api/graph/stream?cursor=&limit=500 + react-window 虚拟列表、>1k 物理冻结。

简化的数据库操作

• 两个存储，一个接口：每个项目使用自己的 memory.db；全部七个数据库工具也可以通过 database: "central" 访问中央聚合库

• 核心 CRUD：基本数据库操作（查询、插入、更新、删除）

• SQL 执行：直接执行 SQL 查询

• 数据传输：导入/导出 CSV 和 JSON 文件

• 共 34 个工具：七个数据库工具、十个记忆工具、一个引导工具、十二个运行时伴生工具和四个 UI/流工具（start_ui、close_ui、stop_ui、read_graph_stream）

运行时伴生集成

该仓库包含六个 guardian-* AgentSkills，并通过类型化的 MCP 工具公开其操作能力：

AgentSkills 提供宿主侧的工作流和指令。MCP 运行时直接在 TypeScript 中实现相应的操作，但容器扫描除外，它通过有界的外部进程调用 Trivy。不暴露任何通用的脚本或 shell 执行工具。

AI 引导系统

• 11 个资源：模板、最佳实践、项目状态和伴生能力健康度

• 27 个提示词：覆盖项目管理各个方面的全面预构建工作流

• 专家引导：针对复杂操作的分步说明

• 上下文帮助：基于用户需求的适应性提示词

• 知识库：全面的项目管理智慧

高级特性

• 模式验证：使用 Zod 模式进行全面的输入验证

• 错误处理：详细的错误消息和优雅的失败处理

• 连接管理：有界的 20 连接 LRU 缓存，采用 WAL + synchronous=NORMAL + cache_size=-64000 + journal_size_limit=67108864 + temp_store=MEMORY + busy_timeout=5000，每月 VACUUM（POST /api/vacuum）和关闭时清理

• 文件集成：CSV 和 SQL 导入采用流式处理；CSV 写入使用有界的字符串组装

• 结果限制与分页：无限制的原始 SELECT 上限为 10,000 行；read_graph/readStore 默认 5000，支持 ?limit=&offset=；read_graph_stream 通过 GET /api/graph/stream?cursor=&limit=& + POST /api/vacuum 实现游标 500/page；search_nodes 上限 100（混合 RRF k=60）

企业级特性

• TypeScript：完全类型化，并带有全面的错误处理

• 输入验证：对所有参数进行 Zod 模式验证

• 错误恢复：带有详细错误消息的优雅错误处理

• 资源管理：自动清理连接和资源

• 测试：十个 Jest 测试套件，93 个测试通过（WAL + 分页 + close_ui + read_graph_stream + e2e-vector hybrid）

环境要求

• Node.js：>= 18.0.0

• npm：最新稳定版

• SQLite3：作为依赖自动安装

• Redis：可选；仅通过 REDIS_URL 供 cache_* 工具使用

• Trivy：可选；仅 scan_container_image 需要

安装

1. 克隆仓库：

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

2. 安装依赖：

npm install

3. 构建项目： 在开发构建或生产构建之间选择：

用于开发（包含 source map 和完整的 TypeScript 编译）：

npm run build

用于生产（创建优化、压缩的 bundle）：

npm run build:prod

4. 运行测试套件：

npm test

5. 启动服务器：

npm start

变更后更新

当你拉取新更新或修改代码后，必须重新构建服务器并重启 MCP 客户端（Cursor、Claude Desktop 等），更改才会生效：

1. 拉取最新代码：git pull

2. 安装新依赖（如有）：npm install

3. 重新构建 bundle：npm run build:prod

4. 重要：重启你的 IDE 或 MCP 连接，以便客户端获取新更新的工具和提示词。

可用工具

此 MCP 服务器目前提供 34 个工具：

数据库操作（7 个工具）

所有数据库工具都接受可选的 database 选择器：project（默认）指向当前项目的 memory.db，central 指向位于 ~/memory/memory.db 的中央聚合库。

execute_sql - 执行 SQL 查询

在选定的记忆数据库上执行原始 SQL 查询。

参数：

• query（必填）：SQL 查询字符串

• parameters（可选）：查询参数数组

• database（可选）："project" 或 "central"，默认 "project"

query_data - 查询表数据

使用过滤和分页查询记忆表。

参数：

• table（必填）：表名

• conditions（可选）：WHERE 条件对象

• limit（可选）：返回的最大行数

• offset（可选）：跳过的行数

• orderBy（可选）：排序依据的列

• orderDirection（可选）：排序方向（"ASC" 或 "DESC"）

• database（可选）："project" 或 "central"，默认 "project"

insert_data - 插入记录

向记忆表插入记录。

参数：

• table（必填）：表名

• records（必填）：要插入的记录对象数组

• database（可选）："project" 或 "central"，默认 "project"

update_data - 更新记录

更新记忆表中的记录。

参数：

• table（必填）：表名

• conditions（必填）：要更新记录的 WHERE 条件

• updates（必填）：要更新的字段

• database（可选）："project" 或 "central"，默认 "project"

delete_data - 删除记录

从记忆表中删除记录。

参数：

• table（必填）：表名

• conditions（必填）：要删除记录的 WHERE 条件

• database（可选）："project" 或 "central"，默认 "project"

import_data - 导入数据

从 CSV 或 JSON 文件将数据导入记忆表。

参数：

• table（必填）：目标表名

• filePath（必填）：源文件路径

• format（可选）：文件格式（"csv" 或 "json"）

• options（可选）：导入选项（delimiter、hasHeader）

• database（可选）："project" 或 "central"，默认 "project"

export_data - 导出数据

将记忆表数据导出到 CSV 或 JSON 文件。

参数：

• table（必填）：源表名

• filePath（必填）：输出文件路径

• format（可选）：输出格式（"csv" 或 "json"）

• conditions（可选）：用于过滤导出的 WHERE 条件

• options（可选）：导出选项（delimiter、includeHeader）

• database（可选）："project" 或 "central"，默认为 "project"

记忆与指导工具（11 个工具）

initialize_memory - 初始化记忆系统

设置项目记忆数据库的模式和表。

参数： 无

create_entity - 创建项目实体

在项目知识图谱中创建实体（支持单个或批量）。

参数：

• entities（必填）：实体对象数组

  • name：实体名称

  • entityType：类型（project、task、person、resource）

  • observations：关于实体的备注数组

create_relation - 创建实体关系

在项目实体之间创建关系（支持单个或批量）。

参数：

• relations（必填）：关系对象数组

  • from：源实体名称

  • to：目标实体名称

  • relationType：关系类型（depends_on、blocks、owns 等）

add_observation - 添加实体观察

向项目实体添加观察/备注（支持单个或批量）。

参数：

• observations（必填）：观察对象数组

  • entityName：目标实体名称

  • contents：要添加的观察字符串数组

delete_entity - 删除项目实体

从项目记忆中移除实体及其关系（支持单个或批量）。

参数：

• entityNames（必填）：要删除的实体名称数组

delete_observation - 移除实体观察

从实体中移除特定的观察（支持单个或批量）。

参数：

• deletions（必填）：删除对象数组

  • entityName：目标实体名称

  • observations：要移除的观察字符串数组

delete_relation - 删除实体关系

移除项目实体之间的关系（支持单个或批量）。

参数：

• relations（必填）：要删除的关系对象数组

  • from：源实体名称

  • to：目标实体名称

  • relationType：要删除的关系类型

read_graph - 读取项目知识图谱

检索完整知识图谱，将活动项目数据库与中央聚合数据库合并。同名时项目条目优先于中央条目。支持分页。

参数：

• database（可选）："project"（默认，合并）、"central"（仅中央）

• limit（可选，1-10000，默认 5000）：返回的最大实体/关系数量，ORDER BY updated_at DESC

• offset（可选，0+）：跳过的行数

search_nodes - 搜索项目知识

在项目数据库和中央聚合数据库中，跨名称、类型和内容搜索与查询匹配的实体和关系。使用 FTS5 MATCH + bm25() 排序。

参数：

• query（必填）：搜索词

• limit（可选，1-100，默认 20）：返回的最大排序实体数量

open_node - 获取实体详情

检索项目实体的详细信息（支持单个或批量）。

参数：

• names（必填）：要检索的实体名称数组

get_project_guidance - 访问 AI 指导

调用项目指导框架，以获取针对特定工作流的专门说明和检查清单。这使 AI 能够自主获取并遵循既定的项目管理协议。

参数：

• guidance_name（必填）：指导名称（例如 project-setup、sprint-planning）

• arguments（可选）：特定指导框架所需的参数

运行时伴生工具（12 个工具）

sync_central_memory

将活动项目知识图谱复制到中央记忆数据库（默认 ~/memory/memory.db，可通过 GUARDIAN_CENTRAL_DB 覆盖）。实体进行 upsert，关系去重，因此中央数据库会累积跨所有项目的可搜索映射。每次记忆写入也会自动同步；调用此工具可按需强制同步。每天首次同步时还会对中央数据库进行快照，并清理最新七个以外的旧备份。

set_project_root

将活动项目记忆数据库切换到给定的绝对项目路径。当服务器在项目目录之外启动时，请在会话开始时使用此工具，以便将记忆写入项目而不是共享的回退数据库。

• path（必填）：项目根的绝对路径。在 Git 仓库内，使用顶层目录。

setup_pre_commit

按需在活动项目根目录创建 .pre-commit-config.yaml 并安装 Git 钩子。需要已安装 pre-commit。生成的 .gitignore 条目有意保持宽泛：除了 memory.db 之外，该块还忽略常见的本地工具目录，如 .claude/、.vscode/、.idea/、.gemini/ 和 .cursor/，以及 .env 文件。.gitignore 中已存在的条目绝不会重复。服务器在启动时绝不会自动执行这些操作。

get_session_context

直接从知识图谱总结活动任务、未解决的缺陷、最近的更改、阻塞项和下一步建议操作。

• limit（可选，1-50，默认 10）：每个结果组的最大条目数。

analyze_git_changes

从 Git 返回精确的机器可读更改路径，包括重命名和可选的未跟踪文件。

• commit（可选）：分析一个提交与其父提交的差异。

• since（可选，默认 1）：分析自 N 个提交之前或某个 Git 日期以来的更改。

• includeUntracked（可选，默认 true）：为工作树分析包含未跟踪文件。

• maxFiles（可选，1-500，默认 100）：限制返回的路径数量。

• commit 和自定义 since 值互斥。

inspect_untrusted_text

规范化最多 256 KiB 的不可信文本，并检测隐藏格式、指令覆盖、角色模仿、隐藏的 HTML/CSS、远程外泄标记以及编码的类指令内容。

• text（必填）：外部或其他不可信内容。

• 检测是启发式的。返回的规范化文本仍然是不可信数据。

scan_project_secrets

扫描工作区相对路径下的文件或目录，查找可能硬编码的凭据。结果仅包含类型、相对文件路径和行号；绝不返回匹配的值。

• path（可选，默认 .）：工作区相对扫描目标。

• exclude（可选）：要跳过的其他目录名称。

• maxFindings（可选，1-500，默认 100）：限制发现数量。

• 绝对路径、路径遍历、不存在的路径和符号链接逃逸均被拒绝。

scan_container_image

运行有时间限制的 Trivy 扫描，并返回有数量限制的 HIGH/CRITICAL 漏洞摘要。

• image（必填）：容器镜像引用。

• maxFindings（可选，1-500，默认 100）：限制发现数量。

• 需要 Trivy。以 - 开头、包含空白字符或包含控制字符的镜像值均被拒绝。

Redis 缓存工具

• cache_get：读取一个 mema:<category>:<name> 键。

• cache_set：存储最大 512 KiB 的值，可选的 ttlSeconds 范围为 1 到 604800。

• cache_delete：删除一个带命名空间的键。

• cache_scan：以有界数量游标扫描 mema:* 模式。

项目扫描路径限制在当前 Git 工作区内。Redis 工具采用惰性连接，当 REDIS_URL 未设置时返回不可用错误。容器扫描在安装 Trivy 之前保持不可用。阅读 project-guardian://companions/catalog 以了解当前能力健康状况。

UI 工具（4 个工具）

start_ui

启动按需的 Project Guardian Web UI 服务器，以便在浏览器中可视化浏览知识图谱。它会自动查找空闲端口（默认 3000，冲突时尝试 3001…）并返回本地 HTTP URL。UI 从 ui/dist 提供 CRT 主题的力导向图，并带有正确的静态路径回退（ui/dist → MCPservers/.../ui/dist）。

• 参数： 无

• 返回： UI Server successfully started on http://localhost:<port>

• 特性： 仅桌面端（移动端门槛为 <768px），实体浏览器始终可见，观察球体（聚集的琥珀色 → 展开为青色），/api/graph/* 上支持分页的 ?limit=&offset=。

close_ui / stop_ui

如果 Web UI 服务器正在运行，则停止它并释放端口。

• 参数： 无

• 返回： UI Server stopped

• stop_ui 是 close_ui 的别名。

AI 指导系统

Project Guardian MCP 包含全面的资源和提示，以帮助 AI 模型有效使用该工具集进行项目管理。

可用资源

Project Guardian 提供 11 个关键资源，AI 模型可以阅读这些资源来理解项目管理概念、访问能力健康状况并获取全面的项目洞察：

project-guardian://templates/entity-types

用于项目管理的标准实体类型，包含示例和使用指南。

project-guardian://templates/relationship-types

项目实体之间的常见关系类型，包含实用示例。

project-guardian://templates/project-workflows

在不同场景下使用 Project Guardian 工具的标准工作流。

project-guardian://templates/best-practices

有效项目知识管理的全面最佳实践指南。

project-guardian://status/current-graph

项目知识图谱的当前状态及汇总统计。

project-guardian://cache/recent-activities

最近执行的项目管理活动和更新，用于跟踪进度。

project-guardian://cache/workflow-templates

常用工作流模板，包含示例和实施指南。

project-guardian://metrics/project-stats

项目实体、关系和活动的统计概览，包含健康指标。

project-guardian://cache/team-members

关于项目团队成员及其在组织内角色的缓存信息。

project-guardian://status/recent-changes

知识图谱最近的添加、更新和修改，用于审计和监控。

project-guardian://companions/catalog

列出全部六个伴生工具、它们的 MCP 工具、外部先决条件和当前可用性。

可用提示

Project Guardian 提供 27 个提示，涵盖项目设置、规划、质量、运营和事件工作流：

核心项目管理

project-setup - 项目初始化

参数：

• project_name（必填）：项目名称

• team_members（可选）：逗号分隔的团队成员列表

提供逐步指导，用于建立具有适当实体和关系的新项目结构。

sprint-planning - 冲刺规划

参数：

• sprint_name（必填）：冲刺的名称/编号

• duration_days（可选）：冲刺持续时间（天）

指导完成全面的冲刺规划，包括任务分解、依赖关系和容量规划。

progress-update - 进度跟踪

参数：

• task_name（必填）：要更新的任务名称

• progress_notes（必填）：进度更新描述

用于更新任务进度和管理依赖关系的结构化流程。

retrospective - 项目回顾

参数：

• time_period（必填）：正在回顾的时间段（例如 "last sprint"、"Q1"）

全面的回顾流程，包括数据分析、模式识别和改进行动创建。

质量与流程管理

code-review - 代码审查流程

参数：

• pull_request_title（必填）：正在审查的拉取请求的标题

• reviewer_name（可选）：审查者姓名

结构化的代码审查流程，包含技术检查清单、问题文档和审批工作流。

bug-tracking - 缺陷管理

参数：

• bug_description（必填）：缺陷或问题的描述

• severity_level（可选）：严重程度：Critical、High、Medium 或 Low

从发现到解决的完整缺陷跟踪工作流，包含影响分析和干系人沟通。

technical-debt-assessment - 技术债务分析

参数：

• component_name（必填）：被评估的组件或代码库的名称

• assessment_scope（可选）：评估范围（file、module、system）

全面的技术债务识别、优先级排序和修复规划。

发布与部署管理

release-planning - 发布规划

参数：

• release_version（必填）：发布版本号（例如 "v2.1.0"）

• release_date（可选）：目标发布日期

完整的发布规划流程，包括质量门禁、风险评估和部署协调。

风险与变更管理

risk-assessment - 风险管理

参数：

• risk_description（必填）：风险的描述

• impact_level（可选）：影响程度：High、Medium 或 Low

用于记录风险、识别影响和制定缓解策略的完整工作流。

change-management - 变更控制

参数：

• change_description（必填）：拟议变更的描述

• impact_assessment（可选）：影响评估：High、Medium 或 Low

结构化的变更管理流程，包含影响分析、审批工作流和实现跟踪。

团队与资源管理

team-productivity - 生产力分析

参数：

• timeframe（必填）：要分析的时间段（week、month、quarter）

• focus_area（可选）：重点关注领域（velocity、quality、collaboration）

团队生产力评估，包含性能指标、根本原因分析和改进规划。

resource-allocation - 资源规划

参数：

• resource_type（必填）：资源类型（human、infrastructure、budget）

• planning_horizon（可选）：规划时间范围（sprint、quarter、year）

资源分配优化，包含容量规划、差距分析和利用率跟踪。

文档与沟通

stakeholder-communication - 沟通管理

参数：

• communication_type（必填）：沟通类型（status_update、issue_alert、milestone_reached）

• audience（可选）：目标受众（team、management、client、all）

干系人沟通规划与执行，包含针对特定受众的策略和效果跟踪。

documentation-management - 文档更新

参数：

• documentation_type（必填）：文档类型（api、user_guide、technical_spec）

• update_reason（可选）：文档更新的原因

文档维护流程，包含内容规划、评审工作流和发布协调。

需求与规划管理

requirements-gathering - 需求收集

参数：

• requirement_type（必填）：需求类型（functional、non-functional、business、technical）

• stakeholders（可选）：关键干系人的逗号分隔列表

引导完成全面的需求收集流程，包含干系人管理和需求分类。

user-story-management - 用户故事管理

参数：

• feature_name（必填）：功能或史诗（epic）的名称

• user_role（可选）：主要用户角色（例如 "customer"、"admin"、"developer"）

用于创建、管理和优先级排序用户故事的结构化流程，包含验收标准和依赖关系。

质量与技术管理

testing-strategy - 测试策略制定

参数：

• application_type（必填）：应用程序类型（web、mobile、api、desktop）

• criticality_level（可选）：业务关键程度（critical、high、medium、low）

全面的测试策略制定，包括自动化测试、质量门禁和基于风险的测试。

security-assessment - 安全评估

参数：

• assessment_scope（必填）：安全评估范围（application、infrastructure、data）

• compliance_requirements（可选）：合规标准（GDPR、HIPAA、SOC2 等）

安全评估框架，包含漏洞管理、合规性验证和安全控制实施。

performance-optimization - 性能优化

参数：

• performance_metric（必填）：要优化的主要指标（response_time、throughput、resource_usage）

• optimization_goal（可选）：具体的性能目标或改进百分比

性能监控设置、瓶颈识别和优化实施，并持续监控。

ci-cd-setup - CI/CD 流水线设置

参数：

• pipeline_type（必填）：流水线类型（build、test、deploy、full_ci_cd）

• target_platform（可选）：部署目标（aws、azure、gcp、kubernetes、heroku）

完整的 CI/CD 流水线设置，包括质量门禁、回滚流程和安全集成。

architecture-review - 架构评审

参数：

• architecture_type（必填）：架构类型（microservices、monolithic、serverless、hybrid）

• review_focus（可选）：主要关注领域（scalability、security、maintainability、performance）

架构评估框架，包含设计模式分析、技术栈评估和改进建议。

知识与团队管理

knowledge-transfer - 知识转移

参数：

• knowledge_domain（必填）：知识领域（technical、process、business）

• transfer_recipients（可选）：需要接收知识的人员（team、individual、department）

知识转移规划与执行，包含会议管理、文档和有效性验证。

vendor-management - 供应商管理

参数：

• vendor_type（必填）：供应商服务类型（cloud、development、consulting、infrastructure）

• contract_value（可选）：合同价值范围（small、medium、large、enterprise）

供应商关系管理，包括合同跟踪、性能监控和成本优化。

事件与危机管理

incident-response - 事件响应

参数：

• incident_severity（必填）：严重程度（critical、high、medium、low）

• incident_type（可选）：事件类型（security、performance、functionality、availability）

事件响应框架，包含遏制、恢复、根本原因分析和事后回顾。

财务与资源管理

cost-management - 成本管理

参数：

• cost_category（必填）：主要成本类别（infrastructure、personnel、tools、licenses）

• budget_constraint（可选）：预算约束级别（strict、flexible、unlimited）

成本监控、优化策略和预算管理，包含预测和报告。

客户与创新管理

customer-feedback - 客户反馈管理

参数：

• feedback_channel（必填）：主要反馈渠道（survey、support、reviews、analytics）

• feedback_focus（可选）：关注领域（usability、features、performance、support）

客户反馈收集、分析和行动规划，包含持续改进循环。

innovation-planning - 创新规划

参数：

• innovation_type（必填）：创新类型（product、process、technology、business_model）

• risk_tolerance（可选）：风险承受级别（conservative、moderate、aggressive）

创新管理框架，包含创意生成、实验和成功衡量。

AI 模型如何使用指南

1. 发现：列出可用资源和提示，以了解能力

2. 学习：阅读相关资源，以了解项目管理概念

3. 规划：对复杂工作流使用适当的提示

4. 执行：遵循结构化指南，以有效使用工具

5. 验证：检查结果并根据需要迭代 该指南系统确保 AI 模型能够使用 Project Guardian 工具集提供专家级的项目管理协助。

行为协议（系统规则）

此 MCP 服务器的每个 prompts/get 响应都包含一个共享的 行为协议 作为系统消息（在 src/prompts/behavioral-protocol.ts 中实现）。该协议强制要求：

• 采用安全优先的方法，编写最小化、生产就绪、自文档化的代码。

• 不使用流行语、不必要的表情符号或填充内容；直接、技术准确的回答。

• 根据用户的请求自适应响应深度（快速回答 vs. 复杂分解）。

• 在系统、编程、UI/UX 和设计方面持续使用经过验证的最佳实践。

集成此 MCP 服务器的客户端应将第一条系统消息视为使用这些提示的任何下游模型的管理规则。

使用示例

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'
    }
  ]
});

项目管理工作流

// 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']
});

数据库操作

// 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'
});

配置

环境变量

服务器在启动时读取以下变量：

MCP 客户端会使用自己的工作目录启动服务器，该目录通常是您的主文件夹，而不是您正在编辑的项目。在这种情况下，Git 检测无法找到项目，每个会话都会写入共享回退数据库。有两种修复方法：

1. 在项目的 MCP 配置中设置 GUARDIAN_PROJECT_ROOT（请参阅下面的客户端示例）。

2. 在会话开始时调用 set_project_root 工具并传入项目绝对路径——无需编辑配置。此切换仅适用于正在运行的服务器；如果您希望它自动应用于未来的每个会话，请设置环境变量。

可选运行时服务

Redis 是可选的，启动时绝不会被连接。仅在需要缓存工具时才进行配置：

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

调用 scan_container_image 时，会从 PATH 中发现 Trivy。缺少 Redis 或 Trivy 只会影响与其关联的工具；内存、数据库、指导、会话、Git、wall 和项目密钥工具仍然可用。

配套目录会为每项运行时能力报告 available、optional 或 unavailable。服务器使用 stdio 传输，不暴露 HTTP 监听器。

适用于 Cursor IDE

将此服务器添加到你的 Cursor MCP 配置（~/.cursor/mcp.json）中。将 GUARDIAN_PROJECT_ROOT 的值替换为该配置所属的项目：

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

适用于 Claude Desktop

按照同样的模式，将此服务器添加到你的 Claude Desktop 配置（claude_desktop_config.json）中：

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

项目结构

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

关键组件

• server.ts：MCP 服务器生命周期、传输、处理器和关闭协调

• handlers/request-handlers.ts：中央调度器，负责将工具调用路由到相应的管理器

• tools/：工具定义与注册系统（共 34 个工具）

  • tool-registry.ts：列出所有可用工具（7 个数据库 + 10 个内存 + 1 个指导 + 12 个运行时 + 3 个 UI）

  • database-tools.ts：数据库操作模式（7 个工具）

  • memory-tools.ts：内存管理模式（10 个工具）

  • guidance-tools.ts：自主指导工具模式（1 个工具）

  • runtime-tools.ts：类型化配套能力模式（12 个工具）

• runtime/：工作区守卫和配套运行时实现

• resources/：资源管理系统（共 11 个资源）

  • resource-registry.ts：资源列表与内容提供

  • resource-definitions.ts：静态资源元数据

  • resource-handlers.ts：动态内容生成

• prompts/：提示管理系统（共 27 个提示）

  • prompt-registry.ts：提示列表与内容提供

  • prompt-definitions.ts：静态提示元数据

  • prompt-handlers.ts：带上下文的动态提示生成

  • behavioral-protocol.ts：集中式行为协议系统消息，供所有提示使用

• memory-manager.ts：针对实体、关系和观察的知识图谱操作

• sqlite-manager.ts：具有有界连接缓存和模式管理的数据库抽象

• import-export.ts：CSV、JSON 和 SQL 数据传输工具

• types.ts：用于输入验证和 TypeScript 类型安全的 Zod 模式

• skills/：面向六个配套包的智能体端工作流、脚本、参考资料和资产

本地状态

memory.db 及其 memory.db-* 伴生文件属于运行时状态，会被 Git 忽略。每个项目都在其解析出的项目根目录下维护自己的数据库（参见环境变量）；位于任何 Git 仓库之外且没有显式根目录的项目，共享 $XDG_DATA_HOME/project-guardian 下的回退数据库。此外，每次内存写入都会镜像到位于 ~/memory/memory.db 的中央数据库，该数据库是跨项目的合并结果：删除一个项目中的实体并不会将其从中央副本中移除，因此请将中央数据库视为可搜索的聚合库，而非按项目的备份。每日快照存放在 ~/memory/backup/。克隆的仓库初始没有任何项目内存；服务器会在首次运行时在本地创建数据库和模式。当内存需要在机器之间迁移时，请显式备份或导出内存。切勿提交数据库，因为观察可能包含私有项目上下文。

数据库工具（execute_sql、query_data、insert_data、update_data、delete_data、import_data、export_data）接受一个 database 选择器：project（默认）指向当前活动的项目数据库，central 指向聚合数据库。

开发

1. 克隆仓库：

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

2. 安装依赖：

npm install

3. 构建项目： 用于持续开发（带文件监听）：

npm run dev

对于标准构建：

npm run build

对于生产优化构建：

npm run build:prod

4. 运行测试：

npm test

5. 启动服务器：

npm start

许可证

MIT License - 详细信息请参阅 LICENSE 文件。