codebase state manager MCP

代码库状态管理器MCP

     ](<>)

AI编码代理的持久项目状态。

代码库状态管理器MCP为任何支持MCP的编码代理提供了对项目的持久记忆。代理可以在采取行动之前查询编号状态、转换、Git感知的更改摘要、压缩SCC-E（状态压缩代码嵌入）上下文、奖励和修复元数据，而不是用稍微不同的提示重试相同的修复。

如果代理一直无法解决同一个错误，那么缺少的成分通常不是更好的提示。这是一个可靠的状态。此服务器将您的代码库历史转换为可查询的系统，模型可以在会话之间检查、比较和重用。

为什么使用AI代理的开发人员会关心

• 每次上下文窗口重置时，您都可以停止重新解释仓库。
• 即使在模型交换或冷启动之后，您也可以为每个新的代理会话分配相同的项目内存。
• 您可以捕捉到发生了什么变化，为什么会发生变化，以及哪种转变真正推动了项目向前发展。
• 你防止顽固的重复问题变成无休止的快速考古。
• 您可以选择适合您工作流程的存储模型：托管Neo4j、外部Neo4j或SQLite。

项目存储什么

每个州都可以坚持：

• 促使变革的动力；
• 分支机构信息；
• Git感知的更改信息(git_diff_info);
• 文件哈希快照或增量；
• SCC-E（状态压缩码嵌入）紧凑上下文(llm_context, compression_version, compacted_at).

每个转变都可以持续下去：

• 源状态；
• 目的地国；
• 用户提示；
• 时间戳；
• 可选奖励。

这为您的代理提供了仅靠聊天历史无法提供的东西：在单个对话之后仍然存在的项目范围内存。

SCC和SCC-E在本项目中的含义

用本项目的语言来说， 鳞状细胞癌 手段 州压缩代码这是将冗长的状态数据压缩为更小、模型友好的表示的总体思路。

SCC-E 手段 状态压缩码——嵌入这是目前在 src/mcp_server/services/scc_codec.py 并通过以下方式存储在每个状态中 llm_context, compression_version，以及 compacted_at.

在实践中，SCC-E将状态历史中的嘈杂部分（更改的路径、差异元数据和文件哈希）重写为紧凑的JSON有效载荷，代理可以廉价地查询。编解码器使用共享路径词汇表、短动作标记和紧凑哈希编码，因此模型可以看到变化的结构，而无需支付每次重放原始差异的全部令牌成本。

这 鳞状细胞癌 该术语也出现在早期的概念细化文档中，作为更广泛的压缩概念和更简单的基线，主要用数字ID替换路径。当前的代码库更进一步并实现了 SCC-E 作为面向LLM的表示，因为该项目需要对代理有用的紧凑状态上下文，而不仅仅是较小的存储空间。

它如何帮助解决顽固的反复出现的问题

当修复程序在“几乎正确”和“仍然损坏”之间来回跳动时，Codebase状态管理器会给出下一轮修复的接地上下文：

1. 导致当前状态的确切快速线索；
2. 更改与代码库相关的证据，而不仅仅是聊天线程；
3. 紧凑的面向LLM的摘要，代理可以快速查询；
4. 有助于浮出成功之路的有回报的转变。

在实践中，这将工作流程从“使用新提示重试”更改为“检查发生了什么，重用有效的东西，纠正无效的东西”。这就是代理再次猜测和代理使用内存操作之间的区别。

这是给谁的

本项目旨在：

• 与具有MCP功能的编码代理一起发货的开发人员；
• 在同一仓库上在不同模型或代理运行时之间切换的团队；
• 希望获得人工智能辅助更改的可审计跟踪的维护人员；
• 尽管有重复的指示，但一个错误或损坏的重构仍然不断返回的项目；
• 本地优先工作流，需要可检查的基础设施而不是黑盒内存。

当它变得有价值时

在以下情况下，您将最快地感受到价值：

• 代理在长会话后失去上下文；
• 一个bug在多次修复尝试中幸存下来；
• 您想比较多种代理生成的方法；
• 你需要一个简洁的摘要，而不是重放整个聊天；
• 你想稍后继续工作，而不相信模型能正确记住。

为什么这与普通聊天历史不同

• 聊天历史记录是线程绑定的。代码库状态管理器是项目绑定的。
• 一份即时的成绩单告诉你说了什么。状态机告诉你发生了什么变化。
• 模型内存是特定于代理的。MCP查询与代理无关。
• 重复的“再次修复此问题”循环会隐藏成功的步骤。奖励转换使它们可见。
• 长上下文窗口仍然会衰减。持久的紧凑状态保持可查询性。

核心能力

专为当今的智能体设计，旨在强化学习

目前的产品方向比单独的状态跟踪更大。路线图正在积极趋同 编码代理的强化学习支持：更丰富的状态动作历史、更好的奖励信号和更强的反馈循环，有助于代理驱动的开发随着时间的推移而改进，而不是在每次会话中从头开始。

这个方向非常适合这个项目，因为从代码生成工作流程中学习的困难部分不仅仅是评分结果。它正在保护 状态，the 行动轨迹，以及 奖励上下文 以一种可以查询、审核和重用的形式。代码库状态管理器正在被塑造成内存和反馈层。

