MCP session tools: normalize session identifier key across `list_sessions` and `get_session` #70

New issue

Open

opened 2026-05-10 23:59:03 +02:00 by jesse · 0 comments

jesse commented

2026-05-10 23:59:03 +02:00

Owner

Background

The MCP session tools surface use two different keys for the session identifier depending on which tool is called. list_sessions returns entries keyed session_id; get_session returns the same id under id. Every consumer learns the asymmetry the hard way.

Source: code review of branch phase-8/dashboard-ui-pr3-sessions
File: crates/cognix-mcp/src/tools/session/list.rs, crates/cognix-mcp/src/tools/session/get.rs, crates/cognix-server/assets/schema.js:16-17
Branch: phase-8/dashboard-ui-pr3-sessions

Failure mode

list_sessions items expose session_id, name, created_at, updated_at, closed_at.
get_session exposes id, name, created_at, updated_at, closed_at — same record, different identifier key.
The dashboard mirrors the asymmetry: assets/schema.js:16 requires session_id, schema.js:17 requires id; assets/sessions.js:109 reads entry.session_id, sessions.js:154 reads session.id, and sessions.js:264 sends { session_id: sessionId } while consuming the response's id.
Any future consumer that normalizes the field on the assumption of symmetry breaks both validators silently.
Any new session tool added later inherits the choice arbitrarily.

Why deferred from `phase-8/dashboard-ui-pr3-sessions`

The fix is a breaking change to the MCP tool contract; dashboard consumers are not the only audience (CLI, scripted agents).
PR3 was scoped to the dashboard sessions sidebar; aligning the server-side schema needs its own change with a contract-version bump.

Proposed work

Decide canonical key — session_id is the more common spelling and matches the parameter name on get_session/get_thoughts arguments
Update crates/cognix-mcp/src/tools/session/get.rs to emit the chosen key
Update crates/cognix-server/assets/schema.js validators to share a single REQUIRED_SESSION_KEYS constant
Update assets/sessions.js call sites to use the unified key
Audit non-dashboard consumers (cognix-cli, any scripted agent flows) for hard-coded id accesses on session payloads
Update docs/MCP_TOOLS.md examples and the golden parity fixtures

Acceptance

list_sessions and get_session agree on the session identifier key
Both validators in schema.js reference the same REQUIRED_SESSION_KEYS constant
Golden parity tests updated and passing
docs/MCP_TOOLS.md reflects the unified shape
Migration note added if the change is observable to existing consumers

References

Branch: phase-8/dashboard-ui-pr3-sessions
Code review finding: MEDIUM — schema.js:16-17 asymmetric session_id vs id
Related: #69 (dashboard get_thoughts JSON envelope)

## Background The MCP session tools surface use two different keys for the session identifier depending on which tool is called. `list_sessions` returns entries keyed `session_id`; `get_session` returns the same id under `id`. Every consumer learns the asymmetry the hard way. **Source:** code review of branch `phase-8/dashboard-ui-pr3-sessions` **File:** `crates/cognix-mcp/src/tools/session/list.rs`, `crates/cognix-mcp/src/tools/session/get.rs`, `crates/cognix-server/assets/schema.js:16-17` **Branch:** `phase-8/dashboard-ui-pr3-sessions` ## Failure mode - `list_sessions` items expose `session_id`, `name`, `created_at`, `updated_at`, `closed_at`. - `get_session` exposes `id`, `name`, `created_at`, `updated_at`, `closed_at` — same record, different identifier key. - The dashboard mirrors the asymmetry: `assets/schema.js:16` requires `session_id`, `schema.js:17` requires `id`; `assets/sessions.js:109` reads `entry.session_id`, `sessions.js:154` reads `session.id`, and `sessions.js:264` sends `{ session_id: sessionId }` while consuming the response's `id`. - Any future consumer that normalizes the field on the assumption of symmetry breaks both validators silently. - Any new session tool added later inherits the choice arbitrarily. ## Why deferred from `phase-8/dashboard-ui-pr3-sessions` - The fix is a breaking change to the MCP tool contract; dashboard consumers are not the only audience (CLI, scripted agents). - PR3 was scoped to the dashboard sessions sidebar; aligning the server-side schema needs its own change with a contract-version bump. ## Proposed work - [ ] Decide canonical key — `session_id` is the more common spelling and matches the parameter name on `get_session`/`get_thoughts` arguments - [ ] Update `crates/cognix-mcp/src/tools/session/get.rs` to emit the chosen key - [ ] Update `crates/cognix-server/assets/schema.js` validators to share a single `REQUIRED_SESSION_KEYS` constant - [ ] Update `assets/sessions.js` call sites to use the unified key - [ ] Audit non-dashboard consumers (`cognix-cli`, any scripted agent flows) for hard-coded `id` accesses on session payloads - [ ] Update `docs/MCP_TOOLS.md` examples and the golden parity fixtures ## Acceptance - `list_sessions` and `get_session` agree on the session identifier key - Both validators in `schema.js` reference the same `REQUIRED_SESSION_KEYS` constant - Golden parity tests updated and passing - `docs/MCP_TOOLS.md` reflects the unified shape - Migration note added if the change is observable to existing consumers ## References - Branch: `phase-8/dashboard-ui-pr3-sessions` - Code review finding: MEDIUM — schema.js:16-17 asymmetric `session_id` vs `id` - Related: #69 (dashboard `get_thoughts` JSON envelope)

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

jesse/cognix#70

No description provided.

Rows
Columns

MCP session tools: normalize session identifier key across list_sessions and get_session #70