context-portal

Контекстный портал MCP (ConPort)

(Это банк памяти!)

Сервер Model Context Protocol (MCP) на основе базы данных для управления структурированным контекстом проекта, предназначенный для использования помощниками ИИ и инструментами разработчиков в IDE и других интерфейсах.

Что такое сервер Context Portal MCP (ConPort)?

Context Portal (ConPort) — это банк памяти вашего проекта. Это инструмент, который помогает помощникам ИИ лучше понимать ваш конкретный программный проект, сохраняя важную информацию, такую как решения, задачи и архитектурные шаблоны, в структурированном виде. Думайте об этом как о создании базы знаний, специфичной для проекта, к которой ИИ может легко получить доступ и использовать ее, чтобы давать вам более точные и полезные ответы.

Что он делает:

• Отслеживает решения по проекту, ход выполнения и проекты систем.
• Сохраняет пользовательские данные проекта (например, глоссарии или спецификации).
• Помогает ИИ быстро находить нужную информацию о проекте (подобно интеллектуальному поиску).
• Позволяет ИИ использовать контекст проекта для более точного реагирования (RAG).
• Более эффективно для управления, поиска и обновления контекста по сравнению с простыми банками памяти на основе текстовых файлов.

ConPort предоставляет надежный и структурированный способ для помощников ИИ хранить, извлекать и управлять различными типами контекста проекта. Он эффективно создает граф знаний, специфичный для проекта , фиксируя такие сущности, как решения, прогресс и архитектура, а также их взаимосвязи. Эта структурированная база знаний, улучшенная векторными вложениями для семантического поиска, затем служит мощным бэкэндом для Retrieval Augmented Generation (RAG) , позволяя помощникам ИИ получать доступ к точной, актуальной информации для более контекстно-зависимых и точных ответов.

Он заменяет старые файловые системы управления контекстом, предлагая более надежный и запрашиваемый бэкэнд базы данных (SQLite на рабочее пространство). ConPort разработан как универсальный бэкэнд контекста, совместимый с различными IDE и клиентскими интерфейсами, которые поддерживают MCP.

Ключевые особенности включают в себя:

• Структурированное хранилище контекста с использованием SQLite (одна база данных на рабочее пространство, создается автоматически).
• Сервер MCP ( context_portal_mcp ), созданный с использованием Python/FastAPI.
• Полный набор определенных инструментов MCP для взаимодействия (см. «Доступные инструменты ConPort» ниже).
• Поддержка нескольких рабочих пространств через workspace_id .
• Основной режим развертывания: STDIO для тесной интеграции с IDE.
• Позволяет создавать динамический график знаний проекта с явными связями между элементами контекста.
• Включает в себя возможности хранения векторных данных и семантического поиска для поддержки расширенного RAG.
• Служит идеальным бэкэндом для Retrieval Augmented Generation (RAG) , предоставляя ИИ точную, запрашиваемую память проекта.
• Предоставляет структурированный контекст, который помощники на базе искусственного интеллекта могут использовать для оперативного кэширования с совместимыми поставщиками LLM.

Предпосылки

Прежде чем начать, убедитесь, что у вас установлено следующее:

• Python: рекомендуется версия 3.8 или выше.
  • Загрузить Питон
  • Убедитесь, что Python добавлен в PATH вашей системы во время установки (особенно в Windows).
• uv: (Настоятельно рекомендуется) Быстрая среда Python и менеджер пакетов. Использование uv значительно упрощает создание виртуальной среды и установку зависимостей.
  • Установить УФ
  • Если вы решили не использовать uv , вы можете использовать стандартные Python venv и pip , но для этого проекта предпочтительнее uv .

Установка через PyPI:

Создайте и активируйте виртуальную среду в каталоге, где установлены ваши серверы MCP:

Использование uv (рекомендуется):

Активируйте среду:

Linux/macOS (bash/zsh):

Windows (командная строка):

Windows (PowerShell):

(Если вы столкнулись с проблемами политики выполнения в PowerShell, вам может потребоваться сначала выполнить Set-ExecutionPolicy RemoteSigned -Scope CurrentUser .)

Используя стандартный venv (если не используете uv ):

В каталоге вашего сервера MCP:

Команды активации такие же, как и для uv выше.

Установите ConPort через PyPi:

