Project Guardian MCP

Сервер Model Context Protocol (MCP) для постоянной памяти проектов, операций с графом знаний, доступа к данным SQLite, проверок безопасности в рантайме и управляемых рабочих процессов управления проектами. Текущий реестр предоставляет 34 инструмента, 11 ресурсов и 27 промптов.

Содержание

• Возможности

  • Система памяти Project Guardian

  • Упрощённые операции с базой данных

  • Интеграция с рантайм-компаньонами

  • Система ИИ-руководства

  • Расширенные возможности

  • Корпоративные возможности

• Требования

• Установка

• Доступные инструменты

  • Операции с базой данных (7 инструментов)

  • Инструменты памяти и руководства (11 инструментов)

  • Инструменты рантайм-компаньонов (12 инструментов)

  • UI-инструменты (4 инструмента)

• Система ИИ-руководства

  • Доступные ресурсы

  • Доступные промпты

  • Как ИИ-модели используют руководство

• Примеры использования

  • Настройка Project Guardian

  • Рабочий процесс управления проектом

  • Операции с базой данных

• Конфигурация

  • Дополнительные рантайм-сервисы

  • Для Cursor IDE

  • Для Claude Desktop

• Структура проекта

• Разработка

• Лицензия

Related MCP server: Engram

Возможности

Система памяти Project Guardian

• Граф знаний: поддержка сущностей проекта, связей и наблюдений

• Управление сущностями: проекты, задачи, люди, ресурсы с богатыми метаданными

• Сопоставление связей: зависимости, владельцы, блокирующие факторы и соединения

• Отслеживание наблюдений: контекстные заметки и обновления прогресса

• Семантический поиск: быстрый локальный RAG-поиск через встроенное расширение FTS5 в SQLite (MATCH и ранжирование bm25()) по именам сущностей, типам и наблюдениям

• Память по проектам: каждый проект получает собственный 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 по запросу: ничего не устанавливается при запуске. Вызовите setup_pre_commit, когда захотите получить сгенерированный .pre-commit-config.yaml и Git-хуки в активном проекте

• Веб-интерфейс по запросу: запустите интерактивный граф узлов в терминальной тематике через 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)

Интеграция с рантайм-компаньонами

Репозиторий включает шесть AgentSkills вида guardian-* и предоставляет их операционные возможности через типизированные MCP-инструменты:

AgentSkills предоставляют рабочие процессы и инструкции на стороне хоста. MCP-рантайм реализует соответствующие операции напрямую в TypeScript, за исключением сканирования контейнеров, которое вызывает Trivy как ограниченный внешний процесс. Никакого универсального инструмента выполнения скриптов или shell-команд не предоставляется.

Система ИИ-руководства

• 11 ресурсов: шаблоны, лучшие практики, статус проекта и состояние возможностей компаньонов

• 27 промптов: комплексные готовые рабочие процессы для всех аспектов управления проектами

• Экспертное руководство: пошаговые инструкции для сложных операций

• Контекстная помощь: адаптивные промпты на основе потребностей пользователя

• База знаний: всесторонняя мудрость управления проектами

Расширенные возможности

• Проверка схем: комплексная проверка входных данных с помощью Zod-схем

• Обработка ошибок: подробные сообщения об ошибках и корректная обработка сбоев

• Управление соединениями: ограниченный LRU-кэш на 20 соединений с 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 курсор 500/страница через GET /api/graph/stream?cursor=&limit=& + POST /api/vacuum, 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: опционально; требуется только для инструментов cache_* через REDIS_URL

• 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 maps и полную компиляцию TypeScript):

npm run build

Для продакшена (создаёт оптимизированный, минифицированный бандл):

npm run build:prod

4. Запустите набор тестов:

npm test

5. Запустите сервер:

npm start

Обновление после изменений

Когда вы получаете новые обновления или изменяете код, необходимо пересобрать сервер и перезапустить ваш MCP-клиент (Cursor, Claude Desktop и т. д.), чтобы изменения вступили в силу:

1. Получите последний код: git pull

2. Установите новые зависимости (если есть): npm install

3. Пересоберите бандл: 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 — Доступ к ИИ-руководствам

Вызывает фреймворк проектных руководств для получения специализированных инструкций и чек-листов для конкретных рабочих процессов. Это позволяет ИИ самостоятельно получать и соблюдать установленные протоколы управления проектами.

Параметры:

• guidance_name (обязательно): название руководства (например, project-setup, sprint-planning)

