appspace / appspace/kwwhat

Implement MCP context server (get_driver, get_charger, get_charge_attempt)

Open
#143 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
No language data
Stars
14
Forks
3
PR merge metrics
No merged PRs in 30d

Description

## Business question

External agents (Claude Desktop, calling-agent backends, MCP Inspector) need read-only, PII-safe context about a driver, charger, or charge attempt mid-conversation — e.g. a support agent handling "my last charge failed" needs to look up the attempt, then the charger, without a human running a BI query.

## Who asks it

Support/agent tooling integrators (MCP-compatible clients) calling the kwwhat data platform programmatically, not human analysts. This is API surface, not a dashboard.

## Grain

Three independent lookups, each by opaque ID, one row returned per call:
- `get_driver`: one row per `driver_key` (dim_drivers grain)
- `get_charger`: one row per `charger_id` (dim_chargers grain)
- `get_charge_attempt`: one row per `charge_attempt_id` (fact_charge_attempts grain)

## Key dimensions

Not applicable in the BI sense — these are point lookups by ID, not slice-and-dice reports. Chaining dimension: `get_charge_attempt` returns `charger_id` and driver identifier so a client can chain into `get_charger` / `get_driver`.

## Expected output

Per tool: `structuredContent` (validated against `outputSchema`) + a `content[0].text` natural-language summary, consistent with each other. Missing record → `{"found": false}` with HTTP 200, not an error. Invalid/PII-shaped input → tool execution error (`isError: true`), not HTTP 400. Full contract, auth (OAuth client-credentials + shared-secret modes), and transport (Streamable HTTP) are specified in `demo/mcp-server-plan.md` on the `mcp` branch.

## Out of scope

- Vehicle profile fields (`make`/`model`/`connector_type`) on `get_driver` — deferred until a CRM source exists (join key TBD).
- Any write/mutation tool — read-only context only.
- Any PII (name, email, phone, address) in any tool response.
- Human-facing BI/reporting — that's `chat-bi`, unaffected by this work.

## Known blockers / open modeling questions

1. **Charger operational status** (`get_charger` needs `available/in-use/faulted/offline`) — status currently only exists at connector grain (`dim_connectors.latest_status`, raw OCPP enum). No charger-grain rollup exists yet. Related to #73 (port status to dim_ports) — needs a decision on rollup rule + OCPP→simplified-enum mapping before `get_charger` can ship with this field.
2. **Charge attempt session state** (`get_charge_attempt` needs `active/completed/interrupted/errored`) — `fact_charge_attempts` only has `is_successful` (bool) + raw OCPP `status` + `transaction_stop_reason`. No existing derivation to the 4-value state described in the plan.
3. Charger hardware attributes (model/firmware_version) aren't modeled yet — tracked as sub-issue #144, threaded through the existing `chargers` raw source (no separate seed). `power_kw` not yet scoped.
4. CRM join key for vehicle fields (plan open question #1) — genuinely unresolved, out of scope for v1 per above.

## Acceptance criteria

- [ ] `demo/mcp/` FastAPI service implementing `get_driver`, `get_charger`, `get_charge_attempt` per `demo/mcp-server-plan.md`
- [ ] Both auth modes (OAuth client-credentials, shared-secret) implemented and tested
- [ ] ID validation / PII rejection on every tool call before any query runs
- [ ] Charger status and charge-attempt state derivation rules decided and documented (resolves blockers 1–2 above) before those fields ship, or fields explicitly deferred with a tracking note
- [ ] Service wired into `docker-compose.yml` as Service 4, decision made on `run-demo.sh` inclusion (plan open question #3)
- [ ] `demo/README.md` updated with an MCP section
- [ ] Tests: auth, happy-path + not-found + invalid-ID per tool

Plan: `demo/mcp-server-plan.md` (branch `mcp`)

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading demo/mcp-server-plan.md on the mcp branch, then inspect the requested entry point under demo/mcp/. Review the acceptance criteria for auth, validation, lookup, and not-found tests before resolving the documented charger-status and charge-attempt-state blockers. Done means the service, tests, docker-compose.yml wiring, and demo/README.md MCP section meet the specified contract.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker-compose, fastapi, python
Domain
api, authentication, backend, devops
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.