Команда установки PyPI для context-portal-mcp с использованием uv:

Если вы используете стандартный pip в виртуальной среде, команда будет следующей:

Конфигурация для установки PyPI

Если вы установили ConPort через PyPI ( pip install context-portal-mcp ), сервер ConPort можно запустить напрямую с помощью интерпретатора Python в вашей виртуальной среде. Этот метод, как правило, более надежен, поскольку он явно указывает на исполняемый файл.

Важно: ОБЯЗАТЕЛЬНО замените путь-заполнитель /home/USER/PATH/TO/.venv/bin/python (или C:\\Users\\USER\\PATH\\TO\\.venv\\Scripts\\python.exe в Windows) на абсолютный путь к исполняемому файлу Python в вашей конкретной виртуальной среде ConPort.

Пример для Linux/macOS:

Пример для Windows:

• command : Это должен быть абсолютный путь к исполняемому файлу python (или python.exe в Windows) в .venv вашей установки ConPort.
• args : Содержит аргументы для запуска модуля сервера ConPort ( -m context_portal_mcp.main ) и аргументы сервера ( --mode stdio --workspace_id "${workspaceFolder}" ).
• ${workspaceFolder} : эта переменная IDE используется для автоматического предоставления абсолютного пути к текущему рабочему пространству проекта.
• --log-file : Необязательно: Путь к файлу, в который будут записываться журналы сервера. Если не указано, журналы направляются в stderr (консоль). Полезно для постоянного журналирования и отладки поведения сервера.
• --log-level : Необязательно: Устанавливает минимальный уровень ведения журнала для сервера. Допустимые варианты: DEBUG , INFO , WARNING , ERROR , CRITICAL . По умолчанию INFO . Установите DEBUG для подробного вывода во время разработки или устранения неполадок.

При установке через PyPI команда conport-mcp доступна непосредственно в PATH вашей виртуальной среды. Команда для запуска сервера упрощается до:

Установка из репозитория Git

Эти инструкции помогут вам настроить ConPort, клонировав его репозиторий Git и установив зависимости. Использование виртуальной среды имеет решающее значение.

1. Клонируйте репозиторий: Откройте терминал или командную строку и выполните:
   git clone https://github.com/GreatScottyMac/context-portal.git cd context-portal
2. Создайте и активируйте виртуальную среду:
   • Использование uv (рекомендуется): В каталоге context-portal :
     uv venv
     • Активируйте среду:
       • Linux/macOS (bash/zsh):
         source .venv/bin/activate
       • Windows (командная строка):
         .venv\Scripts\activate.bat
       • Windows (PowerShell):
         .venv\Scripts\Activate.ps1
         (Если вы столкнулись с проблемами политики выполнения в PowerShell, вам может потребоваться сначала выполнить Set-ExecutionPolicy RemoteSigned -Scope CurrentUser .)
   • Используя стандартный venv (если не используете uv ): В каталоге context-portal :
     python3 -m venv .venv # Or 'python -m venv .venv'
     • Команды активации такие же, как и для uv выше.
3. Установите зависимости: После активации вашей виртуальной среды:
   • Использование uv (рекомендуется):
     uv pip install -r requirements.txt
     Примечание: uv часто может обнаружить и использовать .venv в текущем каталоге даже без явной активации для команд uv pip install . Тем не менее, активация все еще является хорошей практикой, особенно если вы собираетесь запускать скрипты Python напрямую.
   • Используя стандартный pip :
     pip install -r requirements.txt
4. Проверка установки (необязательно): убедитесь, что ваша виртуальная среда активирована.
   • Использование uv :
     uv run python src/context_portal_mcp/main.py --help
   • Используя стандартный python : bash python src/context_portal_mcp/main.py --help Это должно вывести справку командной строки для сервера ConPort.

Рекомендуемая конфигурация (прямой вызов Python):

Эта конфигурация напрямую вызывает интерпретатор Python из виртуальной среды context-portal . Это надежный метод, который не зависит от того, является ли uv командой или клиент поддерживает поле cwd для серверного процесса.

Важный:

• Вам ОБЯЗАТЕЛЬНО нужно заменить пути-заполнители на абсолютные пути, соответствующие месту, где вы клонировали и настроили свой репозиторий context-portal .
• Переменная "${workspaceFolder}" для аргумента --workspace_id — это обычный заполнитель IDE, который должен расширяться до абсолютного пути к рабочей области текущего проекта.

