Blues Notehub MCP 服务器 (Python)

这是一个模型上下文协议 (MCP) 服务器的实现，它使用官方的 notehub_py SDK 与 Blues Notehub API 交互。它允许大型语言模型与您的 Blues Notehub 项目、设备和数据进行交互。

什么是 MCP？

模型上下文协议 (MCP) 是一个开放协议，它实现了 LLM 应用程序与外部数据源和工具之间的无缝集成。它标准化了 LLM 与外部工具和服务交互的方式。

前提条件

• Python 3.8 或更高版本
• 一个 Blues Notehub 帐户 (https://notehub.io)
• 您的 Notehub 帐户用户名（电子邮件）和密码

安装

选项 1：使用 pip (推荐)

1. 克隆或下载此存储库。
2. 创建一个虚拟环境：

   python -m venv venv
   source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate
   

3. 安装依赖项：

   pip install -r requirements.txt
   

选项 2：使用 uv (更快的替代方案)

1. 按照 https://github.com/astral-sh/uv 上的说明安装 uv
2. 创建环境并安装依赖项：

   uv venv
   source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate
   uv pip install -r requirements.txt
   

运行服务器

使用以下命令启动服务器：

python notehub.py

MCP 服务器将使用 stdio 作为传输层运行，这是大多数 MCP 客户端的标准传输方式。

身份验证方法

此服务器使用 X-Session-Token 身份验证与 Notehub API 进行身份验证。您需要在使用这些工具时提供您的 Notehub 用户名（电子邮件）和密码。服务器将自动执行以下操作：

1. 使用 /auth/login 端点获取会话令牌
2. 缓存令牌最多 29 分钟（令牌在 30 分钟后过期）
3. 在需要时自动处理令牌刷新

连接到 MCP 客户端

Claude for Desktop (macOS/Windows)

1. 安装 Claude for Desktop
2. 更新您的 Claude Desktop 配置文件：

对于 macOS：

mkdir -p ~/Library/Application\ Support/Claude/

编辑或创建 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "notehub": {
      "command": "python",
      "args": [
        "--directory",
        "/path/to/your/mcp-server",
        "run",
        "notehub.py"
      ],
      "availableTo": ["claude-3-opus-20240229", "claude-3-sonnet-20240229", "claude-3-5-sonnet-20240307", "claude-3-haiku-20240307"]
    }
  }
}

对于 Windows，配置文件位于： %APPDATA%\Claude\claude_desktop_config.json

3. 重新启动 Claude for Desktop

自定义 MCP 客户端

如果您正在构建自定义 MCP 客户端，您需要：

1. 将此服务器作为子进程启动
2. 使用 stdin/stdout 按照 MCP 协议与其通信
3. 配置您的客户端以发现此服务器公开的工具

可用工具

此 MCP 服务器公开以下工具：

1. get-projects - 获取所有可访问的 Notehub 项目
2. get-project-devices - 获取特定项目的所有设备（带有可选的过滤）
3. get-project-events - 获取特定项目的所有事件（带有可选的过滤）
4. send-note - 向特定设备发送一条 note

使用示例

当与 Claude for Desktop 一起使用时，您可以提出如下问题：

• "你能展示我所有的 Notehub 项目吗？我的用户名是 example@email.com，密码是 mypassword123"
• "使用我的 Notehub 用户名 (example@email.com) 和密码，从我的项目 app:12345 中获取所有设备"
• "获取项目 app:12345 中设备 dev:12345 的最后 10 个事件"
• "使用以下有效负载 {"message": "Hello from MCP"} 向项目 app:12345 中的设备 dev:12345 发送一条 note"

安全注意事项

• 此服务器需要您的 Notehub 用户名和密码才能运行。
• 永远不要共享包含路径或凭据的配置文件。
• MCP 协议在本地运行，因此您的凭据不会发送到远程服务器。
• 该服务器实现了令牌缓存，以在保持安全性的同时获得更好的性能。
• 如果您的 Notehub 帐户是使用“使用 GitHub 登录”创建的，您需要首先在 Notehub.io 的帐户设置面板中设置密码。

故障排除

如果您遇到问题：

1. 检查日志中是否有任何错误消息：

   • macOS: ~/Library/Logs/Claude/mcp-server-notehub.log
   • Windows: %APPDATA%\Claude\Logs\mcp-server-notehub.log

2. 验证您的 Notehub 凭据是否正确。

3. 如果您使用 GitHub 注册，请确保您已在 Notehub 帐户设置中设置了密码。

4. 确保服务器正在使用正确的 Python 版本运行。

5. 确保 mcp 和 notehub_py 包都已正确安装。

扩展服务器

要向此服务器添加更多功能：

1. 使用其他 Notehub API 功能扩展这些函数
2. 使用 @mcp.tool() 装饰器注册新工具
3. 向现有工具添加更多过滤选项
4. 实施额外的错误处理和报告

许可证

MIT