关键词

工程日志Git钩子AI自动化上下文捕获结构化日志

项目简介

MCP Commit Story 是一个为开发者设计的个人工程日志服务器，旨在自动捕获开发工作流中的关键上下文（如Git提交、AI对话、终端命令），并利用AI生成结构化、有叙事性的日志条目。它以Model Context Protocol (MCP) 服务器的形式运行，供AI客户端或集成工具调用，而非一个供人工直接操作的日常命令行工具。

主要功能点

  • 自动化上下文捕获: 作为MCP服务器，它被设计与AI客户端或其他工具协作，自动收集Git提交信息、AI聊天记录、终端命令等上下文数据。
  • AI驱动的日志生成: 根据收集到的上下文，生成详细的日志条目，包括摘要、技术概述、成就、遇到的挑战、情绪基调、讨论要点等。
  • 结构化日志格式: 生成的日志采用Markdown格式，结构清晰，易于阅读和解析。
  • 按需目录创建: 日志文件及其所属的子目录（如每日、每周总结目录）在写入时自动创建，避免预创建文件系统结构。
  • Git钩子集成: 提供安装'post-commit' Git钩子的能力，以便在每次提交后自动触发日志生成过程。
  • 可观测性遥测: 内建对OpenTelemetry的支持，用于跟踪服务器操作、文件读写、AI生成过程的性能和错误。
  • 可热加载配置: 服务器配置支持从文件加载，并可在运行时重新加载，无需重启。
  • 标准化错误处理: 通过'handle_mcp_error'装饰器提供统一的MCP操作错误响应格式。

安装步骤

由于项目仍在积极开发中，以下是基于仓库结构推测的标准 Python 项目安装流程。请参考项目官方文档获取最新和最准确的安装指南。

  1. 克隆仓库: 
    git clone https://github.com/wiggitywhitney/mcp-commit-story.git
cd mcp-commit-story
  2. 创建并激活虚拟环境 (推荐): 
    python -m venv .venv
# On Linux/macOS:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate
  3. 安装依赖: 使用 Poetry 或 pip 安装项目及其依赖 (包括开发依赖，以便运行测试等)。如果 'pyproject.toml' 已配置 Poetry，使用 Poetry 安装；否则使用 pip。 
    # If using Poetry:
# pip install poetry
# poetry install

# If using pip (based on pyproject.toml's dependencies):
pip install -e .
# For development dependencies:
pip install -e .[dev]
  4. 初始化日志仓库: 在你想要记录开发历程的Git仓库根目录运行（不是 mcp-commit-story 本身的仓库）： 
    # 假设你在你的项目仓库根目录
mcp-commit-story-setup journal-init
    这会在当前Git仓库中创建 '.mcp-commit-storyrc.yaml' 配置文件和 'journal/' 目录。
  5. 安装Git钩子: 在你的项目Git仓库根目录运行： 
    # 假设你在你的项目仓库根目录
mcp-commit-story-setup install-hook
    这会在你项目的 '.git/hooks/' 目录下安装 'post-commit' 钩子，以便在每次提交后触发日志生成。

服务器配置 (供MCP客户端参考)

MCP Commit Story 作为一个MCP服务器，其核心功能通过JSON-RPC接口提供，主要用于被AI客户端或集成工具调用。MCP客户端需要配置如何启动该服务器进程并与之通信。

以下是一个示例的MCP客户端配置结构，说明需要配置的关键信息：

{
  "server": {
    "name": "mcp-commit-story",
    "command": ["python", "-m", "mcp_commit_story.server"], 
    "args": [], 
    "transport": "stdio", 
    "tools": [
      "journal/new-entry",
      "journal/add-reflection",
      "journal/init",
      "journal/install-hook"
      // ... 可能还有其他日志相关的工具
    ]
  }
}
  • 'name': MCP服务器的唯一标识名，在此为 "mcp-commit-story"。
  • 'command': 启动MCP服务器进程的命令。基于项目结构和'FastMCP'的常见用法，这可能是一个直接执行服务器模块的命令，如 '["python", "-m", "mcp_commit_story.server"]'，或者一个由项目提供的专用启动脚本。请查阅最新的项目文档确认准确的启动命令。
  • 'args': 传递给启动命令的命令行参数列表。在当前阶段可能为空，或用于指定配置文件路径等。
  • 'transport': 客户端与服务器通信的传输协议。对于本地运行的工具，'stdio'（标准输入/输出）是常见且推荐的协议。其他可能的协议（如 SSE, WebSocket）取决于服务器的具体实现是否已支持。
  • 'tools': 该MCP服务器提供的工具列表。客户端可以声明或发现这些工具，并按MCP规范通过JSON-RPC调用它们（例如，调用 'journal/new-entry' 工具）。

基本使用方法

安装并配置Git钩子后，核心功能在Git提交时自动触发。AI客户端可以通过调用相应的MCP工具来实现更高级的功能或进行交互式日志管理。

  1. 通过Git提交自动生成日志: 在你的项目仓库中进行代码修改、提交。Git钩子会自动运行，触发MCP Commit Story服务器收集上下文并尝试为该提交生成日志条目，追加到你的'journal/'文件中。
  2. 通过MCP客户端添加反思: 如果你使用的AI客户端集成了MCP Commit Story服务器，你可以通过客户端调用 'journal/add-reflection' 工具，提供反思文本和日期，手动向日志文件添加一条反思记录。
  3. 通过MCP客户端初始化或安装钩子: 虽然提供了命令行工具用于设置，AI客户端也可以通过调用 'journal/init' 或 'journal/install-hook' 工具来执行这些初始化操作。

信息

分类

开发者工具

访问项目