• arguments (необязательно): аргументы, требуемые конкретным фреймворком руководств

Инструменты компаньона времени выполнения (12 инструментов)

sync_central_memory

Копирует активный граф знаний проекта в центральную базу данных памяти (~/memory/memory.db по умолчанию, переопределяется через GUARDIAN_CENTRAL_DB). Сущности обновляются (upsert), связи дедуплицируются, поэтому центральная база данных накапливает доступную для поиска карту по всем проектам. Каждая запись в память также синхронизируется автоматически; вызывайте этот инструмент для принудительной синхронизации по требованию. Первая синхронизация каждого дня также создаёт снимок центральной базы данных и удаляет старые резервные копии, оставляя семь самых новых.

set_project_root

Переключает активную базу данных памяти проекта на указанный абсолютный путь проекта. Используйте это в начале сеанса, если сервер был запущен вне каталога проекта, чтобы память записывалась в проект, а не в общую резервную базу данных.

• path (обязательно): абсолютный путь к корню проекта. Внутри Git-репозитория используется верхний уровень (toplevel).

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 КиБ недоверенного текста и обнаруживает скрытое форматирование, переопределения инструкций, имитацию ролей, скрытые HTML/CSS, разметку удалённой эксфильтрации и закодированное содержимое, похожее на инструкции.

• text (обязательно): внешнее или иным образом недоверенное содержимое.

• Обнаружение эвристическое. Возвращаемый нормализованный текст остаётся недоверенными данными.

scan_project_secrets

Сканирует файл или каталог относительно рабочей области на предмет вероятных жёстко заданных учётных данных. Результаты содержат только тип, относительный путь к файлу и номер строки; совпавшие значения никогда не возвращаются.

• path (необязательно, по умолчанию .): цель сканирования относительно рабочей области.

• exclude (необязательно): дополнительные имена каталогов для пропуска.

• maxFindings (необязательно, 1-500, по умолчанию 100): ограничивает количество находок.

• Абсолютные пути, обход каталогов, отсутствующие пути и выходы через символьные ссылки отклоняются.

scan_container_image

Запускает сканирование Trivy с ограничением по времени и возвращает ограниченные сводки уязвимостей HIGH/CRITICAL.

• image (обязательно): ссылка на образ контейнера.

• maxFindings (необязательно, 1-500, по умолчанию 100): ограничивает количество находок.

• Требуется Trivy. Значения image, начинающиеся с -, содержащие пробелы или управляющие символы, отклоняются.

Инструменты кэша Redis

• cache_get: читает один ключ mema:<category>:<name>.

• cache_set: сохраняет значение размером до 512 КиБ с необязательным ttlSeconds от 1 до 604800.

• cache_delete: удаляет один ключ с пространством имён.

• cache_scan: курсорное сканирование шаблона mema:* с ограниченным количеством.

Пути сканирования проекта ограничены текущей рабочей областью Git. Инструменты Redis подключаются лениво и возвращают ошибку недоступности, если REDIS_URL не задан. Сканирование контейнеров остаётся недоступным, пока не установлен Trivy. Прочитайте project-guardian://companions/catalog для получения текущего состояния возможностей.

Инструменты UI (4 инструмента)

start_ui

Запускает по требованию сервер веб-интерфейса Project Guardian для визуального просмотра графа знаний в браузере. Он автоматически находит свободный порт (по умолчанию 3000, при коллизии пробует 3001…) и возвращает локальный HTTP-URL. Интерфейс обслуживает силовой граф в стиле CRT из ui/dist с корректным запасным статическим путём (ui/dist → MCPservers/.../ui/dist).

• Параметры: нет

• Возвращает: UI Server successfully started on http://localhost:<port>