Пример для Linux/macOS:

Представьте, что ваш репозиторий context-portal клонирован в /home/youruser/mcp-servers/context-portal .

Пример для Windows:

Представьте, что ваш репозиторий context-portal клонирован в C:\Users\YourUser\MCP-servers\context-portal . Обратите внимание на использование двойных обратных косых черт \\ для путей в строках JSON.

• command : Это должен быть абсолютный путь к исполняемому файлу python (или python.exe в Windows) в .venv вашей установки context-portal .
• Первый аргумент в args : это должен быть абсолютный путь к скрипту main.py в вашей установке context-portal .
• --workspace_id "${workspaceFolder}" : сообщает ConPort, контекстом какого проекта управлять. ${workspaceFolder} должен быть разрешен вашей IDE в корневой путь текущего проекта.
• --log-file : Необязательно: Путь к файлу, в который будут записываться журналы сервера. Если не указано, журналы направляются в stderr (консоль). Полезно для постоянного журналирования и отладки поведения сервера.
• --log-level : Необязательно: Устанавливает минимальный уровень ведения журнала для сервера. Допустимые варианты: DEBUG , INFO , WARNING , ERROR , CRITICAL . По умолчанию INFO . Установите DEBUG для подробного вывода во время разработки или устранения неполадок.

При установке через клонированный репозиторий Git среда IDE обычно создает и запускает команду, похожую на эту:

/path/to/your/context-portal/ — это абсолютный путь, по которому вы клонировали репозиторий context-portal . "/actual/path/to/your/project_workspace" — это абсолютный путь к корню проекта, контекстом которого будет управлять ConPort (например, ${workspaceFolder} в VS Code). ConPort автоматически создает свою базу данных по адресу your_project_workspace/context_portal/context.db .

Назначение аргумента командной строки --workspace_id :

При запуске сервера ConPort, особенно в режиме STDIO ( --mode stdio ), аргумент --workspace_id служит нескольким ключевым целям:

1. Начальный контекст сервера: предоставляет серверному процессу абсолютный путь к рабочей области проекта, с которой он должен быть изначально связан.
2. Критическая проверка безопасности: в режиме STDIO этот путь используется для выполнения важной проверки, которая не позволяет серверу ошибочно создавать свои файлы базы данных ( context.db , conport_vector_data/ ) внутри собственного установочного каталога. Это защищает от неправильных конфигураций, когда клиент может неправильно указать путь к рабочему пространству.
3. Сигнал запуска клиента: это стандартный способ, которым клиент MCP (например, расширение IDE) сообщает серверу, какой проект он запускает.

Важное примечание: --workspace_id предоставляемый при запуске сервера, не используется автоматически как параметр workspace_id для каждого последующего вызова инструмента MCP. Инструменты ConPort разработаны так, чтобы явно требовать параметр workspace_id при каждом вызове (например, get_product_context({"workspace_id": "..."}) ). Такая конструкция поддерживает возможность управления несколькими рабочими пространствами одним экземпляром сервера и обеспечивает ясность для каждой операции. Ваш клиент IDE/MCP несет ответственность за предоставление правильного workspace_id при каждом вызове инструмента.

Ключевой вывод: ConPort критически полагается на точный --workspace_id для определения целевого проекта. Убедитесь, что этот аргумент правильно разрешается в абсолютный путь вашего рабочего пространства проекта, либо через переменные IDE, такие как ${workspaceFolder} , либо путем предоставления прямого абсолютного пути.

Очистка кэша байт-кода Python

Иногда после обновления или переустановки ConPort вы можете столкнуться с неожиданным поведением или ошибками из-за устаревших файлов байт-кода Python ( .pyc ), хранящихся в каталогах __pycache__ . Очистка этого кэша может решить такие проблемы.

Для поиска и удаления этих файлов и каталогов в Unix-подобных системах (Linux, macOS, WSL) можно использовать команду find .

1. Удалить каталоги __pycache__ :
   find . -type d -name "__pycache__" -exec rm -rf {} +
2. Удалить файлы .pyc :
   find . -type f -name "*.pyc" -delete

Где запускать эти команды:

