with-context-mcp AGENTS.md

Agent Guidelines for with-context-mcp

Project Overview

TypeScript MCP server for project-scoped note management (Obsidian, etc). Uses ES modules, Vitest for testing, strict TypeScript.

Documentation & Research

Use the vault for implementation planning and research:

When working on features, bugs, or tests, create notes in the vault instead of the repo:

// Research and plan implementations
write_note({
  path: 'dev/features/fuzzy-search-implementation.md',
  content: '# Fuzzy Search Implementation\n\n## Research...',
});

// Document test strategies
write_note({
  path: 'dev/testing/prepend-mode-test-plan.md',
  content: '# Prepend Mode Test Plan\n\n## Test Cases...',
});

// Track bugs and investigations
write_note({
  path: 'dev/bugs/path-traversal-investigation.md',
  content: '# Path Traversal Bug\n\n## Analysis...',
});

Benefits:

• Persistent across sessions
• Searchable and linkable
• Organized with other project docs
• Doesn't clutter the repo
• Easy to reference in future work

Vault structure for development:

Projects/with-context-mcp/
├── docs/           (public documentation)
├── dev/            (implementation notes)
│   ├── features/   (feature research & planning)
│   ├── bugs/       (bug investigations)
│   ├── testing/    (test strategies)
│   └── research/   (API research, decisions)
└── meetings/       (if needed)

Build & Test Commands

• npm run build - Compile TypeScript to dist/
• npm run dev - Run in dev mode with tsx
• npm run lint - Lint with ESLint (fixes with npm run lint:fix)
• npm run format - Format with Prettier (check with npm run format:check)
• npm test - Run all tests in watch mode
• npm run test:run - Run tests once (for CI)
• vitest run tests/unit/config-parser.test.ts - Run a single test file
• npm run test:coverage - Generate coverage report

Code Style

Imports: Use .js extensions for local imports (ES modules). Group: external deps, then local imports with blank line between.