Second Brain MCP Public

SecondBrainMCP

Swift中的本地MCP服务器，允许Claude Desktop对Markdown笔记库进行读/写访问，并对PDF参考库进行只读访问。每次注释编辑都会自动提交到git。

Claude Desktop  ─┐
                 ├── stdio ──> SecondBrainMCP
Claude Code CLI ─┘                |
                                  +── notes/       (Markdown, read/write, git tracked)
                                  +── references/  (PDFs, read-only)

重要提示： MCP服务器仅适用于 克劳德桌面 （macOS应用程序）和 克劳德代码 （CLI）。他们确实如此 不 在浏览器中使用claude.ai。

特性

• 17个MCP工具 --搜索、读取（单次和批量）、创建、更新、移动、删除笔记；搜索和阅读PDF；git历史和还原
• 4 MCP资源 --vault索引、最新笔记、标签摘要、参考文献索引
• Git自动提交 --每次写入都会创建一个commit [SecondBrainMCP] 前缀
• 软删除 --已删除的笔记移动到 .trash/，从未永久删除
• 全文搜索 --跨笔记和PDF搜索缓存的基于磁盘的grep
• 基于图像的PDF阅读 --每页双内容（提取文本+JPEG图像）、图书页面导航、PDF大纲/书签
• 只读模式 — --read-only 标志隐藏所有写入工具
• 路径安全 --符号链接解析、遍历预防、扩展allowlists
• 审计日志 --记录到的每个操作 .secondbrain-mcp/audit.log
• 与黑曜石、iA Writer、Logseq合作 --保险库是纯Markdown；应用程序配置目录被忽略
• 自定义指令 --放下一个 INSTRUCTIONS.md 在vault根目录中定义自己的约定

快速开始

# 1. Build
swift build -c release
# Binary is at .build/release/second-brain-mcp

# 2. Create a vault
./setup-vault.sh

# 3. Connect to Claude Desktop or Claude Code (see below)

# 4. Ask Claude: "What notes do I have?"

需求

• Swift 6.2
• macOS 26（Tahoe）
• Xcode 26

安装

git clone https://github.com/yourusername/SecondBrainMCP.git
cd SecondBrainMCP
swift build -c release

二进制文件位于 .build/release/second-brain-mcp。您可以在任何地方复制它：

cp .build/release/second-brain-mcp /usr/local/bin/

连接到克劳德

SecondBrainMCP与 克劳德桌面 （macOS应用程序）和 克劳德代码 （CLI）。确实如此 不 在浏览器中使用claude.ai。

选项A：克劳德桌面（macOS应用程序）

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "second-brain": {
      "command": "/absolute/path/to/.build/release/second-brain-mcp",
      "args": ["--vault", "/absolute/path/to/your/vault"]
    }
  }
}

保存后重新启动Claude Desktop （Cmd+Q，然后重新打开）。当Claude需要时，服务器会自动启动。通过询问Claude进行验证 *“你有什么工具？”* --您应该看到SecondBrainMCP工具。

选项B：克劳德代码（CLI）

claude mcp add second-brain -- \
  /absolute/path/to/.build/release/second-brain-mcp \
  --vault /absolute/path/to/your/vault

这将全局注册服务器。它立即以新的形式提供 claude 会话--无需重新启动。

要将其范围改为特定项目，请使用 -s project:

claude mcp add -s project second-brain -- \
  /absolute/path/to/.build/release/second-brain-mcp \
  --vault /absolute/path/to/your/vault

您也可以直接导入Claude Desktop配置：

claude mcp add-from-claude-desktop

通过以下方式进行验证：

claude mcp list

什么不起作用

• claude.ai （网站）-不支持MCP服务器
• 克劳德移动应用 --不支持MCP服务器
• 任何不是克劳德桌面或克劳德代码的克劳德界面

拱顶结构

