Claude Writers Aid MCP

🚀 Claude Writer's Aid MCP

Claude Writer's Aid MCP 是專為使用 Markdown 手稿的作家和作者設計的模型上下文協議（MCP）服務器。它集成到 Claude Code 中，提供智能分析、質量檢查和寫作輔助工具，助力用戶高效完成寫作項目。

🚀 快速開始

Claude Writer's Aid MCP 專為使用 Markdown 手稿的創作者打造，能為寫作項目提供智能分析、質量檢查和寫作輔助等功能。使用前請確保已安裝 Claude Code CLI 和 Node.js（版本 18 或更高），然後按照以下步驟完成安裝和配置。

✨ 主要特性

• 手稿索引：自動對寫作項目中的所有 Markdown 文件進行索引和跟蹤。
• 語義搜索：使用自然語言查詢在整個手稿中查找內容。
• 質量分析：檢查術語一致性、可讀性、重複內容和結構問題。
• 鏈接管理：驗證內部鏈接，查找損壞的引用，並提供交叉引用建議。
• 進度跟蹤：監控字數、跟蹤更改並生成進度報告。
• 主題提取：發現並分析內容中反覆出現的主題。
• 待辦事項管理：提取並跟蹤所有 TODO、FIXME 和 DRAFT 標記。
• 寫作統計：為寫作項目提供全面的指標和分析。

⚠️ 重要提示

本 MCP 服務器僅適用於 Claude Code CLI，不適用於 Claude Desktop、Claude Web 或其他 Claude 集成。

Writer's Aid MCP 將手稿數據存儲在項目文件夾內的 .writers-aid/manuscript.db 中，使所有寫作數據與手稿文件有序存放。

📦 安裝指南

前提條件

• Claude Code CLI：https://github.com/anthropics/claude-code
• Node.js：版本 18 或更高

快速安裝（推薦）

從 npm 全局安裝：

# 全局安裝包
npm install -g claude-writers-aid-mcp

# 為 Claude Code CLI 自動配置
writers-aid init-mcp

init-mcp 命令會自動執行以下操作：

• 檢測安裝路徑
• 使用正確的設置配置 ~/.claude.json
• 提供驗證的後續步驟

替代方案：開發安裝

若要從本倉庫進行本地開發或使用，請執行以下操作：

# 克隆倉庫
git clone https://github.com/xiaolai/claude-writers-aid-mcp.git
cd claude-writers-aid-mcp

# 安裝依賴
npm install

# 構建項目
npm run build

# 配置 MCP 服務器
npm run init-mcp

手動配置（高級）

若您傾向於手動設置，請將以下內容添加到 ~/.claude.json（而非 ~/.claude/config.json）：

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

將 /path/to/ 替換為您實際安裝包的路徑。

驗證安裝

檢查 MCP 配置：

writers-aid mcp-status

重啟 Claude Code CLI 並使用以下命令進行測試：

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

若 MCP 工具正常工作，您將看到分析結果和統計信息！

MCP 配置命令

該包包含用於管理 Claude Code MCP 配置的命令：

# 檢查 MCP 配置狀態
writers-aid mcp-status

# 配置或更新 MCP 服務器
writers-aid init-mcp

# 刪除 MCP 配置
writers-aid remove-mcp

重要提示：更新後重啟

更新到新版本時，您必須重啟 Claude Code CLI 以重新加載 MCP 服務器：

1. 完全退出 Claude Code CLI
2. 重新啟動它
3. 新版本將被加載

原因是 Claude Code 會緩存 MCP 服務器。如果不重啟，即使您全局升級了 npm 包，它仍將繼續使用舊的緩存版本。

快速檢查：重啟後，您可以使用以下命令驗證版本：

claude-conversation-memory-mcp --version

💻 使用示例

基礎用法

首次設置

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)

搜索過往對話

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

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

修改文件前

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]

跟蹤決策

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

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

從錯誤中學習

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

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

查找相關工作

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

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

查看文件歷史

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

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

回憶並應用上下文

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]

更多示例：

• "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"

高級用法

索引特定會話

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

排除 MCP 對話

默認情況下，關於 MCP 本身的對話會被排除，以防止自引用循環。若要包含它們，請使用以下命令：

You: "Index all conversations, including MCP conversations"

索引選項

在索引對話時，有幾個選項可控制存儲的內容：

包含思考塊

默認值：false（排除思考塊）

思考塊包含 Claude 的內部推理過程，可能非常大（數據量是普通對話的 3 - 5 倍），通常搜索時不需要。

# 默認行為（推薦）
You: "Index conversations"
# 思考塊被排除

# 包含思考塊（顯著增加數據庫大小）
You: "Index conversations with thinking blocks"

啟用時機：

