mcpvault: Instructions file for Codex

Agent Instructions

Project Overview

MCPVault is a Model Context Protocol (MCP) server that provides a universal AI bridge for Obsidian vaults. It enables any MCP-compatible AI assistant (Claude, ChatGPT, Gemini, etc.) to safely read and write notes in Obsidian vaults while preserving YAML frontmatter and enforcing security boundaries.

Commands

# MCP server
npm run build          # Compile TypeScript to dist/
npm test               # Run test suite (Vitest)
npm run test:watch     # Tests in watch mode
npm start /path/vault  # Run server locally with tsx

# Single test
npm test -- path/to/test.test.ts
npm test -- -t "test name pattern"

# Publishing
npm run publish:dry     # Dry run
npm run publish:beta    # Explicit beta publish
# Production: follow RELEASING.md and create a GitHub Release

# Website
npm run website         # Start Astro dev server with Bun (http://localhost:4321)

# MCP Inspector
npx @modelcontextprotocol/inspector npm start /path/to/vault

Architecture

File Structure

server.ts              # MCP server entry point, tool registration, request handlers
src/
  filesystem.ts        # FileSystemService — all file operations with security
  frontmatter.ts       # FrontmatterHandler — YAML parsing via gray-matter
  pathfilter.ts        # PathFilter — security layer for path validation
  search.ts            # SearchService — full-text search with token-optimized output
  uri.ts               # Obsidian URI generation
  types.ts             # All TypeScript interfaces
  *.test.ts            # Co-located test files
website-shibumi/       # Bun + Hono + TSX website serving mcpvault.org (separate package)

Core Components

server.ts — Entry point. Registers 18 MCP tools, handles CLI args (--help, --version, --read-only, vault path), initializes services, routes tool calls. Read-only mode hides mutating tools and rejects direct mutation calls. Auto-trims whitespace from all path arguments. Exits on stdin EOF / SIGTERM / SIGINT (graceful server.close()), otherwise hosts orphan the process (#159).