Context Portal MCP (ConPort)

什么是 Context Portal MCP 服务（ConPort）？

Context Portal（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 助手与兼容的大模型提供商配合使用，实现提示词缓存。
• 使用 Alembic 迁移管理数据库架构演进，确保更新顺畅且数据完整。

前置条件

开始之前，请确保已安装以下内容：

• **Python：**建议使用 3.8 或更高版本。
  • 下载 Python
  • 安装时确保将 Python 添加到系统的 PATH 中（尤其是在 Windows 上）。
• uv：（强烈推荐）一款快速的 Python 环境和包管理器。使用 uv 可大幅简化虚拟环境的创建和依赖项安装。
  • 安装 uv

安装和配置（推荐）

推荐使用 uvx 直接从 PyPI 执行软件包，以安装和运行 ConPort。此方法无需手动创建和管理虚拟环境。

uvx 配置（适用于大多数 IDE）

在 MCP 客户端设置中（例如 mcp_settings.json），使用以下配置：

{
  "mcpServers": {
    "conport": {
      "command": "uvx",
      "args": [
        "--from",
        "context-portal-mcp",
        "conport-mcp",
        "--mode",
        "stdio",
        "--workspace_id",
        "${workspaceFolder}",
        "--log-file",
        "./logs/conport.log",
        "--log-level",
        "INFO"
      ]
    }
  }
}

• command：uvx 会为你处理环境。
• args：包含运行 ConPort 服务的参数。
• ${workspaceFolder}：此 IDE 变量用于自动提供当前项目工作区的绝对路径。
• --log-file：可选：日志写入的文件路径。如果未提供，日志将输出到 stderr（控制台）。适用于持久化日志记录和调试服务行为。
• --log-level：可选：设置服务的最低日志级别。有效选项为 DEBUG、INFO、WARNING、ERROR、CRITICAL。默认为 INFO。在开发或排查问题时，可设为 DEBUG 以输出详细信息。

重要：许多 IDE 在启动 MCP 服务时不会展开 ${workspaceFolder}。请使用以下安全选项之一：

1. 为 --workspace_id 提供绝对路径。
2. 启动时省略 --workspace_id，并依赖每次调用时传入的 workspace_id（如果客户端每次调用都会提供该参数，推荐使用此选项）。

替代配置（启动时不使用 --workspace_id）：

{
  "mcpServers": {
    "conport": {
      "command": "uvx",
      "args": [
        "--from",
        "context-portal-mcp",
        "conport-mcp",
        "--mode",
        "stdio",
        "--log-file",
        "./logs/conport.log",
        "--log-level",
        "INFO"
      ]
    }
  }
}

如果省略 --workspace_id，服务将跳过预初始化，并在首次工具调用时使用该调用中提供的 workspace_id 初始化数据库。

开发者安装（从 Git 仓库安装）

开发和测试 ConPort 最合适的方式，是使用上面的配置在 IDE 中将其作为 MCP 服务运行。这样可以在 STDIO 模式下测试，并体验客户端的实际行为。

如果需要基于本地检出版本和虚拟环境运行，可以配置 MCP 客户端，通过 uv run 和 .venv/bin/python 启动开发服务：

{
  "mcpServers": {
    "conport": {
      "command": "uv",
      "args": [
        "run",
        "--python",
        ".venv/bin/python",
        "--directory",
        "<path to context-portal repo> ",
        "conport-mcp",
        "--mode",
        "stdio",
        "--log-file",
        "./logs/conport-dev.log",
        "--log-level",
        "DEBUG"
      ],
      "disabled": false
    }
  }
}

说明：

• 将 --directory 设置为仓库路径；这会使用本地检出版本和虚拟环境解释器。
• 日志将以 DEBUG 详细级别写入 ./logs/conport-dev.log。

本地环境设置

通过 Git 仓库进行开发或贡献时，请按以下步骤设置。

1. 克隆仓库

   git clone https://github.com/GreatScottyMac/context-portal.git
   cd context-portal
   

2. 创建虚拟环境

   uv venv
   

   使用 shell 的标准激活方式激活环境（例如，在 macOS/Linux 上运行 source .venv/bin/activate）。

3. 安装依赖项

   uv pip install -r requirements.txt
   

4. 在 IDE 中运行（推荐） 使用上文中的“uvx 配置”或开发用 uv run 配置来设置 IDE 的 MCP 设置。这是在 STDIO 模式下测试 ConPort 最具代表性的方式。

