Obsidian GitHub MCP

Obsidian GitHub MCP

一个白标 Model Context Protocol 服务，为指定的 AI Agent 提供受限且可审计的访问权限，使其能够提议修改存储在 GitHub 中的 Obsidian 知识库。

每个 Agent 都会获得独立且会过期的 MCP bearer token。GitHub 凭据保留在服务端。读写路径、拒绝规则、受保护区域、提案分支和令牌吊销均由运营方管理的 YAML 文件控制。

这是一个独立的开源项目，与 Obsidian 或 GitHub 无关联，也未获其认可。

为什么使用它？

为 Agent 提供通用 GitHub 令牌很难加以限制，也容易被滥用。此服务建立了更严格的边界：

AI agent + individual MCP token
        |
        v
identity + fixed broker
        |
        v
agent write scope AND broker publication scope
        |
        v
deny, path, frontmatter, mutability, size, and secret checks
        |
        v
server-side GitHub App token
        |
        v
proposal branch for human review

此服务不提供删除文件、合并分支、推送到 main 或 master、更改仓库设置、编辑工作流或泄露凭据的工具。

功能

• 无状态 MCP Streamable HTTP 传输
• 独立且会过期的 bearer token，以 SHA-256 绑定形式存储
• 按 Agent 设置读取、写入和拒绝路径 glob
• 独立的 Git 中介允许列表和固定提案分支
• 可为共享或敏感区域配置 frontmatter 要求
• living、review-first、append-only 和 immutable 笔记处理方式
• 防止路径遍历，并允许指定文件扩展名和大小
• 检测类似凭据的内容
• 仓库范围受限的 GitHub App 令牌；本地测试可回退使用 PAT
• 不包含内容的 JSONL 审计记录
• 主机／来源验证、安全标头、速率限制和 HTTP 超时
• Docker、CI、测试和部署文档

MCP 工具

工具	用途
vault_whoami	显示经过身份验证的身份、中介、分支和策略范围。
vault_list_allowed_paths	说明实际生效的读取／写入／拒绝边界。
vault_explain_access	对单一路径执行试运行，报告是否允许读取、列出或写入，以及由哪条策略规则决定。不调用 GitHub。
vault_list_files	列出已授权目录，同时过滤被拒绝的子项。
vault_read_file	读取已授权的 UTF-8 知识库文件。
vault_create_file	在该身份固定的提案分支上创建文件。
vault_update_file	在遵守可变性规则的前提下更新允许修改的文件。
vault_append_file	追加内容，同时保留所有现有字节。

要求

• Node.js 22+
• 位于 GitHub 仓库中的 Obsidian 知识库
• 为每个中介设置专用的非默认提案分支
• 仅安装在知识库仓库中的 GitHub App，并授予 Contents: read and write 权限；或使用 fine-grained PAT 进行本地测试

快速开始

从源码安装（当前支持的方式）：

git clone https://github.com/YOUR_ACCOUNT/obsidian-github-mcp.git
cd obsidian-github-mcp
npm ci
cp .env.example .env
cp config/policy.example.yaml config/policy.yaml
cp config/tokens.example.yaml config/tokens.yaml
npm run token:new
npm run check
# Configure .env with your GitHub repository and token/app credentials before starting:
npm start

配置 .env（指定仓库以及 GITHUB_TOKEN 或 GitHub App 凭据），替换示例策略，并仅将生成的令牌的 SHA-256 值放入 config/tokens.yaml。将原始 bearer token 仅提供给一个 MCP 客户端。

配置运行中的服务之前，可先检查检出内容：

npm ci
npm run check
npm run test:e2e

这些检查使用合成笔记、模拟 GitHub 响应和环回传输。 无需 GitHub 或 MCP 凭据。回归测试涵盖 Unicode／路径编码、CRLF frontmatter、格式错误的元数据、UTF-8 大小限制，以及仅追加时的字节保留。CI 使用 Node.js 22 和 24，在 Linux 与 Windows 上运行相同的检查。上面列出的 8 个工具构成当前服务接口；测试不会将提案发布到真实知识库。

