上下文门户MCP（ConPort）
（这是一个记忆库！）
一种数据库支持的模型上下文协议（MCP）服务器，用于管理结构化项目上下文，旨在供IDE和其他接口中的AI助手和开发工具使用。
什么是上下文门户MCP服务器（ConPort）？
上下文门户（ConPort）是您项目的 存储体这是一种工具，通过以结构化的方式存储决策、任务和架构模式等重要信息，帮助人工智能助手更好地理解您的特定软件项目。将其视为构建一个特定于项目的知识库，人工智能可以轻松访问和使用，为您提供更准确和有用的答案。
它的作用：
- 跟踪项目决策、进度和系统设计。
- 存储自定义项目数据（如术语表或规格）。
- 帮助人工智能快速找到相关的项目信息（如智能搜索）。
- 使人工智能能够使用项目上下文进行更好的响应（RAG）。
- 与简单的基于文本文件的内存库相比，更有效地管理、搜索和更新上下文。
ConPort为AI助手提供了一种强大而结构化的方式来存储、检索和管理各种类型的项目上下文。它有效地构建了一个 项目特定知识图，捕获决策、进度和架构等实体及其关系。这个结构化的知识库，通过以下方式得到增强 向量嵌入 对于语义搜索，然后作为一个强大的后端 检索增强生成（RAG），使人工智能助手能够访问精确、最新的信息，以获得更具情境意识和准确的响应。
它通过提供更可靠和可查询的数据库后端（每个工作区使用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上）。
- 紫外线： （强烈推荐）一个快速的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不会扩展${workspaceFolder}启动MCP服务器时。使用以下安全选项之一： 1. 为提供绝对路径--workspace_id. 1. 省略--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模式和真实的客户端行为。
如果需要对本地签出和virtualenv运行，可以配置MCP客户端以通过以下方式启动开发服务器 uv run 和你的 .venv/bin/python:
{
"mcpServers": {
"conport": {
"command": "uv",
"args": [
"run",
"--python",
".venv/bin/python",
"--directory",
"
",
"conport-mcp",
"--mode",
"stdio",
"--log-file",
"./logs/conport-dev.log",
"--log-level",
"DEBUG"
],
"disabled": false
}
}
}笔记：
- 集
--directory转到您的回购路径；这使用您的本地结账和venv解释器。 - 日志转到
./logs/conport-dev.log随着DEBUG冗长。
本地环境设置
通过Git仓库进行开发或贡献设置。
- 克隆存储库
git clone https://github.com/GreatScottyMac/context-portal.git
cd context-portal- 创建虚拟环境
uv venv使用shell的标准激活（例如。， source .venv/bin/activate 在macOS/Linux上）。
- 安装依赖项
uv pip install -r requirements.txt- 在IDE中运行（推荐）
使用“uvx配置”或dev配置IDE的MCP设置 uv run 配置如上所示。这是STDIO模式下ConPort最具代表性的测试。
- 可选：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代理的使用（自定义说明）
通过向LLM提供特定的自定义指令或系统提示，ConPort对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 _当_ 和 _为什么_ 执行概念交互（如记录决策或更新产品上下文），而不是硬编码特定的工具调用细节。
如何使用这些策略文件：
- 确定与LLM代理环境相关的策略文件。
- 复制 全部内容 该文件。
- 将其粘贴到LLM的自定义说明或系统提示区域。方法因LLM平台（IDE扩展设置、web UI、API配置）而异。
这些说明使法学硕士具备以下知识：
- 从ConPort初始化并加载上下文。
- 用新信息（决策、进度等）更新ConPort。
- 管理自定义数据和关系。
- 了解以下内容的重要性
workspace_id.
开始会话的重要提示： 为了确保LLM代理正确初始化和加载上下文，特别是在可能并不总是严格遵守第一条消息上的自定义指令的接口中，最好用一个明确的指令开始交互，比如： Initialize according to custom instructions. 这可以帮助提示代理执行其策略文件中定义的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规则。
- 简化了示例，并包含了最少的操作调用配方。
- 文档阐明了MCP的IDE工作区路径处理。
工作区中的初始ConPort使用情况
当您首次在新的或现有的项目工作区中开始使用ConPort时，ConPort数据库(context_portal/context.db)如果它不存在，将由服务器自动创建。为了帮助引导初始项目上下文，特别是 产品背景，请考虑以下事项：
使用a projectBrief.md 文件（推荐）
- 创建
projectBrief.md: 在项目工作区的根目录中，创建一个名为projectBrief.md. - 添加内容： 用项目的高级概述填充此文件。这可能包括：
- 项目的主要目标或目的。 - 关键特征或组件。 - 目标受众或用户。 - 总体架构风格或关键技术（如已知）。 - 定义项目的任何其他基础信息。
- 自动提示导入： 当LLM代理使用所提供的ConPort自定义指令集之一时（例如。，
roo_code_conport_strategy)在工作区中初始化，其设计目的是：
- 检查是否存在 projectBrief.md. - 如果找到，它将读取文件并询问您是否要将其内容导入ConPort 产品背景. - 如果您同意，内容将添加到ConPort中，为项目的产品上下文提供即时基线。
手动初始化
如果 projectBrief.md 未找到，或者如果您选择不导入它：
- LLM代理（在其自定义说明的指导下）通常会通知您ConPort产品上下文似乎未初始化。
- 它可能会帮助您手动定义产品上下文，可能是通过在工作区中列出其他文件来收集相关信息。
通过以下方式提供初始上下文 projectBrief.md 或者手动输入，您可以使ConPort和连接的LLM代理从一开始就对您的项目有更好的基础了解。
自动工作空间检测
ConPort可以自动确定正确的 workspace_id 因此，您不需要在MCP客户端配置中硬编码绝对路径。这对于无法扩展的IDE尤其有用 ${workspaceFolder} 启动MCP服务器时。
默认情况下启用检测，可以通过CLI标志进行控制：
旗帜：
--auto-detect-workspace（默认：启用）打开自动检测。--no-auto-detect禁用检测（显式--workspace_id或按工具workspace_id然后必须提供）。- `--workspace-search-start
` 用于向上搜索的可选起始目录（默认为当前工作目录）。
其工作原理（多策略）：
- 强指标（快速路径）：寻找包含以下任何一项的高置信度项目根：
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工具）显示一个诊断字典，显示：
- 开始路径 - 已检测工作空间 - 检测方法（strong_indicators |多个indicators | existing_text_portal |回退） - 指示器_找到 - 相关环境变量
最佳实践：
- 保持检测启用，除非您操作的是需要对每个调用进行显式隔离的多根场景。
- 如果IDE传递文字字符串
${workspaceFolder}，ConPort将忽略它并自动安全检测（记录在警告中）。 - 对于调试不明确的根（例如嵌套存储库），请运行检测信息工具以确认选择了哪个目录。
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公开以下工具，允许与底层进行交互 项目知识图。这包括以下工具 语义搜索 由...驱动 矢量数据存储这些工具有助于 检索 关键方面 增强生成（RAG） AI代理。所有工具都需要 workspace_id 参数（字符串，必填），用于指定目标项目工作区。
注意：为方便起见，所有类整数参数都接受数字或纯数字字符串（例如“10”、“3”）。服务器修剪空格并将其强制转换为整数，同时保留验证边界（例如，ge=1）。来源：@cipradu。
- 产品上下文管理：
- get_product_context：检索总体项目目标、功能和架构。 - update_product_context：更新产品上下文。接受完整 content （对象）或 patch_content （object）用于部分更新（使用 __DELETE__ 作为补丁中删除密钥的值）。
- 主动上下文管理：
- get_active_context：检索当前工作重点、最近的更改和未解决的问题。 - update_active_context：更新活动上下文。接受完整 content （对象）或 patch_content （object）用于部分更新（使用 __DELETE__ 作为补丁中删除密钥的值）。
- 决策记录：
- log_decision：记录架构或实现决策。 - Args： summary （str，req）， rationale （str，opt）， implementation_details （str，opt）， tags （list\[str\]，opt）。 - get_decisions：检索记录的决策。 - Args： limit （int、opt）， tags_filter_include_all （list\[str\]，opt）， tags_filter_include_any （list\[str\]，opt）。 - search_decisions_fts：在决策字段（摘要、基本原理、详细信息、标签）之间进行全文搜索。 - Args： query_term （str，req）， limit （int，opt）。 - delete_decision_by_id：按ID删除决定。 - Args： decision_id （int，req）。
- 进度跟踪：
- log_progress：记录进度条目或任务状态。 - Args： status （str，req）， description （str，req）， parent_id （int、opt）， linked_item_type （str，opt）， linked_item_id （str，opt）。 - get_progress：检索进度条目。 - Args： status_filter （str，opt）， parent_id_filter （int、opt）， limit （int，opt）。 - update_progress：更新现有进度条目。 - Args： progress_id （int，req）， status （str，opt）， description （str，opt）， parent_id （int，opt）。 - delete_progress_by_id：按ID删除进度条目。 - Args： progress_id （int，req）。
- 系统模式管理：
- log_system_pattern：记录或更新系统/编码模式。 - Args： name （str，req）， description （str，opt）， tags （list\[str\]，opt）。 - get_system_patterns：检索系统模式。 - Args： tags_filter_include_all （list\[str\]，opt）， tags_filter_include_any （list\[str\]，opt）。 - delete_system_pattern_by_id：按ID删除系统模式。 - Args： pattern_id （int，req）。
- 自定义数据管理：
- log_custom_data：在类别下存储/更新自定义键值条目。值是JSON可序列化的。 - Args： category （str，req）， key （str，req）， value （任何，要求）。 - get_custom_data：检索自定义数据。 - Args： category （str，opt）， key （str，opt）。 - delete_custom_data：删除特定的自定义数据条目。 - Args： category （str，req）， key （str，req）。 - search_project_glossary_fts：在“ProjectGlossary”自定义数据类别中进行全文搜索。 - Args： query_term （str，req）， limit （int，opt）。 - search_custom_data_value_fts：对所有自定义数据值、类别和键进行全文搜索。 - Args： query_term （str，req）， category_filter （str，opt）， limit （int，opt）。
- 上下文链接：
- link_conport_items：在两个ConPort项之间创建关系链接，显式构建 项目知识图. - Args： 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：检索链接到特定项的项。 - Args： 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：检索产品或活动上下文的版本历史记录。 - Args： item_type （“product_context”|“active_context”，请求）， version （int、opt）， before_timestamp （日期时间，可选）， after_timestamp （日期时间，可选）， limit （int，opt）。 - get_recent_activity_summary：提供最近ConPort活动的摘要。 - Args： hours_ago （int、opt）， since_timestamp （日期时间，可选）， limit_per_type （int，opt，默认值：5）。 - get_conport_schema：检索可用ConPort工具及其参数的架构。
- 进口/出口：
- export_conport_to_markdown：将ConPort数据导出到markdown文件。 - Args： output_path （str，opt，默认值：“./conport_export/”）。 - import_markdown_to_conport：将数据从markdown文件导入ConPort。 - Args： input_path （str，opt，默认值：“./conport_export/”）。
- 批量操作：
- batch_log_items：在一次通话中记录多个相同类型的项目（例如，决策、进度条目）。 - Args： item_type （str，req-例如“决策”、“进展尝试”）， items （list\[dict\]，req-项目类型的Pydantic模型字典列表）。
进一步阅读
要更深入地了解ConPort的设计、架构和高级使用模式，请参阅：
贡献
请查看我们的 贡献.md 关于如何为ConPort项目做出贡献的详细指南。
许可证
该项目根据 Apache-2.0许可证.
致谢
- 特别感谢 @cipradu 对于为数字参数实现整数字符串强制转换的宝贵建议，这改善了从各种客户端与MCP服务器交互时的用户体验。
数据库迁移和更新指南
有关如何管理您的 context.db 文件，特别是在跨包含数据库架构更改的版本更新ConPort时，请参阅专用 v0.2.4_UPDATE_GUIDE.md。本指南提供了手动数据迁移（导出/导入）的步骤（如果需要）和故障排除提示。