书签同步工具

XBookmark

将X（推特）书签同步到黑曜石保险库的MCP服务器。 多帐户支持、OAuth 2.0 PKCE身份验证和结构化JSON存储。

特性

• 多账户支持 --通过个人资料创建无限X帐户
• 一键OAuth登录 --浏览器打开，回调被捕获，令牌自动保存
• 集中存储 --将所有书签放在一个文件夹中 bookmarks.json （原子写入）
• 线程检测 --多推特线程的自动线程获取
• 跨帐户重复数据删除 --来自2个帐户的同一推文书签=1条
• 费率限制处理 --具有自动重试功能的顺序处理
• 两步工作流程 --先同步，后删除（测试安全）
• 人工智能驱动的摘要 — /xbookmark-digest Claude分析和分类的代码技能

可用工具

快速安装（Claude代码插件）

将XBookmark与Claude Code结合使用的最简单方法：

1. 设置X API凭据 （添加到 ~/.bashrc 或 ~/.zshrc):

   复制

   export X_CLIENT_ID="your_oauth2_client_id"
   export X_CLIENT_SECRET="your_client_secret"          # optional
   export X_REDIRECT_URI="http://localhost:8080/callback" # optional
   

2. 安装插件 （克劳德法典）：

   复制

   /plugin marketplace add isezen/XBookmarks
   /plugin install xbookmark@XBookmarks
   

3. 重新启动克劳德代码。 MCP服务器在首次启动时自动安装。

4. 使用它：

   复制

   /xbookmark:digest                          # Analyze all bookmarks
   /xbookmark:digest https://x.com/.../12345  # Process single tweet
   

开发人员安装

先决条件

• Python 3.10+
• 紫外线 包管理器（推荐）或pip
• 启用OAuth 2.0的X开发人员帐户

设置

1. 克隆并安装

   复制

   git clone git@github-isezen:isezen/XBookmarks.git
   cd XBookmarks
   uv sync
   

2. 设置环境变量

   复制

   cp .env.example .env
   

   编辑 .env 使用您的X API证书：

   复制

   X_CLIENT_ID="your_client_id"
   X_CLIENT_SECRET="your_client_secret"
   X_REDIRECT_URI="http://localhost:8080/callback"
   

3. 创建配置 （可选--默认值适用于大多数设置）

   复制

   mkdir -p ~/.config/XBookmark
   cat > ~/.config/XBookmark/config.json << 'EOF'
   {
     "obsidian_vault_path": "/path/to/your/obsidian/vault",
     "xbookmarks_folder": "XBookmarks"
   }
   EOF
   

   或设置 XBOOKMARK_HOME env-var使用自定义配置目录。

X API设置

获取OAuth 2.0凭据

1. 首选 X开发者门户
2. 创建一个 项目 和a 应用
3. 在“应用程序设置”下，启用 OAuth 2.0 与：
   • 类型： 机密客户 （或公开）
   • 重定向URI: http://localhost:8080/callback
4. 所需范围： bookmark.read, bookmark.write, tweet.read, users.read, offline.access
5. 复制 客户端ID 和 客户端密钥 致你的 .env 文件

备注：书签端点需要 基本层 访问或按使用次数付费积分。

与MCP客户端一起使用

克劳德代码/克劳德桌面

添加到MCP设置中：

{
  "mcpServers": {
    "xbookmark": {
      "command": "/path/to/XBookmarks/.venv/bin/xbookmark-mcp"
    }
  }
}

工作流程

第一步：身份验证

> "Login to my X account"

代理人打电话来 xbookmark_auth_login() --浏览器打开，您授权，令牌保存。

对于多个帐户，请使用配置文件：

> "Login to my work X account as 'work'"

第二步：同步书签

> "Sync my X bookmarks"

代理人打电话来 xbookmark_sync_all() 其中：

• 从所有经过身份验证的配置文件下载
• 跨帐户进行重复数据消除
• 保存到 XBookmarks/bookmarks.json
• 不从X中删除

步骤3：处理和分类

使用 /xbookmark-digest 技能（或手动）：

1. 从以下位置读取书签条目 bookmarks.json
2. 分析推特内容，获取链接的网址
3. 在黑曜石主题文件夹中创建丰富的笔记
4. 跟踪已处理的推文 index.json

步骤4：从X中删除 （可选）

> "Delete processed bookmarks from X"

代理人打电话来 xbookmark_delete() （没有profile参数，这会删除 从所有配置文件中）并清理 bookmarks.json.

数据存储

书签.json

所有已同步的书签都存储在 XBookmarks/bookmarks.json 作为一个扁平的JSON数组。 每个条目都包含推文文本、作者信息、实体、媒体、帖子回复， 以及源配置文件。写入时使用原子tmp，然后重命名以确保崩溃安全。

index.json

跟踪哪些推文已被摘要技能处理。 地图 tweet_id 到 {path, date, tags} 黑曜石交叉引用。

发展

快速命令

# Install with dev dependencies
uv sync --extra dev

# Run all tests
.venv/bin/pytest

# Run single test
.venv/bin/pytest tests/test_config.py::TestLoadConfig -v

# Coverage report
.venv/bin/pytest --cov=src/xbookmark

# Lint & format
.venv/bin/ruff check . && .venv/bin/ruff format .

# Run MCP server
.venv/bin/xbookmark-mcp

# Debug with MCP Inspector
npx @modelcontextprotocol/inspector .venv/bin/xbookmark-mcp

项目结构

XBookmarks/
├── .claude-plugin/
│   └── marketplace.json       # Claude Code plugin marketplace
├── plugins/xbookmark/         # Claude Code plugin
│   ├── .claude-plugin/plugin.json
│   ├── .mcp.json              # MCP server config
│   ├── commands/
│   │   └── digest.md          # AI digest skill (source of truth)
│   ├── hooks/hooks.json       # SessionStart auto-install hook
│   └── scripts/ensure-installed.sh
├── .claude/commands/
│   └── xbookmark-digest.md    # Symlink → plugins/xbookmark/commands/digest.md
├── src/xbookmark/
│   ├── config.py              # Config loading, lazy singleton
│   ├── mcp/
│   │   ├── server.py          # FastMCP entry point
│   │   ├── tools_auth.py      # 6 OAuth 2.0 PKCE auth tools
│   │   └── tools_sync.py      # 6 sync/delete/list tools
│   ├── x_api/
│   │   ├── auth.py            # OAuth 2.0 PKCE flow, token storage
│   │   ├── callback_server.py # Local HTTP server for one-click login
│   │   ├── client.py          # Async HTTP client with retry
│   │   ├── bookmarks.py       # Bookmark CRUD (X API v2)
│   │   └── tweets.py          # Tweet/thread fetching
│   └── obsidian/
│       └── writer.py          # Markdown generation, JSON I/O
├── tests/
│   ├── conftest.py            # Shared fixtures
│   ├── test_config.py
│   ├── test_writer.py
│   └── test_tools.py
├── docs/                      # Architecture & API docs
├── pyproject.toml
├── CLAUDE.md                  # Claude Code guidance
└── README.md

测试

• 框架：pytest with asyncio_mode = "auto"
• HTTP模拟： respx 图书馆
• 固定装置： tests/conftest.py （mock_config、mock_auth_manager、mock_tweet等）
• 按模块分类组织的测试

代码的风格

• Python 3.10+，规则：E/F/I/N/W/UP
• 现代风格提示： str | None, list[str]
• 多行结构中的双引号和尾随逗号

许可证

麻省理工学院