context-portal

上下文门户 MCP (ConPort)

（这是一个记忆库！）

用于管理结构化项目上下文的数据库支持的模型上下文协议 (MCP) 服务器，旨在供 IDE 和其他界面中的 AI 助手和开发人员工具使用。

什么是 Context Portal MCP 服务器 (ConPort)？

上下文门户 (ConPort) 是您项目的记忆库。它是一种工具，能够以结构化的方式存储决策、任务和架构模式等重要信息，从而帮助 AI 助手更好地理解您的特定软件项目。您可以将其视为构建一个特定于项目的知识库，AI 可以轻松访问和使用它，从而为您提供更准确、更有用的响应。

它的作用：

• 跟踪项目决策、进度和系统设计。
• 存储自定义项目数据（如词汇表或规格）。
• 帮助AI快速找到相关项目信息（如智能搜索）。
• 使 AI 能够利用项目上下文来获得更好的响应（RAG）。
• 与基于简单文本文件的存储库相比，管理、搜索和更新上下文更加高效。

ConPort 为 AI 助手提供了一种强大且结构化的方式来存储、检索和管理各种类型的项目上下文。它有效地构建了特定于项目的知识图谱，捕捉决策、进度和架构等实体及其关系。该结构化知识库通过向量嵌入进行语义搜索增强，并作为**检索增强生成 (RAG)**的强大后端，使 AI 助手能够访问精确、最新的信息，从而提供更具情境感知和更准确的响应。

它通过提供更可靠、更易于查询的数据库后端（每个工作区一个 SQLite）来取代旧式的基于文件的上下文管理系统。ConPort 旨在成为一个通用的上下文后端，兼容各种支持 MCP 的 IDE 和客户端界面。

主要特点包括：

• 使用 SQLite 的结构化上下文存储（每个工作区一个数据库，自动创建）。
• 使用 Python/FastAPI 构建的 MCP 服务器（ context_portal_mcp ）。
• 一套全面的用于交互的定义 MCP 工具（参见下面的“可用的 ConPort 工具”）。
• 通过workspace_id支持多工作区。
• 主要部署模式：STDIO，用于紧密的 IDE 集成。
• 能够构建具有上下文项之间明确关系的动态项目知识图。
• 包括矢量数据存储和语义搜索功能，为高级 RAG 提供支持。
• 作为**检索增强生成 (RAG)**的理想后端，为 AI 提供精确、可查询的项目记忆。
• 提供结构化上下文，AI 助手可以利用该上下文与兼容的 LLM 提供商进行快速缓存。

先决条件

开始之前，请确保已安装以下软件：

• **Python：**建议使用3.8或更高版本。
  • 下载 Python
  • 确保在安装过程中将 Python 添加到系统的 PATH 中（尤其是在 Windows 上）。
• **uv：（**强烈推荐）一个快速的 Python 环境和包管理器。使用uv可以显著简化虚拟环境的创建和依赖项的安装。
  • 安装 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相同。

通过 PyPi 安装 ConPort：

使用 uv 的 context-portal-mcp 的 PyPI 安装命令是：

如果您在虚拟环境中使用标准 pip，则命令为：

PyPI 安装配置

如果您通过 PyPI（ pip install context-portal-mcp ）安装了 ConPort，则可以在虚拟环境中使用 Python 解释器直接启动 ConPort 服务器。此方法通常更可靠，因为它明确指向可执行文件。

重要提示：您必须将占位符路径/home/USER/PATH/TO/.venv/bin/python （或 Windows 上的C:\\Users\\USER\\PATH\\TO\\.venv\\Scripts\\python.exe ）替换为特定 ConPort 虚拟环境中的 Python 可执行文件的绝对路径。

Linux/macOS 示例：

Windows 示例：

• command ：这必须是 ConPort 安装的.venv中可执行文件的python （或 Windows 上的python.exe ）的绝对路径。
• 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 存储库安装

