finizi-app-agent

CLI + MCP server for the finizi-app-api Vietnamese accounting, tax, payroll, and operations platform — built to work with the admin.finizi.ai application.

Private distribution only — not published to public PyPI.

What it is

finizi-app-agent is a thin wrapper that exposes 96 carefully-chosen workflows of the finizi-app-api as:

1. finizi-app CLI — a scriptable command-line tool with stable JSON output
2. MCP server — agent-callable tools via stdio or Streamable HTTP

Both surfaces share a single core/ package, so the same business logic is exercised in tests, CLI, and MCP.

The wrapper targets the production admin.finizi.ai application by default but every endpoint is fully configurable through the credential resolution chain.

Install

# Editable install (development)
uv pip install -e .

# Internal distribution (from this monorepo's git URL)
pip install "git+ssh://git@github.com/finizi-app/finizi-agentize.git@<SHA>#subdirectory=finizi-app"

# With dev extras (pytest, ruff, mypy)
pip install "git+ssh://git@github.com/finizi-app/finizi-agentize.git@<SHA>#subdirectory=finizi-app[dev]"

The finizi-app CLI and finizi-app-mcp entry points are auto-installed.

What's new (2026-06-30 session)

Three additive CLI usability improvements:

Run finizi-app --version and finizi-app auth status after install to verify the upgrade took effect.

What's new (2026-06-27 session)

8 new audit-skill read-only commands were added to support the review-invoice-and-entries skill workflow:

All 8 are read-only. All 8 honor --json. All 8 use the standard exit codes (0/1/2/3/4) defined in docs/cli.md.

Backend ticket #1443 fixed the documents list --ref-id filter; flag is exposed in the CLI.

What's new (2026-06-28, slice 3)

finizi-app coa get now returns raw account state only — no regulatory classification. Closes issue #9.

BREAKING: removed source, account_regime (per account), and the top-level regime field. Renamed is_custom_account → is_entity_specific_account in the response. The wrapper no longer performs the second round trip to /accounting-models. Finizi is a data transport, not a regulatory authority; auditors / skill agents apply their own classification against Vietnamese accounting regulations.

What's new (2026-06-28, slice 2)

finizi-app coa get upgraded to return all postable accounts (cấp 1 + cấp 2/3 sub-accounts like TK 3311, 3318, 13311-13313) with correct parent_account_id linking. Backed by /chart-of-accounts/postable (slice 1 used /chart-of-accounts which only returned cấp 1).

BREAKING: --page and --per-page flags were removed (pagination is trivial now — /postable returns the full set in one round trip). Users who scripted coa get --page 2 should remove the flag.

Adds:

• --levels 1,2,3|all filter (default = all)
• --include-inactive flag (forward-compatible; backend doesn't expose inactive accounts yet — see b4b-api#1483)
• source field now returns "standard_tt<regime>" for non-custom accounts (was "unknown"); "custom_entity" for is_custom_account=true
• Pagination metadata: total, page, per_page, pages, has_next, has_prev (always single-page; backend returns full set in one shot)

Closes gaps 1, 2, 3, 4 from issue #5 against PATEDELI (110 accounts, 73 sub-accounts, all properly tagged). Gap 5 (true regime_mismatch) partially addressed — full support pending b4b-api#1482 (linked_regime field per account).

What's new (2026-06-28, slice 1)

Added finizi-app coa get for the audit-coa-organization skill in finizi_bpo_knowledge. Returns the entity's Chart of Accounts with account_regime derived from the assigned accounting model. Read-only; 2 backend round trips composed client-side.

Backend ticket b4b-api#1479 filed for type / source / linked_regime tagging per account — wrapper emits null / unknown until that lands.

Endpoint configuration

The CLI/MCP client talks to a finizi-app-api backend. By default it targets the production admin.finizi.ai application. Override through any of:

FINIZI_MCP_URL is also configurable; it defaults to {api_url}/mcp.

finizi-app doctor --json reports which layer resolved without printing values.

Quick start

# Check the API is reachable (uses default https://admin.finizi.ai)
finizi-app doctor

# Override for staging
FINIZI_API_URL=https://staging.admin.finizi.ai finizi-app doctor

# Authenticate (caches to OS keychain)
finizi-app auth login --phone +84xxxxxxxxx --password '...'

# Pick a tenant
finizi-app entities use --entity-id 42

# Run a workflow
finizi-app invoices list --entity-id 42 --page 1
finizi-app invoices import-xml --entity-id 42 ./invoice.xml
finizi-app einvoice issue --entity-id 42 --invoice-id 1234

# Audit-skill workflows
finizi-app invoices get --entity-id 42 --invoice-id 1234
finizi-app ledger get-entries --entity-id 42 --invoice-id 1234
finizi-app tax check-status --tax-code 0123456789 --date 2026-01-15

MCP server

# stdio (for local Claude Code / Cursor) — connects to admin.finizi.ai by default
finizi-app-mcp --transport stdio

# Streamable HTTP (self-hosted MCP server, e.g. alongside the admin app)
finizi-app-mcp --transport http --host 0.0.0.0 --port 8080 --bearer-token "$FINIZI_MCP_BEARER_TOKEN"

See docs/cli.md and docs/mcp.md for full reference.

Architecture

finizi-app-agent/
├── core/         # framework-agnostic (no typer, no mcp)
├── cli/          # Typer app, thin adapter over core
├── mcp/          # FastMCP server, thin adapter over core
└── tests/

See docs/architecture.md for details.

Naming

License

Proprietary — Finizi Engineering. Internal use only.