CLAUDE.mdtypescript

hledger-mcp CLAUDE.md

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

View Source

CLAUDE.md

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

Project Overview

This is an HLedger MCP (Model Context Protocol) server implementation built with TypeScript. The project creates a bridge between HLedger accounting software and MCP-compatible applications using the Model Context Protocol SDK.

Commands

Building

  • npm run build - Compiles TypeScript to JavaScript and makes the output executable

Development

  • Node.js version: v24.7.0 (specified in .nvmrc)
  • Use nvm use to set correct Node version

Architecture

Core Structure

  • Entry Point: src/index.ts - Main server implementation
  • Output: build/index.js - Compiled executable with shebang
  • Binary: Available as hledger-mcp command after build

Key Components

  • MCP Server: Uses @modelcontextprotocol/sdk for Model Context Protocol implementation
  • Transport: StdioServerTransport for stdio-based communication
  • Validation: Zod library for schema validation
  • Configuration: Configurable via CLI flags for read/write behaviour
  • Write Tools: hledger_add_transaction, hledger_import, hledger_rewrite, hledger_remove_entry, hledger_replace_entry, and hledger_close all write through temporary copies with optional backups
  • Read Tools: new commands such as hledger_notes extend the reporting surface while reusing query + output-format helpers

Server Structure

The server is configured as:

  • Name: "hledger-mcp"
  • Version: "1.0.0"
  • Capabilities: tooling plus resource discovery (we call hledger files and register every reported ledger as an MCP resource before the transport connects)
  • Transport: Stdio-based communication

The server runs on stdio and logs startup message to stderr to avoid interfering with the MCP protocol communication on stdout.

Runtime flags

  • --read-only: disable the add-transaction tool (all attempts return a validation error). Default: off.
  • --skip-backup: skip creating .bak files when appending to an existing journal. Default: off.
  • Journal path remains the first non-flag argument; flags can be passed before or after it.