~/SecondBrain/
├── notes/              ` | `info` | `debug`, `info`, `warning`, `error` |

## 工具

### 备注

|工具|说明|
|------|-------------|
| `read_note` |阅读笔记的全部内容|
| `read_notes` |一次通话最多可阅读20条笔记，并附有摘要索引和每条笔记的错误报告|
| `list_notes` |列出注释，按目录或标签筛选|
| `get_note_metadata` |标题、标签、字数、链接|
| `search_notes` |在所有笔记中进行全文grep搜索|
| `create_note` |使用自动生成的frontmatter创建|
| `update_note` |替换或附加模式|
| `move_note` |在notes/中移动/重命名注释，保留git历史记录|
| `move_notes` |以原子方式批量移动最多20个音符（全部或无）|
| `delete_note` |软删除到 `.trash/` |

### 参考文献（只读）

|工具|说明|
|------|-------------|
| `list_references` |列出所有带有元数据的PDF|
| `read_reference` |以文本+JPEG图像读取页面，具有页面/范围/查询/book_page模式|
| `search_references` |在所有PDF文件中进行全文搜索|
| `get_reference_metadata` |不读取内容的PDF元数据|

### Git历史记录

|工具|说明|
|------|-------------|
| `note_history` |提交特定笔记的历史记录|
| `revert_note` |恢复到以前的版本（新提交）|
| `vault_changelog` |vault中最近的更改|

## 资源

|URI|描述|
|-----|-------------|
| `secondbrain://index` |所有注释：路径、标题、标签|
| `secondbrain://recent` |过去7天内修改的注释|
| `secondbrain://tags` |所有带有笔记计数的标签|
| `secondbrain://references` |所有带有元数据的PDF|

## 自定义指令

丢一个 `INSTRUCTIONS.md` vault根目录中的文件，以定义AI在管理笔记时应遵循的约定。例如：

VAULT RULES:

1. Always create notes inside a container directory — never as loose files.
2. Every note must have YAML frontmatter with title, created date, and tags.
3. Ticket notes should start with the ticket ID.

服务器在启动过程中将文件内容附加到其默认指令中。如果文件不存在，则只发送内置默认值。无需重建——只需创建或编辑文件并重新启动MCP服务器。

## 安全

- **路径遍历预防** --通过验证的所有路径 `PathValidator` 具有符号链接分辨率
- **没有任意shell执行** --只有 `/usr/bin/git` 和 `/usr/bin/grep` 使用程序化参数数组
- **结构化写入边界** — `ReferenceManager` 设计上没有写方法
- **仅软删除** --文件永远不会被永久删除
- **提交邮件净化** --从git消息中删除shell元字符

## 文档

|文件|描述|
|------|-------------|
| [用法-通用.md](USAGE-GUIDE.md) |完整的使用指南、工具参考、第三方应用程序兼容性|
| [建筑几何.md](BUILD-GUIDE.md) |包含设计决策的分阶段构建日志|
| [SETUP-SCRIPT.md](SETUP-SCRIPT.md) |设置脚本文档和机器传输指南|
| [SecondBrainMCP-Speci.md](SecondBrainMCP-Spec.md) |项目规范（事实来源）|

## 建筑

Sources/SecondBrainMCP/ ├── main.swift # Entry point ├── Config/ServerConfig.swift # CLI args -> config ├── Server/MCPServerSetup.swift # Server init, all handlers ├── Core/ │ ├── PathValidator.swift # Path security (struct, static) │ ├── VaultManager.swift # Note I/O (actor) │ ├── ReferenceManager.swift # PDF ops, zero write methods (Sendable struct) │ ├── PDFPageRenderer.swift # PDF page JPEG rendering + outline extraction (struct, static) │ ├── PDFTextExtractor.swift # PDFKit text extraction + search (struct, static) │ ├── ReferenceCache.swift # Lightweight search cache (enum, pure namespace) │ ├── SearchEngine.swift # Disk-based grep search (Sendable struct) │ ├── GitManager.swift # Git via /usr/bin/git (actor) │ └── MarkdownParser.swift # YAML frontmatter (struct, static) └── Logging/AuditLogger.swift # Operation log (actor)

**并发模型：** 可变状态的参与者（VaultManager、GitManager、AuditLogger），无状态I/O的可发送结构（ReferenceManager、SearchEngine），纯逻辑的静态方法结构（PathValidator、PDFPageRenderer、PDFTextExtractor、MarkdownParser），缓存操作的枚举命名空间（ReferenceCache）。Swift 6.2严格并发——构造上没有数据竞争。

## 测试

swift test # Run all 92 tests swift test --filter PathValidatorTests # Run specific suite

|套件|测试|它涵盖了什么|
|-------|-------|----------------|
|PathValidator（4套）|24|遍历攻击、符号链接、边缘情况|
|GitManager |8|初始化、提交、日志、清理|
|MarkdownParser（4套）|16|前端、链接、生成|
|VaultManager（2个套件）|28|读取、列表、过滤、元数据、移动、批量移动|
|SearchEngine | 16 |基于磁盘的grep、代码段生成、参考搜索|