hyperspell-mcp

The single, canonical Model Context Protocol surface for the Hyperspell company brain.

This package owns the tool catalog (names, descriptions, annotations, parameter defaults, compaction) and the backend seam that lets the same catalog run over two transports:

• Remote — register_tools(mcp, InProcessBackend()) mounted as Streamable HTTP at /mcp on core-api. InProcessBackend lives in core-api because it calls the real route handlers in-process.
• Local — register_tools(mcp, HttpBackend(...)) run over stdio by the sync daemon, plus register_context_tools(mcp, sync_dir) for the disk-only *_context tools and hyperbrain:// resources.

It deliberately does not copy core-api's request models. The tool parameters are simple primitives; the only shared models are the lightweight response ("lite") models that results are validated into so compaction is defined exactly once.

See specs/components/unified-mcp-surface.md for the full design and the minimum-maintenance invariants.

Version 0.11.0 forwards the MCP response profile before listing reads and preserves limitation notices, continuation, and supplied body status. It does not activate bounded bodies on the explicit full=true listing path. Custom BrainBackend implementations accept list_memories(response_profile="api") to select server budgets. Adapters accepting arbitrary keyword arguments receive the profile too and must honor or forward it. Older adapters that cannot accept this keyword remain callable with their legacy budgets; upgrading only the catalog does not activate the MCP budget on those adapters.

Core and the CLI install this package from PyPI. Merge the matching backend adapters before publishing 0.11.0, then update both consumers' dependency pins/locks to activate the catalog. Older API servers do not enforce the new limits; clients must not infer a bounded response from the package version alone.