finizi-app-agent (PyPI: finizi-app)

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

What it is

finizi-app-agent (distributed as the PyPI package finizi-app) is a thin wrapper that exposes 33 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

# from finizi-app-api repo root (editable)
uv pip install -e ./finizi-app-agent

# or, once published, install the distribution
uv pip install finizi-app

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

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.

Distribution naming

License

Proprietary — Finizi Engineering.