Code Trajectory MCP

代码轨迹MCP服务器

在AI会话中保持你的编码势头。 *将“基于状态”的编码转变为“基于流”的开发。*

代码轨迹MCP 是一个模型上下文协议（MCP）服务器，它为大型语言模型（LLM）提供了编码历史的持久内存。它追踪 *进化* 在影子存储库中存储代码，允许您切换AI聊天会话，而不会丢失您的势头、架构意图或最近决策的上下文。

______________________________________________________________________

🚀 为什么是代码轨迹？

问题：“新会话失忆症”

每个使用LLM的开发人员都知道这场斗争：

1. 上下文溢出： 你正处于深度编码流程中，但聊天时间太长了。LLM速度减慢或达到令牌限制。
2. 强制重置： 你必须开始一个 新聊天.
3. 上下文丢失： 新的人工智能会话对你最后2个小时的工作一无所知。你浪费时间重新解释： *“我正在重构登录…还记得我们决定使用JWT吗？”*

解决方案：持续的动力

代码轨迹 充当人工智能的外部“海马体”（长期记忆）。

• 之前： AI只看到代码的原样 *现在*.
• 使用代码轨迹： AI看到 *如何* 代码的演变和 *哪里* 你中断了。

> *“我看到你正在迁移 auth.py 在上一届会议上，OAuth2。我会在你停下来的地方继续。”*

______________________________________________________________________

✨ 主要特点

1.♾️ 会话连续性

这是核心超级大国。当您开始新的聊天时，AI可以查询此MCP以检索您的聊天摘要 最近的轨迹。它弥合了不连贯的聊天会话之间的差距，确保您的架构决策在“新聊天”按钮后仍然有效。

2.⚡ 自动阴影快照

后台文件监视器会自动在 隐藏影子git存储库 (.trajectory)每当您保存文件时。

• 零污染： 你的主要项目 git 历史是干净的。
• 全粒度： 每次保存都会被记录下来，允许AI分析您的试错过程。

3.🌊 “流动”意识

当前的LLM就像GPS一样工作，它知道你的位置，但不知道你的速度。此工具提供 向量:

• get_file_trajectory：将文件历史记录转换为叙述性故事（过去->现在）。
• get_global_trajectory：分析一个文件中最近的更改如何影响其他文件的“涟漪效应”。

4.🎯 意图和噪声过滤

• 意图记录： 您可以明确地告诉系统： *“我正在重构Auth系统。”* 在更改之前，此意图将标记到所有后续快照。
• 智能整合： 这 consolidate 当任务完成时，该功能将嘈杂的“试错”快照压缩为干净、有意义的历史点。

______________________________________________________________________

🛠️ 技术栈

• 运行时间： Python 3.14+
• 包管理器： 紫外线 （快速Python包安装程序）
• 核心库： mcp, gitpython, watchdog

______________________________________________________________________

📦 安装和设置

1.先决条件

确保你有 uv 安装：

curl -LsSf https://astral.sh/uv/install.sh | sh

2.项目设置

确保目标项目是一个git存储库（MCP使用它来root自己，尽管它将数据存储在 .trajectory).

cd /path/to/your/project
git init

3.配置您的AI客户端

• 克劳德桌面： claude_desktop_config.json
• 光标/IDE： settings.json （或“MCP服务器”配置）

"mcpServers": {
    "code-trajectory": {
        "command": "uvx",
        "args": [
            "--from",
            "git+https://github.com/SynTaek/code-trajectory-mcp.git",
            "code-trajectory-mcp"
        ]
    }
}

4.设置AI说明（推荐）

为了确保AI自主有效地使用Code Trajectory，您必须为其提供操作指南。

1. 复制的完整内容 AGENT_GUIDE.md 从这个存储库。
2. 将其粘贴到AI的自定义指令或系统提示中：

- 光标： 创建或附加到 .cursorrules 项目根目录中的文件。 - 克劳德项目： 添加到“项目说明”。 - 一般法学硕士： 添加到“系统提示”或“自定义说明”中。

提示： 本指南指导人工智能何时查询轨迹以及如何整合历史，确保其作为主动的编码合作伙伴。

______________________________________________________________________

🤖 代理工作流程指南

充分利用 代码轨迹，遵循此工作流程。它确保您的AI上下文在会话中保持不变。

步骤1：初始化（新会话）

当你开始一个 新聊天，始终以以下内容开头：

1. 配置： 呼叫 configure_project(path="/path/to/project").
2. 还原上下文： 呼叫 get_session_summary() 或 get_global_trajectory().

- *结果：* AI下载您上一次会话的“记忆”（例如。， *“上次编辑是在5分钟前 User.ts，目的是“修复API错误”*).

第二步：工作循环

1. 设定意图： set_trajectory_intent("Implementing Dark Mode")

- *为什么？* 这会标记每个保存有此目标的文件，使历史具有语义。

1. 工作： 您或AI编辑文件。服务器自动快照 [AUTO-TRJ] 在背景中。

步骤3：整合（任务完成）

1. 巩固： consolidate("Completed Dark Mode implementation")

- *为什么？* 这将把混乱的中间保存清理到一个清晰的历史节点中，为 *下一个* 会议。

______________________________________________________________________

📊 可视化你的动力

自从 .trajectory 是一个标准的Git存储库，您可以使用标准工具可视化您的“思维过程”。

• VSCode： 打开 .trajectory 在新窗口中创建文件夹并使用 Git图形.
• 终端：

  # View the narrative log
  git --git-dir=.trajectory/.git log --graph --oneline --all

📄 许可证

麻省理工学院