money-manager-mcp: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents (Claude, Copilot, ZCode, etc.) working in this repository. Read this before making changes.

Project Overview

Money Manager MCP is a Model Context Protocol server that lets AI assistants manage personal finances through the Realbyte Money Manager Android app's "PC Manager" web server (a local-network HTTP service).

The server runs over stdio and exposes 18 tools (no resources, no prompts). It is built on FastMCP and written in TypeScript (strict mode, ESM, Node ≥ 22).

A phone running the Money Manager app and the computer running the server must be on the same Wi-Fi network. There is no automated test suite.

Repository Structure

src/
├── index.ts          # Server bootstrap — thin; wires FastMCP + HTTP client + stdio
├── client/
│   ├── http-client.ts  # axios + cookie sessions, retry, XML & JS-literal parsing
│   └── identifiers.ts  # character classifiers used by the JS-literal parser
├── config/
│   └── index.ts      # Layered config: CLI > env > .money-manager-mcp.json > defaults
├── errors/
│   └── index.ts      # McpError taxonomy (Network/API/Session/File/Internal)
├── schemas/
│   └── index.ts      # Zod input schemas — single source of truth for tool inputs
├── tools/
│   └── handlers.ts   # Tool handlers + the TOOLS registry (one definition per tool)
└── types/
    └── index.ts      # Domain/response types (response shapes; inputs come from schemas)
docs/
├── SETUP.md                      # Installation & configuration
├── USAGE.md                      # Tool reference with example prompts
└── technical/
    ├── ARCHITECTURE.md           # System design
    └── API_DOCUMENTATION.md      # Upstream Money Manager HTTP API reference

Important Commands

npm run build    # tsc → dist/  (the gate: must stay clean)
npm run dev      # tsx src/index.ts (run from source, no build)
npm start        # node dist/index.js (run compiled output)
npm run lint     # ESLint
npm run format   # Prettier