Basalt MCP

玄武岩MCP

加强安保 模型上下文协议 具有两个独立工具模块的服务器： 黑曜石保险库工具 用于管理知识库，以及 git工具 用于LLM辅助代码审查。专为无法信任连接的AI的对抗环境而构建。

工具

黑曜石保险库工具(--vault)

Git工具(--repo)

所有git工具都是只读的。无突变（无提交、推送、重置、签出）。

快速开始

npm install
npm run build

用法

# Both modules — vault for context, repo for code review
node dist/index.js --vault /path/to/vault --repo /path/to/repo

# Vault only
node dist/index.js --vault /path/to/vault

# Repo only
node dist/index.js --repo /path/to/repo

至少一个 --vault 或 --repo 是必需的。vault和repo是独立的目录——vault是一个知识库（Obsidian），repo是一个代码库（git）。

克劳德桌面版

添加 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "basalt": {
      "command": "node",
      "args": [
        "/absolute/path/to/basalt-mcp/dist/index.js",
        "--vault", "/path/to/your/vault",
        "--repo", "/path/to/your/repo"
      ]
    }
  }
}

光标

添加 .cursor/mcp.json 在您的项目中：

{
  "mcpServers": {
    "basalt": {
      "command": "node",
      "args": [
        "/absolute/path/to/basalt-mcp/dist/index.js",
        "--vault", "/path/to/your/vault",
        "--repo", "/path/to/your/repo"
      ]
    }
  }
}

服务器使用MCP JSON-RPC协议通过stdio进行通信。

安全

服务器将每个工具调用都视为潜在的恶意调用。

Vault工具 --所有文件系统访问都通过多个独立层沙盒化到vault目录：

• 9步写入验证链 --空字节、点路径、扩展允许列表、路径限制、vault包含、符号链接父级遍历、原子 O_NOFOLLOW 写
• 扩展allowlist --只有 .md 和 .canvas （原生黑曜石格式）
• 三层符号链防御 --全局级排除、父目录遍历、内核级 O_NOFOLLOW
• 错误清理 --永不泄露系统路径或操作系统详细信息
• 不受信任的内容元数据 --文件名、文件内容、待办事项、搜索结果和git输出被标记为MCP客户端不信任
• 资源限制 --10 MB读取上限，1 MB写入上限，每个请求50个文件名，5个部分匹配结果，20个搜索匹配上限

Git工具 --所有git执行都被沙盒到repo目录中：

• execFileSync 仅 --没有shell，无法进行命令注入
• 参考名称列表 --拒绝shell元字符、回溯符、， $()，管道，分号
• 路径验证 --非责任文件路径要经过空字节检查、repo包含和符号链接遍历
• 输出净化 --从所有输出中剥离repo路径，100KB输出上限，10秒超时

看 安全.md 对于完整的威胁模型、设计原理和所有118个测试的攻击向量。

发展

npm test            # run all 341 tests
npm run test:watch  # watch mode
npm run lint        # type-check without emitting
npm run dev         # watch mode compilation

项目结构

src/
├── index.ts                    Server entrypoint (--vault/--repo flags, stdio transport)
├── core/                       Shared security framework
│   ├── validation.ts           Assertion functions (7)
│   ├── vault.ts                Immutable vault path management
│   ├── repo.ts                 Immutable repo path management + git validation
│   ├── contentBoundary.ts      Boundary markers for untrusted content (spotlighting)
│   └── errors.ts               Error sanitization
└── tools/
    ├── obsidian/               Obsidian vault tool module
    │   ├── getAllFilenames.ts
    │   ├── readMultipleFiles.ts
    │   ├── getOpenTodos.ts
    │   ├── updateFileContent.ts
    │   ├── searchVault.ts
    │   ├── appendToFile.ts
    │   └── listFiles.ts
    └── git/                    Git tool module
        ├── exec.ts             Safe git execution helper
        ├── gitStatus.ts
        ├── gitLog.ts
        ├── gitDiff.ts
        └── gitBlame.ts

该架构将安全核心与工具实现分离。核心处理验证、沙盒和错误清理。工具模块插入核心并继承所有保护。这两个模块是独立的，您可以运行其中之一或两者。

许可证

麻省理工学院