Каталог, в котором следует запускать эти команды, зависит от того, как вы установили ConPort:

• Если установлено из репозитория Git: выполните эти команды из корневого каталога клонированного репозитория context-portal .
• Если установлено через PyPI: выполните эти команды из каталога site-packages среды Python, в которой установлен ConPort (например, из корня lib/pythonX.Y/site-packages/ вашей виртуальной среды).
• При запуске из образа Docker: обычно эти команды запускаются внутри работающего контейнера Docker с помощью docker exec <container_id> <command> .

Использование с агентами LLM (индивидуальные инструкции)

Эффективность ConPort с агентами LLM значительно повышается за счет предоставления LLM специальных пользовательских инструкций или системных подсказок. Этот репозиторий включает в себя файлы стратегий, адаптированные для различных сред:

• Для кода Ру:
  • roo_code_conport_strategy : содержит подробные инструкции для LLM, работающих с расширением Roo Code VS Code, помогающие им использовать инструменты ConPort для управления контекстом.
• Для CLine:
  • cline_conport_strategy : содержит подробные инструкции для LLM, работающих с расширением Cline VS Code, помогающие им использовать инструменты ConPort для управления контекстом.
• Для виндсерфинга Cascade:
  • cascade_conport_strategy : Специальное руководство для LLM, интегрированное со средой Windsurf Cascade. Важно : при инициировании сеанса в Cascade необходимо явно указать LLM:
  Initialize according to custom instructions
• Для общего/платформенно-независимого использования:
  • generic_conport_strategy : Предоставляет набор инструкций, не зависящий от платформы, для любого MCP-совместимого LLM. Он подчеркивает использование операции ConPort get_conport_schema для динамического обнаружения точных имен инструментов ConPort и их параметров, направляя LLM, когда и почему выполнять концептуальные взаимодействия (например, регистрацию решения или обновление контекста продукта), а не жестко кодировать конкретные детали вызова инструмента.

Как использовать эти файлы стратегии:

1. Определите файл стратегии, соответствующий среде вашего агента LLM.
2. Скопируйте все содержимое этого файла.
3. Вставьте его в пользовательские инструкции LLM или область системных подсказок. Метод зависит от платформы LLM (настройки расширения IDE, веб-интерфейс, конфигурация API).

Эти инструкции дают магистру права знания, необходимые для:

• Инициализация и загрузка контекста из ConPort.
• Обновляйте ConPort новой информацией (решениями, прогрессом и т. д.).
• Управляйте пользовательскими данными и отношениями.
• Поймите важность workspace_id . Важный совет по началу сеансов: чтобы гарантировать, что агент LLM правильно инициализирует и загружает контекст, особенно в интерфейсах, которые не всегда строго следуют пользовательским инструкциям в первом сообщении, хорошей практикой будет начать взаимодействие с четкой директивы, например: Initialize according to custom instructions. Это может помочь подтолкнуть агента выполнить последовательность инициализации ConPort, как определено в его файле стратегии.

Первоначальное использование ConPort в рабочем пространстве

Когда вы впервые начинаете использовать ConPort в новом или существующем рабочем пространстве проекта, база данных ConPort ( context_portal/context.db ) будет автоматически создана сервером, если она не существует. Чтобы помочь загрузить начальный контекст проекта, особенно контекст продукта , рассмотрите следующее:

Использование файла projectBrief.md (рекомендуется)

1. Создайте projectBrief.md : в корневом каталоге рабочей области проекта создайте файл с именем projectBrief.md .
2. Добавить контент: Заполните этот файл общим обзором вашего проекта. Это может включать:
   • Основ��ая цель или назначение проекта.
   • Ключевые особенности или компоненты.
   • Целевая аудитория или пользователи.
   • Общий архитектурный стиль или ключевые технологии (если известны).
   • Любая другая основополагающая информация, определяющая проект.
3. Автоматический запрос на импорт: когда агент LLM, использующий один из предоставленных наборов пользовательских инструкций ConPort (например, roo_code_conport_strategy ), инициализируется в рабочей области, он предназначен для:
   • Проверьте существование projectBrief.md .
   • Если файл найден, он прочитает его и спросит, хотите ли вы импортировать его содержимое в контекст продукта ConPort.
   • Если вы согласны, контент будет добавлен в ConPort, что станет немедленной основой для контекста продукта проекта.

