basalt-mcp AGENTS.md

Basalt MCP — Agent Navigation

Security-hardened MCP server with Obsidian vault tools and git tools. The AI is treated as the attacker.

Quick Reference

• Full details: See CLAUDE.md for architecture, security rules, testing, and conventions
• Threat model: See SECURITY.md

1. Environment — Check Before Starting

• Repository state: git status, git stash list, git branch
• CI/PR state: gh run list --limit 5, gh pr list, gh pr view
• Recent history: git log --oneline -20
• Escalation: If CI is already failing on an unrelated issue, note it and proceed

2. Memory — Check Prior Knowledge

• Git memory: git log --oneline -- <file>, git blame -L <start>,<end> <file>
• QMD vault: Use QMD search and vector_search tools. QMD indexes ~/src/**/*.md
• ContextKeep: list_all_memories, retrieve_memory (when configured, skip if unavailable)
• Escalation: If Memory reveals a prior decision that contradicts the current task, surface to user

3. Task — Assemble Context for the Work

• Find code via codesight-mcp: search_symbols, get_symbol, get_callers, get_file_outline
• Read specific functions, not whole files
• Read the adversarial test file (tests/security/adversarial*.test.ts) for the tool you're modifying — it documents the attack surface
• Read SECURITY.md before touching any validation or path handling
• Check prior analysis: scan reports in docs/
• Don't pre-load — load incrementally

Structure

Area	Location	Purpose
Core	src/core/	Validation, vault/repo path, error sanitization
Obsidian	src/tools/obsidian/	7 vault tools (read, write, search, list, todos)
Git	src/tools/git/	4 read-only git tools (status, log, diff, blame)
Entry	src/index.ts	Server, flag parsing, conditional tool registration

Commands

npm run build                     # Compile TypeScript
npm test                          # Run all tests (vitest) — 341 tests
npm run lint                      # Type-check
npm audit --omit=dev              # Security audit