CodeStat 面向模型上下文的后端服务

使用说明（Markdown 格式）

• 项目简介

  • 本仓库实现了一个本地化的 MCP 风格服务器，核心目标是为大型语言模型（LLM）客户端提供可复用的上下文服务。通过注册工具，LLM 可以在本地执行编辑前后对比、记录 diff 信息并汇总统计，同时提供数据持久化与备份能力。

• 主要功能点

  • 工具注册与发现：通过 FastMCP 框架提供的工具机制，注册 RecordBeforeEdit、RecordAfterEdit 等工具，并提供 /mcp/tools 的发现端点，供客户端自动发现和注册。
  • 编辑记录与差异提取：RecordBeforeEdit 用来在编辑前缓存代码，RecordAfterEdit 计算对比差异行（新增/修改）、提取行号并存储为会话级别的摘要与详细差异。
  • 本地数据存储：使用 SQLite 数据库保存临时的编辑前代码、会话摘要、差异行明细，以及备份记录。
  • 数据备份与清理：内置调度器实现定时备份数据库、清理旧数据，支持手动备份与恢复。
  • 客户端交互与展示：提供 CLI 与可扩展的前端视图，用于查看全局/会话/文件/项目维度的指标，并支持结果导出为 JSON/CSV。
  • 运行方式灵活：支持直接前台运行与简单后台模式，便于开发和测试使用。
  • 安全与隔离：编辑前的缓存数据在完成记录后会被清理，差异信息以最小必要的形式持久化，降低隐私风险。

• 安装步骤

  • 克隆仓库并进入项目目录。
  • 安装依赖（如 requirements.txt 中列出的依赖）。
  • 通过以下任意方式启动服务器：
    • 直接启动 MCP 服务（推荐作为本地服务器运行）：
      • 启动命令示例（主机/端口可自定义）： python local_mcp_server.py start --host 127.0.0.1 --port 8000
    • 或使用主程序入口启动 CLI 与服务器协同工作（详见 main.py 的使用说明）。
  • 服务器启动后，客户端即可通过以下端点发现并调用工具：
    • 工具发现端点：GET /mcp/tools
    • 记录编辑前工具：POST /mcp/record_before
    • 记录编辑后工具：POST /mcp/record_after

• 服务器配置（MCP 客户端所需的配置信息以 JSON 形式给出，客户端不需要该配置，但方便理解服务器的运行参数）

  • JSON 配置示例（仅供参考，实际运行时客户端通常不需要此配置）： { "server": { "name": "CodeStat 本地环境", "command": "python", "args": ["local_mcp_server.py", "start", "--host", "127.0.0.1", "--port", "8000"] } // 运行时服务器的主机、端口等信息由运行命令中的参数决定，以上仅为描述用 }
  • 注解说明：
    • name：服务器在本地环境中的标识名称，便于区分多实例。
    • command/args：启动服务器所需的命令及参数，通常由开发者在启动脚本时指定。

• 基本使用方法

  • 发现工具
    • 通过工具发现端点获取可用工具清单，选择要注册和使用的工具。
  • 记录代码差异流程（示例）
    • 调用 RecordBeforeEdit，传入会话 ID、目标文件路径、编辑前的完整代码内容。
    • 编辑文件后，调用 RecordAfterEdit，传入相同的会话 ID 与文件路径，以及编辑后的完整代码内容，可附带会话信息。
    • 服务端返回的结果包含新增/修改的行数、总行数等统计信息，并清理临时记录。
  • 数据查询与导出
    • 使用 CLI/UI 查询全局、会话、文件、项目层面的指标。
    • 如需离线分析，可将结果导出为 JSON/CSV。

• 关键词

  • 本地开发、代码对比、差异提取、会话统计、数据备份

• 分类ID

  • 6