内容
# 浏览器书签工具
<p align="center">
<a href="https://github.com/casey/just"><img src="https://img.shields.io/badge/just-ready_to_go-7c5cfc?style=flat-square&logo=just&logoColor=white" alt="Just"></a>
<a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
<a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.13+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python"></a>
<a href="https://github.com/PrefectHQ/fastmcp"><img src="https://img.shields.io/badge/FastMCP-3.3-7c5cfc?style=flat-square" alt="FastMCP"></a>
</p>
> 📖 **[安装指南](INSTALL.md)** — 快速开始，手动设置，故障排除
FastMCP 3.3 MCP 服务器，包含多个组合工具（而非一个巨大的 `bookmarks` 工具）。从 database-operations-mcp 移植而来。
## MCP 工具（组合接口）
| 工具 | 用途 |
|------|---------|
| `browser_bookmarks` | 通用 CRUD/搜索/导出，适用于 Firefox、Chrome、Edge、Brave |
| `firefox_profiles` | Firefox 配置文件创建/加载/组合配置文件 |
| `firefox_backup` | 备份/恢复 Firefox 配置文件数据 |
| `firefox_curated` | 精选书签源集合 |
| `firefox_tagging` | 基于文件夹/年份的自动标签 |
| `firefox_utils` | Firefox 路径、锁定检查、places DB 信息 |
| `sync_bookmarks` | 跨浏览器同步（支持 dry-run） |
| `chrome_profiles` | Chromium 配置文件管理 |
| `ai_bookmark_portmanteau` | AI 分类、去重、精选、维护、导出 |
`firefox_bookmarks` 仍然是一个内部助手，用于 Firefox 特定的 SQLite 操作。
## 快速开始
```powershell
git clone https://github.com/sandraschi/bookmarks-mcp
cd bookmarks-mcp
just
```
这将打开一个交互式仪表板，显示所有可用的命令。运行 `just bootstrap` 安装依赖，然后运行 `just serve` 或 `just dev` 启动。
## 安装
### 先决条件
- [uv](https://docs.astral.sh/uv/) 已安装（推荐）
- Python 3.12+
### 快速开始
通过 `uvx` 立即运行：
```bash
uvx bookmarks-mcp
```
### Claude 桌面集成
添加到您的 `claude_desktop_config.json`：
```json
"mcpServers": {
"bookmarks-mcp": {
"command": "uv",
"args": ["--directory", "D:/Dev/repos/bookmarks-mcp", "run", "bookmarks-mcp"]
}
}
```
### 运行服务器
#### 作为 Python 模块（推荐用于 MCP 客户端）
```bash
python -m browser_bookmarks_tools
```
#### 作为直接脚本（开发）
```bash
python src/browser_bookmarks_tools/mcp_server.py
```
#### 使用 uv
```bash
uv run python -m browser_bookmarks_tools
```
## MCP 客户端配置
### Cursor IDE（mcp.json）
```json
{
"mcpServers": {
"bookmarks-mcp": {
"command": "python",
"args": ["-m", "browser_bookmarks_tools"],
"env": {
"PYTHONPATH": "D:/Dev/repos/bookmarks-mcp/src",
"PYTHONUNBUFFERED": "1"
}
}
}
}
```
### Claude 桌面（claude_desktop_config.json）
```json
{
"mcpServers": {
"bookmarks-mcp": {
"command": "python",
"args": ["-m", "browser_bookmarks_tools"],
"env": {
"PYTHONPATH": "/path/to/bookmarks-mcp/src"
}
}
}
}
```
## 可用操作
查看工具文档字符串以获取完整的操作列表。主要入口：
- **`browser_bookmarks`** — `list_bookmarks`、`add_bookmark`、`search_bookmarks`、`find_duplicates`、`export_bookmarks`、标签操作、年龄分析、损坏链接等
- **`sync_bookmarks`** — 跨浏览器传输，支持 `dry_run`
- **`ai_bookmark_portmanteau`** — `categorize`、`dedupe`、`curate`、`maintain`、`export`
## 浏览器支持详情
### Firefox（主要）
- **存储：** `places.sqlite` 数据库
- **功能：** 完整历史、标签、文件夹、图标
- **路径：** `~/.mozilla/firefox/*/places.sqlite`
### Chrome/Edge/Brave
- **存储：** JSON 书签文件
- **功能：** 基本书签，包含文件夹
- **路径：** `~/Library/Application Support/Google/Chrome/Default/Bookmarks`
### Safari（仅 macOS）
- **存储：** 二进制 plist 文件
- **功能：** 基本书签
- **路径：** `~/Library/Safari/Bookmarks.plist`
## 开发
### 项目结构
```
bookmarks-mcp/
src/browser_bookmarks_tools/
__init__.py # 包初始化
__main__.py # 模块入口，用于 `python -m`
mcp_server.py # FastMCP 服务器实现
bookmarks/ # 核心书签操作
manager.py # CRUD 操作
organizer.py # 组织功能
portmanteau.py # 主要工具接口
sync.py # 跨浏览器同步
ai/ # AI 驱动的功能
analyzer.py # 内容分析
summarizer.py # 摘要生成
tagger.py # 智能标签
browsers/ # 浏览器特定的实现
tests/
pyproject.toml
```
### 运行测试
```bash
python -m pytest tests/
```
### 代码质量
```bash
# 格式化代码
black src/
# 检查代码
ruff check src/
# 类型检查
mypy src/
```
## 故障排除
### "模块未找到" 错误
确保 `PYTHONPATH` 包含 `src` 目录：
```bash
export PYTHONPATH="/path/to/bookmarks-mcp/src:$PYTHONPATH"
```
### 浏览器权限问题
- **Firefox:** 确保在访问 `places.sqlite` 时 Firefox 未运行
- **Chrome/Edge:** 读取书签文件不需要特殊权限
- **Safari:** 需要 macOS 和适当的文件权限
### MCP 连接问题
- 验证服务器在手动运行时是否启动正常
- 检查 MCP 客户端配置中是否正确设置了 `PYTHONPATH`
- 确保没有防火墙/防病毒软件阻止连接
## 贡献
1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 为新功能添加测试
5. 提交拉取请求
## 🛡️ 工业质量堆栈
该项目遵循 **SOTA 14.1** 工业标准，用于高保真代理编排：
- **Python（核心）：** [Ruff](https://astral.sh/ruff) 用于检查和格式化。核心处理程序中禁止 `print` 语句（`T201`）。
- **Webapp（UI）：** [Biome](https://biomejs.dev/) 用于毫秒级检查。严格执行 `noConsoleLog`。
- **协议合规性：** 加强 `stdout/stderr` 隔离，以确保崩溃抗性的 JSON-RPC 通信。
- **自动化：** [Justfile](./justfile) 用于所有舰队操作（`just lint`、`just fix`、`just dev`）。
- **安全：** 通过 `bandit` 和 `safety` 进行自动审计。
## 许可证
[添加适当的许可证信息]
## 更新日志
### v0.1.0
- 初始 FastMCP 3.1.0 合规实现
- Firefox、Chrome、Edge、Brave 和 Safari 支持
- 统一的组合工具接口
- AI 驱动的书签分析和标签
- 跨浏览器同步
## Web 仪表板
| 服务 | 端口 | 备注 |
|---------|------|-------|
| 前端（Vite） | **10802** | `web_sota/start.ps1` |
| 后端（FastAPI + MCP） | **10803** | `MCP_TRANSPORT=http` |
页面：仪表板、书签（CRUD + 分页）、搜索（文件夹/标签过滤）、树、批量操作（同步向导、导出下载）、标签、AI 命令、MCP 工具、设置、帮助。
### 生产身份验证
`/api/*` 路由上的 HTTP 基本身份验证**默认启用**。
| 变量 | 默认值 | 用途 |
|----------|---------|---------|
| `BOOKMARKS_WEB_AUTH` | `1` | 设置为 `0` 以禁用（仅限开发） |
| `BOOKMARKS_WEB_USER` | `admin` | 用户名 |
| `BOOKMARKS_WEB_PASS` | `mcp` | 密码 |
在 **设置 → API 身份验证** 中配置凭证（存储在浏览器本地存储中作为基本身份验证标头）。
根 `/health` 对负载均衡器是未经身份验证的。
### Tauri 桌面
```powershell
cd native
.\build.ps1
```
启动 MCP 后端侧车并加载构建的 SPA。
## Webapp 仪表板
此 MCP 服务器包含一个 React Web 界面用于监控和控制。
默认情况下，Web 仪表板在端口 **10802** 上运行。
*（已分配端口：**10802** （Web 仪表板前端），**10803** （Web 仪表板后端）*
要启动 Web 应用程序：
1. 导航到 `webapp` （或 `web`、`frontend`）目录。
2. 运行 `start.bat`（Windows）或 `./start.ps1`（PowerShell）。
3. 在浏览器中打开 `http://localhost:10802`。