• Возможности: только для настольных компьютеров (мобильный шлюз на <768px), браузер сущностей всегда виден, сферы наблюдений (янтарные в кластере → разворачиваются в голубые), пагинация ?limit=&offset= на /api/graph/*.

close_ui / stop_ui

Останавливает сервер веб-интерфейса, если он запущен, и освобождает порт.

• Параметры: нет

• Возвращает: UI Server stopped

• stop_ui — псевдоним для close_ui.

Система ИИ-руководств

Project Guardian MCP включает обширные ресурсы и промпты, помогающие моделям ИИ эффективно использовать набор инструментов для управления проектами.

Доступные ресурсы

Project Guardian предоставляет 11 ключевых ресурсов, которые модели ИИ могут читать, чтобы понимать концепции управления проектами, получать доступ к состоянию возможностей и получать всесторонние сведения о проектах:

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 (обязательно): рассматриваемый период времени (например, «последний спринт», «Q1»)

Всесторонний процесс ретроспективы, включающий анализ данных, выявление закономерностей и создание действий по улучшению.

Управление качеством и процессами

code-review — Процесс ревью кода

Аргументы:

• pull_request_title (обязательно): заголовок проверяемого pull request

• reviewer_name (необязательно): имя ревьюера

Структурированный процесс ревью кода с техническими чек-листами, документированием проблем и рабочими процессами утверждения.

bug-tracking — Управление ошибками

Аргументы:

• bug_description (обязательно): Описание ошибки или проблемы

• severity_level (необязательно): Критичность: Critical, High, Medium или Low

Полный рабочий процесс отслеживания ошибок от обнаружения до устранения с анализом влияния и коммуникацией с заинтересованными сторонами.

technical-debt-assessment — Анализ технического долга

Аргументы:

• component_name (обязательно): Название компонента или кодовой базы, для которой проводится оценка

• assessment_scope (необязательно): Область оценки (файл, модуль, система)

Комплексная идентификация технического долга, приоритизация и планирование исправлений.

Управление релизами и развертыванием

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 (обязательно): Период времени для анализа (неделя, месяц, квартал)

• focus_area (необязательно): Область фокуса (скорость, качество, сотрудничество)

Оценка продуктивности команды с метриками производительности, анализом корневых причин и планированием улучшений.

resource-allocation — Планирование ресурсов

Аргументы:

• resource_type (обязательно): Тип ресурса (человеческие, инфраструктура, бюджет)

• planning_horizon (необязательно): Горизонт планирования (спринт, квартал, год)

Оптимизация распределения ресурсов с планированием мощностей, анализом пробелов и отслеживанием использования.

Документация и коммуникация

stakeholder-communication — Управление коммуникациями

Аргументы:

• communication_type (обязательно): Тип коммуникации (status_update, issue_alert, milestone_reached)

• audience (необязательно): Целевая аудитория (команда, руководство, клиент, все)

Планирование и выполнение коммуникаций с заинтересованными сторонами с учетом специфики аудитории и отслеживанием эффективности.

documentation-management — Обновление документации

Аргументы:

• documentation_type (обязательно): Тип документации (api, user_guide, technical_spec)

• update_reason (необязательно): Причина обновления документации

Процесс поддержки документации с планированием содержимого, рабочими процессами рецензирования и координацией публикации.

Управление требованиями и планированием

requirements-gathering — Сбор требований

Аргументы:

• requirement_type (обязательно): Тип требований (функциональные, нефункциональные, бизнес-требования, технические)

• stakeholders (необязательно): Список ключевых заинтересованных сторон через запятую

Проводит через комплексный процесс сбора требований с управлением заинтересованными сторонами и категоризацией требований.

user-story-management — Управление пользовательскими историями

Аргументы:

• feature_name (обязательно): Название функции или эпика

• user_role (необязательно): Основная роль пользователя (например, "customer", "admin", "developer")

Структурированный процесс создания, управления и приоритизации пользовательских историй с критериями приемки и зависимостями.

Управление качеством и техническими аспектами

testing-strategy — Разработка стратегии тестирования

Аргументы:

• application_type (обязательно): Тип приложения (web, mobile, api, desktop)

• criticality_level (необязательно): Бизнес-критичность (critical, high, medium, low)

Комплексная разработка стратегии тестирования, включая автоматизированное тестирование, контроль качества и тестирование на основе рисков.

security-assessment — Оценка безопасности

Аргументы:

• assessment_scope (обязательно): Область оценки безопасности (приложение, инфраструктура, данные)

• 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 (обязательно): Тип архитектуры (микросервисы, монолитная, бессерверная, гибридная)

• review_focus (необязательно): Основная область фокуса (масштабируемость, безопасность, поддерживаемость, производительность)

Структура архитектурной оценки с анализом паттернов проектирования, оценкой технологического стека и рекомендациями по улучшению.

Управление знаниями и командой

knowledge-transfer — Передача знаний

Аргументы:

• knowledge_domain (обязательно): Область знаний (технические, процессные, бизнес-знания)

• transfer_recipients (необязательно): Кто должен получить знания (команда, отдельный сотрудник, отдел)

Планирование и выполнение передачи знаний с управлением сессиями, документацией и проверкой эффективности.

vendor-management — Управление поставщиками

Аргументы:

• vendor_type (обязательно): Тип услуг поставщика (облачные, разработка, консалтинг, инфраструктура)

• contract_value (необязательно): Диапазон стоимости контракта (small, medium, large, enterprise)

Управление взаимоотношениями с поставщиками, включая отслеживание контрактов, мониторинг производительности и оптимизацию затрат.

Управление инцидентами и кризисами

incident-response — Реагирование на инциденты

Аргументы:

• incident_severity (обязательно): Уровень серьезности (critical, high, medium, low)

• incident_type (необязательно): Тип инцидента (security, performance, functionality, availability)

Структура реагирования на инциденты с локализацией, восстановлением, анализом корневых причин и посленицидентным обзором.

Финансовое управление и управление ресурсами

cost-management — Управление затратами

Аргументы:

• cost_category (обязательно): Основная категория затрат (инфраструктура, персонал, инструменты, лицензии)

• budget_constraint (необязательно): Уровень бюджетных ограничений (strict, flexible, unlimited)

Мониторинг затрат, стратегии оптимизации и управление бюджетом с прогнозированием и отчетностью.

Управление клиентами и инновациями

customer-feedback — Управление отзывами клиентов

Аргументы:

• feedback_channel (обязательно): Основной канал обратной связи (опрос, поддержка, отзывы, аналитика)

• feedback_focus (необязательно): Область фокуса (удобство использования, функции, производительность, поддержка)

Сбор, анализ и планирование действий по отзывам клиентов с циклами непрерывного улучшения.

innovation-planning — Планирование инноваций

Аргументы:

• innovation_type (обязательно): Тип инноваций (продуктовые, процессные, технологические, бизнес-модель)

• risk_tolerance (необязательно): Уровень толерантности к риску (консервативный, умеренный, агрессивный)

Структура управления инновациями с генерацией идей, экспериментированием и измерением успеха.

Как ИИ-модели используют руководство

1. Обнаружение: Просмотр доступных ресурсов и промптов для понимания возможностей

2. Обучение: Чтение соответствующих ресурсов для понимания концепций управления проектами

3. Планирование: Использование подходящих промптов для сложных рабочих процессов

4. Выполнение: Следование структурированным инструкциям для эффективного использования инструментов

5. Проверка: Проверка результатов и итерация при необходимости Эта система руководства гарантирует, что ИИ-модели могут предоставлять экспертную помощь в управлении проектами с использованием набора инструментов Project Guardian.

Поведенческий протокол (системные правила)

Каждый ответ prompts/get от этого MCP-сервера включает общий Поведенческий протокол в качестве системного сообщения (реализован в src/prompts/behavioral-protocol.ts). Этот протокол обеспечивает:

• Минимальный, готовый к продакшену, самодокументируемый код с подходом, ориентированным на безопасность.

• Без модных словечек, ненужных эмодзи или воды; прямые, технически точные ответы.

• Адаптивная глубина ответа в зависимости от запроса пользователя (быстрые ответы против сложных разборов).

• Последовательное использование проверенных лучших практик для систем, программирования, 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. Установите GUARDIAN_PROJECT_ROOT в конфигурации MCP проекта (см. примеры клиентов ниже).

2. Вызовите инструмент set_project_root с абсолютным путем к проекту в начале сессии — правки конфигурации не требуются. Переключение применяется к работающему серверу; установите переменную окружения, если хотите, чтобы оно применялось автоматически к каждой будущей сессии.

Дополнительные службы времени выполнения

Redis является необязательным и не запрашивается во время запуска. Настройте его только тогда, когда нужны инструменты кэширования:

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

Trivy обнаруживается через PATH при вызове scan_container_image. Отсутствие Redis или Trivy влияет только на связанные с ними инструменты; инструменты memory, database, guidance, session, Git, wall и project-secret остаются доступными.

Каталог компаньона сообщает 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 DB + 10 memory + 1 guidance + 12 runtime + 3 UI)

  • database-tools.ts: схемы операций с базой данных (7 инструментов)

  • memory-tools.ts: схемы управления памятью (10 инструментов)

  • guidance-tools.ts: схема автономного инструмента guidance (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: централизованное системное сообщение Behavioral Protocol, используемое всеми промптами

• memory-manager.ts: операции с графом знаний для сущностей, связей и наблюдений

• sqlite-manager.ts: абстракция базы данных с ограниченным кэшированием соединений и управлением схемой

• import-export.ts: утилиты передачи данных CSV, JSON и SQL

• types.ts: схемы Zod для проверки входных данных и типобезопасности TypeScript

• 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.