npm package: @iflow-mcp/xiaolai_claude-writers-aid-mcp
Description: MCP server for nonfiction writers - AI-powered manuscript assistant for research, structure, and quality control
Author: xiaolai
Latest version: 0.3.0

# Claude Writer's Aid MCP

A Model Context Protocol (MCP) server designed specifically for writers and authors working with markdown manuscripts. Provides intelligent analysis, quality checks, and writing assistance tools integrated into Claude Code.

## 💡 What It Does

- **Manuscript Indexing** - Automatically index and track all markdown files in your writing project
- **Semantic Search** - Find content across your manuscript using natural language queries
- **Quality Analysis** - Check for terminology consistency, readability, duplicates, and structure issues
- **Link Management** - Validate internal links, find broken references, and suggest cross-references
- **Progress Tracking** - Monitor word counts, track changes, and generate progress reports
- **Theme Extraction** - Discover and analyze recurring themes across your content
- **TODO Management** - Extract and track all TODO, FIXME, and DRAFT markers
- **Writing Statistics** - Comprehensive metrics and analytics for your writing project

## ⚠️ Important: Claude Code CLI Only

**This MCP server works ONLY with [Claude Code CLI](https://github.com/anthropics/claude-code).**

It does NOT work with:
- ❌ Claude Desktop
- ❌ Claude Web
- ❌ Other Claude integrations

Writer's Aid MCP stores manuscript data in `.writers-aid/manuscript.db` within your project folder, keeping all writing data organized alongside your manuscript files.

## 📦 Installation

### Prerequisites

**Required:**
1. **Claude Code CLI**: https://github.com/anthropics/claude-code
2. **Node.js**: Version 18 or higher

### Quick Install (Recommended)

Install globally from npm:

```bash
# Install the package globally
npm install -g claude-writers-aid-mcp

# Auto-configure for Claude Code CLI
writers-aid init-mcp
```

That's it! The `init-mcp` command automatically:
- Detects your installation paths
- Configures `~/.claude.json` with the correct settings
- Provides next steps for verification

### Alternative: Development Install

For local development/use from this repository:

```bash
# Clone the repository
git clone https://github.com/xiaolai/claude-writers-aid-mcp.git
cd claude-writers-aid-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Configure MCP server
npm run init-mcp
```

### Manual Configuration (Advanced)

If you prefer manual setup, add to your `~/.claude.json` (NOT `~/.claude/config.json`):

```json
{
  "mcpServers": {
    "writers-aid": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/path/to/claude-writers-aid-mcp/dist/index.js"
      ]
    }
  }
}
```

Replace `/path/to/` with the actual path where you installed the package.

### Verify Installation

Check your MCP configuration:

```bash
writers-aid mcp-status
```

Restart Claude Code CLI and test with:

```
"Index my manuscript files"
"Check my manuscript for quality issues"
"Show writing statistics"
```

If the MCP tools are working, you'll see analysis results and statistics!

### MCP Configuration Commands

The package includes commands to manage your Claude Code MCP configuration:

```bash
# Check MCP configuration status
writers-aid mcp-status

# Configure or update MCP server
writers-aid init-mcp

# Remove MCP configuration
writers-aid remove-mcp
```

### Important: Restarting After Updates

**When you upgrade to a new version**, you MUST restart Claude Code CLI to reload the MCP server:

1. Exit Claude Code CLI completely
2. Start it again
3. The new version will be loaded

**Why?** Claude Code caches MCP servers. Without restarting, it will continue using the old cached version even after you've upgraded the npm package globally.

**Quick check**: After restart, you can verify the version with:
```bash
claude-conversation-memory-mcp --version
```

## 🖥️ Standalone CLI / REPL Mode

Beyond the MCP server, this package includes a powerful **standalone CLI** for managing your conversation memory directly from the terminal.

### Three Modes of Operation

**1. Interactive REPL Mode** (Default)
```bash
claude-conversation-memory-mcp
# Starts interactive shell with 40+ commands
```

**2. Single Command Mode**
```bash
claude-conversation-memory-mcp status
claude-conversation-memory-mcp "search authentication"
claude-conversation-memory-mcp mistakes --limit 5
```

**3. MCP Server Mode** (Used by Claude Code CLI)
```bash
claude-conversation-memory-mcp --server
# Or automatically via stdio from Claude Code CLI
```

### Quick CLI Examples

```bash
# View database status
claude-conversation-memory-mcp status

# Index conversations
claude-conversation-memory-mcp index --include-mcp

# Search for topics
claude-conversation-memory-mcp "search database migration" --limit 3

# Find past mistakes
claude-conversation-memory-mcp mistakes "async" --type logic_error

# Check file context before editing
claude-conversation-memory-mcp check src/auth.ts

# Configure embedding model
claude-conversation-memory-mcp config
claude-conversation-memory-mcp set model mxbai-embed-large
claude-conversation-memory-mcp set dimensions 1024

# View help
claude-conversation-memory-mcp help
claude-conversation-memory-mcp "help search"
```

### Configuration Management

The CLI includes built-in commands for managing embedding models and dimensions:

```bash
# View current configuration
claude-conversation-memory-mcp config

# Switch to Ollama with mxbai-embed-large (1024 dimensions)
claude-conversation-memory-mcp set provider ollama
claude-conversation-memory-mcp set model mxbai-embed-large
claude-conversation-memory-mcp set dimensions 1024

# Switch to Transformers.js (offline, no setup)
claude-conversation-memory-mcp set provider transformers
claude-conversation-memory-mcp set model Xenova/all-MiniLM-L6-v2
claude-conversation-memory-mcp set dimensions 384

# Get specific config value
claude-conversation-memory-mcp get provider
```

### Available Commands

- **📥 Indexing**: `index`, `reindex`
- **🔍 Search**: `search`, `decisions`, `mistakes`, `similar`
- **📋 Files**: `check`, `history`
- **🔗 Git**: `commits`
- **📝 Other**: `requirements`, `tools`, `docs`
- **ℹ️ Info**: `status`, `version`, `help`
- **⚙️ Config**: `config`, `get`, `set`
- **🧹 Maintenance**: `vacuum`, `reset`

**👉 See [Complete CLI Guide](docs/CLI-USAGE.md) for all commands, examples, and workflows**

## 🎯 Usage Examples

### First Time Setup

```
You: "Index my conversation history for this project"

Claude: I'll index all conversations for this project...
✓ Indexed 5 conversations with 2,341 messages
✓ Semantic search enabled (embeddings generated)
```

### Search Past Conversations

```
You: "What did we discuss about the authentication system?"

Claude: Let me search our conversation history...
[Returns relevant messages with context and timestamps]
```

### Before Modifying Files

```
You: "Before I change database.ts, what should I know?"

Claude: Let me check the context for database.ts...
[Shows recent changes, related decisions, and past mistakes]
```

### Track Decisions

```
You: "Why did we choose SQLite over PostgreSQL?"

Claude: Let me check our decision history...
[Returns the decision with rationale and alternatives considered]
```

### Learn from Mistakes

```
You: "Have we had issues with async/await before?"

Claude: Let me search past mistakes...
[Shows previous errors and how they were fixed]
```

### Find Related Work

```
You: "Have we worked on similar API endpoints before?"

Claude: Let me find similar sessions...
[Returns past conversations about similar work]
```

### View File History

```
You: "Show me how auth.ts evolved over time"

Claude: Let me trace the file evolution...
[Shows complete timeline with conversations, commits, and decisions]
```

### Recall and Apply Context

```
You: "Recall how we implemented authentication, now add OAuth support using that same pattern"

Claude: Let me recall the authentication implementation context...
[Returns relevant conversations, decisions, mistakes, file changes, and commits]
[Provides suggestions for applying this context to OAuth implementation]
```

**More examples:**
- "Remember the bug we fixed in parser.ts, check if similar issue exists in lexer.ts"
- "Recall all decisions about database schema, now design the migration strategy"
- "Find mistakes we made with async/await, avoid them in this new async function"

## 🔧 Advanced Usage

### Index Specific Session

```
You: "Index conversation from session a1172af3-ca62-41be-9b90-701cef39daae"
```

### Exclude MCP Conversations

By default, conversations about the MCP itself are excluded to prevent self-referential loops. To include them:

```
You: "Index all conversations, including MCP conversations"
```

### Indexing Options

When indexing conversations, several options control what gets stored:

#### Include Thinking Blocks

**Default**: `false` (thinking blocks are excluded)

Thinking blocks contain Claude's internal reasoning process. They can be **very large** (3-5x more data) and are usually not needed for search.

```
# Default behavior (recommended)
You: "Index conversations"
# Thinking blocks are excluded

# Include thinking blocks (increases database size significantly)
You: "Index conversations with thinking blocks"
```

**When to enable**:
- ✅ You want to search Claude's reasoning process
- ✅ You're analyzing decision-making patterns
- ❌ Don't enable if you just want to search visible conversation content

#### Exclude MCP Conversations

**Default**: `"self-only"` (excludes only conversation-memory MCP calls)

Controls which MCP tool interactions are indexed:

- `"self-only"` (default): Excludes messages about this conversation-memory MCP to prevent self-referential loops
- `false`: Index all MCP tool calls from all servers
- `"all-mcp"` or `true`: Exclude all MCP tool calls from all servers
- `["server1", "server2"]`: Exclude specific MCP servers

```
# Default - exclude only conversation-memory MCP
You: "Index conversations"

# Include all MCP conversations (including this one)
You: "Index conversations, include all MCP tools"

# Exclude all MCP tool calls
You: "Index conversations, exclude all MCP interactions"
```

**What gets filtered**: Only the specific **messages** that invoke MCP tools are excluded, not entire conversations. This preserves conversation context while preventing self-referential loops.

#### Enable Git Integration

**Default**: `true` (git commits are linked)

Links git commits to conversations based on timestamps and file changes.

```
# Default behavior
You: "Index conversations"
# Git commits are automatically linked

# Disable git integration
You: "Index conversations without git integration"
```

#### Index Output

After indexing, you'll see:

```
📁 Indexed from: /path/to/modern-folder, /path/to/legacy-folder
💾 Database: /path/to/.claude-conversations-memory.db
```

This shows:
- **Indexed folders**: Which conversation folders were used (including legacy if it exists)
- **Database location**: Where your indexed data is stored

### Search with Date Filters

```
You: "What were we working on last week?"
```

### Generate Documentation

```
You: "Generate project documentation from our conversations"
```

Claude will create comprehensive docs combining code analysis with conversation history.

### Migrate Conversation History

When you rename or move a project directory, your conversation history becomes inaccessible because Claude Code creates a new folder for the new path. Use the migration tools to recover your history:

**Step 1: Discover old conversation folders**

```
You: "Discover old conversations for this project"
```

Claude will scan `~/.claude/projects/` and show you folders that match your current project, ranked by similarity score. The output includes:
- Folder name and path
- Original project path stored in the database
- Number of conversations and files
- Last activity timestamp
- Similarity score (higher = better match)

**Step 2: Migrate the history**

```
You: "Migrate conversations from /Users/name/.claude/projects/-old-project-name, old path was /Users/name/old-project, new path is /Users/name/new-project"
```

Claude will:
- Copy all conversation JSONL files to the new location
- Update the `project_path` in the database
- Create automatic backups (`.claude-conversations-memory.db.bak`)
- Preserve all original data (copy, not move)

**Example workflow:**

```markdown
# You renamed your project directory
# Old: /Users/alice/code/my-app
# New: /Users/alice/code/my-awesome-app

You: "Discover old conversations for this project"

Claude: Found 1 potential old conversation folder:
- Folder: -Users-alice-code-my-app
- Original path: /Users/alice/code/my-app
- Conversations: 15
- Files: 47
- Score: 95.3

You: "Migrate from /Users/alice/.claude/projects/-Users-alice-code-my-app, old path /Users/alice/code/my-app, new path /Users/alice/code/my-awesome-app"

Claude: Successfully migrated 47 conversation files.
Now you can index and search your full history!
```

**Dry run mode:**

Test the migration without making changes:

```
You: "Dry run: migrate from [source] old path [old] new path [new]"
```

This shows what would be migrated without actually copying files.

### Merge Conversations from Different Projects

**NEW in v0.4.0**: Combine conversation history from different projects into one folder using merge mode.

**Use case**: You want to merge conversations from `/project-a/drafts/2025-01-05` into your current project `/project-b`.

**Step 1: Discover the source folder**

```
You: "Discover old conversations for project path /Users/name/project-a/drafts/2025-01-05"
```

**Step 2: Merge into current project**

```
You: "Merge conversations from /Users/name/.claude/projects/-project-a-drafts-2025-01-05, old path /Users/name/project-a/drafts/2025-01-05, new path /Users/name/project-b, mode merge"
```

Claude will:
- Copy only **new** conversation files (skip duplicates)
- Keep target conversations when IDs collide (no data loss)
- Merge all database entries using INSERT OR IGNORE
- Create backup of target database before merge
- Preserve all original source data

**Example workflow:**

```markdown
# Scenario: You have conversations from different projects to combine

Current project: /Users/alice/main-project (already has 20 conversations)
Source project: /Users/alice/drafts/experiment (has 10 conversations, 3 overlap with main)

You: "Discover old conversations for /Users/alice/drafts/experiment"

Claude: Found 1 folder:
- Folder: -Users-alice-drafts-experiment
- Original path: /Users/alice/drafts/experiment
- Conversations: 10
- Files: 10

You: "Merge from /Users/alice/.claude/projects/-Users-alice-drafts-experiment, old path /Users/alice/drafts/experiment, new path /Users/alice/main-project, mode merge"

Claude: Successfully merged 7 new conversation files into /Users/alice/.claude/projects/-Users-alice-main-project
(3 duplicate conversations were skipped to preserve target data)
Backup created at: .claude-conversations-memory.db.bak

# Result: main-project now has 27 conversations (20 original + 7 new from experiment)
```

**Key differences between migrate and merge:**

| Feature | Migrate Mode (default) | Merge Mode |
|---------|----------------------|------------|
| Target has data | ❌ Rejected (conflict) | ✅ Allowed |
| Duplicate IDs | Overwrites target | Skips source (keeps target) |
| Use case | Renamed project | Combine different projects |
| Backup location | Source folder | Target folder |

## 📚 Learn More

- **[Tool Examples](docs/TOOL-EXAMPLES.md)** - 50+ natural language examples for each tool
- **[Quick Reference](docs/QUICK-REFERENCE.md)** - Common phrases cheat sheet
- **[Embeddings FAQ](docs/EMBEDDINGS-FAQ.md)** - How semantic search works


## 🐛 Troubleshooting

### "No conversations found"

Make sure you're running this in a directory where you've had Claude Code CLI conversations. Check `~/.claude/projects/` to verify conversation files exist.

### "Embeddings failed"

The MCP falls back to full-text search if embeddings fail. Everything still works, just without semantic search.

### "MCP not responding"

Restart Claude Code CLI to reload the MCP server.

## 📄 License

MIT License - See [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

Inspired by [code-graph-rag-mcp](https://github.com/er77/code-graph-rag-mcp).

---

**Made with ❤️ for the Claude Code CLI community**