Metadata-Version: 2.4
Name: finizi-app
Version: 0.2.0
Summary: CLI + MCP server for the Finizi.AI Vietnamese accounting/tax platform
Author-email: Finizi Engineering <engineering@finizi.app>
License-Expression: LicenseRef-Proprietary
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Office/Business :: Financial :: Accounting
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: httpx>=0.28.1
Requires-Dist: keyring>=25.0.0
Requires-Dist: keytar>=0.1.0; sys_platform == 'darwin' or sys_platform == 'linux'
Requires-Dist: mcp>=1.6.0
Requires-Dist: pydantic-settings>=2.10.1
Requires-Dist: pydantic>=2.11.7
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.9.0
Requires-Dist: starlette>=0.41.0
Requires-Dist: tenacity>=9.0.0
Requires-Dist: typer>=0.15.0
Requires-Dist: uvicorn>=0.35.0
Provides-Extra: dev
Requires-Dist: anyio>=4.6.0; extra == 'dev'
Requires-Dist: mypy>=1.13.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.1.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
Requires-Dist: pytest>=8.4.1; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Requires-Dist: ruff>=0.7.0; extra == 'dev'
Requires-Dist: trustme>=1.2.0; extra == 'dev'
Description-Content-Type: text/markdown

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

CLI + MCP server for the [finizi-app-api](../README.md) Vietnamese accounting, tax, payroll, and operations platform — built to work with the [admin.finizi.ai](https://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

```bash
# 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:

| Layer | Variable | Example |
|-------|----------|---------|
| Flag (CLI) | `--api-url` | `finizi-app doctor --api-url https://staging.admin.finizi.ai` |
| Process env | `FINIZI_API_URL` | `export FINIZI_API_URL=https://staging.admin.finizi.ai` |
| `.env.local` | `FINIZI_API_URL=...` | per-developer override |
| `.env.<FINIZI_ENV>` | same | per-environment |
| `.env` | same | shared default |
| User config | `~/.config/finizi-app/credentials.json` | `{"api_url": "..."}` |
| Project config | `./.finizi-app/credentials.json` | same |
| OS keychain | `finizi-app-agent/api_url` | `security add-generic-password -s finizi-app-agent -a api_url -w 'https://...'` |
| **Default** | built-in | `https://admin.finizi.ai` |

`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

```bash
# 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

```bash
# 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`](docs/cli.md) and [`docs/mcp.md`](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`](docs/architecture.md) for details.

## Distribution naming

| What | Name |
|------|------|
| PyPI distribution (`pip install ...`) | `finizi-app` |
| Python import package | `finizi_app` |
| CLI entry point | `finizi-app` |
| MCP server entry point | `finizi-app-mcp` |

## License

Proprietary — Finizi Engineering.
