hyperspell-mcp 0.1.0__tar.gz

hyperspell_mcp-0.1.0/.gitignore

@@ -0,0 +1,51 @@
+.DS_Store
+.env
+.env.*
+!.env.example
+apps/*/.env.local
+*.log
+node_modules
+
+# Local test scratchpad for development
+local_tests/
+
+# Personal scratch files (scripts, loom outlines, notes, etc.)
+scratch/
+
+# Git worktrees for isolated feature development
+/.worktrees
+.claude/worktrees
+
+# Python cache
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+apps/*/plans/*
+# ENG-2475: this plan travels with the migration stack (referenced from the spec)
+!apps/core/plans/resource_to_document_migration.md
+.vercel
+.terraform/
+
+# Per-session handoff/braindump docs — see CLAUDE.md "Session handoff notes"
+docs/handoffs/
+
+# Real-prod-sourced labeled cluster fixture (PII-bearing — produced by
+# `task api:seed-cluster-fixture` from prod canary apps then hand-labeled).
+# Keep local for scoring; don't commit Slack/email content to the repo.
+# labeled_docs/ fixtures use synthetic placeholders so they're safe; this
+# fixture carries full mention contexts from the source.
+apps/core/tests/fixtures/entity_extraction/labeled_clusters.json
+
+# Claude Code & agent runtime artifacts
+.agents/
+.claude/projects/
+.claude/*.lock
+.vercel-snapshots/
+AGENTIC_RESUME.md
+skills-lock.json
+infra/.terraform-version
+
+# Tool scratch (firecrawl scrapes, playwright-mcp snapshots) — never commit
+.firecrawl/
+.playwright-mcp/

hyperspell_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: hyperspell-mcp
+Version: 0.1.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.

hyperspell_mcp-0.1.0/README.md

@@ -0,0 +1,21 @@
+# 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.

hyperspell_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "hyperspell-mcp"
+version = "0.1.0"
+description = "Shared MCP tool catalog and backends for the Hyperspell company brain."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "mcp>=1.28,<2",
+    "httpx>=0.27,<1",
+    "pydantic>=2,<3",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hyperspell_mcp"]
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[tool.ruff]
+line-length = 100

hyperspell_mcp-0.1.0/src/hyperspell_mcp/__init__.py

@@ -0,0 +1,17 @@
+# @implements specs/components/unified-mcp-surface.md
+"""The single, canonical MCP surface for the Hyperspell company brain.
+
+One tool catalog, rendered through any ``BrainBackend`` (in-process on core-api, or
+HTTP from the local daemon). See ``specs/components/unified-mcp-surface.md``.
+"""
+
+from .backend import BrainBackend, HttpBackend, UserIdentityRequired
+from .catalog import register_context_tools, register_tools
+
+__all__ = [
+    "BrainBackend",
+    "HttpBackend",
+    "UserIdentityRequired",
+    "register_tools",
+    "register_context_tools",
+]

hyperspell_mcp-0.1.0/src/hyperspell_mcp/backend.py

@@ -0,0 +1,207 @@
+# @implements specs/components/unified-mcp-surface.md
+"""The backend seam for the unified MCP catalog.
+
+``BrainBackend`` is the only transport-specific surface. Methods take primitives and
+return the ``contract`` lite models; compaction and presentation live in the catalog.
+
+``HttpBackend`` is the thin client used by the local stdio daemon. ``InProcessBackend``
+lives in core-api (it imports the real route handlers) and is not part of this package.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+import httpx
+
+from .contract import (
+    ConnectionListLite,
+    JSONObject,
+    MemoryPageLite,
+    QueryResultRaw,
+    RememberResultLite,
+    clamp_page_size,
+    clamp_results,
+)
+
+
+class UserIdentityRequired(Exception):
+    """Raised when a user-scoped operation is attempted with an app-only credential."""
+
+
+@runtime_checkable
+class BrainBackend(Protocol):
+    """Data access for the brain tools, independent of transport."""
+
+    async def query(
+        self,
+        *,
+        query: str,
+        answer: bool,
+        effort: str,
+        max_results: int,
+        sources: list[str] | None = None,
+    ) -> QueryResultRaw: ...
+
+    async def remember(self, *, text: str, title: str | None) -> RememberResultLite: ...
+
+    async def list_memories(
+        self, *, source: str | None, status: str | None, size: int, cursor: str | None
+    ) -> MemoryPageLite: ...
+
+    async def list_connections(self) -> ConnectionListLite: ...
+
+    async def brain_status(self) -> JSONObject: ...
+
+
+class HttpBackend:
+    """``BrainBackend`` over HTTP against the Hyperspell REST API (~6 endpoints).
+
+    Used by the local stdio daemon. Auth is the config API key; an optional user id is
+    sent as ``X-As-User`` for user-scoped calls.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        user_id: str | None = None,
+        client: httpx.AsyncClient | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        # Cache of connected sources so the all-source fan-out costs one /auth/me per
+        # client lifetime, not one per query.
+        self._connected: list[str] | None = None
+        # Matches the hyperspell SDK's auth headers exactly: Bearer api key + X-As-User.
+        headers = {"Authorization": f"Bearer {api_key}"}
+        if user_id:
+            headers["X-As-User"] = user_id
+        if client is not None:
+            client.headers.update(headers)
+            self._client = client
+        else:
+            self._client = httpx.AsyncClient(
+                base_url=base_url.rstrip("/"), headers=headers, timeout=timeout
+            )
+
+    async def _connected_sources(self) -> list[str]:
+        """All sources to search by default: the vault plus every connected integration.
+
+        So ask/search fan out across Slack, email, Drive, etc. rather than silently
+        searching the vault only (the API defaults omitted ``sources`` to vault). Cached
+        for the client's lifetime.
+
+        Uses ``installed_integrations`` (actually connected by this user), NOT
+        ``available_integrations`` (everything configured on the app): a
+        configured-but-unconnected source is at best noise, and a live-only integration
+        would spin up a real-time component a stale token could fail. ``/auth/me`` is
+        called unconditionally — it authenticates any user-scoped credential, including
+        the daemon's device JWT, which carries no separate ``user_id``. Only a userless
+        app-only key 401s there and falls back to vault.
+        """
+        if self._connected is not None:
+            return self._connected
+        sources = ["vault"]
+        resp = await self._client.get("/auth/me")
+        if resp.status_code == 200:
+            for s in resp.json().get("installed_integrations") or []:
+                if s not in sources:
+                    sources.append(s)
+        self._connected = sources
+        return self._connected
+
+    async def query(
+        self,
+        *,
+        query: str,
+        answer: bool,
+        effort: str,
+        max_results: int,
+        sources: list[str] | None = None,
+    ) -> QueryResultRaw:
+        limit = clamp_results(max_results)
+        if sources is None:
+            sources = await self._connected_sources()
+        resp = await self._client.post(
+            "/memories/query",
+            json={
+                "query": query,
+                "answer": answer,
+                "effort": effort,
+                "sources": sources,
+                # Send max_results top-level only. QueryRequest's set_options validator
+                # copies the top-level value into options.max_results (the field the
+                # search reads); sending it under options instead would be overwritten by
+                # the top-level default (10).
+                "max_results": limit,
+            },
+        )
+        resp.raise_for_status()
+        return QueryResultRaw.model_validate(resp.json())
+
+    async def remember(self, *, text: str, title: str | None) -> RememberResultLite:
+        body: dict[str, object] = {"text": text}
+        if title:
+            body["title"] = title
+        resp = await self._client.post("/memories/add", json=body)
+        resp.raise_for_status()
+        return RememberResultLite.model_validate(resp.json())
+
+    async def list_memories(
+        self, *, source: str | None, status: str | None, size: int, cursor: str | None
+    ) -> MemoryPageLite:
+        params: dict[str, object] = {"size": clamp_page_size(size)}
+        if source:
+            params["source"] = source
+        if status:
+            params["status"] = status
+        if cursor:
+            params["cursor"] = cursor
+        resp = await self._client.get("/memories/list", params=params)
+        resp.raise_for_status()
+        data = resp.json()
+        return MemoryPageLite(documents=data.get("items", []), next_cursor=data.get("next_cursor"))
+
+    async def list_connections(self) -> ConnectionListLite:
+        # Don't gate on self._user_id: a device JWT is user-scoped but carries no
+        # separate user_id. Let the server decide — /connections/list 401/403s for a
+        # userless app-only key, which we surface as UserIdentityRequired.
+        resp = await self._client.get("/connections/list")
+        if resp.status_code in (401, 403):
+            raise UserIdentityRequired("list_connections requires a user identity")
+        resp.raise_for_status()
+        return ConnectionListLite.model_validate(resp.json())
+
+    async def brain_status(self) -> JSONObject:
+        """Network identity + coverage for this token (the remote-flavored brain_status).
+
+        ``/auth/me`` gives identity + connected integrations for any user-scoped
+        credential (incl. the daemon's device JWT, which has no separate user_id); a
+        userless app-only key 401s there but still gets app-wide coverage from
+        ``/memories/status``. Both calls are made unconditionally — no user_id gate.
+        """
+        status: JSONObject = {"app_id": None, "user_scoped": False}
+        me = await self._client.get("/auth/me")
+        if me.status_code == 200:
+            data = me.json()
+            app = data.get("app") or {}
+            status.update(
+                {
+                    "app_id": app.get("id"),
+                    "user_scoped": True,
+                    "available_integrations": data.get("available_integrations", []),
+                    "installed_integrations": data.get("installed_integrations", []),
+                }
+            )
+        # The spec's brain_status is "identity + brain health/coverage"; compose
+        # /memories/status for document-level coverage (works for app-only keys too).
+        # Best-effort: never fail brain_status if the status route is unavailable.
+        cov = await self._client.get("/memories/status")
+        if cov.status_code == 200:
+            status["coverage"] = cov.json()
+        return status
+
+    async def aclose(self) -> None:
+        """Close the underlying httpx client."""
+        await self._client.aclose()

hyperspell_mcp-0.1.0/src/hyperspell_mcp/catalog.py

@@ -0,0 +1,204 @@
+# @implements specs/components/unified-mcp-surface.md
+"""The canonical Hyperspell brain tool catalog, registered onto any FastMCP server.
+
+``register_tools`` is the single definition of the six brain tools + the ``ask_brain``
+prompt — names, descriptions, annotations, parameter defaults, and compaction all live
+here, once, and run against any ``BrainBackend``. ``register_context_tools`` adds the
+local-only filesystem tools and ``hyperbrain://`` resources for the stdio daemon.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from mcp.server.fastmcp import FastMCP
+from mcp.types import ToolAnnotations
+
+from . import context as ctx
+from .backend import BrainBackend, UserIdentityRequired
+from .contract import (
+    DEFAULT_EFFORT,
+    DOC_CITATION_FIELDS,
+    EFFORTS,
+    AskPayload,
+    ConnectionListLite,
+    JSONObject,
+    MemoryPageLite,
+    QueryResultRaw,
+    RememberResultLite,
+    SearchPayload,
+    clamp_page_size,
+    clamp_results,
+)
+
+_READ_QUERY = ToolAnnotations(readOnlyHint=True, openWorldHint=True)
+_READ_INTERNAL = ToolAnnotations(readOnlyHint=True, openWorldHint=False)
+_WRITE = ToolAnnotations(
+    readOnlyHint=False, destructiveHint=False, idempotentHint=False, openWorldHint=True
+)
+
+
+def _effort(value: str) -> str:
+    if value not in EFFORTS:
+        raise ValueError(f"effort must be one of {sorted(EFFORTS)}")
+    return value
+
+
+def _compact_doc(doc: JSONObject) -> JSONObject:
+    """Reduce a document to its citation fields (single definition of compaction)."""
+    return {k: doc[k] for k in DOC_CITATION_FIELDS if k in doc}
+
+
+def _ask_payload(raw: QueryResultRaw, full: bool) -> AskPayload:
+    """Assemble the ``ask`` wire payload — citations compacted unless ``full``."""
+    citations = raw.documents if full else [_compact_doc(d) for d in raw.documents]
+    return AskPayload(
+        answer=raw.answer, citations=citations, errors=raw.errors, query_id=raw.query_id
+    )
+
+
+def _search_payload(raw: QueryResultRaw, full: bool) -> SearchPayload:
+    """Assemble the ``search`` wire payload — documents compacted unless ``full``."""
+    documents = raw.documents if full else [_compact_doc(d) for d in raw.documents]
+    return SearchPayload(documents=documents, errors=raw.errors, query_id=raw.query_id)
+
+
+def register_tools(mcp: FastMCP, backend: BrainBackend) -> None:
+    """Register the six canonical brain tools + the ``ask_brain`` prompt on ``mcp``."""
+
+    async def ask(
+        question: str,
+        effort: str = DEFAULT_EFFORT,
+        max_results: int = 10,
+        full: bool = False,
+    ) -> AskPayload:
+        """Ask the company brain a question; returns a synthesized, cited answer."""
+        raw = await backend.query(
+            query=question,
+            answer=True,
+            effort=_effort(effort),
+            max_results=clamp_results(max_results),
+        )
+        return _ask_payload(raw, full)
+
+    async def search(
+        query: str,
+        max_results: int = 10,
+        effort: str = "minimal",
+        full: bool = False,
+    ) -> SearchPayload:
+        """Search the brain for ranked documents matching a query (no synthesis)."""
+        raw = await backend.query(
+            query=query,
+            answer=False,
+            effort=_effort(effort),
+            max_results=clamp_results(max_results),
+        )
+        return _search_payload(raw, full)
+
+    async def remember(text: str, title: str | None = None) -> RememberResultLite:
+        """Write a note/document into the brain so future queries surface it."""
+        return await backend.remember(text=text, title=title)
+
+    async def list_memories(
+        source: str | None = None,
+        status: str | None = None,
+        size: int = 25,
+        cursor: str | None = None,
+    ) -> MemoryPageLite:
+        """List indexed documents (one page); filter by source/status."""
+        return await backend.list_memories(
+            source=source, status=status, size=clamp_page_size(size), cursor=cursor
+        )
+
+    async def list_connections() -> ConnectionListLite:
+        """List the active integration connections for this user/app."""
+        try:
+            return await backend.list_connections()
+        except UserIdentityRequired:
+            return ConnectionListLite(error="user_identity_required")
+
+    async def brain_status() -> JSONObject:
+        """Report brain status for this token.
+
+        One tool, two behaviors by transport: the remote backend returns network
+        identity (app, user-scope, connected integrations); the local backend returns
+        filesystem sync status (is a summary synced, how to read it).
+        """
+        return await backend.brain_status()
+
+    mcp.tool(
+        description="Ask the company brain a question; returns a synthesized, cited answer.",
+        annotations=_READ_QUERY,
+    )(ask)
+    mcp.tool(
+        description="Search the brain for ranked documents matching a query (no synthesis).",
+        annotations=_READ_QUERY,
+    )(search)
+    mcp.tool(
+        description="Write a note/document into the brain so future queries surface it.",
+        annotations=_WRITE,
+    )(remember)
+    mcp.tool(
+        description="List indexed documents (one page); filter by source/status.",
+        annotations=_READ_INTERNAL,
+    )(list_memories)
+    mcp.tool(
+        description="List the active integration connections for this user/app.",
+        annotations=_READ_INTERNAL,
+    )(list_connections)
+    mcp.tool(
+        description="Report brain status and how to use it — local sync status on this "
+        "machine, or network identity and coverage.",
+        annotations=_READ_INTERNAL,
+    )(brain_status)
+
+    @mcp.prompt()
+    def ask_brain(question: str) -> str:
+        """Prompt the host to use the ``ask`` tool for a brain question."""
+        return f"Use the `ask` tool to answer this from the company brain: {question}"
+
+
+def register_context_tools(mcp: FastMCP, sync_dir: Path | str) -> None:
+    """Register the local-only filesystem tools + ``hyperbrain://`` resources.
+
+    These read the synced ``~/.hyperspell`` summary off local disk and make no API call,
+    so they are only meaningful on the stdio (daemon) transport. The reachability and
+    symlink-escape hardening lives in ``context`` and is shared with the read resource.
+    """
+    root = Path(sync_dir).expanduser()
+
+    async def list_context() -> list[str]:
+        """List the locally-synced company-brain summary files (no API call)."""
+        return ctx.list_context_paths(root)
+
+    async def read_context(path: str) -> str:
+        """Read one locally-synced summary file by its relative path (no API call)."""
+        return ctx.read_context_file(root, path)
+
+    async def grep_context(query: str, max_results: int = 50) -> JSONObject:
+        """Case-insensitive substring search over the local summary tree (no API call)."""
+        return ctx.grep_context(root, query, max_results)
+
+    mcp.tool(
+        description="List the locally-synced company-brain summary files (no API call).",
+        annotations=_READ_INTERNAL,
+    )(list_context)
+    mcp.tool(
+        description="Read one locally-synced summary file by its relative path (no API call).",
+        annotations=_READ_INTERNAL,
+    )(read_context)
+    mcp.tool(
+        description="Keyword-search across the locally-synced summary (no API call).",
+        annotations=_READ_INTERNAL,
+    )(grep_context)
+
+    @mcp.resource("hyperbrain://context")
+    def context_index() -> list[str]:
+        """The list of locally-synced summary files."""
+        return ctx.list_context_paths(root)
+
+    @mcp.resource("hyperbrain://context/{path}")
+    def context_file(path: str) -> str:
+        """The contents of one locally-synced summary file."""
+        return ctx.read_context_file(root, path)