Ledger CLI MCP Server

Instructions

Implementation Reference

• main.py:232-239 (handler)

  The handler function for the 'ledger_stats' tool. It constructs a 'ledger stats' command (optionally filtered by query) and executes it using the shared run_ledger helper.

  @mcp.tool(description="Show statistics about the ledger file")
  def ledger_stats(params: LedgerStats) -> str:
      cmd = ["stats"]
  
      if params.query:
          cmd.append(params.query)
  
      return run_ledger(cmd)

• main.py:84-86 (schema)

  Pydantic schema/model defining the input parameters for the ledger_stats tool, including an optional query filter.

  class LedgerStats(BaseModel):
      query: Optional[str] = Field(None, description="Filter for statistics")

• main.py:107-129 (helper)

  Shared helper function that runs ledger CLI commands with input validation, error handling, and uses the LEDGER_FILE environment variable.

  def run_ledger(args: List[str]) -> str:
      try:
          if not LEDGER_FILE:
              return "Ledger file path not set. Please provide it via --ledger-file argument or LEDGER_FILE environment variable."
  
          # Validate inputs to prevent command injection
          for arg in args:
              if ";" in arg or "&" in arg or "|" in arg:
                  return "Error: Invalid characters in command arguments."
  
          result = subprocess.run(
              ["ledger", "-f", LEDGER_FILE] + args,
              check=True,
              text=True,
              capture_output=True,
          )
          return result.stdout
      except subprocess.CalledProcessError as e:
          error_message = f"Ledger command failed: {e.stderr}"
          if "couldn't find file" in e.stderr:
              error_message = f"Ledger file not found at {LEDGER_FILE}. Please provide a valid path via --ledger-file argument or LEDGER_FILE environment variable."
          return error_message