mcp-markdown-vault: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Headless, Dockerized TypeScript MCP (Model Context Protocol) server for markdown-based knowledge bases (Obsidian, Logseq, Dendron, Foam, or any folder of .md files). Provides semantic search, AST-based note editing, and workflow state tracking via stdio or SSE transport.

Development Commands

# Install dependencies
npm install

# Build (compiles to dist/, excludes test files)
npm run build

# Run all tests (318 tests across 31 files)
npm test

# Run a single test file
npx vitest run src/domain/errors/domain-errors.test.ts

# Run tests in watch mode
npm run test:watch

# Lint (type-check without emitting)
npm run lint

# Docker (uses pre-built image from ghcr.io)
docker compose up

Architecture

Clean Architecture with four layers:

• src/domain/ — Domain errors, port interfaces (IFileSystemAdapter, IEmbeddingProvider, IVectorStore, IMarkdownRepository, IDiffService, ITemplateEngine), value objects (SafePath)
• src/use-cases/ — Business logic: AST parsing/patching, chunking, scoring, retrieval, hybrid search, read-by-heading, bulk-read, frontmatter management, update-file, dry-run edit, create-from-template, workflow state, hints, fuzzy matching, wikilink resolution, vault indexing
• src/infrastructure/ — Adapters: LocalFileSystemAdapter (fs/promises), OllamaEmbeddingProvider (REST), TransformersEmbeddingProvider (local @huggingface/transformers), InMemoryVectorStore (cosine similarity), MarkdownFileRepository (AST + frontmatter from file), UnifiedDiffService (unified diff via diff package), RegexTemplateEngine ({{key}} placeholder replacement)
• src/presentation/ — 5 MCP tool bindings (createMcpServer()), transport layer (transport.ts: stdio/SSE selection, Express SSE app)

Entry point: src/index.ts — composition root, reads env vars, wires dependencies, selects transport.