Claude Writer's Aid MCP

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