这些说明将指导您通过克隆 Git 存储库并安装依赖项来设置 ConPort。使用虚拟环境至关重要。

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 pip install命令， uv通常也能检测并使用当前目录中的.venv文件。不过，激活仍然是一个好习惯，尤其是在你打算直接运行 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 调用）：

此配置直接从context-portal虚拟环境调用 Python 解释器。这是一种可靠的方法，它不依赖于uv作为命令，也不依赖于客户端是否支持服务器进程的cwd字段。

重要的：

• 您必须将占位符路径替换为您克隆并设置context-portal存储库的位置对应的绝对路径。
• --workspace_id参数的"${workspaceFolder}"变量是一个常见的 IDE 占位符，它应该扩展为当前项目工作区的绝对路径。

Linux/macOS 示例：

假设您的context-portal存储库已克隆到/home/youruser/mcp-servers/context-portal 。

Windows 示例：

假设您的context-portal仓库被克隆到C:\Users\YourUser\MCP-servers\context-portal 。注意 JSON 字符串中路径使用双反斜杠\\ 。

• command ：这必须是context-portal安装的.venv中可执行文件的python （或 Windows 上的python.exe ）的绝对路径。
• args中的第一个参数：这必须是context-portal安装中的main.py脚本的绝对路径。
• --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 将管理其上下文的项目根目录的绝对路径（例如，VS Code 中的${workspaceFolder} ）。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不会自动用作后续每次 MCP 工具调用的workspace_id参数。ConPort 工具的设计要求在每次调用时都明确指定workspace_id参数（例如， get_product_context({"workspace_id": "..."}) ）。此设计支持单个服务器实例管理多个工作区，并确保每个操作清晰明了。您的客户端 IDE/MCP 客户端负责在每次工具调用时提供正确的workspace_id 。

关键要点： ConPort 非常依赖准确的--workspace_id来识别目标项目。请确保此参数正确解析为项目工作区的绝对路径，可以通过 IDE 变量（例如${workspaceFolder}或直接提供绝对路径来实现。

清除 Python 字节码缓存

有时，在更新或重新安装 ConPort 后，您可能会遇到意外行为或错误，这是由于__pycache__目录中存储了过时的 Python 字节码文件 ( .pyc ) 造成的。清除此缓存可以解决此类问题。

您可以在类 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 安装：**从安装 ConPort 的 Python 环境的 site-packages 目录中运行这些命令（例如，从虚拟环境的lib/pythonX.Y/site-packages/根目录）。
• **如果从 Docker 镜像运行：**您通常会使用docker exec <container_id> <command>在正在运行的 Docker 容器内运行这些命令。

与 LLM 代理一起使用（自定义指令）

ConPort 通过向 LLM 提供特定的自定义指令或系统提示，显著提升了其与 LLM 代理的协同效率。此存储库包含针对不同环境的定制策略文件：

• 对于 Roo 代码：
  • roo_code_conport_strategy ：包含在 Roo Code VS Code 扩展中操作的 LLM 的详细说明，指导他们如何使用 ConPort 工具进行上下文管理。
• 对于 CLine：
  • cline_conport_strategy ：包含在 Cline VS Code 扩展中操作的 LLM 的详细说明，指导他们如何使用 ConPort 工具进行上下文管理。
• 对于 Windsurf Cascade：
  • cascade_conport_strategy ：针对与 Windsurf Cascade 环境集成的 LLM 的具体指导。重要提示：在 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 扩展设置、Web UI、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. **自动导入提示：**当使用提供的 ConPort 自定义指令集（例如roo_code_conport_strategy ）之一的 LLM 代理在工作区中初始化时，它旨在：
   • 检查projectBrief.md是否存在。
   • 如果找到，它将读取该文件并询问您是否要将其内容导入 ConPort产品上下文。
   • 如果您同意，内容将被添加到 ConPort，为项目的产品环境提供直接基准。

手动初始化

如果未找到projectBrief.md ，或者您选择不导入它：

