金大哥 - reading-companion MCP 详情

article

README

🚀 阅读伴侣

这是一个分为四个阶段的阅读伴侣，它能帮助你设定阅读目标、发现书籍、跟踪阅读进度，并通过反思深化学习。它作为一个与Claude Desktop集成的MCP（模型上下文协议）服务器运行。

🚀 快速开始

阅读伴侣是一个能助力你完成阅读全流程的工具，从设定目标到深入反思，它都能提供帮助。以下是使用前的准备和操作步骤。

安装

前提条件

Python 3.10及以上版本
uv （Python包管理器）
Claude Desktop

安装步骤

# 克隆仓库
git clone https://github.com/aby0/reading-companion
cd reading-companion

# 安装依赖
uv sync

配置Claude Desktop

将以下内容添加到Claude Desktop的配置文件中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "reading-companion": {
      "command": "uv",
      "args": ["--directory", "/path/to/reading-companion", "run", "reading-companion"]
    }
  }
}

将 /path/to/reading-companion 替换为你克隆仓库的实际路径。重启Claude Desktop，你应该能在MCP服务器列表（锤子图标）中看到“Reading Companion”。

使用方法

初始设置（仅需执行一次）

步骤1：进行访谈

你: "Interview me for my reading goals"

Claude会询问你的阅读目标、偏好和背景信息，结束后会保存你的阅读档案。

步骤2：提取上下文（可选）

你: "Analyze my reading profile"

Claude会提取更深入的模式以改进推荐。

步骤3：构建你的书籍列表

你: "Build me a reading stack for classic literature"

获取每个领域的精选书籍推荐。

持续使用

记录已读完的书籍

你: "I just finished Anna Karenina by Tolstoy"

反思一本书

你: "I want to reflect on Anna Karenina"

检查阅读进度

你: "How's my reading progress?"

获取下一本推荐书籍

你: "What should I read next?"

手动添加一本书

你: "Add 'War and Peace' to my classic lit stack"

✨ 主要特性

四个阶段

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   STAGE 1    │     │   STAGE 2    │     │   STAGE 3    │
│ Interviewer  │ ──▶ │   Context    │ ──▶ │   Syllabus   │
│              │     │   Builder    │     │   Builder    │
│ "Who are you │     │  "Extract    │     │ "Build your  │
│  as a reader"│     │   patterns"  │     │  book stacks"│
└──────────────┘     └──────────────┘     └──────────────┘
       │                                          │
       │              ┌──────────────┐            │
       └────────────▶ │   STAGE 4    │ ◀──────────┘
                      │  Reflection  │
                      │   Partner    │
                      │              │
                      │ "What did    │
                      │  you learn?" │
                      └──────────────┘

访谈者 - 通过对话构建你的阅读档案。
上下文构建器 - 从你的档案中提取更深入的模式。
课程大纲构建器 - 为每个领域创建精选的书籍列表。
反思伙伴 - 帮助处理书籍并跟踪成长。

可用工具

阶段1：访谈者

| 工具 | 描述 | |------|-------------| | start_interview | 开始阅读目标访谈 | | save_profile | 将访谈结果保存为档案 | | get_profile | 查看当前档案 |

阶段2：上下文构建器

| 工具 | 描述 | |------|-------------| | extract_context | 分析档案以获取更深入的模式 | | update_latent_features | 保存提取的特征 |

阶段3：课程大纲构建器

| 工具 | 描述 | |------|-------------| | build_bookstack | 为某个领域生成推荐书籍 | | save_bookstack | 保存生成的书籍列表 | | get_bookstacks | 查看所有书籍列表 | | get_next_book | 获取下一本未读的书籍 | | add_book_to_stack | 手动添加一本书 |

阶段4：反思

| 工具 | 描述 | |------|-------------| | log_book | 快速记录一本已读完的书籍 | | start_reflection | 开始深度反思会话 | | save_reflection | 保存反思见解 | | get_reading_log | 查看阅读历史 | | get_progress | 获取进度总结 |

作者与模式分析

| 工具 | 描述 | |------|-------------| | analyze_reading_patterns | 分析你的阅读历史以找出模式 | | get_author_profile | 查看你读过的作者的档案 | | update_author_notes | 添加关于作者风格的笔记 | | get_favorite_authors | 列出你最喜爱的作者 | | add_book_connection | 将相关书籍关联起来 | | get_similar_books | 查找与你读过的书籍相关的书籍 |

📦 数据存储

所有的阅读数据都存储在 ~/reading-companion-data/ （与代码分开）：

~/reading-companion-data/
├── profile.md                    # 你的档案（人类可读）
├── profile.json                  # 档案数据（系统）
├── bookstacks.json               # 所有书籍列表数据（系统）
├── authors.json                  # 作者跟踪（系统）
├── patterns.json                 # 阅读模式（系统）
├── connections.json              # 书籍关联（系统）
│
├── bookstacks/                   # 书籍推荐
│   ├── _index.md                 # 所有书籍列表概述
│   ├── classic_lit.md            # 每个领域一个文件
│   └── neuroscience.md
│
├── progress/                     # 进度跟踪
│   ├── _current.md               # 带有进度条的当前状态
│   ├── _insights.md              # 阅读模式见解
│   └── reading_log.json          # 结构化日志（系统）
│
├── authors/                      # 作者档案
│   ├── _index.md                 # 按亲和力排序的所有作者
│   ├── leo-tolstoy.md            # 每个作者一个文件
│   └── james-clear.md
│
└── reflections/                  # 书籍反思
    ├── _index.md                 # 所有已读书籍索引
    ├── anna-karenina.md          # 每本书一个文件
    └── atomic-habits.md

关键特性：所有 .md 文件都是人类可读的，可以在VS Code、Obsidian或任何文本编辑器中打开。

📚 详细文档

自定义

提示语

指导每个阶段的提示语位于 reading_companion/prompts/ 目录下：

interviewer.md - 访谈的进行方式
context_builder.md - 档案的分析方式
syllabus_builder.md - 书籍的精选方式
reflection.md - 反思的引导方式你可以根据自己的喜好自定义这些提示语。

领域

你可以设置任何你想要的阅读领域，它们不是硬编码的。在访谈过程中，定义你感兴趣的领域，例如：

经典文学
科幻小说
神经科学
哲学
工程学
历史
任何你感兴趣的领域！

原则

有目的而非随机 - 每本书都有其目的。
注重学习而非单纯阅读 - 反思与阅读同样重要。
追求进步而非完美 - 稳步前进胜过雄心勃勃。
个性化而非大众化 - 适合你的才是最好的，而不是畅销书榜单。

故障排除

“Reading Companion未在Claude Desktop中显示”

检查 claude_desktop_config.json 中的路径是否正确。
重启Claude Desktop。
检查MCP日志是否有错误。

“未找到档案”

先运行 start_interview 创建你的档案。

“未找到领域”

检查你的领域ID是否与档案中的一致。
使用 get_profile 查看可用的领域。

开发

直接运行服务器进行测试：

uv run reading-companion

使用MCP检查器进行测试：

npx @modelcontextprotocol/inspector uv run reading-companion

📄 许可证

本项目采用MIT许可证。

reading-companion