Jarca
2ccfc9c064
- add Docker deployment for independent jarca-ledger container - enable FastMCP streamable-http runtime configuration - document dcy-013, REQ-019, and BAT-015 verification evidence - update structure/runtime baselines and deployment runbook
45 lines
1.7 KiB
Markdown
45 lines
1.7 KiB
Markdown
# BAT-015 Design
|
|
|
|
## Architecture Decision
|
|
|
|
`jarca-ledger` is deployed as an independent Docker service that directly serves FastMCP `streamable-http` transport on port 8000. `genichin-agent` is no longer the process launcher for Jarca Ledger MCP. It may remain a client, but the Jarca Ledger service lifecycle belongs to Docker.
|
|
|
|
## Runtime topology
|
|
|
|
```text
|
|
finance-agent / Hermes client
|
|
│
|
|
│ Streamable HTTP MCP
|
|
▼
|
|
http://192.168.55.253:8000/mcp
|
|
│
|
|
▼
|
|
jarca-ledger container
|
|
├─ jarca-ledger-mcp FastMCP server
|
|
├─ /data/ledger.sqlite3
|
|
└─ Docker healthcheck on 127.0.0.1:8000
|
|
│
|
|
▼
|
|
Synology host /volume1/docker/jarca-ledger/data
|
|
```
|
|
|
|
## Transport contract
|
|
|
|
- Default remains `stdio` when no env is set.
|
|
- `JARCA_MCP_TRANSPORT=streamable-http` runs Uvicorn/FastMCP network transport.
|
|
- `JARCA_MCP_HOST=0.0.0.0`, `JARCA_MCP_PORT=8000`, `JARCA_MCP_STREAMABLE_HTTP_PATH=/mcp` define the Docker service endpoint.
|
|
- Tool names and tool payload contracts remain unchanged.
|
|
|
|
## Data migration design
|
|
|
|
- Source: `jarca:/root/.local/share/jarca/ledger.sqlite3`
|
|
- Target: `jarca-ledger:/data/ledger.sqlite3`
|
|
- Snapshot method: SQLite `Connection.backup()` to avoid copying a live DB mid-write.
|
|
- Pre-replacement safety: back up the new empty `/data/ledger.sqlite3` under `/data/backups/pre_migration_empty_<timestamp>.sqlite3`.
|
|
- Verification: sha256, `PRAGMA integrity_check`, table counts, MCP `get_ledger_db_status`.
|
|
|
|
## Security and exposure boundary
|
|
|
|
- This batch exposes MCP only on the Synology host/internal network port mapping `8000:8000`.
|
|
- Internet exposure, reverse proxy, TLS, and auth policy are not included and must be handled as a separate approved change before external access.
|