MCP Commit Story: Your Engineering Journey, Remembered

MCP Commit Story：铭记你的工程历程

什么是 MCP Commit Story？

MCP Commit Story 是面向开发者的个人工程日志，帮助你记录的不只是构建了什么，还有过程中的感受，以及它为何重要。

它仍在持续开发中，由关注代码背后故事的开发者为开发者打造。

MCP Commit Story 以 Model Context Protocol（MCP）服务的形式运行，旨在与 AI Agent 协同工作。这些 Agent 会帮助收集并总结开发工作流中的真实背景，让日志条目始终以实际发生的事情为依据。

---

为什么要构建它？

作为开发者，你很容易忘记工作背后的“为什么”——遇到了哪些挑战、学到了什么，以及自己如何成长。 MCP Commit Story 能帮你：

• 记录历程： 每次提交都会变成一篇日志，记录的不只是技术变更，还有一路上的决策、挫折和小小的胜利。
• 铭记感受： 日志会记录心情和情绪背景，让你回顾时不只看见做了什么，也能看见当时的感受。
• 呈现故事与洞见： 收集工作流中的真实背景（AI Agent 聊天、终端、代码变更、提交消息），有助于你发现挑战与成功的脉络——非常适合撰写博客、准备会议演讲，或只是了解自己的成长（这可不是小事！）
• 支持回顾与评审： 总结和洞见能帮助你进行反思、争取职业晋升，或解释做出某些选择的原因。

---

一天会是什么样？

以下是根据真实开发数据生成的每日总结示例：

# Daily Summary - June 4, 2025

## Summary
June 4th was a day of strategic evolution from "making it work" to "making it production-ready" - a journey that revealed the hidden complexities of building robust systems. The day progressed from adding comprehensive MCP best practices to breakthrough insights about AI orchestration patterns, culminating in the humbling realization that AI content quality requires more sophisticated approaches than initially anticipated. This represents the classic progression from proof-of-concept excitement to production engineering reality.

## Key Insights & Breakthrough Moments
**The Production Readiness Awakening**: Creating seven new production readiness tasks revealed the gap between "functional" and "deployable." The realization that issues like stdout pollution, performance validation, and logging infrastructure could break MCP client compatibility demonstrates how production systems require thinking beyond core functionality to operational excellence.

**AI Orchestration Architecture Insight**: The breakthrough that AI Function Pattern functions needed centralized orchestration rather than individual context detection represents a significant architectural insight. The discovery that calling AI functions directly always returned stubs, regardless of context, led to the realization that AI capability needs to be handled at the system boundary rather than embedded in individual functions.

**The Quality vs. Speed Trade-off Reality**: Multiple iterative attempts to improve AI content quality revealed the fundamental challenge of building reliable AI-powered systems. The discovery that AI agents needed increasingly explicit instructions to avoid shortcuts and hallucinations shows how AI system reliability requires different engineering approaches than traditional deterministic systems.

## Strategic Thinking Highlights
**Scope Management Evolution**: The tension between "thoroughness and scope creep" when adding production readiness tasks demonstrates mature project thinking. The recognition that MVP delivery requires balancing best practices against shipping velocity shows the evolution from technical perfectionism to product delivery focus.

**Architecture Pattern Discovery**: The AI orchestration solution established a reusable pattern for building AI-powered MCP tools. Rather than trying to make every function AI-aware, centralizing AI capability at the system boundary creates cleaner separation of concerns and more maintainable systems.

## Discussion Highlights
> **Human:** "Follow this task completion workflow for the current task"

This simple instruction led to discovering the value of systematic archival processes for maintaining development velocity and system performance.

> **Human:** "CLI Architecture: You suggest extending CLI with operational commands, but our current architecture is 'setup-only CLI' per the docs"

This correction revealed the importance of architectural consistency and how easy it is to drift from established patterns when planning new features.

> **User Reflection**: "I'm not happy with the summary generated... The recency bias problem persists and the AI seems to be taking shortcuts despite explicit instructions not to."

This honest assessment captures the ongoing challenge of building reliable AI systems - the gap between what we instruct AI to do and what it actually does in practice.

