Metadata-Version: 2.5
Name: hyperspell-mcp
Version: 0.15.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,
  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.
