Reflect MCP Server

这是一个使用Python编写的MCP（模型上下文协议）服务器，它提供了与Reflect Notes API的无缝集成。该服务器使AI助手能够与您的Reflect笔记进行交互，允许您创建笔记、保存链接、追加到日常笔记，并通过编程方式管理知识图谱。

功能

• OAuth2认证：安全的身份验证流程，自动令牌管理
• 笔记管理：使用Markdown内容创建新的笔记
• 日常笔记：可选地追加文本到日常笔记
• 链接保存：保存带有标题、描述和高亮的网页链接
• 图谱操作：列出并管理多个知识图谱
• 用户管理：获取当前用户信息和默认图谱设置

安装

使用uvx快速启动（推荐）

无需克隆仓库！只需配置并运行：

{
  "mcpServers": {
    "reflect": {
      "command": "uvx",
      "args": ["reflect-mcp"],
      "env": {
        "REFLECT_ACCESS_TOKEN": "your_access_token_here"
      }
    }
  }
}

获取访问令牌的方法：

1. 访问Reflect开发者OAuth
2. 如果尚未创建，请创建凭证
3. 生成访问令牌
4. 复制令牌并添加到上述配置中

手动安装

pip install reflect-mcp

或者使用uv：

uv pip install reflect-mcp

配置

使用访问令牌（推荐）

最简单的使用服务器的方式是直接使用访问令牌：

REFLECT_ACCESS_TOKEN=your_access_token_here
REFLECT_DEFAULT_GRAPH_ID=your_default_graph_id  # 可选

获取访问令牌的方法：

1. 访问Reflect开发者OAuth
2. 如果尚未创建，请创建凭证
3. 生成访问令牌
4. 复制令牌并添加到您的配置中

使用OAuth2（替代方案）

如果您更喜欢OAuth2身份验证：

REFLECT_CLIENT_ID=your_oauth_client_id
REFLECT_CLIENT_SECRET=your_oauth_client_secret
REFLECT_REDIRECT_URI=http://localhost:8080/callback  # 可选
REFLECT_DEFAULT_GRAPH_ID=your_default_graph_id  # 可选

Claude Desktop配置

在您的Claude Desktop配置文件中添加服务器：

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

使用已发布的包和访问令牌：

{
  "mcpServers": {
    "reflect": {
      "command": "uvx",
      "args": ["reflect-mcp"],
      "env": {
        "REFLECT_ACCESS_TOKEN": "your_access_token_here"
      }
    }
  }
}

如果从源代码运行：

{
  "mcpServers": {
    "reflect": {
      "command": "/path/to/uv",
      "args": [
        "--directory",
        "/path/to/reflect-m_",
        "run",
        "reflect_server.py"
      ],
      "env": {
        "REFLECT_ACCESS_TOKEN": "your_access_token_here"
      }
    }
  }
}

替代OAuth2配置（如果不使用访问令牌）：

