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 社区用心打造 ❤️