coulomb/qonto-assistant
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
qonto-assistant/README.md

60 lines
2.3 KiB
Markdown
Raw Normal View History

Initial commit
2026-07-21 21:19:44 +00:00
# qonto-assistant
Bootstrap qonto-assistant: intent, blueprint, research, workplans Author INTENT and SCOPE; persist ArchitectureBlueprint under specs/ and MCP gateway research under research/. Register with State Hub (QONTO-WP- prefix); seed QONTO-WP-0001 (bootstrap, finished) and QONTO-WP-0002 (Phase 1 REST policy kernel, ready).
2026-07-21 23:32:24 +02:00
Policy-governed Qonto domain API and MCP assistant for Binky (and later
multi-tenant dogfood).
**One choke point for bank access across every coding agent and harness.**
Clients never hold the Qonto API key. v1 policy: **read for awareness only —
no spend, no volume-cost actions.**
## Start here
| Doc | What |
| --- | --- |
| [`INTENT.md`](INTENT.md) | Why this exists; boundaries |
| [`specs/ArchitectureBlueprint.md`](specs/ArchitectureBlueprint.md) | Architecture, phases, policy model |
| [`research/2026-07-21-mcp-gateway-and-governed-domain-assistant.md`](research/2026-07-21-mcp-gateway-and-governed-domain-assistant.md) | External + internal research |
Complete Phase 1: policy kernel, REST service, and local smoke tooling Implements QONTO-WP-0002 (policy-gated Qonto REST service with audit logging, rate limiting, and credential handling) and the ADHOC-2026-07-21 follow-up (fixture-backed local smoke mode, repo classification metadata). Marks QONTO-WP-0001/0002 and the ad-hoc workplan finished, and regenerates WORK-RECORDS.md and the ADHOC workplan's state_hub_workstream_id via fix-consistency. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-22 21:21:05 +02:00
| [`docs/operator-runbook.md`](docs/operator-runbook.md) | How to run and verify Phase 1 |
Bootstrap qonto-assistant: intent, blueprint, research, workplans Author INTENT and SCOPE; persist ArchitectureBlueprint under specs/ and MCP gateway research under research/. Register with State Hub (QONTO-WP- prefix); seed QONTO-WP-0001 (bootstrap, finished) and QONTO-WP-0002 (Phase 1 REST policy kernel, ready).
2026-07-21 23:32:24 +02:00
## Status
Complete Phase 1: policy kernel, REST service, and local smoke tooling Implements QONTO-WP-0002 (policy-gated Qonto REST service with audit logging, rate limiting, and credential handling) and the ADHOC-2026-07-21 follow-up (fixture-backed local smoke mode, repo classification metadata). Marks QONTO-WP-0001/0002 and the ad-hoc workplan finished, and regenerates WORK-RECORDS.md and the ADHOC workplan's state_hub_workstream_id via fix-consistency. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-22 21:21:05 +02:00
Phase 1 runtime is implemented:
- Python 3.12 service under `src/qonto_assistant/`
- default-deny YAML policy
- Qonto read-only client (`organization`, `transactions`)
- REST endpoints: `/v1/health`, `/v1/accounts`, `/v1/transactions`, `/v1/snapshot`
- audit metadata, rate limiting, concurrency bounds, tests
QONTO-WP-0003-T02: MCP tool catalog on the shared capability core Add qonto_org_summary, qonto_list_transactions, and qonto_cost_run_rate_hints MCP tools, all routed through CapabilityService with protocol="mcp" -- same PolicyEngine.decide() path as REST, same deny-reason vocabulary. Skip snapshot_bundle as an MCP tool (REST already covers the composite read; not a separate privilege). CapabilityService now threads protocol through _execute/_emit_audit instead of hardcoding "rest". cost_run_rate_hints gets its own service method since it's an independent policy capability, not only a snapshot sub-field. Actor identity reuses REST's X-Actor-* header convention via a shared auth.actor_claims_from_headers(), read from the MCP Context's request when present. Fixed streamable_http_path defaulting to "/mcp", which doubled to "/mcp/mcp" once mounted under the "/mcp" prefix. Verified end-to-end with the mcp SDK's streamablehttp_client against the live fixture-backed server: tool list, allow/deny paths, and X-Actor-ID flowing through to the audit log exactly like REST. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-22 21:48:09 +02:00
Phase 2 (MCP surface, `workplans/QONTO-WP-0003-mcp-surface.md`) is in
progress: a streamable-HTTP MCP adapter is mounted at `/mcp` on the same
capability core and policy kernel as REST, with tools `qonto_org_summary`,
QONTO-WP-0003-T03: MCP client auth + shared multi-harness config snippet Gate /mcp with a shared-secret bearer token (QONTO_ASSISTANT_MCP_TOKEN, mcp_auth.py::BearerTokenAuthMiddleware, constant-time compare, REST untouched) since no OIDC issuer exists in this fleet yet -- pointing FastMCP's OAuth Protected Resource flow at a non-existent issuer would be worse than not having it. This token is a service credential, never a bank credential; per-actor identity stays the existing X-Actor-* convention. Add docs/mcp-integration.md: tool catalog, the two-layer auth model (workload auth today vs. deferred OIDC target), and one shared {"mcpServers": {...}} client config snippet (url + headers) usable across Claude Code, Claude Desktop, Cursor, and Codex/Grok-style harnesses. Verified live using only that snippet: unauthenticated and wrong-token requests get 401 before reaching any tool; a request built from the snippet's URL + headers lists tools and calls qonto_org_summary successfully against the fixture-backed server. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-23 09:41:25 +02:00
`qonto_list_transactions`, and `qonto_cost_run_rate_hints`. The endpoint is
gated by a shared-secret bearer token (`QONTO_ASSISTANT_MCP_TOKEN`) — see
`docs/mcp-integration.md` for the auth model, its gap vs. the OIDC/workload
target, and the shared multi-harness client config snippet. The
`finance-qonto-read` tool profile is not yet implemented.
QONTO-WP-0003-T02: MCP tool catalog on the shared capability core Add qonto_org_summary, qonto_list_transactions, and qonto_cost_run_rate_hints MCP tools, all routed through CapabilityService with protocol="mcp" -- same PolicyEngine.decide() path as REST, same deny-reason vocabulary. Skip snapshot_bundle as an MCP tool (REST already covers the composite read; not a separate privilege). CapabilityService now threads protocol through _execute/_emit_audit instead of hardcoding "rest". cost_run_rate_hints gets its own service method since it's an independent policy capability, not only a snapshot sub-field. Actor identity reuses REST's X-Actor-* header convention via a shared auth.actor_claims_from_headers(), read from the MCP Context's request when present. Fixed streamable_http_path defaulting to "/mcp", which doubled to "/mcp/mcp" once mounted under the "/mcp" prefix. Verified end-to-end with the mcp SDK's streamablehttp_client against the live fixture-backed server: tool list, allow/deny paths, and X-Actor-ID flowing through to the audit log exactly like REST. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-22 21:48:09 +02:00
Complete Phase 1: policy kernel, REST service, and local smoke tooling Implements QONTO-WP-0002 (policy-gated Qonto REST service with audit logging, rate limiting, and credential handling) and the ADHOC-2026-07-21 follow-up (fixture-backed local smoke mode, repo classification metadata). Marks QONTO-WP-0001/0002 and the ad-hoc workplan finished, and regenerates WORK-RECORDS.md and the ADHOC workplan's state_hub_workstream_id via fix-consistency. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-22 21:21:05 +02:00
Current verification:
- `PYTHONPATH=src ../state-hub/.venv/bin/python -m pytest` → `16 passed`
- `python3 -m compileall src tests scripts`
- `../state-hub/.venv/bin/python scripts/smoke_rest_api.py --python ../state-hub/.venv/bin/python`
Local fixture-backed smoke mode is available through `QONTO_FIXTURE_DIR`, so the
service can be exercised without real Qonto credentials. The smoke path checks
both a `31`-day recent snapshot and a `90`-day recurring-cost snapshot.
Normal local workflow, when toolchain support exists:
```bash
make install-dev
make test
make run
```
Bootstrap qonto-assistant: intent, blueprint, research, workplans Author INTENT and SCOPE; persist ArchitectureBlueprint under specs/ and MCP gateway research under research/. Register with State Hub (QONTO-WP- prefix); seed QONTO-WP-0001 (bootstrap, finished) and QONTO-WP-0002 (Phase 1 REST policy kernel, ready).
2026-07-21 23:32:24 +02:00
## Related
- OpenBao lane: `tenants/binky/qonto-api` (ops-warden `binky-qonto-api`)
- First pull / CostRunRate: `binky-control` BINKY-WP-0005
Reference in a new issue Copy permalink