CLAUDE-old.md•9.04 kB
# AI 对话记录 MCP 服务器开发规则
## 项目概述
我们要创建一个 MCP (Model Context Protocol) 服务器，用于记录和管理我与 AI 工具的对话历史。这个工具需要支持多个 AI 平台（Claude Code、Cursor、VS Code Copilot、IDEA Copilot）。
## 重要说明 如果与其他地方冲突，以这里为准
- MCP的配置文件在 ~/.claude.json 的最后部分
- MCP配置说明：https://docs.anthropic.com/en/docs/claude-code/mcp
- HOOK配置说明：https://docs.anthropic.com/en/docs/claude-code/hooks
- 会话存储位置：各项目根目录下的 `ai-logs/` 文件夹
- MCP服务器自动检测当前工作目录来确定项目位置
## 核心功能需求
### 1. 对话记录功能
- 记录用户指令和 AI 回复的主要内容
- 记录 AI 执行的具体操作
- 按项目和时间自动组织存储
- 支持自定义总结和标签
### 2. 历史检索功能
- 按项目、时间范围、关键词搜索历史记录
- 智能推荐相关的历史上下文
- 支持模糊搜索和语义搜索
### 3. 上下文管理功能
- 在新对话中方便地调取历史记录作为上下文
- 自动识别当前对话的项目和主题
- 提供上下文建议和推荐
## 技术架构要求
### MCP 服务器规格
- **语言**: TypeScript/Node.js
- **框架**: @modelcontextprotocol/sdk
- **存储**: 本地文件系统（Markdown 格式）
- **位置**: 各项目根目录下的 `ai-logs/` 目录
- **检测机制**: 基于当前工作目录自动识别项目
### 支持的工具 (Tools)
#### 1. log_conversation
```typescript
interface LogConversationParams {
project: string; // 项目名称
userInput: string; // 用户输入
aiResponse: string; // AI完整回复
platform?: string; // 平台标识 (claude-code, cursor, vscode, idea)
customSummary?: string; // 自定义总结
tags?: string[]; // 标签数组
actions?: string[]; // AI执行的操作列表
}
```
#### 2. search_conversations
```typescript
interface SearchParams {
project?: string; // 项目过滤
keywords?: string[]; // 关键词搜索
timeRange?: { // 时间范围
start?: string;
end?: string;
};
days?: number; // 最近N天
platform?: string; // 平台过滤
tags?: string[]; // 标签过滤
limit?: number; // 结果数量限制
}
```
#### 3. get_context_suggestions
```typescript
interface ContextSuggestionsParams {
currentInput: string; // 当前用户输入
project?: string; // 当前项目
maxSuggestions?: number; // 最大建议数量
}
```
#### 4. list_projects
```typescript
interface ListProjectsParams {
includeStats?: boolean; // 是否包含统计信息
}
```
#### 5. export_conversations
```typescript
interface ExportParams {
project?: string; // 导出特定项目
format?: 'markdown' | 'json'; // 导出格式
timeRange?: DateRange; // 时间范围
}
```
## 文件组织结构
### 项目根目录结构
```
project-root/
├── src/
├── package.json
├── README.md
└── ai-logs/
├── 2025-08-03.md
├── 2025-08-04.md
├── config.json
└── index.json
```
### MCP服务器配置目录
```
~/.ai-conversation-logger/
├── templates/
│ ├── conversation-template.md
│ └── daily-log-template.md
├── global-index/
│ ├── projects-registry.json
│ └── search-index.json
└── config/
└── settings.json
```
## Markdown 文件格式规范
### 日常对话记录格式
```markdown
# AI对话记录 - [日期]
> 项目: [自动检测的项目名]
> 日期: [YYYY-MM-DD]
> 工作目录: [项目根目录路径]
> 总对话数: [当天数量]
---
## [HH:MM:SS] - [平台] - [标签]
### 用户指令
[用户输入的完整内容]
### AI执行操作
- [操作1: 文件路径:行号]
- [操作2: 命令执行]
- [操作3: 工具调用]
### AI回复要点
[AI回复的关键内容总结，避免完整复制]
### 生成/修改代码
```[语言]
// 文件: [相对路径]
[关键代码片段]
```
### 学习要点
- [技术要点1]
- [解决方案2]
### 相关文件
- [src/component.tsx:123]
- [package.json]
---
```
## 开发阶段规划
### 阶段 1: 基础 MCP 服务器 (优先级: 高)
- [ ] 创建 TypeScript 项目结构
- [ ] 实现基础的 MCP 服务器框架
- [ ] 实现 `log_conversation` 工具（支持项目根目录存储）
- [ ] 实现工作目录检测和项目识别逻辑
- [ ] 实现基础文件存储逻辑（ai-logs文件夹）
- [ ] 测试与 Claude Code 的集成
### 阶段 2: 搜索和检索功能 (优先级: 高)
- [ ] 实现 `search_conversations` 工具
- [ ] 实现 `list_projects` 工具
- [ ] 添加关键词搜索功能
- [ ] 实现时间范围过滤
### 阶段 3: 智能化功能 (优先级: 中)
- [ ] 实现 `get_context_suggestions` 工具
- [ ] 添加自动标签识别
- [ ] 实现智能分类功能
- [ ] 添加相关性推荐算法
### 阶段 4: 高级功能 (优先级: 低)
- [ ] 实现导出功能
- [ ] 添加统计分析
- [ ] 实现配置管理
- [ ] 添加数据备份功能
## 代码质量要求
### TypeScript 编码规范
- 使用严格的 TypeScript 配置
- 所有函数必须有类型注解
- 使用 async/await 处理异步操作
- 实现适当的错误处理
### 文件操作规范
- 使用 `fs/promises` 进行文件操作
- 实现原子性文件写入
- 添加适当的错误恢复机制
- 确保跨平台兼容性
### MCP 集成规范
- 严格遵循 MCP 协议规范
- 提供清晰的工具描述和参数说明
- 实现适当的输入验证
- 返回结构化的响应
## 测试要求
### 单元测试
- 测试所有核心功能模块
- 测试文件操作的边界情况
- 测试搜索算法的准确性
### 集成测试
- 测试与 Claude Code 的集成
- 测试多项目并发操作
- 测试大量数据的性能
## 部署和配置
### 开发环境设置
```json
{
"name": "ai-conversation-logger-mcp",
"version": "1.0.0",
"type": "module",
"scripts": {
"build": "tsc",
"start": "node dist/index.js",
"dev": "tsx src/index.ts",
"test": "jest"
}
}
```
### Claude Code 配置示例
```json
{
"mcpServers": {
"conversation-logger": {
"command": "node",
"args": ["/path/to/ai-conversation-logger-mcp/dist/index.js"]
}
}
}
```
## 期望的使用体验
### 记录对话示例
```
用户在项目根目录下使用 Claude Code：
"帮我实现一个 React 登录组件"
AI 自动检测当前工作目录为项目根目录，
回复后自动调用 log_conversation 工具记录到 ./ai-logs/2025-08-04.md
```
### 检索上下文示例
```
用户在同一项目下开始新对话：
"我需要修改之前的登录组件"
用户可以说：
"搜索之前关于登录组件的对话记录"
系统在当前项目的 ai-logs/ 目录中搜索相关记录
```
## 成功标准
1. **功能完整性**: 所有核心工具都能正常工作
2. **易用性**: 用户可以通过简单命令完成所有操作
3. **可靠性**: 数据不会丢失，操作不会出错
4. **性能**: 搜索和记录操作在 3 秒内完成
5. **可扩展性**: 容易添加新功能和支持新平台
## 注意事项
- 确保处理中文字符和特殊字符
- 实现适当的并发控制
- 考虑大文件的性能优化
- 预留未来 Obsidian 集成的接口
- 考虑团队协作的需求
---
# 🎯 项目当前状态 (2025-08-07)
## ✅ 已完成重大优化
### 纯保存模式架构
- **移除所有自动提取功能** - 代码块、文件路径、学习要点不再自动识别
- **AI完全控制内容** - MCP只做格式化和保存，内容完全由AI决定
- **简化记录格式** - 专注于AI操作历史，便于后续追溯
### 自动化配置完善
- **Hooks自动记录** - 通过`~/.claude/settings.json`配置Stop Hook
- **所有项目自动覆盖** - 每次对话结束自动记录到对应项目ai-logs/
- **手动记录补充** - AI可通过log_conversation工具记录重要内容
### 技术改进
- **本地时区日期** - 修复UTC时间问题，使用本地日期创建文件
- **移除文件锁** - 简化单用户场景，提升性能
- **防记录覆盖** - 修复文件追加逻辑，确保历史记录不丢失
- **项目自动检测** - project参数可选，自动识别当前项目
## 🔧 当前配置状态
### MCP服务器: ✅ 已配置
```
~/.claude.json -> mcpServers.conversation-logger
```
### 自动记录Hook: ✅ 已配置
```
~/.claude/settings.json -> hooks.Stop
-> /scripts/auto-log-hook.js
```
### 记录目标: ✅ 项目级存储
```
每个项目/ai-logs/YYYY-MM-DD.md
```
## 📋 工作模式
1. **自动记录**: 每次对话结束自动触发记录
2. **手动记录**: AI主动调用工具记录重要内容
3. **搜索历史**: 通过search_conversations搜索过往记录
4. **项目管理**: 通过list_projects查看所有项目
**结论**: 系统已实现全自动对话记录到所有项目，无需用户干预。