basalt-mcp CLAUDE.md

CLAUDE.md

Project Overview

Basalt MCP is a security-hardened MCP server with two independent tool modules: Obsidian vault tools and git tools. The connected AI is treated as the attacker — see SECURITY.md for the full threat model.

Architecture

• src/core/ — Shared security framework (validation, vault path, repo path, error sanitization)
• src/tools/obsidian/ — Obsidian vault tool module (getAllFilenames, readMultipleFiles, getOpenTodos, updateFileContent, searchVault, appendToFile, listFiles)
• src/tools/git/ — Git tool module (gitStatus, gitLog, gitDiff, gitBlame) — read-only, no mutations
• src/index.ts — Server entrypoint, --vault/--repo flag parsing, conditional tool registration

The vault and repo are independent directories. The vault is a knowledge base (Obsidian markdown), the repo is a code repository (git). Either or both can be provided at startup.

CLI

node dist/index.js --vault <path> --repo <path>

At least one of --vault or --repo is required.

Commands

• npm run build — Compile TypeScript
• npm test — Run all tests (vitest)
• npm run test:watch — Watch mode
• npm run lint — Type-check without emitting
• npm run dev — Watch mode compilation

Recent Security Notes

• dist/ was rebuilt to match the hardened src/ tree. If you change security-sensitive code, run npm run build before relying on e2e results or publishing.
• getAllFilenames and listFiles now emit _meta.contentTrust: "untrusted" with filename-specific warnings. Filenames are attacker-controlled strings and must not be treated as trusted UI content.
• readMultipleFiles returns { found, notFound } in its envelope contract. Keep e2e expectations aligned with that shape.
• re2 is an active production dependency for searchVault ReDoS protection. If install/build issues recur, verify node_modules/re2 is present before debugging TypeScript.
• package.json uses overrides to pin patched transitive versions for @hono/node-server, express-rate-limit, hono, and tar. Do not remove these without re-running npm audit.
• Current verification baseline: npm run lint, npm run build, npm test, and npm audit --omit=dev.