5. 可选：CLI 帮助

   uv run python src/context_portal_mcp/main.py --help
   

说明：

• 关于 --workspace_id 的行为和 IDE 路径处理，请参阅上文“uvx 配置”部分的说明。许多 IDE 不会展开 ${workspaceFolder}。

有关升级前清理（包括清除 Python 字节码缓存），请参阅 v0.2.4_UPDATE_GUIDE.md。

在 LLM Agent 中使用（自定义指令）

为 LLM 提供具体的自定义指令或系统提示词，可以显著提升 ConPort 的使用效果。本仓库针对不同环境提供了量身定制的策略文件：

• 用于 Roo Code：

  • 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 Agent 环境的策略文件。
2. 复制该文件的全部内容。
3. 将其粘贴到 LLM 的自定义指令或系统提示词区域。具体方法因 LLM 平台而异（IDE 扩展设置、Web UI、API 配置）。

这些指令将帮助 LLM：

• 初始化 ConPort 并加载上下文。
• 使用新信息（决策、进度等）更新 ConPort。
• 管理自定义数据和关系。
• 理解 workspace_id 的重要性。 启动会话的重要提示： 为确保 LLM Agent 正确初始化并加载上下文，尤其是在首条消息不一定会严格遵循自定义指令的界面中，建议在开始交互时使用清晰的指令，例如： Initialize according to custom instructions. 这有助于提示 Agent 按照策略文件中的定义执行 ConPort 初始化流程。

全新策略集：mem4sprint（新内容）

本仓库新增了一套专注于 Sprint 规划和操作流程的策略与文档：

• conport-custom-instructions/mem4sprint.md — 提供简明的指导和模式，说明如何使用扁平类别和有效的 FTS 前缀。
• conport-custom-instructions/mem4sprint.schema_and_templates.md — 包含元架构、精简入门示例、FTS 查询规则和最简操作调用示例。

主要亮点：

• 扁平类别模型（例如 artifacts、rfc_doc、retrospective、ProjectGlossary、critical_settings）。
• 仅使用有效的 FTS5 前缀：自定义数据使用 category:、key:、value_text:；决策使用 summary:、rationale:、implementation_details:、tags:。
• 在处理器层规范化查询；数据库层保持不变。

发布说明摘要：

• 新增 mem4sprint 策略与文档，采用扁平化类别并明确 FTS 规则。
• 简化示例并加入最简操作调用示例。
• 文档明确了 MCP 的 IDE 工作区路径处理方式。

在工作区中初次使用 ConPort

首次在新的或现有的项目工作区中使用 ConPort 时，如果 ConPort 数据库（context_portal/context.db）不存在，服务会自动创建它。为帮助初始化项目的上下文，尤其是产品上下文，请考虑以下做法：

使用 projectBrief.md 文件（推荐）

1. 创建 projectBrief.md： 在项目工作区的根目录中，创建一个名为 projectBrief.md 的文件。
2. 添加内容： 在此文件中填写项目的高层概述。内容可以包括：
   • 项目的主要目标或用途。
   • 关键功能或组件。
   • 目标受众或用户。
   • 整体架构风格或关键技术（如果已知）。
   • 任何其他能够定义项目的基础信息。
3. 自动提示导入： 使用所提供的某个 ConPort 自定义指令集（例如，roo_code_conport_strategy）的 LLM Agent 在工作区中初始化时，会执行以下操作：
   • 检查 projectBrief.md 是否存在。
   • 如果存在，它会读取该文件，并询问你是否要将其内容导入 ConPort 的产品上下文。
   • 如果你同意，内容将添加到 ConPort，为项目的产品上下文提供即时的基线。

手动初始化

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

• LLM Agent（在其自定义指令的引导下）通常会告知你，ConPort 产品上下文似乎尚未初始化。
• 它可能会提出协助你手动定义产品上下文，例如列出工作区中的其他文件以收集相关信息。

通过 projectBrief.md 或手动输入提供初始上下文，你可以让 ConPort 和已连接的 LLM Agent 从一开始就更充分地了解你的项目。

自动检测工作区

ConPort 可以自动确定正确的 workspace_id，这样你就不必在 MCP 客户端配置中硬编码绝对路径。这对于启动 MCP 服务时无法展开 ${workspaceFolder} 的 IDE 尤其有用。

默认启用自动检测，可通过 CLI 标志进行控制：

