关键词

项目上下文管理AI后端知识图谱决策记录进度追踪结构化数据存储

项目简介

Context Portal (ConPort) 是一个基于 Model Context Protocol (MCP) 实现的服务器后端，旨在为人工智能助手和开发者工具（如集成开发环境 - IDE）提供一个结构化、可查询的项目上下文管理系统。它使用 SQLite 数据库存储项目的关键信息，如技术决策、开发进度、设计模式和自定义数据，有效构建一个项目专属知识图谱。ConPort 作为 LLM 应用的检索增强生成 (RAG) 后端，帮助 AI 更准确地理解项目情况并生成更相关的响应。

主要功能点

  • 结构化上下文存储: 使用 SQLite 数据库安全存储项目上下文，每个工作区（Workspace）一个独立的数据库文件。
  • MCP 服务器实现: 基于 Python 和 FastAPI 构建的标准 MCP 服务器，提供多种数据访问和操作接口。
  • 丰富的工具集: 提供了用于管理项目上下文、记录决策、追踪进度、存储自定义数据、创建项目知识图谱链接等多种工具供 LLM 调用。
  • 多工作区支持: 通过 'workspace_id' 参数区分和管理不同项目的上下文。
  • IDE 集成优化: 支持 STDIO 模式，方便与 IDE 紧密集成，由 IDE 管理服务器进程。
  • RAG 强大后端: 为 AI 提供精确、可查询的项目记忆，提升 AI 助手的感知能力。

安装步骤

ConPort 使用 Python 开发，推荐使用 'uv' 或 'venv' 创建虚拟环境进行安装。

  1. 克隆仓库: 打开终端，执行以下命令克隆项目代码并进入目录：

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

  2. 创建并激活虚拟环境:

    • 使用 'uv' (推荐): 在 'context-portal' 目录下运行 'uv venv'。然后根据你的操作系统和 shell 激活环境（例如：'source .venv/bin/activate'）。
    • 使用标准 'venv': 在 'context-portal' 目录下运行 'python3 -m venv .venv'。然后根据你的操作系统和 shell 激活环境。

  3. 安装依赖: 在虚拟环境已激活的状态下，运行以下命令安装项目所需的依赖：

    uv pip install -r requirements.txt
# 或者使用 pip:
# pip install -r requirements.txt

  4. 验证安装 (可选): 激活虚拟环境后，运行 'python src/context_portal_mcp/main.py --help'，如果能看到服务器的帮助信息，则表示安装成功。

服务器配置 (MCP 客户端视角)

作为 MCP 服务器，ConPort 不直接运行为一个独立的 HTTP 服务（除非以 'http' 模式启动），它主要设计为由 MCP 客户端（如 IDE 插件）按需启动和管理，特别是通过 STDIO 模式进行通信。

MCP 客户端通常需要一个 JSON 格式的配置文件或通过设置面板指定如何启动 ConPort 服务器。以下是配置示例的关键信息说明（具体格式取决于你的 MCP 客户端）：

  • 服务器名称: 'conport' (这是客户端用于引用此服务器的名称)
  • 启动命令 (command): 指定运行 ConPort 服务器 Python 脚本的解释器路径。必须使用虚拟环境内的 Python 解释器的绝对路径。
    • Linux/macOS 示例: '/home/youruser/projects/context-portal/.venv/bin/python'
    • Windows 示例: 'C:\Users\YourUser\Projects\context-portal\.venv\Scripts\python.exe' (注意 Windows 路径中的双反斜杠)
  • 命令参数 (args): 传递给启动命令的参数列表。
    • 第一个参数通常是 'main.py' 脚本的绝对路径。
      • Linux/macOS 示例: '/home/youruser/projects/context-portal/src/context_portal_mcp/main.py'
      • Windows 示例: 'C:\Users\YourUser\Projects\context-portal\src\context_portal_mcp\main.py'
    • '--mode stdio': 指定 ConPort 运行在 STDIO 模式，通过标准输入/输出进行通信。这是 IDE 集成的推荐模式。
    • '--workspace_id "绝对路径"': 必须提供当前项目工作区的绝对路径。ConPort 会根据此路径创建和管理数据库。MCP 客户端通常提供占位符（如 '${workspaceFolder}'），客户端应负责将其解析为实际的绝对路径。

MCP 客户端配置示例 (概念说明，非直接代码):

一个典型的 MCP 客户端配置会包含类似以下结构的信息：

{
  "mcpServers": {
    "conport": {
      "command": "你的 Python 虚拟环境解释器绝对路径",
      "args": [
        "你的 ConPort 项目 main.py 脚本绝对路径",
        "--mode", "stdio",
        "--workspace_id", "当前项目工作区的绝对路径 (使用 IDE 占位符或硬编码)"
      ]
      // 客户端可能还需要其他设置，如 "cwd" 来设置进程的工作目录
    }
  }
  // ... 其他 MCP 配置
}

请务必将上述示例中的占位符替换为你的 ConPort 安装路径和实际项目工作区路径。

基本使用方法

ConPort 服务器主要通过 MCP 工具被 LLM 客户端调用来使用。一旦 ConPort 被客户端按上述配置成功启动并连接，LLM 就可以通过调用其暴露的工具来与项目上下文进行交互：

  1. 初始化上下文: LLM 客户端（根据其自定义指令）可以在新的工作区启动时，调用工具检查 'product_context' 或 'active_context' 是否已初始化。如果未初始化，可以通过 'update_product_context' 或 'update_active_context' 工具导入初始信息（例如从 'projectBrief.md' 文件导入）。
  2. 获取上下文: LLM 可以随时调用 'get_product_context' 或 'get_active_context' 获取项目概况或当前工作焦点，以便理解对话背景。
  3. 记录信息: LLM 可以根据用户指令或自身活动，调用相应的工具记录信息：
    • 'log_decision': 记录重要的技术决策。
    • 'log_progress': 记录任务状态或开发进度。
    • 'log_system_pattern': 记录项目中常用的设计模式或技术方案。
    • 'log_custom_data': 存储任意结构的自定义项目数据（如项目术语表、角色信息）。
  4. 查询信息: LLM 可以调用工具查询已记录的信息：
    • 'get_decisions', 'get_progress', 'get_system_patterns', 'get_custom_data': 按条件（如标签、状态、类别、Key）检索信息。
    • 'search_decisions_fts', 'search_custom_data_value_fts', 'search_project_glossary_fts': 使用全文搜索查找相关信息。
    • 'get_linked_items': 获取与特定项目项相关联的其他项，探索知识图谱。
    • 'get_item_history': 查看产品或活跃上下文的历史版本。
    • 'get_recent_activity_summary': 获取近期项目活动的概览。
  5. 更新/删除信息: LLM 可以调用 'update_product_context', 'update_active_context', 'delete_decision_by_id', 'delete_system_pattern_by_id', 'delete_custom_data' 等工具修改或移除信息。
  6. 知识图谱构建: LLM 可以调用 'link_conport_items' 工具在不同项目项之间创建显式关系链接。
  7. 数据导入/导出: 支持使用 'export_conport_to_markdown' 和 'import_markdown_to_conport' 将数据导出到 Markdown 文件或从 Markdown 文件导入。
  8. 获取能力: LLM 可以调用 'get_conport_schema' 工具动态获取所有可用工具及其参数的详细 schema，以便正确调用。

通过这些工具，LLM 客户端可以与 ConPort 存储的项目知识进行深度互动，从而为用户提供更智能、更精准的帮助。

信息

分类

AI与计算

访问项目