jsfamily/jarca-ledger-mcp
5
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: deploy jarca ledger network mcp service

Browse Source 
- 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
This commit is contained in:
Jarca
2026-07-07 23:04:42 +09:00
parent a7b18c435d
commit 2ccfc9c064
19 changed files with 829 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/runtime-flows.md
+23 -5
View File
@@ -4,8 +4,8 @@
- Baseline Seed: `.stage-pilot/bootstrap/baseline.yaml`
- Status: draft
- Owner: Jarca / project maintainer
- Last Updated (KST): 2026-07-03
- Source Discovery / Batch: bootstrap-baseline, BAT-006, BAT-007, BAT-008, BAT-010, BAT-012, BAT-013, BAT-014
- Last Updated (KST): 2026-07-07
- Source Discovery / Batch: bootstrap-baseline, BAT-006, BAT-007, BAT-008, BAT-010, BAT-012, BAT-013, BAT-014, dcy-013/BAT-015
- Primary Runtime: mixed
## Project Summary
@@ -20,19 +20,36 @@
- Does not duplicate full acceptance criteria or low-level implementation details.
## Covered Entry Points
- `jarca-ledger-mcp` :: MCP stdio server for Hermes tool calls.
- `jarca-ledger-mcp` :: MCP stdio server for local Hermes tool calls, or streamable-http server when configured by env.
- `jarca-ledger` Docker service :: Streamable HTTP MCP endpoint at `http://<synology-host>:8000/mcp`.
- `dashboard/app.py` :: Streamlit local dashboard.
- `pytest` :: regression test runner.
- `.github/workflows/ci.yml` :: GitHub Actions CI gate runner for PR/push/manual checks.
## Shared Components
- SQLite database at `~/.local/share/jarca/ledger.sqlite3` by default.
- SQLite database at `~/.local/share/jarca/ledger.sqlite3` by default for local runs; Docker service uses `JARCA_LEDGER_DB_PATH=/data/ledger.sqlite3` backed by `/volume1/docker/jarca-ledger/data`.
- `jarca_ledger_mcp/service.py` compatibility facade over application modules.
- `jarca_ledger_mcp/infrastructure/sqlite/*` for DB path resolution, schema, migration, and connection lifecycle.
- `jarca_ledger_mcp/adapters/mcp/tool_contracts.py` + `adapters/mcp/server.py` for MCP contract and registration seams.
- `jarca_ledger_mcp/adapters/streamlit/*_gateway.py` + `service_gateway.py` compatibility aggregator for dashboard-facing service calls.
- `jarca_ledger_mcp/infrastructure/parsers/*` plus legacy parser modules for KB/Toss/SeoulPay sources.
## Flow: `Docker network MCP service`
1. Docker daemon starts the `jarca-ledger` container from `jarca-ledger:latest` with `restart: unless-stopped`.
2. Compose mounts `/volume1/docker/jarca-ledger/data` to `/data` and sets `JARCA_LEDGER_DB_PATH=/data/ledger.sqlite3`.
3. `jarca-ledger-mcp` starts FastMCP with `JARCA_MCP_TRANSPORT=streamable-http`, `JARCA_MCP_HOST=0.0.0.0`, `JARCA_MCP_PORT=8000`, and path `/mcp`.
4. Finance agents connect to `http://<synology-host>:8000/mcp` or a shared Docker network DNS endpoint.
5. The MCP adapter routes tool calls through `adapters/mcp/tool_contracts.py` and existing application/persistence services.
6. Docker healthcheck verifies TCP readiness on `127.0.0.1:8000`; functional readiness is verified by MCP tool discovery and `ledger_health_check`.
## Flow: `Operating DB migration to jarca-ledger container`
1. Identify source DB in the legacy `jarca` container: `/root/.local/share/jarca/ledger.sqlite3`.
2. Create a consistent source snapshot using SQLite `Connection.backup()` rather than copying a live DB file directly.
3. Back up the current target `/data/ledger.sqlite3` under `/data/backups/` before replacement.
4. Stop `jarca-ledger`, remove target WAL/SHM sidecar files, copy the snapshot to `/data/ledger.sqlite3`, and restart.
5. Verify Docker health, SQLite `PRAGMA integrity_check`, table counts, sha256, and MCP `get_ledger_db_status`.
## Flow: `MCP server tool call`
1. Hermes MCP client invokes a tool exposed by `jarca_ledger_mcp.server` / `jarca_ledger_mcp.adapters.mcp.server`.
2. MCP adapter forwards arguments to the matching callable exposed by `adapters/mcp/tool_contracts.py`.
@@ -121,7 +138,7 @@
## Current Gaps / Planned Changes
- Browser-level evidence exists locally and remains outside required CI gates by design.
- Post-Phase-7 adapter narrowing is complete for the current compatibility architecture; deeper repository/use-case extraction and richer presenter/view-model layers remain future work.
- HTTP adapter and remote ops re-architecture remain deferred.
- Streamable HTTP MCP is now deployed for internal Synology operation. External exposure, reverse proxy/TLS/auth, and broader HTTP/REST adapter work remain deferred.
## Update Triggers
- Update this document when a command entry point changes.
@@ -138,3 +155,4 @@
- 2026-06-30 KST: REQ-007/REQ-008/BAT-007 기준으로 contract-regression/lint CI required-check flow 추가.
- 2026-07-03 KST: REQ-013/REQ-014/BAT-010 기준으로 service facade → application, db shim → infrastructure/sqlite, MCP/Streamlit adapter seam flow를 반영했다.
- 2026-07-03 KST: REQ-016/REQ-017/REQ-018 및 BAT-012/BAT-013/BAT-014 기준으로 imports/advanced owning services, parser seam, MCP tool_contracts, Streamlit page/domain gateway flow를 반영했다.
- 2026-07-07 KST: REQ-019/BAT-015 기준으로 Docker network MCP service flow와 legacy `jarca` DB → `jarca-ledger` volume migration flow를 추가했다.