标志：

• --auto-detect-workspace（默认：启用）开启自动检测。
• --no-auto-detect 禁用检测（此时必须提供显式的 --workspace_id 或针对每个工具提供 workspace_id）。
• --workspace-search-start <path> 用于向上搜索的可选起始目录（默认为当前工作目录）。

工作原理（多策略）：

1. 强指示器（快速路径）：查找包含以下任意文件的高置信度项目根目录：package.json、.git、pyproject.toml、Cargo.toml、go.mod、pom.xml。
2. 多个常规指示器：如果某个目录中存在 ≥2 个常规指示器（README、许可证、构建文件等），则将其视为根目录。
3. 现有 ConPort 工作区：存在 context_portal/ 目录表示这是一个有效工作区。
4. MCP 环境上下文：遵循已设置且有效的环境变量，例如 VSCODE_WORKSPACE_FOLDER 或 CONPORT_WORKSPACE。
5. 回退：如果未找到任何指示器，则详细使用起始目录（并发出警告）。

工具：

• get_workspace_detection_info（MCP 工具）会提供一个诊断字典，其中显示：
  • start_path
  • detected_workspace
  • detection_method（strong_indicators | multiple_indicators | existing_context_portal | fallback）
  • indicators_found
  • 相关环境变量

最佳实践：

• 除非你需要在多根场景下针对每次调用进行显式隔离，否则请保持启用检测。
• 如果 IDE 传入了字面字符串 ${workspaceFolder}，ConPort 将忽略它并安全地自动检测（日志级别为 WARNING）。
• 要调试有歧义的根目录（例如嵌套仓库），请运行检测信息工具，确认选中了哪个目录。

完全依赖自动检测的 MCP 启动示例：

{
  "mcpServers": {
    "conport": {
      "command": "uvx",
      "args": [
        "--from", "context-portal-mcp",
        "conport-mcp",
        "--mode", "stdio",
        "--log-level", "INFO"
      ]
    }
  }
}

显式禁用检测（仅强制使用提供的 ID）：

{
  "mcpServers": {
    "conport": {
      "command": "uvx",
      "args": [
        "--from", "context-portal-mcp",
        "conport-mcp",
        "--mode", "stdio",
        "--no-auto-detect",
        "--workspace_id", "/absolute/path/to/project"
      ]
    }
  }
}

如果启动器从较深的子目录启动，请提供更高层级的起始路径：

conport-mcp --mode stdio --workspace-search-start ../../

完整的设计依据、边缘情况和故障排除说明，请参阅 UNIVERSAL_WORKSPACE_DETECTION.md。

可用的 ConPort 工具

ConPort 服务通过 MCP 提供以下工具，可用于与底层的项目知识图谱交互。其中包括由向量数据存储提供支持的语义搜索工具。这些工具支持 AI Agent 实现**增强生成（RAG）**这一关键环节。所有工具都必须提供 workspace_id 参数（必填字符串），以指定目标项目工作区。

注意：为方便起见，所有类似整数的参数既接受数字，也接受仅包含数字的字符串（例如 "10"、" 3"）。服务端会去除空白并将这些值强制转换为整数，同时保留验证边界（例如 ge=1）。致谢：@cipradu。

• 产品上下文管理：
  • get_product_context：获取项目整体目标、功能和架构。
  • update_product_context：更新产品上下文。接受完整的 content（对象），或用于部分更新的 patch_content（对象）（在补丁中将 __DELETE__ 作为值可删除某个键）。
• 活动上下文管理：
  • get_active_context：获取当前工作重点、近期变更和未解决的问题。
  • update_active_context：更新活动上下文。接受完整的 content（对象），或用于部分更新的 patch_content（对象）（在补丁中将 __DELETE__ 作为值可删除某个键）。
• 决策记录：
  • log_decision：记录架构或实现决策。
    • 参数：summary（str，必需）、rationale（str，可选）、implementation_details（str，可选）、tags（list[str]，可选）。
  • get_decisions：获取已记录的决策。
    • 参数：limit（int，可选）、tags_filter_include_all（list[str]，可选）、tags_filter_include_any（list[str]，可选）。
  • search_decisions_fts：对决策字段（摘要、理由、详情、标签）进行全文搜索。
    • 参数：query_term（str，必需）、limit（int，可选）。
  • delete_decision_by_id：根据 ID 删除一项决策。
    • 参数：decision_id（int，必需）。