• 您想搜索 Claude 的推理過程
• 您正在分析決策模式
• 若僅想搜索可見的對話內容，請不要啟用

排除 MCP 對話

默認值："self-only"（僅排除對話內存 MCP 調用）

控制哪些 MCP 工具交互被索引：

• "self-only"（默認）：排除關於此對話內存 MCP 的消息，以防止自引用循環
• false：索引所有服務器的所有 MCP 工具調用
• "all-mcp" 或 true：排除所有服務器的所有 MCP 工具調用
• ["server1", "server2"]：排除特定的 MCP 服務器

# 默認 - 僅排除對話內存 MCP
You: "Index conversations"

# 包含所有 MCP 對話（包括此對話）
You: "Index conversations, include all MCP tools"

# 排除所有 MCP 工具調用
You: "Index conversations, exclude all MCP interactions"

過濾內容：僅排除調用 MCP 工具的特定 消息，而非整個對話。這樣可以保留對話上下文，同時防止自引用循環。

啟用 Git 集成

默認值：true（鏈接 Git 提交）

根據時間戳和文件更改將 Git 提交與對話關聯起來。

# 默認行為
You: "Index conversations"
# Git 提交會自動關聯

# 禁用 Git 集成
You: "Index conversations without git integration"

索引輸出

索引完成後，您將看到以下信息：

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

這顯示了：

• 索引文件夾：使用了哪些對話文件夾（如果存在舊文件夾也會包含）
• 數據庫位置：索引數據的存儲位置

按日期過濾搜索

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

生成文檔

You: "Generate project documentation from our conversations"

Claude 將結合代碼分析和對話歷史創建全面的文檔。

遷移對話歷史

當您重命名或移動項目目錄時，由於 Claude Code 會為新路徑創建新文件夾，您的對話歷史將無法訪問。您可以使用遷移工具恢復歷史： 步驟 1：發現舊對話文件夾

You: "Discover old conversations for this project"

Claude 將掃描 ~/.claude/projects/ 並顯示與您當前項目匹配的文件夾，按相似度得分排序。輸出包括：

• 文件夾名稱和路徑
• 數據庫中存儲的原始項目路徑
• 對話和文件的數量
• 最後活動時間戳
• 相似度得分（得分越高，匹配度越好） 步驟 2：遷移歷史

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 將執行以下操作：

• 將所有對話 JSONL 文件複製到新位置
• 更新數據庫中的 project_path
• 創建自動備份（.claude-conversations-memory.db.bak）
• 保留所有原始數據（複製，而非移動） 示例工作流程：

# 您重命名了項目目錄
# 舊路徑: /Users/alice/code/my-app
# 新路徑: /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!

試運行模式： 在不進行更改的情況下測試遷移：

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

這將顯示會遷移哪些內容，但不會實際複製文件。

合併不同項目的對話

v0.4.0 新增功能：使用合併模式將不同項目的對話歷史合併到一個文件夾中。 使用場景：您想將 /project-a/drafts/2025-01-05 中的對話合併到當前項目 /project-b 中。 步驟 1：發現源文件夾

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

步驟 2：合併到當前項目

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 將執行以下操作：

• 僅複製 新的 對話文件（跳過重複文件）
• 當 ID 衝突時保留目標對話（無數據丟失）
• 使用 INSERT OR IGNORE 合併所有數據庫條目
• 在合併前創建目標數據庫的備份
• 保留所有原始源數據 示例工作流程：

# 場景：您有來自不同項目的對話需要合併

當前項目: /Users/alice/main-project（已有 20 個對話）
源項目: /Users/alice/drafts/experiment（有 10 個對話，其中 3 個與主項目重疊）

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

# 結果：主項目現在有 27 個對話（20 個原始對話 + 7 個來自實驗項目的新對話）

遷移和合並的主要區別：

特性	遷移模式（默認）	合併模式
目標有數據	❌ 拒絕（衝突）	✅ 允許
重複 ID	覆蓋目標	跳過源（保留目標）
使用場景	重命名項目	合併不同項目
備份位置	源文件夾	目標文件夾

📚 詳細文檔

• 工具示例 - 每個工具的 50 多個自然語言示例
• 快速參考 - 常用短語速查表
• 嵌入常見問題解答 - 語義搜索的工作原理

🐛 故障排除

"No conversations found"

確保您在有 Claude Code CLI 對話的目錄中運行此命令。檢查 ~/.claude/projects/ 以驗證對話文件是否存在。

"Embeddings failed"

如果嵌入失敗，MCP 將回退到全文搜索。一切仍然可以正常工作，只是沒有語義搜索功能。

"MCP not responding"

重啟 Claude Code CLI 以重新加載 MCP 服務器。

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

🙏 致謝

本項目受 code-graph-rag-mcp 啟發。

---

為 Claude Code CLI 社區用心打造 ❤️