Basalt MCP Server

Basalt MCP

A security-hardened Model Context Protocol server with two independent tool modules: Obsidian vault tools for managing a knowledge base, and git tools for LLM-assisted code review. Built for adversarial environments where the connected AI cannot be trusted.

Tools

Obsidian Vault Tools (`--vault`)

Git Tools (`--repo`)

All git tools are read-only. No mutations (no commit, push, reset, checkout).

Quick Start

npm install
npm run build

Usage

# 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

At least one of --vault or --repo is required. The vault and repo are independent directories — the vault is a knowledge base (Obsidian), the repo is a code repository (git).

Claude Desktop

Add to ~/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

Add to .cursor/mcp.json in your project:

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

The server communicates over stdio using the MCP JSON-RPC protocol.

Security

The server treats every tool call as potentially hostile.

Vault tools — all filesystem access is sandboxed to the vault directory through multiple independent layers:

• 9-step write validation chain — null bytes, dot-paths, extension allowlist, path limits, vault containment, symlinked parent walk, atomic O_NOFOLLOW write
• Extension allowlist — only .md and .canvas (native Obsidian formats)
• 3-layer symlink defense — glob-level exclusion, parent directory walk, kernel-level O_NOFOLLOW
• Error sanitization — never leaks system paths or OS details
• Untrusted-content metadata — filenames, file content, todos, search results, and git output are marked untrusted for MCP clients
• Resource limits — 10 MB read cap, 1 MB write cap, 50 filenames per request, 5 partial match results, 20 search match cap

Git tools — all git execution is sandboxed to the repo directory:

• execFileSync only — no shell, no command injection possible
• Ref name allowlist — rejects shell metacharacters, backticks, $(), pipes, semicolons
• Path validation — blame file paths go through null byte check, repo containment, and symlink walk
• Output sanitization — repo path stripped from all output, 100KB output cap, 10s timeout

See SECURITY.md for the full threat model, design rationale, and all 118 tested attack vectors.

Development

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

Project Structure

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 m