Metadata-Version: 2.5
Name: hyperspell-mcp
Version: 0.19.0
Summary: Shared MCP tool catalog and backends for the Hyperspell company brain.
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Requires-Dist: mcp<2,>=1.28
Requires-Dist: pydantic<3,>=2
Description-Content-Type: text/markdown

# 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.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.
