org-mcp-server: 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

GitHub repo: https://github.com/szaffarano/org-mcp-server/

MCP server for org-mode knowledge management in Rust. Provides search, content access, agenda views, and note linking for org-mode files through the Model Context Protocol.

Development Commands

cargo build                          # Build all crates (~47s, never cancel)
cargo test                           # Run all tests
cargo test <test_name>               # Run specific test
cargo test -p <crate_name>           # Test specific crate (org-core, org-mcp-server, org-cli)
cargo test --test integration_tests  # Run MCP server integration tests
cargo clippy --all-targets --all-features -- -D warnings  # Lint
cargo fmt --all                      # Format code
cargo run --bin org-cli -- --help    # Run CLI tool
cargo run --bin org-mcp-server       # Run MCP server (needs valid org directory)
cargo run --example <name>           # Run playground examples (in org-core/examples/)

Just Commands (available in nix devShell)

just dev          # Full workflow: format, lint, test, coverage
just check        # Quality gate: fmt-check, lint, test, coverage
just test         # Run all tests
just lint         # Clippy with -D warnings
just fmt          # Format code
just coverage-html # HTML coverage in coverage/html/

Architecture

Rust 2024 edition, multi-crate workspace with async-first design (tokio).

Crate Dependency Flow

org-core  <--  org-mcp-server
org-core  <--  org-cli
test-utils <-- org-core (dev), org-mcp-server (dev), org-cli (dev)

• org-core — All business logic: org-mode parsing (orgize), file discovery (ignore crate's Walk), fuzzy search (nucleo-matcher), agenda/task querying, configuration loading (config crate with TOML/YAML/JSON + env vars). Central type is OrgMode struct (org-core/src/org_mode/types.rs) which holds an OrgConfig and provides all operations. Custom error type OrgModeError in org-core/src/error.rs.