重要提示： 全面强化学习支持 版本中不可用 0.2.1.

当前版本已经为您提供了什么：

• 代理驱动工作的持久状态历史；
• 紧凑的SCC-E环境，可实现低成本召回；
• 奖励转换作为早期反馈原语；
• 在聊天重置和代理交换中幸存下来的持久存储。

当前版本之前还有什么：

• 端到端强化学习工作流程；
• 自动训练或策略优化循环；
• MCP服务器上的生产就绪RL编排。

这意味着您现在可以采用该项目来立即提高可靠性，同时将自己与一个路线图保持一致，该路线图针对的是那些不仅仅生成代码的代理——这些代理最终可以从重复的结果中学习。

存储模式

托管Neo4j模式自动创建或重用 项目范围 Neo4j容器。在此模式下，MCP客户端配置不需要Neo4j凭据。

当 VOLUME_PATH 如果未设置，则托管工作区快照默认为：

/opt/codebase-state-manager/volumes/

默认情况下，这会将托管快照保留在项目树之外。

快速启动

先决条件

必修的：

• python 3.10+
• uv
• Git

仅适用于托管Neo4j模式：

• Docker守护进程在本地运行

安装

git clone 
cd codebase_state_manager_mcp
./scripts/setup.sh

紫外线直接安装的替代方案：

uv sync --extra dev

启动服务器

推荐启动器：

python run_mcp_server.py

替代模块入口点：

python -m src.mcp_server

传统兼容性启动器：

python init_neo4j_and_mcp.py

使用 run_mcp_server.py 对于所有新的集成。

最小MCP客户端配置

托管Neo4j模式的推荐配置：

{
  "mcp": {
    "codebase-state-manager": {
      "type": "local",
      "command": [
        "uv",
        "run",
        "--project",
        "/absolute/path/to/codebase_state_manager_mcp",
        "python",
        "run_mcp_server.py"
      ],
      "enabled": true
    }
  }
}

对于SQLite模式，设置：

{
  "DB_MODE": "sqlite"
}

对于外部Neo4j模式，设置：

{
  "DB_MODE": "neo4j",
  "NEO4J_BOOTSTRAP_MODE": "external",
  "NEO4J_URI": "bolt://localhost:7687",
  "NEO4J_USER": "neo4j",
  "NEO4J_PASSWORD": "your_password"
}

看 设置.md 获取完整的安装、环境和故障排除指南。

用于代理工作流的高价值工具

FastMCP服务器当前公开 25 工具。大多数代理驱动的工作流都从以下工具开始。

初始化并捕获状态

• genesis_tool
• start_genesis_tool
• get_genesis_status_tool
• get_genesis_result_tool
• new_state_transition_tool
• arbitrary_state_transition_tool

检查和搜索历史记录

• get_current_state_info_tool
• get_state_info_tool
• get_current_state_number_tool
• total_states_tool
• search_states_tool
• get_state_transitions_tool
• get_current_state_transitions_tool
• get_transition_info_tool
• track_transitions_tool

查询紧凑的LLM上下文

• get_current_state_compact_context_tool
• get_compact_states_tool

重用成功的路径

• get_rewarded_transitions_tool
• set_transition_reward_tool

恢复和修复运行时状态

• fix_volume_path_tool
• start_fix_volume_path_tool
• get_fix_volume_path_status_tool
• get_fix_volume_path_result_tool
• check_consistency_tool
• repair_consistency_tool

国家代表

返回a的工具 State 支持：

• raw --完整的遗留有效载荷
• compact --仅紧凑的SCC-E（状态压缩代码嵌入）视图
• both --两种表示方式结合在一起

今天支持：

• genesis_tool
• get_genesis_result_tool
• new_state_transition_tool
• arbitrary_state_transition_tool
• get_current_state_info_tool
• get_state_info_tool

质量和架构信号

该存储库旨在赢得每天与代理商合作的开发人员的信任：

• 分层运行时结构 src/mcp_server/{tools,services,repositories,models,utils};
• 具有奇偶校验期望的双后端持久性 State 和 Transition 领域；
• 使用mypy配置键入Python代码；
• 使用Bandit进行安全扫描；
• 跨单元、集成、端到端、安全、性能和压力套件的测试覆盖率。

如果你想了解确切的实现细节，请阅读：

• 建筑.md --系统架构和存储映射
• 设置.md --安装、环境变量、故障排除
• QUICKSTART.md --最小设置和客户端配置
• 贡献.md --贡献者工作流程和验证清单
• 更改日志.md --发布历史和发布意图
• 代理商.md --编码代理的存储库说明

收养是什么样子的

典型的工作流程如下：

1. 使用以下命令初始化项目一次 genesis_tool.
2. 让您的代理创建有意义的检查点 new_state_transition_tool.
3. 当修复停滞时，查询 search_states_tool, get_current_state_info_tool, get_compact_states_tool，以及 get_rewarded_transitions_tool 在再次盲目提示之前。
4. 如果托管工作区或运行时漂移，请使用 check_consistency_tool, repair_consistency_tool，或 fix_volume_path_tool.
5. 从真实的项目状态恢复，而不是相信模型会记住一切。

该工作流使MCP服务器不仅仅是一个记录器。它成为代码生成、调试和恢复的内存层。

许可证

MIT。看 许可证.