• 进度跟踪：
  • log_progress：记录进度条目或任务状态。
    • 参数：status（str，必需）、description（str，必需）、parent_id（int，可选）、linked_item_type（str，可选）、linked_item_id（str，可选）。
  • get_progress：获取进度条目。
    • 参数：status_filter（str，可选）、parent_id_filter（int，可选）、limit（int，可选）。
  • update_progress：更新现有进度条目。
    • 参数：progress_id（int，必需）、status（str，可选）、description（str，可选）、parent_id（int，可选）。
  • delete_progress_by_id：根据 ID 删除进度条目。
    • 参数：progress_id（int，必需）。
• 系统模式管理：
  • log_system_pattern：记录或更新系统／编码模式。
    • 参数：name（str，必需）、description（str，可选）、tags（list[str]，可选）。
  • get_system_patterns：获取系统模式。
    • 参数：tags_filter_include_all（list[str]，可选）、tags_filter_include_any（list[str]，可选）。
  • delete_system_pattern_by_id：根据 ID 删除系统模式。
    • 参数：pattern_id（int，必需）。
• 自定义数据管理：
  • log_custom_data：在某个类别下存储／更新自定义键值条目。值必须可序列化为 JSON。
    • 参数：category（str，必需）、key（str，必需）、value（any，必需）。
  • get_custom_data：获取自定义数据。
    • 参数：category（str，可选）、key（str，可选）。
  • delete_custom_data：删除特定的自定义数据条目。
    • 参数：category（str，必需）、key（str，必需）。
  • search_project_glossary_fts：在 ProjectGlossary 自定义数据类别中进行全文搜索。
    • 参数：query_term（str，必需）、limit（int，可选）。
  • search_custom_data_value_fts：在所有自定义数据值、类别和键中进行全文搜索。
    • 参数：query_term（str，必需）、category_filter（str，可选）、limit（int，可选）。
• 上下文关联：
  • link_conport_items：在两个 ConPort 条目之间建立关联，明确构建项目知识图谱。
    • 参数：source_item_type（str，必需）、source_item_id（str，必需）、target_item_type（str，必需）、target_item_id（str，必需）、relationship_type（str，必需）、description（str，可选）。
  • get_linked_items：获取与特定条目关联的条目。
    • 参数：item_type（str，必需）、item_id（str，必需）、relationship_type_filter（str，可选）、linked_item_type_filter（str，可选）、limit（int，可选）。
• 历史记录与元工具：
  • get_item_history：获取产品上下文或活动上下文的版本历史。
    • 参数：item_type（"product_context" | "active_context"，必需）、version（int，可选）、before_timestamp（datetime，可选）、after_timestamp（datetime，可选）、limit（int，可选）。
  • get_recent_activity_summary：汇总近期 ConPort 活动。
    • 参数：hours_ago（int，可选）、since_timestamp（datetime，可选）、limit_per_type（int，可选，默认值：5）。
  • get_conport_schema：获取可用 ConPort 工具及其参数的架构。
• 导入／导出：
  • export_conport_to_markdown：将 ConPort 数据导出为 Markdown 文件。
    • 参数：output_path（str，可选，默认值："./conport_export/"）。
  • import_markdown_to_conport：将 Markdown 文件中的数据导入 ConPort。
    • 参数：input_path（str，可选，默认值："./conport_export/"）。
• 批量操作：
  • batch_log_items：通过单次调用记录多个相同类型的条目（例如决策、进度条目）。
    • 参数：item_type（str，必需，例如 "decision"、"progress_entry"）、items（list[dict]，必需，条目类型对应的 Pydantic 模型字典列表）。

延伸阅读

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

• conport_mcp_deep_dive.md

贡献

有关如何为 ConPort 项目做出贡献的详细信息，请参阅 CONTRIBUTING.md 指南。

许可证

本项目采用 Apache-2.0 许可证授权。

致谢

• 特别感谢 @cipradu 提出宝贵建议，为数字参数实现整数与字符串之间的强制转换，从而提升了用户通过各种客户端与 MCP 服务交互时的使用体验。

数据库迁移与更新指南

有关如何管理 context.db 文件的详细说明，尤其是在更新 ConPort 并遇到数据库架构变更时，请参阅专门的 v0.2.4_UPDATE_GUIDE.md。本指南提供了必要时手动迁移数据（导出/导入）的步骤，以及故障排除提示。