Expose the tool layer over MCP

[xfznprojects]

SessionIQ now speaks the Model Context Protocol, so any MCP client — Claude Desktop, Cursor, or an agent of your own — can query a local library.

What it exposes

The same seven tools the in-app assistant calls: list_projects, search_library, filter_assets, compute_stat, asset_details, similar_tracks and next_up.

Each one delegates to the same LibraryToolbox, so a question answered through MCP and the same question asked inside the app are computed by identical code. That logic is what evals/ already measures — the tool layer scores 7/7 — so this adds a new surface without adding a second implementation to maintain.

Design decisions

The SDK is an optional extra (pip install -e ".[mcp]"), imported lazily, so the base install is unaffected. The entry point reports a missing extra in plain language rather than letting a protocol error surface.

stdio transport. MCP servers for local tools normally speak stdio, which fits a local-first app exactly: no port, no network exposure, the client launches it.

Retrieval runs in memory, not through ChromaDB. This is a read-only query surface that should start instantly and must not need an embedding model. The lexical-plus-metadata blend scored 0.733 hit@1 against 0.767 with vectors — not worth a model download here. Documented in the module.

Read-only, and reads at startup. It answers questions and changes nothing. It sees the library as of when the client launched it, which is stated in the README so nobody is surprised that a file added mid-session is missing.

A bug this surfaced in the shared path

LibraryToolbox.execute() truncated over-long results by chopping the serialised string and appending '…"}', which produced invalid JSON. The model coped with it; an MCP client would simply fail to parse it, and a large filter_assets over a real library hits this.

Payloads are now trimmed structurally — whole list items first, then oversized strings — so the JSON stays valid, and a payload that still cannot fit reports that rather than emitting something malformed. This fixes the in-app path too.

Verification

• 187 tests pass (up from 169), ruff clean
• End-to-end with a real MCP client: I spawned the server as a subprocess and drove it over an actual stdio connection. It initialised, reported its instructions, listed all seven tools with correct required parameters, and returned the right answers — compute_stat(rms_db, max) → loud.wav @ -9.0 dB, filter_assets(status=Ready) → 1 match, list_projects → both projects.
• 13 MCP tests cover loading, wiring, the exposed surface and delegation; they skip cleanly when the optional SDK is absent, and CI installs it so the surface stays covered
• No stray stdout output, which would corrupt the protocol — a real failure mode for stdio servers

Note

The SDK is at version 2.x, where FastMCP was renamed to MCPServer and moved to mcp.server.mcpserver. This is built against the current API rather than the superseded one.