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.15.0 disables brain generation, configuration changes, and connection revocation over MCP. The implementations and backend protocol remain intact for a deliberate future re-enable, but discovery omits the tools and cached calls fail. Read-only configuration access remains available. Core and CLI adapters enforce the same policy even when installed with earlier catalogs; after publication, update their dependency pins/locks and remove only the temporary fallback policy copies, not the retained implementations. Direct authorized REST and CLI administration is unchanged.

Version 0.14.0 adds get_memory(cursor=None, response_profile="api") to the backend protocol. The catalog selects the MCP profile, and HttpBackend forwards the cursor and documented profile header. Slack/Teams point reads on a supporting Core server return authorized pages of indexed chunks (up to 16 chunks and 32 KiB of JSON), with body_status, notices, and an optional next_cursor. Pass that cursor to the next get_memory call; an empty page may still have a continuation. Responses never include full channel history, and permissions are rechecked for every page. Other providers keep their existing read behavior. Older custom adapters remain callable without a cursor; attempts to continue through an adapter without cursor support fail explicitly.

Version 0.13.0 added query(response_profile="api") to the backend protocol. The catalog selects mcp for ask/search; HttpBackend forwards it in the documented X-Hyperspell-Response-Profile request header. Direct backend callers keep the API default. Query date bounds (after/before) also ship in 0.13.0; listing response profiles have been available since 0.11.0.

Custom adapters must accept and honor or forward the profile, including adapters with **kwargs. Older adapters that cannot accept it remain callable with their legacy budgets; upgrading only the catalog does not activate MCP limits on those adapters. Hosted Core queries already select the MCP profile.

Compact query results preserve supplied excerpt/omitted body statuses and limitation errors. Full/preview or unknown statuses are dropped when the body is removed, because highlights can be generated summaries. Compact listing stubs contain no source content, so a supplied status becomes omitted; legacy absent statuses stay absent. full=true preserves the server representation and status. This release does not activate query body_mode, automatic full bodies, or bounded explicit reads for other providers or body-enabled listings.

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