Ручная инициализация

Если projectBrief.md не найден или вы решили не импортировать его:

• Агент LLM (руководствуясь своими пользовательскими инструкциями) обычно сообщает вам, что контекст продукта ConPort выглядит неинициализированным.
• Он может помочь вам определить контекст продукта вручную, потенциально перечислив другие файлы в вашем рабочем пространстве для сбора соответствующей информации.

Предоставляя начальный контекст либо через projectBrief.md , либо вручную, вы позволяете ConPort и подключенному агенту LLM с самого начала получить более глубокое базовое понимание вашего проекта.

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

Сервер ConPort предоставляет следующие инструменты через MCP, позволяя взаимодействовать с базовым графом знаний проекта . Сюда входят инструменты для семантического поиска , работающего на основе хранилища векторных данных . Эти инструменты облегчают аспект поиска, критически важный для расширенной генерации (RAG) агентами ИИ. Все инструменты требуют аргумент workspace_id (строка, обязательно) для указания целевого рабочего пространства проекта.

• Управление контекстом продукта:
  • get_product_context : извлекает общие цели, функции и архитектуру проекта.
  • update_product_context : Обновляет контекст продукта. Принимает полное content (объект) или patch_content (объект) для частичных обновлений (используйте __DELETE__ как значение в patch для удаления ключа).
• Активное управление контекстом:
  • get_active_context : извлекает текущий рабочий фокус, последние изменения и открытые проблемы.
  • update_active_context : Обновляет активный контекст. Принимает полное content (объект) или patch_content (объект) для частичных обновлений (используйте __DELETE__ как значение в patch для удаления ключа).
• Регистрация решений:
  • log_decision : регистрирует архитектурное или реализационное решение.
    • Аргументы: summary (str, req), rationale (str, opt), implementation_details (str, opt), tags (list[str], opt).
  • get_decisions : Извлекает зарегистрированные решения.
    • Аргументы: limit (int, opt), tags_filter_include_all (list[str], opt), tags_filter_include_any (list[str], opt).
  • search_decisions_fts : полнотекстовый поиск по полям решений (резюме, обоснование, подробности, теги).
    • Аргументы: query_term (str, req), limit (int, opt).
  • delete_decision_by_id : Удаляет решение по его идентификатору.
    • Аргументы: decision_id (int, req).
• Отслеживание прогресса:
  • log_progress : регистрирует запись о ходе выполнения или статусе задачи.
    • Аргументы: status (str, req), description (str, req), parent_id (int, opt), linked_item_type (str, opt), linked_item_id (str, opt).
  • get_progress : Извлекает записи о ходе выполнения.
    • Аргументы: status_filter (str, opt), parent_id_filter (int, opt), limit (int, opt).
  • update_progress : обновляет существующую запись о ходе выполнения.
    • Аргументы: progress_id (int, req), status (str, opt), description (str, opt), parent_id (int, opt).
  • delete_progress_by_id : Удаляет запись о ходе выполнения по ее идентификатору.
    • Аргументы: progress_id (int, req).
• Управление шаблонами системы:
  • log_system_pattern : Регистрирует или обновляет шаблон системы/кодирования.
    • Аргументы: name (str, req), description (str, opt), tags (list[str], opt).
  • get_system_patterns : Извлекает системные шаблоны.
    • Аргументы: tags_filter_include_all (list[str], opt), tags_filter_include_any (list[str], opt).
  • delete_system_pattern_by_id : Удаляет системный шаблон по его идентификатору.
    • Аргументы: pattern_id (int, req).
• Управление пользовательскими данными:
  • log_custom_data : Сохраняет/обновляет пользовательскую запись ключ-значение в категории. Значение является сериализуемым в JSON.
    • Аргументы: category (str, req), key (str, req), value (any, req).
  • get_custom_data : извлекает пользовательские данные.
    • Аргументы: category (str, opt), key (str, opt).
  • delete_custom_data : удаляет определенную пользовательскую запись данных.
    • Аргументы: category (str, req), key (str, req).
  • search_project_glossary_fts : полнотекстовый поиск в пользовательской категории данных «ProjectGlossary».
    • Аргументы: query_term (str, req), limit (int, opt).
  • search_custom_data_value_fts : полнотекстовый поиск по всем пользовательским значениям данных, категориям и ключам.
    • Аргументы: query_term (str, req), category_filter (str, opt), limit (int, opt).
