上下文门户

Name: 上下文门户
Author: GreatScottyMac

作者：GreatScottyMac686 星标更新：2025-10-31

安装使用来源：spider==github.com

项目介绍

Context Portal MCP (ConPort)

(这是一个记忆库！)

<br>

<br>

一个基于数据库的模型上下文协议（MCP）服务器，用于管理结构化的项目上下文，旨在被AI助手和IDE及其他接口中的开发工具使用。

</div> <br>

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

Context Portal (ConPort) 是您项目的记忆库。它是一个工具，通过存储重要的信息如决策、任务和架构模式来帮助AI助手更好地理解您的特定软件项目。可以将其视为构建一个项目特定的知识库，AI可以轻松访问并使用这些信息来提供更准确和有用的响应。

它做了什么：

跟踪项目决策、进度和系统设计。
存储自定义项目数据（如术语表或规格）。
帮助AI快速找到相关项目信息（就像智能搜索一样）。
允许AI利用项目上下文给出更好的响应（RAG）。
相比简单的文本文件记忆库，更高效地管理和更新上下文。

ConPort 提供了一种强大且结构化的方式让AI助手存储、检索和管理各种类型的项目上下文。它有效地构建了一个项目特定的知识图谱，捕捉了决策、进度和架构等实体及其关系。这个结构化的知识库通过向量嵌入增强了语义搜索功能，然后作为强大的后端支持检索增强生成（RAG），使AI助手能够访问精确、最新的信息，以提供更有上下文意识和准确的响应。

它通过提供一个更可靠和可查询的数据库后端（每个工作区一个SQLite数据库）替换了旧的基于文件的上下文管理系统。ConPort 设计为通用的上下文后端，与支持MCP的各种IDE和客户端界面兼容。

关键特性包括：

使用SQLite进行结构化上下文存储（每个工作区一个数据库，自动创建）。
MCP服务器（context_portal_mcp）使用Python/FastAPI构建。
定义的一整套MCP工具用于交互（见下文“可用的ConPort工具”）。
通过workspace_id支持多工作区。
主要部署模式：STDIO，以便紧密集成到IDE中。
可以构建具有明确关系的动态项目知识图谱。
包括向量数据存储和语义搜索能力，以支持高级RAG。
作为**检索增强生成（RAG）**的理想后端，为AI提供精确、可查询的项目记忆。
提供结构化的上下文，AI助手可以利用这些上下文与兼容的LLM提供商一起进行提示缓存。
使用Alembic迁移管理数据库模式演变，确保无缝更新和数据完整性。

预备条件

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

Python：建议版本3.8或更高。
- 下载Python
- 确保在安装过程中将Python添加到系统的PATH中（特别是在Windows上）。
uv：（强烈推荐）一个快速的Python环境和包管理器。使用uv显著简化虚拟环境的创建和依赖项的安装。
- 安装uv

安装和配置（推荐）

推荐的安装和运行ConPort的方法是使用uvx直接从PyPI执行包。这种方法避免了手动创建和管理虚拟环境的需要。