## Conference Talk Material
This day perfectly illustrates the evolution from "feature development" to "system engineering." The initial excitement of implementing MCP handlers and completing features gives way to the sobering realization that production systems require comprehensive infrastructure: logging, performance monitoring, error handling, and operational tooling.

The AI orchestration breakthrough demonstrates how architectural insights often come from implementation failures rather than theoretical design. The discovery that centralized AI orchestration works better than distributed AI awareness shows how real-world constraints drive architectural evolution.

---

它是如何工作的？

• 后台生成： Git 提交会自动触发日志条目创建，并在后台静默完成。不会中断工作流，也无需等待。
• 丰富的背景信息收集： 系统会自动提取提交消息、代码变更、AI 聊天记录和项目的 README，生成内容丰富、有证据支撑的日志条目，让 AI 始终了解项目目标。
• 智能聊天记录收集： 通过 Cursor 的 AI 聊天记录，捕获两次提交之间的所有 AI 对话，为每次代码变更提供完整的时间顺序背景。完整详情请参阅聊天集成用户指南。
• AI 知识留存： 捕获开发过程中 AI 助手提供的洞见，为今后的日志条目增添内容。避免重复探索相同的解决方案，并建立随项目不断扩展的持久知识库。
• 用户掌控： 日志会自动生成，但背景信息由你掌控。你可以添加手动反思，也可以直接将 AI 助手当前掌握的知识记录到日志中。
• 杜绝幻觉式总结： 日志中的所有内容都有真实行动和对话作为依据。
• 心情与情绪： 日志会根据你与 AI Agent 的交流方式或提交消息中的文字，反映你的心情和语气——因此，无论你是在倾诉、庆祝还是反思，这些情绪都会得到如实记录。
• 自动总结： 系统会自动生成每日总结；周度、月度、季度和年度总结也已列入计划，帮助你发现规律、追踪进展，并找到值得分享的故事。

AI 知识留存实践

在 AI 辅助开发过程中，常常会产生宝贵的见解，但对话结束后，这些见解往往会丢失。MCP Commit Story 的 AI 知识留存功能通过简单的工作流解决了这一问题：

使用场景示例：

1. 发现：你正在和 AI 助手一起调试，并发现使用 React 的 useCallback 可以处理开销较大的列表计算，从而避免重复渲染
2. 记录：使用 journal/capture-context 工具保存这一见解：“对列表项中的高开销计算使用 useCallback——可使产品目录的渲染时间缩短 60%”
3. 整合：这一见解会连同准确的时间戳一起保存到你的每日日志文件中
4. 丰富：当你提交下一次 React 优化时，日志生成系统会自动将这一先前的见解作为上下文
5. 结果：你的提交日志条目会引用先前的发现，形成更丰富的文档，并在以往经验的基础上不断积累

这会形成一个持续学习的循环：今天的见解为明天的日志条目提供参考，避免知识流失，并持续加深对项目不断演进的模式和解决方案的理解。

如需深入了解 MCP Commit Story 背后的架构、工作流和工程决策，请参阅**技术文档**，其中包括：

• 架构概览 - 系统设计和架构决策
• AI 上下文捕获指南 - 知识留存的完整使用指南
• MCP API 规范 - 集成所需的完整 API 参考
• 实现指南 - 开发模式和技术细节
• 日志行为 - 条目的生成方式和结构

如需完整的工程规范，请参阅 engineering-mcp-journal-spec-final.md。

---

实践中的故事

开发者 Bonnie 使用 MCP Commit Story 好几个月后，经理问起过去的一项架构决策。她不必依赖记忆或翻找旧工单。她的日志中有完整的讨论内容、考虑过的替代方案及其原因，还有作为依据的命令和测试。

后来，Bonnie 用她的日志撰写了一场会议演讲。她找到的不只是技术步骤，还有一路走来的挫折、突破和经验教训。她的演讲引起了共鸣，因为它立足于真实经历，而不只是功能清单。

随着时间推移，Bonnie 的日志成了绩效评估、新队友入职培训，甚至个人职业成长的宝贵资源。其价值不在于任何一条记录，而在于她工程历程中不断累积的完整故事。