• Связывание контекста:
  • link_conport_items : создает связь между двумя элементами ConPort, явно выстраивая граф знаний проекта .
    • Аргументы: source_item_type (str, req), source_item_id (str, req), target_item_type (str, req), target_item_id (str, req), relationship_type (str, req), description (str, opt).
  • get_linked_items : Извлекает элементы, связанные с определенным элементом.
    • Аргументы: item_type (str, req), item_id (str, req), relationship_type_filter (str, opt), linked_item_type_filter (str, opt), limit (int, opt).
• История и метаинструменты:
  • get_item_history : извлекает историю версий для продукта или активного контекста.
    • Аргументы: item_type ("product_context" | "active_context", req), version (int, opt), before_timestamp (datetime, opt), after_timestamp (datetime, opt), limit (int, opt).
  • get_recent_activity_summary : предоставляет сводку недавней активности ConPort.
    • Аргументы: hours_ago (целое число, необязательно), since_timestamp (дата и время, необязательно), limit_per_type (целое число, необязательно, по умолчанию: 5).
  • get_conport_schema : извлекает схему доступных инструментов ConPort и их аргументы.
• Импорт/Экспорт:
  • export_conport_to_markdown : экспортирует данные ConPort в файлы разметки.
    • Аргументы: output_path (str, opt, по умолчанию: "./conport_export/").
  • import_markdown_to_conport : импортирует данные из файлов разметки в ConPort.
    • Аргументы: input_path (str, opt, по умолчанию: "./conport_export/").
• Пакетные операции:
  • batch_log_items : регистрирует несколько элементов одного типа (например, решения, записи о ходе выполнения) за один вызов.
    • Аргументы: item_type (str, req - например, "decision", "progress_entry"), items (list[dict], req - список словарей модели Pydantic для типа элемента).

Стратегия кэширования Prompt

ConPort можно использовать для предоставления структурированного контекста (включая векторные данные для семантического поиска), который помощники ИИ могут использовать для кэширования подсказок с совместимыми поставщиками LLM (например, Google Gemini, Anthropic Claude и OpenAI). Кэширование подсказок снижает стоимость токенов и задержку за счет повторного использования часто используемых частей подсказок.

Этот репозиторий включает в себя подробный файл стратегии ( context_portal/prompt_caching_strategy.yml ), который определяет, как помощник LLM должен идентифицировать кэшируемый контент из ConPort и структурировать запросы для разных поставщиков.

Ключевые аспекты стратегии включают в себя:

• Определение кэшируемого контента: определение приоритетности большого, стабильного контекста, например контекста продукта, подробных системных шаблонов или определенных записей пользовательских данных (особенно тех, которые помечены метаданными cache_hint: true ).
• Взаимодействие с конкретным поставщиком:
  • Неявное кэширование (Gemini, OpenAI): структурируйте запросы, размещая кэшируемый контент ConPort в абсолютном начале запроса. Поставщик LLM автоматически обрабатывает кэширование.
  • Явное кэширование (антропное): вставьте точку останова cache_control после кэшируемого содержимого ConPort в полезной нагрузке подсказки.
• Подсказки для пользователя: пользовательские данные ConPort могут включать метаданные, такие как cache_hint: true , чтобы явно указать помощнику LLM, как расставить приоритеты в отношении контента для кэширования.
• Уведомление помощника LLM: помощник LLM должен уведомлять пользователя, когда он структурирует запрос на потенциальное кэширование (например, [INFO: Structuring prompt for caching] ).

Используя ConPort для управления знаниями вашего проекта и предоставляя помощнику LLM эту стратегию оперативного кэширования, вы можете повысить эффективность и экономичность взаимодействия с ИИ.

Дальнейшее чтение

Для более глубокого понимания дизайна, архитектуры и расширенных моделей использования ConPort, пожалуйста, обратитесь к следующим источникам:

• conport_mcp_deep_dive.md

Внося вклад

Подробная информация об участии в проекте ConPort будет добавлена сюда в будущем.

Лицензия

Данный проект лицензирован под лицензией Apache-2.0 .