`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}。使用以下安全选项之一：

在--workspace_id中提供绝对路径。

启动时不提供--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初始化数据库。

<br>

开发者安装（从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设置为您的仓库路径；这将使用您的本地检出和虚拟环境解释器。
日志将发送到./logs/conport-dev.log，并带有DEBUG详细程度。

本地环境设置

通过Git仓库设置开发或贡献环境。

克隆仓库

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

创建虚拟环境
```
uv venv
```
使用您的shell的标准激活命令激活它（例如，在macOS/Linux上使用source .venv/bin/activate）。
安装依赖项
```
uv pip install -r requirements.txt
```
在IDE中运行（推荐） 使用上述的"uvx配置"或开发uv run配置来配置IDE的MCP设置。这是在STDIO模式下对ConPort最代表性的测试。

可选：CLI帮助

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

注意：

对于--workspace_id的行为和IDE路径处理，请参阅上面的"uvx配置"部分的指导。许多IDE不会展开${workspaceFolder}。

<br>

对于升级前的清理，包括清除Python字节码缓存，请参阅v0.2.4_UPDATE_GUIDE.md。

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

通过提供特定的自定义指令或系统提示给LLM，ConPort与LLM代理的有效性得到了显著提升。此仓库包含了针对不同环境定制的战略文件：

对于Roo Code：
- roo_code_conport_strategy：包含详细的指令，指导LLMs如何在Roo Code VS Code扩展内使用ConPort工具进行上下文管理。
<br>
对于CLine：
- cline_conport_strategy：包含详细的指令，指导LLMs如何在CLine VS Code扩展内使用ConPort工具进行上下文管理。
<br>
对于Windsurf Cascade：
- cascade_conport_strategy：针对集成到Windsurf Cascade环境中的LLMs的具体指导。重要：在Cascade中启动会话时，必须明确告诉LLM：
```
根据自定义指令初始化
```
对于通用/平台无关的使用：
- generic_conport_strategy：为任何支持MCP的LLM提供一套平台无关的指令。它强调使用ConPort的get_conport_schema操作动态发现确切的ConPort工具名称及其参数，指导LLM何时以及为何执行概念上的交互（如记录决策或更新产品上下文），而不是硬编码特定工具调用细节。
<br>

如何使用这些战略文件：

识别与您的LLM代理环境相关的战略文件。
复制该文件的全部内容。
将其粘贴到您的LLM的自定义指令或系统提示区域。方法因LLM平台而异（IDE扩展设置、Web UI、API配置）。

这些指令使LLM具备了以下知识：

初始化并从ConPort加载上下文。
使用新信息更新ConPort（决策、进度等）。
管理自定义数据和关系。
理解workspace_id的重要性。 开始会话的重要提示： 为了确保LLM代理正确初始化并加载上下文，尤其是在可能不总是严格遵守首次消息中的自定义指令的接口中，最好以明确的指令开始交互，如： 根据自定义指令初始化。 这可以帮助提示代理执行其策略文件中定义的ConPort初始化序列。

新的战略集：mem4sprint（有什么新的）

仓库中包含一个新的专注于冲刺计划和操作流程的战略/文档集：

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规则。
简化示例并包含最小的操作调用配方。
文档澄清了IDE工作区路径处理的MCP。

在工作区中首次使用ConPort

当您首次在一个新的或现有的项目工作区中使用ConPort时，如果不存在，ConPort数据库（context_portal/context.db）将由服务器自动创建。为了帮助引导初始项目上下文，特别是产品上下文，请考虑以下步骤：

使用`projectBrief.md`文件（推荐）

创建projectBrief.md：在项目工作区的根目录中，创建一个名为projectBrief.md的文件。
添加内容：填充此文件，概述您的项目。这可能包括：
- 项目的主目标或目的。
- 关键功能或组件。
- 目标受众或用户。
- 总体架构风格或关键技术（如果已知）。
- 定义项目的其他基础信息。
自动导入提示：当使用提供的ConPort自定义指令集之一（例如roo_code_conport_strategy）的LLM代理在工作区中初始化时，它会设计为：
- 检查是否存在projectBrief.md。
- 如果找到，它将读取文件并询问您是否希望将其中的内容导入ConPort的产品上下文。
- 如果同意，内容将被添加到ConPort，为项目的产品上下文提供即时基线。

手动初始化

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

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

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

自动工作区检测

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

检测默认启用，可以通过CLI标志控制：

标志：

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

它是如何工作的（多策略）：

强烈指示（快速路径）：查找包含任何以下内容的高置信度项目根目录：package.json、.git、pyproject.toml、Cargo.toml、go.mod、pom.xml。
多个一般指示：如果一个目录中存在≥2个一般指示（README、许可证、构建文件等），则被视为根目录。
已存在的ConPort工作区：存在context_portal/目录表示一个有效的工作区。
MCP环境上下文：当设置并有效时，尊重环境变量如VSCODE_WORKSPACE_FOLDER或CONPORT_WORKSPACE。
回退：如果没有找到指示，则使用起始目录（带有警告）。

工具：

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代理**增强生成（RAG）**的关键检索方面。所有工具都需要一个workspace_id参数（字符串，必需）来指定目标项目工作区。

注意：为了方便，所有类似整数的参数接受数字或纯数字字符串（例如，“10”，“ 3”）。服务器会修剪空白并将它们转换为整数，同时保留验证边界（例如，ge=1）。感谢@cipradu。

产品上下文管理：
- get_product_context：检索整体项目目标、功能和架构。
- update_product_context：更新产品上下文。接受完整的content（对象）或patch_content（对象）进行部分更新（在补丁中使用__DELETE__作为值以删除键）。
活动上下文管理：
- get_active_context：检索当前工作重点、最近更改和开放

上下文门户

项目介绍

Context Portal MCP (ConPort)

(这是一个记忆库！)

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

预备条件

安装和配置（推荐）

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

开发者安装（从Git仓库）

本地环境设置

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

新的战略集：mem4sprint（有什么新的）

在工作区中首次使用ConPort

使用projectBrief.md文件（推荐）

手动初始化

自动工作区检测

可用的ConPort工具

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

使用`projectBrief.md`文件（推荐）