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.

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:

# 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:

# 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):

{
  "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:

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:

# 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:

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)

claude-conversation-memory-mcp
# Starts interactive shell with 40+ commands

2. Single Command Mode

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)

claude-conversation-memory-mcp --server
# Or automatically via stdio from Claude Code CLI

Quick CLI Examples

# 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:

# 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 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:

# 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:

# 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 - 50+ natural language examples for each tool
• Quick Reference - Common phrases cheat sheet
• Embeddings FAQ - 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 file for details.

🙏 Acknowledgments

Inspired by code-graph-rag-mcp.

---

Made with ❤️ for the Claude Code CLI community