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. Context tool/resource registration is retained but disabled.

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.23.1 requests query provenance at every effort. provenance.turns keeps each native provider summary beside that turn's calls and observed outcomes; unavailable summaries are null and calls may be empty. This records existing model calls without adding calls or enabling thinking at lower efforts. Deploy Core's all-effort turn collection first; older servers may return no lower-effort trace, which clients retain without fabricating summaries. Correctable HTTP 422 query rejections retain an empty turns envelope.

Version 0.22.0 adds log_activity: an agent records what it just did as one dated activity entry (a Vault memory with kind = agent_activity metadata, plus agent and workstream when given). share defaults to suggest: the entry stays private to the user and asks them, in their Inbox, whether to share it with the company (personal and shared are the other values). That is the user-tied case (OAuth, a personal key); with a user-less workspace key every write is the company's already, so suggest and shared write it as such and personal is refused (422). entry_id revises one entry in place instead of adding another (one entry per session); it is written under the activity- resource-id namespace, so the tool can never revise a memory saved with remember. Advertised only by adapters that implement it. Merge and deploy the matching hosted/local adapters before publishing, then update the consumer locks.

Version 0.23.0 rejects unknown arguments on the live-query tools before reaching the backend. GET filters belong in query, and read-via-POST arguments in body; params is rejected instead of silently returning unfiltered data. Upgrade both the hosted Core and local CLI dependency to activate this validation.

Version 0.20.0 updates the recency_half_life_days description for ask and search: age now reduces a result's score by at most 50% (one half-life retains 75%, two retain 62.5%), matching core-api's ranking. The parameter, its type, and the omitted-value behavior are unchanged. Deploy core-api first so the description never promises a stronger preference than the server applies.

Version 0.19.0 adds update_memory: replace the text and/or title of a Vault memory (one saved with remember) in place, keeping its resource_id. It is destructive but idempotent, Vault-only (a synced document's next sync would overwrite an edit), and advertised only by adapters that implement it. Merge and deploy the matching hosted/local adapters before publishing, then update the consumer locks.

Version 0.18.0 adds search_entities, get_entity, and get_entity_mentions. Search matches names (an empty query lists one page); it does not run an embedding or a model. Reads preserve the caller's document access, source references, possible-match labels and pagination. HTTP consumers reject entity responses from servers that do not advertise the permission-aware entity contract. Merge and deploy the matching hosted/local adapters before publishing this package, then update the consumer locks. This package release alone cannot update an installed CLI adapter.

Version 0.17.0 additionally disables brain_status, list_context, read_context, and grep_context, including cached calls and local hyperbrain://context resources. Its 12 enabled tools query or manage indexed sources; MCP instructions lead with ask, search, and get_memory, not generated summaries. Stored summaries, filesystem helpers, REST, ordinary CLI, and daemon behavior are unchanged. Local clients need the updated CLI release (0.5.12 or newer); a server deployment alone cannot change an already-installed stdio server.

Version 0.16.0 also disables app integration configuration discovery and brain-config reads over MCP, alongside the generation, configuration changes, and connection revocation disabled in 0.15.0. The implementations and backend protocol remain intact for a deliberate future re-enable, but discovery omits the tools and cached calls fail. list_connections remains available for the caller's actual connected accounts. 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.