{
  "mcpServers": {
    "reflect": {
      "command": "uvx",
      "args": ["reflect-mcp"],
      "env": {
        "REFLECT_CLIENT_ID": "your_client_id",
        "REFLECT_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

可用工具

身份验证

• authenticate - 启动OAuth2身份验证流程（打开浏览器）
• set_access_token - 使用授权码完成OAuth2流程
• set_token_directly - 手动设置访问令牌（如果您已经有一个）

图谱

• list_graphs - 获取所有可访问图谱的ID、名称和时间戳
• get_default_graph - 从配置或用户资料中获取默认图谱ID

笔记及内容

• create_note - 创建带有标题和Markdown内容的新笔记
• append_daily_note - 追加文本到日常笔记（今天或特定日期）
• list_books - 获取图谱中的所有书籍
• list_links - 获取图谱中的所有链接
• create_link - 保存带有可选元数据的网页链接

用户

• get_current_user - 获取有关已认证用户的详细信息

身份验证

使用访问令牌（推荐）

如果您已使用REFLECT_ACCESS_TOKEN配置了服务器，则您已经进行了身份验证，可以立即开始使用所有工具。

使用OAuth2流程

如果您使用的是OAuth2凭证而不是直接访问令牌：

1. 开始身份验证过程：

   authenticate
   

   这将在您的浏览器中打开Reflect OAuth页面。

2. 授权后，您将被重定向到一个包含授权码的URL。

3. 提供代码以完成身份验证：

   set_access_token code="your_authorization_code"
   

4. 服务器将自动处理令牌交换和刷新。

使用示例

创建笔记

create_note(
    subject="会议记录",
    content="## 项目审查\n\n- 讨论时间线\n- 设定Q2目标",
    pinned=False
)

追加到日常笔记

# 追加到今天的日常笔记
append_daily_note(
    text="记得查看项目提案"
)

# 追加到昨天笔记中的特定列表
append_daily_note(
    text="完成用户身份验证功能",
    date="2024-01-18",
    list_name="已完成"
)

保存链接

create_link(
    url="https://example.com/article",
    title="有趣的文章",
    description="关于生产力的关键见解",
    highlights=["文章中的重要引用", "另一个亮点"]
)

列出并管理图谱

# 获取所有可访问图谱
list_graphs()

# 获取默认图谱ID
get_default_graph()

# 列出特定图谱中的所有链接
list_links(graph_id="your_graph_id")

资源

服务器提供以下MCP资源用于检查状态：

• get_auth_status (reflect://auth/status)：检查当前身份验证状态
• get_config (reflect://config)：查看当前配置（不包括秘密）

工作流提示

内置的工作流提示用于常见任务：

• create_reading_list：在Reflect中创建组织良好的阅读清单模板
• daily_journal_workflow：结构化的每日日记模板

开发

从源代码运行

# 克隆仓库
git clone https://github.com/yourusername/reflect-mcp
cd reflect-mcp

# 安装依赖项
uv sync

# 在开发模式下运行
uv run mcp dev reflect_mcp/server.py

测试

# 使用MCP检查器进行测试
uv run mcp inspector reflect_mcp/server.py

构建和发布

# 构建包
uv build

# 发布到PyPI（需要凭据）
uv publish

API参考

服务器实现了版本v0.1.0的Reflect API，具有以下端点：

• GET /graphs - 列出所有图谱
• GET /graphs/{id}/books - 列出图谱中的书籍
• GET /graphs/{id}/links - 列出图谱中的链接
• POST /graphs/{id}/links - 创建新链接
• POST /graphs/{id}/notes - 创建新笔记
• PUT /graphs/{id}/daily-notes - 追加到日常笔记
• GET /users/me - 获取当前用户信息

身份验证

Reflect API使用OAuth2，具有以下流程：

• 授权URL：https://reflect.app/oauth
• 令牌URL：https://reflect.app/api/oauth/token
• 范围：
  • read:graph - 对受保护资源的读取访问
  • write:graph - 对受保护资源的写入访问

故障排除

身份验证问题

• 缺少凭证：确保设置了REFLECT_CLIENT_ID和REFLECT_CLIENT_SECRET
• 无效重定向：检查您的OAuth应用的重定向URI是否与服务器预期的回调匹配
• 令牌刷新：服务器使用authlib库自动处理令牌刷新

连接错误

• 检查您的互联网连接
• 确认可以通过https://api.reflect.app访问Reflect API
• 查看服务器日志以获取详细的错误消息
• 确保您的OAuth应用启用了必要的范围

常见问题

1. “服务器断开”错误在Claude中：通常意味着服务器无法启动。检查：

   • OAuth凭证是否正确设置
   • 配置中没有语法错误
   • 如果是从源代码运行，reflect_server.py文件是否存在

2. “未认证”错误：首先运行authenticate工具以设置OAuth

3. 图谱ID错误：使用list_graphs找到有效的图谱ID，或设置REFLECT_DEFAULT_GRAPH_ID

贡献

欢迎贡献！请随时提交Pull Request。

许可证

MIT许可证 - 详情请参阅LICENSE文件

支持

对于问题和功能请求，请使用GitHub问题跟踪器。