ledger-mcp

AI 에이전트를 위한 도구로 복식부기 원장을 제공하는 작은 MCP 서버입니다. MCP 서버 설계, 에이전트 도구 사용성, 그리고 평가 중심 반복 개발을 주제로 한 2일간의 연습으로 제작되었습니다.

상태: 1일 차 완료. 2일 차(평가 하네스 + 발견 사항) 진행 중.

구성 요소

• ledger.py — SQLite 기반의 복식부기 원장 코어. 금액은 정수 센트 단위로 저장됩니다. 대차가 일치하는 거래와 명명된 계정의 무결성을 강제합니다.

• server.py — 네 가지 도구를 제공하는 MCP 서버: create_account, record_transaction, get_balance, reconcile.

• test_ledger.py — 원장 코어를 위한 pytest 테스트 스위트.

• NOTES.md — Claude Desktop에서 서버를 실행하며 얻은 설계 결정과 관찰 내용을 기록한 실행 로그.

Related MCP server: Agent Ledger

로컬에서 실행

uv sync
uv run pytest -v          # run the ledger tests
uv run mcp dev server.py  # launch with the MCP Inspector

Claude Desktop에서 사용하려면 claude_desktop_config.json에 추가하세요:

{
  "mcpServers": {
    "ledger": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/ledger-mcp", "run", "mcp", "run", "server.py"]
    }
  }
}

2일 차 예정

• 에이전트가 이 도구들에서 성공하는 지점과 실패하는 지점을 측정하는 평가 하네스

• 발견 사항 정리: 명명 vs. 문서화, 암묵적 계정 생성, 가드레일로서의 도구 vs. 실행자로서의 도구