# https://github.com/jomkz/second-brain-joplin 项目说明书 生成时间：2026-07-01 19:40:43 UTC ## 目录 - [Overview & System Architecture](#page-1) - [MCP Tools & JoplinClient Implementation](#page-2) - [Development Workflow, CI/CD & Release](#page-3) - [Configuration, Security, Privacy & Roadmap](#page-4) ## Overview & System Architecture ### 相关页面 相关主题：[MCP Tools & JoplinClient Implementation](#page-2), [Configuration, Security, Privacy & Roadmap](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/jomkz/second-brain-joplin/blob/main/README.md) - [CHANGELOG.md](https://github.com/jomkz/second-brain-joplin/blob/main/CHANGELOG.md) - [CONTRIBUTING.md](https://github.com/jomkz/second-brain-joplin/blob/main/CONTRIBUTING.md) - [SECURITY.md](https://github.com/jomkz/second-brain-joplin/blob/main/SECURITY.md) - [src/second_brain_joplin/__init__.py](https://github.com/jomkz/second-brain-joplin/blob/main/src/second_brain_joplin/__init__.py) - [src/second_brain_joplin/server.py](https://github.com/jomkz/second-brain-joplin/blob/main/src/second_brain_joplin/server.py) - [src/second_brain_joplin/joplin_client.py](https://github.com/jomkz/second-brain-joplin/blob/main/src/second_brain_joplin/joplin_client.py)
# Overview & System Architecture ## 项目概述与目标 `second-brain-joplin` 是一个 **MCP（Model Context Protocol）服务器**，其核心目标是将本地 [Joplin](https://joplinapp.org/) 知识库转换为任何支持 MCP 协议的 AI 客户端可调用的"可搜索记忆"。它是 [second-brain-mcp](https://github.com/noesskeetit/second-brain-mcp)（针对 Obsidian 实现）的 Joplin 版本，提供完全等价的工作流但适配 Joplin 的 REST API 接口 资料来源：[README.md:1-15]()。 当前发布版本为 **v0.1.0 引导版本**（Bootstrap）——MCP 服务器能够启动，所有工具均已注册但仍处于桩（stub）状态 资料来源：[CHANGELOG.md:33-56]()。真正的读工具实现计划在 **v0.2 里程碑** 完成（社区议题 #5–#8），语义搜索将在 **v0.3** 完成（议题 #9），人工把关的写入能力将在 **v0.4** 完成（议题 #10），正式发布则安排在 **v1.0** 资料来源：[README.md:58-66]()。 ## 系统架构 整体系统由三大部分构成：MCP 客户端（如 Claude Code / Cursor）、`second-brain-joplin` 服务器进程、以及本地运行的 Joplin Desktop 应用程序及其暴露的 Web Clipper REST API（默认监听 `localhost:41184`）。 ```mermaid flowchart LR A[Claude Code / Cursor
MCP Client] -->|MCP / stdio| B[second-brain-joplin
FastMCP Server] B -->|HTTP + token
via httpx| C[Joplin Desktop
Web Clipper :41184] C --> D[(本地 Joplin Notes
& Notebooks)] B -.读取环境变量.-> E[JOPLIN_API_TOKEN
JOPLIN_BASE_URL] ``` `src/second_brain_joplin/__init__.py` 仅声明包元数据与版本号 `__version__ = "0.1.0"` 资料来源：[src/second_brain_joplin/__init__.py:1-4]()。运行时入口则由 `src/second_brain_joplin/server.py` 提供：CLI 通过 `argparse` 注册 `serve` 子命令，启动时调用 `load_dotenv()` 加载环境配置，再创建全局 `JoplinClient` 实例 资料来源：[src/second_brain_joplin/server.py:17-33]()。 ## 核心组件 ### JoplinClient（Joplin REST API 适配层） `JoplinClient` 是对 Joplin Web Clipper API 的轻量封装。构造函数接收 `base_url`（去除尾部斜杠）与 `token`（作为 `?token=` 查询参数附加），目前仅 `ping()` 方法可用——通过 `httpx.AsyncClient` 访问 `/ping` 端点，比对返回文本是否为 `JoplinClipperServer` 来确认连通性，并在 `httpx.ConnectError` 时返回 `False` 资料来源：[src/second_brain_joplin/joplin_client.py:1-21]()。 `get_notebooks`、`get_note`、`search`、`get_recent`、`create_note` 五个方法在 v0.1 中显式抛出 `NotImplementedError`，对应的实现见社区议题 #4–#8 与 #10 资料来源：[src/second_brain_joplin/joplin_client.py:23-39]()。这种"先定义接口占位、实现随版本推进"的设计有助于保持 CI 与 90% 覆盖率门槛始终通过 资料来源：[CHANGELOG.md:44-56]()。 ### FastMCP Server 与桩工具 `server.py` 以 `FastMCP("second-brain-joplin")` 实例化服务器，并使用 `@mcp.tool()` 装饰器注册五个工具：`joplin_overview`、`joplin_search`、`joplin_read`、`joplin_recent` 与 `joplin_create`。在 v0.1 中，每个工具都返回 `{"status": "not implemented", "tool": , "issue": }`，使请求不会真正下到 `JoplinClient` 资料来源：[src/second_brain_joplin/server.py:35-55]()。 `_get_client()` 借助模块级全局变量实现惰性单例，从环境变量读取 `JOPLIN_API_TOKEN` 与 `JOPLIN_BASE_URL`（后者默认 `http://localhost:41184`）资料来源：[src/second_brain_joplin/server.py:17-33]()。这与 `.env` 经由 `python-dotenv` 自动加载的机制相配合，简化本地开发体验 资料来源：[CONTRIBUTING.md:43-50]()。 ## 数据流与请求生命周期 一次典型调用遵循以下路径： 1. **MCP 客户端**通过 stdio 发送 `tools/call` 请求（例如调用 `joplin_search`）。 2. **FastMCP** 调度至对应装饰器函数；v0.1 立即返回带 `status: "not implemented"` 的字典。 3. 待 v0.2 实现完成后，函数将调用 `_get_client()` 获取 `JoplinClient`，再通过 `httpx.AsyncClient` 发起 HTTP 请求，附 `?token=` 鉴权 资料来源：[src/second_brain_joplin/joplin_client.py:9-14]()。 4. 服务器通过 stdio 通道将 JSON-RPC 响应回传给客户端。 设计上的一个关键原则是：**v0.1 不做任何静默写入**——只有读取型的桩工具以及一个计划中需要人工把关的 `joplin_create` 工具被注册 资料来源：[SECURITY.md:18-23]()。 ## 与同类项目的对比 | 维度 | second-brain-mcp（Obsidian） | second-brain-joplin | |---|---|---| | 笔记应用 | Obsidian | Joplin | | 数据访问 | 磁盘上的 `.md` 文件 | Joplin REST API | | 是否需要 Joplin/Obsidian 运行 | 否 | 是（需开启 Web Clipper 服务） | | 语义搜索 | 支持（bge-m3） | 计划在 v0.3 实现 | | 写入能力 | 人工把关 | 人工把关（v0.4） | | 安装方式 | `uvx second-brain-mcp` | `uvx second-brain-joplin` | 资料来源：[README.md:48-57]()。 ## 安全与隐私模型 整套设计坚持"本地优先"原则：服务器仅与 `localhost` 上的 Joplin API 通信，不会把笔记外发至第三方服务；API 令牌通过环境变量传入而非提交至版本控制；采用最低权限原则——任何 MCP 客户端可读取的内容，连接的 AI 同样可读取，因此应避免暴露含凭证的笔记本 资料来源：[SECURITY.md:9-23]()。v0.1 不写入任何数据，v0.4 计划引入的人工把关机制将进一步保障写入安全 资料来源：[README.md:73-79]()。 ## See Also - [CHANGELOG.md](https://github.com/jomkz/second-brain-joplin/blob/main/CHANGELOG.md) — 版本演进与 CI/CD 重构记录 - [CONTRIBUTING.md](https://github.com/jomkz/second-brain-joplin/blob/main/CONTRIBUTING.md) — 开发环境、CI 工作原理、标签约定 - [SECURITY.md](https://github.com/jomkz/second-brain-joplin/blob/main/SECURITY.md) — 漏洞上报与数据处理策略 - [README.md](https://github.com/jomkz/second-brain-joplin/blob/main/README.md) — 快速安装、客户端配置与里程碑总览 - 社区议题：#3（包骨架）、#5 (`joplin_overview`)、#6 (`joplin_search`)、#7 (`joplin_read`)、#8 (`joplin_recent`)、#9（语义搜索）、#10（人工把关写入）、#11（v1.0 发布）、#12（PyPI trusted publisher） --- ## MCP Tools & JoplinClient Implementation ### 相关页面 相关主题：[Overview & System Architecture](#page-1), [Development Workflow, CI/CD & Release](#page-3), [Configuration, Security, Privacy & Roadmap](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [src/second_brain_joplin/server.py](https://github.com/jomkz/second-brain-joplin/blob/main/src/second_brain_joplin/server.py) - [src/second_brain_joplin/joplin_client.py](https://github.com/jomkz/second-brain-joplin/blob/main/src/second_brain_joplin/joplin_client.py) - [src/second_brain_joplin/__init__.py](https://github.com/jomkz/second-brain-joplin/blob/main/src/second_brain_joplin/__init__.py) - [README.md](https://github.com/jomkz/second-brain-joplin/blob/main/README.md) - [CHANGELOG.md](https://github.com/jomkz/second-brain-joplin/blob/main/CHANGELOG.md) - [CONTRIBUTING.md](https://github.com/jomkz/second-brain-joplin/blob/main/CONTRIBUTING.md) - [SECURITY.md](https://github.com/jomkz/second-brain-joplin/blob/main/SECURITY.md)
# MCP 工具与 JoplinClient 实现 ## 概述与范围 `second-brain-joplin` 是 v0.1.0 阶段的 MCP 服务器骨架，其核心目标是把 Joplin Desktop 的 Web Clipper 本地 REST API（默认 `http://localhost:41184`）封装为 MCP 工具，供 Claude Code、Cursor 等 MCP 客户端调用，从而让 AI 直接读取与查询本地 Joplin 笔记库。 资料来源：[src/second_brain_joplin/__init__.py:1-3]()、[CHANGELOG.md:1-12]() 在当前 v0.1.0（Bootstrap 版本）中： - 服务器可以正常启动并通过 `serve` 子命令暴露 stdio 传输。 - 全部 5 个 MCP 工具已注册到 FastMCP，但均返回 `{"status": "not implemented"}` 占位响应，未真正调用后端。 - `JoplinClient` 中只有 `ping()` 是可用实现，其余方法（`get_notebooks`、`get_note`、`search`、`get_recent`、`create_note`）显式抛出 `NotImplementedError`，等待 v0.2 里程碑落地。 资料来源：[CHANGELOG.md:24-37]()、[src/second_brain_joplin/server.py:20-49]()、[src/second_brain_joplin/joplin_client.py:18-39]() ## 架构与数据流 整个调用链路为「MCP 客户端 → FastMCP 服务器 → JoplinClient → Joplin REST API → 本地笔记」。服务器进程在 `main()` 中调用 `load_dotenv()` 加载 `.env`，然后通过 `argparse` 解析 `serve` 子命令并执行 `mcp.run()`。`_get_client()` 是一个惰性单例工厂：首次调用时读取 `JOPLIN_API_TOKEN` 与 `JOPLIN_BASE_URL` 环境变量（后者默认 `http://localhost:41184`），并构造 `JoplinClient`。 资料来源：[src/second_brain_joplin/server.py:1-20]()、[src/second_brain_joplin/server.py:54-78]()、[README.md:1-30]() ```mermaid flowchart LR A[MCP 客户端
Claude Code / Cursor] -- stdio / MCP --> B[FastMCP 服务器
second-brain-joplin serve] B -- JoplinClient 单例 --> C[JoplinClient
base_url + token] C -- HTTP + token 查询参数 --> D[Joplin Web Clipper
localhost:41184] D --> E[(本地 Joplin 笔记)] ``` ## MCP 工具一览 下表汇总了 v0.1 中已经通过 `@mcp.tool()` 注册的 5 个工具。**所有工具都是存根**，直接返回带 issue 编号的占位字典，**不会**触达 `JoplinClient`： | 工具名称 | 用途 | 参数 | 是否写入 | 关联 Issue | |---|---|---|---|---| | `joplin_overview` | 列出全部笔记本及其笔记数量 | （无） | 否 | #5 | | `joplin_search` | 按关键字跨库搜索笔记 | `query: str` | 否 | #6 | | `joplin_read` | 按 ID 读取笔记完整内容 | `note_id: str` | 否 | #7 | | `joplin_recent` | 列出最近 N 天修改的笔记 | `days: int = 7` | 否 | #8 | | `joplin_create` | 在指定笔记本下创建笔记（计划为人工确认写入） | `title`, `body`, `notebook_id` | 是（human-gated） | #10 | 资料来源：[src/second_brain_joplin/server.py:25-49]()、[README.md:51-58]()、[CHANGELOG.md:30-37]() 每个工具的实现极其简短，例如： ```python @mcp.tool() async def joplin_search(query: str) -> dict: """Search notes by keyword across all notebooks.""" return {"status": "not implemented", "tool": "joplin_search", "issue": 6} ``` 工具签名（包括 docstring）将在 v0.2 里程碑实现时直接对接 `JoplinClient` 的对应方法。 ## JoplinClient 实现现状 `JoplinClient` 是一个基于 `httpx.AsyncClient` 的轻量包装器。构造时把传入的 `base_url` 去掉末尾 `/`，并把 `token` 作为查询参数保存（用于 `?token=...` 鉴权）。当前版本中唯一具有真实行为的接口是 `ping()`： - 调用 `GET {base_url}/ping`，超时 3 秒； - 当响应正文为字符串 `"JoplinClipperServer"` 时返回 `True`； - 捕获 `httpx.ConnectError` 并返回 `False`，避免在 Joplin 未运行时抛出未处理异常。 其余 5 个方法（`get_notebooks`、`get_note`、`search`、`get_recent`、`create_note`）目前都直接 `raise NotImplementedError`。注释明确说明：v0.1 的 MCP 工具会在到达这些方法之前短路返回占位响应，因此这些异常在实际运行中不会被触发。 资料来源：[src/second_brain_joplin/joplin_client.py:1-39]()、[CHANGELOG.md:30-37]() ## 配置、错误处理与后续里程碑 ### 环境变量与 `.env` 服务器通过 `python-dotenv` 加载 `.env`。必需/可选配置项如下： | 变量 | 必填 | 默认值 | 说明 | |---|---|---|---| | `JOPLIN_API_TOKEN` | 是（除 `--version` 外） | 空 | Joplin Web Clipper 设置面板中的令牌 | | `JOPLIN_BASE_URL` | 否 | `http://localhost:41184` | Joplin Web Clipper REST 端点 | 资料来源：[README.md:36-58]()、[src/second_brain_joplin/server.py:12-20]() ### CLI `build_parser()` 定义 `second-brain-joplin` 程序名，并提供： - `--version`：打印 `__version__`（当前 `0.1.0`）； - `serve` 子命令：调用 `mcp.run()` 启动 stdio 传输的 MCP 服务器； - 无子命令时打印帮助。 资料来源：[src/second_brain_joplin/server.py:62-78]() ### 常见失败模式 1. **Joplin 未启动或 Web Clipper 未启用**：`ping()` 会捕获 `ConnectError` 并返回 `False`；调用任何已实现工具时，连接将超时或失败。需要在 Joplin 中开启 `Tools → Options → Web Clipper → Enable Web Clipper Service`。 2. **令牌缺失或错误**：`_get_client()` 会以空 token 构造客户端，请求会因为缺失 `?token=` 而被 Joplin 拒绝。 3. **调用未实现的工具**：在 v0.1 中这是预期行为，工具会返回 `{"status": "not implemented", ...}`；若绕过 MCP 工具直接调用 `JoplinClient.get_note()` 等，会得到 `NotImplementedError`。 资料来源：[src/second_brain_joplin/joplin_client.py:14-25]()、[src/second_brain_joplin/server.py:25-49]()、[README.md:36-58]() ### 后续里程碑 根据 README 与 CHANGELOG 的路线图： - **v0.2**：实现 4 个读取类工具（`joplin_overview`、`joplin_search`、`joplin_read`、`joplin_recent`）和对应 `JoplinClient` 方法； - **v0.3**：基于 `bge-m3` 与向量索引（如 ChromaDB / FAISS）实现 `joplin_semantic_search`； - **v0.4**：实现 `joplin_create`，并加入人工确认（human-in-the-loop）门控； - **v1.0**：通过 OIDC 受信任发布把包推送至 PyPI，补全文档与 PARA 笔记模板。 资料来源：[README.md:67-75]()、[CHANGELOG.md:1-23]()、[SECURITY.md:13-21]() ## 参见 - README — 项目整体说明与快速开始 - CHANGELOG — 版本变更与路线图 - CONTRIBUTING — 开发流程与 CI 闸门 - SECURITY — 数据本地化与最小权限原则 --- ## Development Workflow, CI/CD & Release ### 相关页面 相关主题：[Overview & System Architecture](#page-1), [MCP Tools & JoplinClient Implementation](#page-2)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/jomkz/second-brain-joplin/blob/main/README.md) - [CHANGELOG.md](https://github.com/jomkz/second-brain-joplin/blob/main/CHANGELOG.md) - [CONTRIBUTING.md](https://github.com/jomkz/second-brain-joplin/blob/main/CONTRIBUTING.md) - [SECURITY.md](https://github.com/jomkz/second-brain-joplin/blob/main/SECURITY.md) - [src/second_brain_joplin/__init__.py](https://github.com/jomkz/second-brain-joplin/blob/main/src/second_brain_joplin/__init__.py) - [src/second_brain_joplin/server.py](https://github.com/jomkz/second-brain-joplin/blob/main/src/second_brain_joplin/server.py) - [src/second_brain_joplin/joplin_client.py](https://github.com/jomkz/second-brain-joplin/blob/main/src/second_brain_joplin/joplin_client.py)
# 开发工作流、CI/CD 与发布 本页面介绍 `second-brain-joplin` 项目面向贡献者的本地开发工作流、CI/CD 流水线设计以及经由 PyPI 的发布链路。读者将了解从 `uv` 安装、`pre-commit` 门禁、`mypy` 静态检查、测试覆盖率门槛,到「可复用 `checks` 工作流」再到 OIDC trusted publisher 全链路的工程化策略。 ## 本地开发工作流 ### 工具链与依赖锁 项目以 [uv](https://docs.astral.sh/uv/) 为统一工具链,通过 `pyproject.toml` 与 `uv.lock` 锁定依赖。推荐的标准克隆与同步流程如下,提交前还要安装 `pre-commit` 钩子,以保证本地与 CI 行为完全一致: ```bash git clone https://github.com/jomkz/second-brain-joplin cd second-brain-joplin uv sync uv run pre-commit install ``` 在不便使用 `uv` 的环境,文档同时给出了 `pip` + `venv` 的回退方案(`pip install -e ".[test]"`)。资料来源:[CONTRIBUTING.md:L1-L20]()。 ### 代码规范、静态检查与测试 工程上把 lint / format 的单一真实源放在 `.pre-commit-config.yaml`,CI 直接执行 `uvx pre-commit run --all-files`,从而避免「本地 ruff 版本 vs 远端 ruff 版本」的漂移。 ```bash uvx pre-commit run --all-files # ruff lint + format uv run mypy src # 静态类型检查 uv run pytest # 运行测试(打印覆盖率) ``` 关键的两点约定值得注意: 1. **覆盖率门槛只在 CI 强制。** 90% 的 `--cov-fail-under=90` 从 `addopts` 中移出,放进 CI 命令,这样本地跑部分测试不会因为未覆盖而误报失败。资料来源:[CONTRIBUTING.md:L21-L36]()。 2. **mypy 采用务实基线。** 在 `pyproject.toml` 中仅启用 `ignore_missing_imports = true`、`warn_unused_ignores`、`warn_redundant_casts`,作用域限制在 `src`,这是因为 FastMCP 的 `@mcp.tool()` 装饰器没有类型标注,直接 `strict = true` 会立刻报错。社区正在推进 [issue #19](https://github.com/jomkz/second-brain-joplin/issues/19),计划逐步收紧并覆盖 `tests/`。 测试栈使用 `pytest + respx`(后者用来 mock `httpx` 异步调用,例如 `JoplinClient.ping`)。资料来源:[src/second_brain_joplin/joplin_client.py:L11-L17]()。 ### 启动本地服务 ```bash cp .env.example .env # 编辑后填入 JOPLIN_API_TOKEN uv run second-brain-joplin serve ``` CLI 通过 `argparse` 暴露 `serve` 子命令与 `--version`,在 `main()` 中先调用 `load_dotenv()` 再解析参数。资料来源:[src/second_brain_joplin/server.py:L18-L36]()。 ## CI/CD 流水线 ### 重构后的可复用 `checks` 工作流 CI/CD 在 v0.1.0 之后被整体重组为单一可复用工作流 `.github/workflows/checks.yml`,集中包含 **lint**、**typecheck**、**test** 矩阵(3.11 / 3.12 / 3.13)与 **build**(`uv build` + `twine check` + wheel smoke test)。`ci.yml` 在 push/PR 触发并调用它,`release.yml` 在打 tag 后也复用同一套流程,做到**构建一次、测试一次、再发布**。资料来源:[CHANGELOG.md:L8-L26]()、`[CONTRIBUTING.md:L42-L52]()`。 ```mermaid flowchart LR PUSH[push/PR 到 main] TAG[v*.*.* tag] CI[ci.yml] RL[release.yml] CHK[checks.yml
可复用工作流] LINT[lint
pre-commit] TC[typecheck
mypy src] TEST[test 矩阵
3.11/3.12/3.13] BUILD[build
uv build + twine check + wheel smoke] PYPI[PyPI Trusted Publisher] PUSH --> CI --> CHK TAG --> RL --> CHK CHK --> LINT CHK --> TC CHK --> TEST CHK --> BUILD RL --> PYPI ``` ### 安全与并发控制 CI 显式设置了最小 `permissions`、并使用 `concurrency` 取消同一分支上的旧运行;安装方式升级为 `uv sync --locked`,一旦 `uv.lock` 漂移任务立即失败,使 PR 阶段就能拦截依赖不一致问题。资料来源:[CHANGELOG.md:L8-L26]()。 ### PR 标签自动化缺口 `.github/labeler.yml` 已经定义了 `component:*` 路径 globs,`docs/project-management.md` 与 `CONTRIBUTING.md` 都声明 PR 上的 `component:*` 标签应**自动应用**,但目前没有真正运行的 `actions/labeler` 工作流——这是社区跟踪中的 [issue #18](https://github.com/jomkz/second-brain-joplin/issues/18),被列入优先事项。 ## 发布流程 ### 版本与里程碑 包版本以 `__version__ = "0.1.0"` 声明在 `src/second_brain_joplin/__init__.py` 中,对应 README 中的 v0.1 Bootstrap 里程碑。后续目标依次为: v0.2(核心读工具,issues #5–#8)、v0.3(语义搜索,issue #9)、v0.4(人工把关写入,issue #10)、v1.0(PyPI & 完整文档,issue #11)。资料来源:[src/second_brain_joplin/__init__.py:L1-L3]()、`[README.md:L38-L48]()`。 ### Trusted Publisher 上 PyPI 发布走 [issue #12](https://github.com/jomkz/second-brain-joplin/issues/12) 的方案:不再走 TestPyPI,而是通过 OIDC trusted publisher 直接发布到 PyPI。`.github/workflows/release.yml` 在 `v*.*.*` tag 触发后调用 `checks.yml`,待所有闸门通过后用官方 `pypa/gh-action-pypi-publish` 上传 **同一份已校验的 artifact**,并启用 `skip-existing` 防止重复推送。这条路径已经经过 [issue #12](https://github.com/jomkz/second-brain-joplin/issues/12) 与 [issue #2](https://github.com/jomkz/second-brain-joplin/issues/2) 中提到的工作完整验证。资料来源:[CHANGELOG.md:L8-L26]()。 ### Changelog 规约 变更日志遵循 [Keep a Changelog](https://keepachangelog.com/) 与 SemVer,`Unreleased` 区段记录了「CI/CD 重组为可复用 `checks` 工作流」「静态类型检查入闸」「覆盖率门槛移出 `addopts`」等近期演进。资料来源:[CHANGELOG.md:L1-L40]()。 ## 提交、PR 与安全 - **Commit 风格**:简短的祈使句,可选用 `git commit -s` 加 DCO sign-off(暂不强制)。资料来源:[CONTRIBUTING.md:L68-L88]()。 - **PR 规约**:目标分支 `main`,每次 PR 只做一个逻辑改动并附测试,CI 全绿方可合并。资料来源:[CONTRIBUTING.md:L68-L88]()。 - **安全策略**:可疑漏洞通过 GitHub Security Advisories 私下提交。服务器只与 `localhost` 的 Joplin Web Clipper 通信,从不把笔记外发;v0.1 不做任何静默写入,v0.4 计划显式人工确认后再创建笔记。资料来源:[SECURITY.md:L1-L25]()。 ## See Also - [README.md](https://github.com/jomkz/second-brain-joplin/blob/main/README.md) — 项目总览与里程碑 - [CONTRIBUTING.md](https://github.com/jomkz/second-brain-joplin/blob/main/CONTRIBUTING.md) — 开发与提交细节 - [CHANGELOG.md](https://github.com/jomkz/second-brain-joplin/blob/main/CHANGELOG.md) — 版本变更 - [SECURITY.md](https://github.com/jomkz/second-brain-joplin/blob/main/SECURITY.md) — 漏洞与数据处理 - 社区议题:#2 搭建 CI、#12 PyPI trusted publish、#18 PR labeler 自动化、#19 mypy 走向 strict --- ## Configuration, Security, Privacy & Roadmap ### 相关页面 相关主题：[Overview & System Architecture](#page-1), [MCP Tools & JoplinClient Implementation](#page-2), [Development Workflow, CI/CD & Release](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/jomkz/second-brain-joplin/blob/main/README.md) - [SECURITY.md](https://github.com/jomkz/second-brain-joplin/blob/main/SECURITY.md) - [CHANGELOG.md](https://github.com/jomkz/second-brain-joplin/blob/main/CHANGELOG.md) - [CONTRIBUTING.md](https://github.com/jomkz/second-brain-joplin/blob/main/CONTRIBUTING.md) - [src/second_brain_joplin/server.py](https://github.com/jomkz/second-brain-joplin/blob/main/src/second_brain_joplin/server.py) - [src/second_brain_joplin/joplin_client.py](https://github.com/jomkz/second-brain-joplin/blob/main/src/second_brain_joplin/joplin_client.py) - [src/second_brain_joplin/__init__.py](https://github.com/jomkz/second-brain-joplin/blob/main/src/second_brain_joplin/__init__.py)
# 配置、安全、隐私与路线图 本页汇总 `second-brain-joplin` 项目的运行时配置、安全模型、隐私边界以及公开的版本路线图，便于使用者评估部署风险并规划集成时序。 ## 1. 运行时配置 服务器在 `main()` 中调用 `load_dotenv()` 自动加载 `.env` 文件，再通过惰性初始化的 `_get_client()` 从环境变量读取运行时参数并构造单例 `JoplinClient` `资料来源：[src/second_brain_joplin/server.py:30-37]()`。两个核心环境变量为：`JOPLIN_API_TOKEN`（必填，Joplin Web Clipper 鉴权令牌）与 `JOPLIN_BASE_URL`（默认 `http://localhost:41184`，Web Clipper REST API 本地地址）`资料来源：[src/second_brain_joplin/server.py:24-28]()`。 命令行入口 `second-brain-joplin` 由 `build_parser()` 定义，暴露 `serve` 子命令与 `--version` 标志；版本字符串 `0.1.0` 由 `__version__` 常量提供 `资料来源：[src/second_brain_joplin/__init__.py:3-4]()` `资料来源：[src/second_brain_joplin/server.py:55-65]()`。Claude Code 注册示例： ```bash claude mcp add -s user second-brain-joplin \ -e JOPLIN_API_TOKEN=your-token-here \ -- uvx second-brain-joplin serve ``` 本地开发可通过 `cp .env.example .env` 复制模板后填入真实令牌，再运行 `uv run second-brain-joplin serve` `资料来源：[CONTRIBUTING.md:36-44]()`。 ## 2. 安全与隐私 服务器遵循"本地优先、最小特权、显式写入"四项原则 `资料来源：[SECURITY.md:11-29]()`： - **本地 API**：仅与 `localhost` 上的 Joplin Web Clipper REST API 通信，笔记不会外发到任何第三方服务。 - **本地运行**：MCP 服务器由客户端在本机启动；Joplin 令牌仅从环境变量读取，严禁提交到版本控制。 - **最小特权**：MCP 客户端可读即 AI 可读——应避免在笔记中保存凭证、受监管数据或他人隐私，并按需划分笔记本。 - **无静默写入**：v0.1 全部工具均为只读桩；v0.4 的笔记创建将被设计为显式人工门控（human-gated）流程，AI 不会在无确认情况下写入。 漏洞披露请通过 GitHub Security Advisories 私下提交，而非公开 issue `资料来源：[SECURITY.md:5-7]()`。 ## 3. 路线图与版本 公开里程碑涵盖从骨架到 v1.0 发布的完整路径 `资料来源：[README.md:78-87]()`： | 里程碑 | 主题 | 状态 | 关键交付 | |---|---|---|---| | v0.1 — Bootstrap | 仓库、CI、包骨架 | 已完成 | FastMCP 包骨架、stub 工具、`JoplinClient.ping()`、uv 工具链、pytest + 90% 覆盖率门控 | | v0.2 — Core Read Tools | 全部只读 MCP 工具 | 计划中 | `joplin_overview` / `_search` / `_read` / `_recent` 真实实现（issue #5–#8） | | v0.3 — Semantic Search | 嵌入索引与语义检索 | 计划中 | 嵌入模型、本地向量索引（ChromaDB 或 FAISS）、增量同步（issue #9） | | v0.4 — Write Workflow | 人工门控写入 | 计划中 | `joplin_create` 实现、人机确认机制、笔记本选择（issue #10） | | v1.0 — Publish | 发布到 PyPI | 计划中 | OIDC trusted publisher、完整文档、PARA 笔记模板、`uvx` 体验（issue #11、#12） | v0.1 已交付的核心改动包括 CLI 入口、五大 stub 工具（`joplin_overview`、`joplin_search`、`joplin_read`、`joplin_recent`、`joplin_create`）、`JoplinClient.ping()`、`.env` 支持、pytest + respx 测试套件以及 90% 覆盖率门控 `资料来源：[CHANGELOG.md:37-51]()`。`Unreleased` 段进一步将 lint/typecheck/测试矩阵/打包构建收敛到可复用的 `.github/workflows/checks.yml`，并新增 `mypy` 静态类型检查门控 `资料来源：[CHANGELOG.md:5-19]()`。 ## 4. 部署注意事项 - **令牌管理**：`.env` 必须加入 `.gitignore`；CI 与 PyPI 发布均经 OIDC trusted publisher 完成，流程中不接触用户令牌 `资料来源：[README.md:64-67]()`。 - **依赖 Joplin 运行**：与 Obsidian 版（`second-brain-mcp`）不同，本服务依赖 Joplin Desktop 与 Web Clipper 服务持续在线 `资料来源：[README.md:70-77]()`。 - **健康探测**：`JoplinClient.ping()` 命中 `/ping`，返回 `JoplinClipperServer` 即视为可用；若 `httpx.ConnectError` 触发则返回 `False` `资料来源：[src/second_brain_joplin/joplin_client.py:14-22]()`。 ## See Also / 参见 - [README.md](https://github.com/jomkz/second-brain-joplin/blob/main/README.md) — 项目总览与快速开始 - [docs/install.md](https://github.com/jomkz/second-brain-joplin/blob/main/docs/install.md) — 各 MCP 客户端安装指南 - [docs/project-management.md](https://github.com/jomkz/second-brain-joplin/blob/main/docs/project-management.md) — 里程碑与标签体系 - [docs/notebook-structure.md](https://github.com/jomkz/second-brain-joplin/blob/main/docs/notebook-structure.md) — PARA 笔记本推荐结构 - 相关 GitHub issue：[#5 joplin_overview](https://github.com/jomkz/second-brain-joplin/issues/5)、[#10 Human-gated note creation](https://github.com/jomkz/second-brain-joplin/issues/10)、[#11 PyPI publish](https://github.com/jomkz/second-brain-joplin/issues/11)、[#12 Trusted publisher](https://github.com/jomkz/second-brain-joplin/issues/12) --- --- ## Doramagic 踩坑日志 项目：jomkz/second-brain-joplin 摘要：发现 32 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安全/权限坑 - 失败模式：security_permissions: Add PR labeler workflow (actions/labeler)。 ## 1. 安全/权限坑 · 失败模式：security_permissions: Add PR labeler workflow (actions/labeler) - 严重度：high - 证据强度：source_linked - 发现：Developers should check this security_permissions risk before relying on the project: Add PR labeler workflow (actions/labeler) - 对用户的影响：Developers may expose sensitive permissions or credentials: Add PR labeler workflow (actions/labeler) - 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/18 | Add PR labeler workflow (actions/labeler) ## 2. 安全/权限坑 · 失败模式：security_permissions: Set up CI pipeline (lint + test matrix) - 严重度：high - 证据强度：source_linked - 发现：Developers should check this security_permissions risk before relying on the project: Set up CI pipeline (lint + test matrix) - 对用户的影响：Developers may expose sensitive permissions or credentials: Set up CI pipeline (lint + test matrix) - 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/2 | Set up CI pipeline (lint + test matrix) ## 3. 安装坑 · 失败模式：installation: Bootstrap second-brain-joplin (v0.1) - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: Bootstrap second-brain-joplin (v0.1) - 对用户的影响：Developers may fail before the first successful local run: Bootstrap second-brain-joplin (v0.1) - 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/1 | Bootstrap second-brain-joplin (v0.1) ## 4. 安装坑 · 来源证据：Bootstrap second-brain-joplin (v0.1) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bootstrap second-brain-joplin (v0.1) - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/jomkz/second-brain-joplin/issues/1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 5. 安装坑 · 来源证据：Semantic search via embedding index (v0.3) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Semantic search via embedding index (v0.3) - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/jomkz/second-brain-joplin/issues/9 | 来源类型 github_issue 暴露的待验证使用条件。 ## 6. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 证据：capability.host_targets | https://github.com/jomkz/second-brain-joplin | host_targets=mcp_host, claude_code, claude, cursor ## 7. 配置坑 · 失败模式：configuration: Implement core read MCP tools (v0.2) - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: Implement core read MCP tools (v0.2) - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Implement core read MCP tools (v0.2) - 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/4 | Implement core read MCP tools (v0.2) ## 8. 配置坑 · 失败模式：configuration: Implement package skeleton and stubbed MCP server - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: Implement package skeleton and stubbed MCP server - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Implement package skeleton and stubbed MCP server - 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/3 | Implement package skeleton and stubbed MCP server ## 9. 配置坑 · 失败模式：configuration: PyPI publish, full docs, and Joplin templates (v1.0) - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: PyPI publish, full docs, and Joplin templates (v1.0) - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: PyPI publish, full docs, and Joplin templates (v1.0) - 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/11 | PyPI publish, full docs, and Joplin templates (v1.0) ## 10. 配置坑 · 来源证据：Tighten mypy toward strict and cover tests/ - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Tighten mypy toward strict and cover tests/ - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/jomkz/second-brain-joplin/issues/19 | 来源类型 github_issue 暴露的待验证使用条件。 ## 11. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/jomkz/second-brain-joplin | README/documentation is current enough for a first validation pass. ## 12. 运行坑 · 来源证据：Implement joplin_read tool - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Implement joplin_read tool - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/jomkz/second-brain-joplin/issues/7 | 来源类型 github_issue 暴露的待验证使用条件。 ## 13. 运行坑 · 来源证据：Implement joplin_search tool - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Implement joplin_search tool - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/jomkz/second-brain-joplin/issues/6 | 来源类型 github_issue 暴露的待验证使用条件。 ## 14. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/jomkz/second-brain-joplin | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/jomkz/second-brain-joplin | no_demo; severity=medium ## 16. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/jomkz/second-brain-joplin | no_demo; severity=medium ## 17. 安全/权限坑 · 来源证据：Add PR labeler workflow (actions/labeler) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add PR labeler workflow (actions/labeler) - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/jomkz/second-brain-joplin/issues/18 | 来源类型 github_issue 暴露的待验证使用条件。 ## 18. 安全/权限坑 · 来源证据：Implement core read MCP tools (v0.2) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Implement core read MCP tools (v0.2) - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/jomkz/second-brain-joplin/issues/4 | 来源类型 github_issue 暴露的待验证使用条件。 ## 19. 安全/权限坑 · 来源证据：Implement joplin_overview tool - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Implement joplin_overview tool - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/jomkz/second-brain-joplin/issues/5 | 来源类型 github_issue 暴露的待验证使用条件。 ## 20. 安全/权限坑 · 来源证据：Implement package skeleton and stubbed MCP server - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Implement package skeleton and stubbed MCP server - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/jomkz/second-brain-joplin/issues/3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 21. 安全/权限坑 · 来源证据：Publish package to PyPI (trusted publisher) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Publish package to PyPI (trusted publisher) - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/jomkz/second-brain-joplin/issues/12 | 来源类型 github_issue 暴露的待验证使用条件。 ## 22. 安全/权限坑 · 来源证据：Set up CI pipeline (lint + test matrix) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Set up CI pipeline (lint + test matrix) - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/jomkz/second-brain-joplin/issues/2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 23. 能力坑 · 失败模式：capability: Human-gated note creation (v0.4) - 严重度：low - 证据强度：source_linked - 发现：Developers should check this capability risk before relying on the project: Human-gated note creation (v0.4) - 对用户的影响：Developers may hit a documented source-backed failure mode: Human-gated note creation (v0.4) - 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/10 | Human-gated note creation (v0.4) ## 24. 能力坑 · 失败模式：capability: Implement joplin_overview tool - 严重度：low - 证据强度：source_linked - 发现：Developers should check this capability risk before relying on the project: Implement joplin_overview tool - 对用户的影响：Developers may hit a documented source-backed failure mode: Implement joplin_overview tool - 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/5 | Implement joplin_overview tool ## 25. 能力坑 · 失败模式：capability: Implement joplin_read tool - 严重度：low - 证据强度：source_linked - 发现：Developers should check this capability risk before relying on the project: Implement joplin_read tool - 对用户的影响：Developers may hit a documented source-backed failure mode: Implement joplin_read tool - 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/7 | Implement joplin_read tool ## 26. 能力坑 · 失败模式：capability: Implement joplin_recent tool - 严重度：low - 证据强度：source_linked - 发现：Developers should check this capability risk before relying on the project: Implement joplin_recent tool - 对用户的影响：Developers may hit a documented source-backed failure mode: Implement joplin_recent tool - 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/8 | Implement joplin_recent tool ## 27. 能力坑 · 失败模式：capability: Implement joplin_search tool - 严重度：low - 证据强度：source_linked - 发现：Developers should check this capability risk before relying on the project: Implement joplin_search tool - 对用户的影响：Developers may hit a documented source-backed failure mode: Implement joplin_search tool - 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/6 | Implement joplin_search tool ## 28. 能力坑 · 失败模式：capability: Semantic search via embedding index (v0.3) - 严重度：low - 证据强度：source_linked - 发现：Developers should check this capability risk before relying on the project: Semantic search via embedding index (v0.3) - 对用户的影响：Developers may hit a documented source-backed failure mode: Semantic search via embedding index (v0.3) - 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/9 | Semantic search via embedding index (v0.3) ## 29. 能力坑 · 失败模式：capability: Tighten mypy toward strict and cover tests/ - 严重度：low - 证据强度：source_linked - 发现：Developers should check this capability risk before relying on the project: Tighten mypy toward strict and cover tests/ - 对用户的影响：Developers may hit a documented source-backed failure mode: Tighten mypy toward strict and cover tests/ - 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/19 | Tighten mypy toward strict and cover tests/ ## 30. 能力坑 · 失败模式：conceptual: Publish package to PyPI (trusted publisher) - 严重度：low - 证据强度：source_linked - 发现：Developers should check this conceptual risk before relying on the project: Publish package to PyPI (trusted publisher) - 对用户的影响：Developers may hit a documented source-backed failure mode: Publish package to PyPI (trusted publisher) - 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/12 | Publish package to PyPI (trusted publisher) ## 31. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/jomkz/second-brain-joplin | issue_or_pr_quality=unknown ## 32. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/jomkz/second-brain-joplin | release_recency=unknown