真实示例： MCP Commit Story 自身的开发过程，具体展示了这类文档的价值。数月的日志条目记录了技术工作、情感历程和架构发现，最终被整理成《在不稳固的地基上建造城堡：我被误导的 AI 建议折腾的一个月》——一份详细记录，讲述了如何发现原先 AI 指导的架构存在根本性缺陷，以及如何通过修复过程构建出更好的系统。这篇博客展示了自动生成日志不仅能记录你构建了什么，还能完整呈现为何构建、如何构建的故事，包括传统文档常常省略的失败和转向。

---

后台生成：先捕获，静默处理

MCP Commit Story 使用 git 钩子，在每次提交后自动在后台生成日志条目和每日摘要。系统会收集 git 上下文，提取相关的 AI 聊天记录，加载近期日志条目，并纳入项目的 README，为全新的 AI Agent 提供全面的上下文，让它始终了解项目的用途和目标。这样可以生成内容丰富、具备上下文感知能力的日志条目，同时不中断你的工作流。

git 钩子支持同步和后台两种模式。后台模式可确保 git 提交立即完成，同时继续异步生成日志，避免干扰工作流。你可以完全掌控整个过程：需要时添加手动感想，或捕获 AI 助手当前的上下文。

---

为什么要使用？

• 为了自己：

  • 记住做出某些选择的原因，以及如何克服障碍。
  • 看到自己作为开发者的成长，而不只是提交列表。
  • 更诚实、更清晰地反思自己的工作。

• 为了创作内容：

  • 找出挑战与成功的脉络，并将其转化为博客文章、演讲或作品集内容。
  • 记录技术历程背后的真实故事，非常适合开发者倡导、教学，或留给未来的自己。

• 为了回顾与评审：

  • 快速找到体现个人影响、挑战和决策的依据。
  • 让绩效评审、职业发展或团队回顾更有意义，也减轻压力。

---

项目状态

此项目由一名独立开发者积极开发。
核心日志引擎、上下文收集和摘要生成功能正在采用测试驱动开发优先（TDD-first）的方法构建和测试。
随着工具逐渐成熟，我们会添加安装和 CLI 使用说明。

---

前提条件

OpenAI API 密钥（AI 功能必需）

MCP Commit Story 使用 OpenAI API 生成内容丰富、具备上下文信息的日志条目。要使用 AI 驱动的功能，你需要：

1. OpenAI API 密钥：访问 OpenAI Platform 并创建新的 API 密钥
2. 设置环境变量：

   export OPENAI_API_KEY="your-openai-api-key-here"
   

没有 API 密钥时：系统仍可运行，但日志条目中的 AI 生成部分（摘要、技术概要等）将为空，同时保留结构格式和非 AI 内容。

费用：系统使用 OpenAI 经济实惠的 gpt-4o-mini 模型。典型使用费用很低（活跃开发时通常每月不到 $1）。

---

入门

MCP Commit Story 仍处于早期开发阶段，尚未准备好供大众使用。如果你对工程故事讲述、开发者体验感兴趣，或只是想关注项目进展，欢迎关注代码仓库，或提出问题、疑问或建议。随着项目不断发展，我们欢迎你的反馈和关注！

---

许可证

MIT

---

MCP Commit Story：因为你的工程工作不只是代码。

技术详情

从这里开始

• 架构概览 - 系统设计、架构决策和组件关系
• 完整工程规范 - 综合参考文档（900+ 行）

API 与集成

• MCP API 规范 - 完整的 MCP 操作、数据格式和客户端集成指南
• 实现指南 - 开发模式、技术实现和最佳实践

核心系统文档

• 日志核心 - 日志条目生成系统、AI 集成和内容指南
• 上下文收集 - 数据收集系统、类型定义和性能优化
• 反思核心 - 手动添加反思，并进行验证和遥测
• 日志行为 - 条目结构、配置选项和生成工作流

可观测性与监控

• 遥测 - 全面的 OpenTelemetry 集成与监控
• 结构化日志 - 支持追踪关联和敏感数据保护的 JSON 日志
• 多导出器 - 根据环境优先级配置 OpenTelemetry 导出器

开发与测试

• 测试标准 - 完整的测试策略（532 个测试、80% 覆盖率、TDD 模式）
• 服务设置 - MCP 服务配置和部署指南