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

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:

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:

Manual Configuration (Advanced)

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

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

Verify Installation

Check your MCP configuration:

Restart Claude Code CLI and test with:

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:

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:

🖥️ 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)

2. Single Command Mode

3. MCP Server Mode (Used by Claude Code CLI)

Quick CLI Examples

Configuration Management

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

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

🎯 Usage Examples

First Time Setup

Search Past Conversations

Before Modifying Files

Track Decisions

Learn from Mistakes

Find Related Work

View File History

Recall and Apply Context

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

Exclude MCP Conversations

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

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.

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

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.

Index Output

After indexing, you'll see:

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

Generate Documentation

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

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

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:

Dry run mode:

Test the migration without making changes:

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

Step 2: Merge into current project

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:

Key differences between migrate and merge:

📚 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