• LLM 代理（由其自定义指令引导）通常会通知您 ConPort 产品上下文似乎未初始化。
• 它可能会帮助您手动定义产品上下文，可能通过列出工作区中的其他文件来收集相关信息。

通过提供初始上下文（通过projectBrief.md或手动输入），您可以让 ConPort 和连接的 LLM 代理从一开始就对您的项目有更好的基础了解。

可用的 ConPort 工具

ConPort 服务器通过 MCP 公开以下工具，允许与底层项目知识图谱进行交互。其中包括基于向量数据存储的语义搜索工具。这些工具有助于 AI 代理实现增强生成 (RAG)所需的检索功能。所有工具都需要一个workspace_id参数（字符串，必需）来指定目标项目工作区。

• 产品上下文管理：
  • get_product_context ：检索整体项目目标、功能和架构。
  • update_product_context ：更新产品上下文。接受完整content （对象）或patch_content （对象）进行部分更新（在 patch 中使用__DELETE__作为值来删除键）。
• 主动上下文管理：
  • get_active_context ：检索当前工作重点、最近的更改和未解决的问题。
  • update_active_context ：更新活动上下文。接受完整content （对象）或patch_content （对象）进行部分更新（在 patch 中使用__DELETE__作为值来删除键）。
• 决策记录：
  • 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 ：根据 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 ：根据 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 ：通过 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 （int，opt）、 since_timestamp （datetime，opt）、 limit_per_type （int，opt，默认值：5）。
  • get_conport_schema ：检索可用 ConPort 工具及其参数的模式。
• 导入/导出：
  • export_conport_to_markdown ：将 ConPort 数据导出到 markdown 文件。
    • 参数： output_path （str，opt，默认值：“./conport_export/”）。
  • import_markdown_to_conport ：将 markdown 文件中的数据导入 ConPort。
    • 参数： input_path （str，opt，默认值：“./conport_export/”）。
• 批量操作：
  • batch_log_items ：在一次调用中记录同一类型的多个项目（例如，决策、进度条目）。
    • 参数： item_type （str，req - 例如，“decision”，“progress_entry”）， items （list[dict]，req - 项目类型的 Pydantic 模型字典列表）。

提示缓存策略

ConPort 可用于提供结构化上下文（包括用于语义搜索的向量数据），AI 助手可以利用兼容的 LLM 提供商（例如 Google Gemini、Anthropic Claude 和 OpenAI）进行提示缓存。提示缓存通过重用提示中常用的部分，降低了令牌成本和延迟。

该存储库包含一个详细的策略文件（ context_portal/prompt_caching_strategy.yml ），该文件定义了 LLM 助手如何从 ConPort 识别可缓存内容并为不同的提供商构建提示。

该战略的关键方面包括：

• **识别可缓存内容：**优先考虑大型、稳定的上下文，如产品上下文、详细的系统模式或特定的自定义数据条目（尤其是那些用cache_hint: true元数据标记的条目）。
• 特定于提供商的交互：
  • **隐式缓存（Gemini、OpenAI）：**通过将可缓存的 ConPort 内容放置在提示符的绝对开头来构建提示符。LLM 提供程序会自动处理缓存。
  • **显式缓存（Anthropic）：**在提示有效负载内的可缓存 ConPort 内容后插入一个cache_control断点。
• 用户提示： ConPort 的自定义数据可以包含诸如cache_hint: true之类的元数据，以明确指导 LLM 助手对缓存的内容进行优先级排序。
• **LLM 助手通知：**指示 LLM 助手在构造潜在缓存提示时通知用户（例如， [INFO: Structuring prompt for caching] ）。

通过使用 ConPort 管理您的项目知识并为 LLM 助手提供这种及时的缓存策略，您可以提高 AI 交互的效率和成本效益。

进一步阅读

如需更深入了解 ConPort 的设计、架构和高级使用模式，请参阅：

• conport_mcp_deep_dive.md

贡献

有关对 ConPort 项目做出贡献的详细信息将在未来添加到此处。

执照

该项目采用Apache-2.0 许可证。