# AI Conversation Logger MCP

[中文版](./README_zh.md) | [日本語版](./README_ja.md)

An intelligent MCP (Model Context Protocol) server designed specifically for AI assistants to automatically log and manage conversation history with developers.

## 🎯 Core Features

- **🤖 AI-Driven Logging** - All content is determined and provided by the AI assistant
- **📝 Pure Save Mode** - MCP only formats and stores, no content extraction or analysis
- **🔄 Designed for AI Retrospection** - Log format optimized for AI to quickly understand project history
- **🏷️ Smart Organization** - Auto-organize by project and date with tagging support
- **🔍 Powerful Search** - Multi-dimensional search by keywords, files, tags, and time range
- **📊 Context Suggestions** - Smart recommendations based on file associations

## 🚀 Quick Start

### 1. Install Dependencies

```bash
npm install
```

### 2. Build Project

```bash
npm run build
```

### 3. Configure Claude Code

Add MCP server configuration to Claude Code's config file (`~/.claude.json`):

```json
{
  "mcpServers": {
    "conversation-logger": {
      "command": "node",
      "args": ["/path/to/ai-conversation-logger-mcp/dist/index.js"]
    }
  }
}
```

### 4. Restart Claude Code

Restart Claude Code to apply the configuration.

## 📚 API Tools

### 1. log_conversation - Core Logging Tool

Records every AI-user interaction with structured information:

```typescript
interface LogConversationParams {
  userRequest: string;      // User's original request + uploaded file descriptions
  aiTodoList: string[];     // AI's execution plan (list even for view-only tasks)
  aiSummary: string;        // AI's operation summary (3-5 sentences)
  fileOperations?: string[]; // File operations in format: "action filepath - description"
  title?: string;           // Conversation title (optional)
  tags?: string[];          // Tag array (optional)
  project?: string;         // Project name (auto-detected if not provided)
}
```

### 2. search_conversations - Search Tool

Search through conversation history with multiple filters:

```typescript
interface SearchParams {
  keywords?: string[];     // Keyword search
  filePattern?: string;    // File name pattern search
  days?: number;          // Recent N days
  project?: string;       // Project filter (defaults to current)
  tags?: string[];        // Tag filter
  limit?: number;         // Result limit (default: 10)
}
```

### 3. get_context_suggestions - Context Recommendations

Get relevant historical context based on current work:

```typescript
interface ContextParams {
  currentInput: string;    // Current user input
  currentFiles?: string[]; // Currently involved files
  project?: string;        // Project filter (optional)
}
```

## 📁 Storage Structure

Logs are stored in the project's `ai-logs/` directory:

```text
project-root/
├── ai-logs/
│   ├── 2025-08-07.md     # Daily conversation logs
│   ├── 2025-08-06.md
│   └── config.json       # Project configuration
├── src/
└── ...
```

## 📝 Log Format

Each conversation is recorded with the following structure:

```markdown
## [Timestamp] Title #tags

### 🗣️ User Request
[Original user request]

### 📋 AI Execution Plan
- [x] Completed task
- [ ] Pending task

### 🤖 AI Summary
[Summary of what was accomplished]

### 📂 File Operations
- **Created** `path/to/file` - Purpose description
- **Modified** `path/to/file` - What was changed
- **Deleted** `path/to/file` - Reason for deletion

### 🏷️ Tags
#module #technology #type
```

## 🎯 Usage Principles

### When to Log

**All conversations should be logged**, including:

- New feature development
- Bug fixes (any size)
- Code refactoring
- Configuration changes
- Code explanations and analysis
- Technical Q&A
- Code reviews
- Any project-related dialogue

### Key Points

1. **AI-Driven Content** - AI determines what information to log
2. **Complete Context** - Include all relevant details for future reference
3. **Focus on "What" not "How"** - Emphasize functionality over technical details
4. **Consistent Format** - Maintain standardized markdown structure

## 🛠️ Development

### Development Mode

```bash
npm run dev
```

### Run Tests

```bash
npm test
```

### Code Linting

```bash
npm run lint
npm run lint:fix
```

### TypeScript Check

```bash
npm run type-check
```

## 🔧 Technical Stack

- **TypeScript** - Type-safe development
- **MCP SDK** - Model Context Protocol implementation
- **Node.js** - Runtime environment
- **Jest** - Testing framework

## 📄 License

MIT

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📮 Contact

For issues or suggestions, please open an issue on GitHub.