v0.1.0 发布到 npm 后，也可进行全局安装：

# Available once v0.1.0 is published (not yet on the npm registry).
npm install -g @sarutobi-sasuke/obsidian-github-mcp

默认端点为：

GET  http://127.0.0.1:3210/healthz
POST http://127.0.0.1:3210/mcp

MCP 客户端必须发送：

Authorization: Bearer vault_<generated-token>

权限模型

实际生效的写入范围是 Agent 授权与其中介权限的交集：

policy_version: 1
authority: operator-only

agents:
  - id: example-writer
    name: Example Writer
    role: bounded knowledge worker
    disclosure_ceiling: internal
    entry_reads: [README.md]
    read: [Knowledge/**, Workspace/**]
    write: [Workspace/Shared/**, Workspace/Example Writer/**]
    deny: [Private/**, People/**, .obsidian/**]

git_brokers:
  - broker: example-writer
    branch: agent/example-writer
    allow: [Workspace/Shared/**, Workspace/Example Writer/**]

never_versioned: [Private/**, People/**, .obsidian/**, secrets/**]

surface_rules:
  - path: Workspace/Shared/**
    required_frontmatter:
      disclosure: public-safe

随后，身份验证绑定会将一个令牌哈希映射到该身份和中介。此绑定无法授予策略未授权的路径。

有关配置和吊销的说明，请参阅权限文档。

GitHub 身份验证

生产部署应使用仅安装在 vault 仓库上的 GitHub App。配置：

GITHUB_APP_ID=123456
GITHUB_APP_INSTALLATION_ID=12345678
GITHUB_APP_PRIVATE_KEY_FILE=/run/secrets/vault-mcp.pem

服务会创建有效期较短的安装令牌，并再次将其限制为配置的仓库和 contents: write。也支持使用限定仓库范围的 GITHUB_TOKEN 作为本地开发的备用方案。

部署

随附的容器以非 root 用户身份运行，根文件系统为只读。在让服务可通过远程访问之前，请在其前方配置 TLS、私有覆盖网络或经过身份验证的网关。

请参阅部署指南。

验证

npm run check
npm audit --audit-level=high

测试涵盖策略解析、写入范围交集、拒绝优先级、路径遍历尝试、frontmatter 规则、可变性、密钥检测、令牌绑定，以及固定分支上的 GitHub 写入。

运行 npm run test:e2e，通过仅用于测试的 GitHub 替代服务，验证干净 tarball 安装和真实 MCP HTTP 客户端。测试会覆盖提案写入、被拒绝的路径/内容、不可变和仅追加笔记、过时写入冲突、无效策略重新加载、实时令牌撤销，以及不含内容的审计记录。CI 会在运行 Node 22/24 的 Windows/Linux 上执行此验证，发布工作流也要求通过该验证。

策略和令牌文件会拒绝未知键。目前仅支持 policy_version: 1 和 authority: operator-only。升级前请修正拼写错误的字段，或移除不受支持的元数据；不再接受被静默忽略的限制。发布证据和剩余门槛。

MCP Registry npm 条目的草案描述的是一个可自托管的 Streamable HTTP 进程，而不是 stdio 服务。兼容的客户端会使用已声明的环境变量启动该进程，并连接到 http://127.0.0.1:{VAULT_MCP_PORT}/mcp（默认端口为 3210）。请提供现有的策略和令牌文件路径，以及仓库所有者/名称。要访问 GitHub，请使用 GITHUB_TOKEN，或全部三个已说明的 GitHub App 变量。清单无法表达这一可选变量组；运行时配置会对其进行验证。该进程不会创建凭据、配置托管端点，也不会绕过现有的持有者令牌检查。命名空间会保留 GitHub 所有者名称的原始拼写。prepublishOnly 包含注册表/软件包门槛；它不会执行登录或发布。

安全

部署前请阅读安全策略。如怀疑存在漏洞，请私下报告，不要在公开问题中提供漏洞利用细节。

许可证

Apache-2.0。请参阅 Apache-2.0 许可证。