indx 0.0.1__py3-none-any.whl

indx/__init__.py

@@ -0,0 +1,36 @@
+"""indx — make directories AI-ready, not just files.
+
+Public SDK surface. The CLI is this same surface with handles (CLI⇄SDK parity).
+"""
+
+from indx._version import __version__
+from indx.core import (
+    Chunk,
+    Document,
+    KnowledgeSpace,
+    Manifest,
+    ParsedDoc,
+    Relation,
+    RelationType,
+    Source,
+    SpaceContext,
+    SpaceStats,
+)
+from indx.pipeline import DirectoryPipeline
+from indx.store.base import SearchHit
+
+__all__ = [
+    "__version__",
+    "DirectoryPipeline",
+    "KnowledgeSpace",
+    "Manifest",
+    "Document",
+    "Chunk",
+    "Relation",
+    "RelationType",
+    "ParsedDoc",
+    "Source",
+    "SearchHit",
+    "SpaceContext",
+    "SpaceStats",
+]

indx/_version.py

@@ -0,0 +1,3 @@
+"""Single source of version truth."""
+
+__version__ = "0.0.1"

indx/agent/__init__.py

@@ -0,0 +1,54 @@
+"""indx.agent — plug a knowledge space into any AI agent, USB-drive style.
+
+A ``.indx`` archive is a portable knowledge space. This package is the plug: one call turns
+it into tools for whichever agent framework you use.
+
+```python
+from indx.agent import connect
+
+kb = connect("ai-ready/handbook.indx")     # load the "USB drive"
+
+kb.langchain()        # LangChain StructuredTools  (+ kb.langchain_retriever())
+kb.openai()           # OpenAI Agents SDK function tools
+kb.pydantic_ai()      # Pydantic AI tools
+kb.claude()           # Claude Agent SDK in-process MCP server
+kb.mcp()              # FastMCP server — Mastra & any MCP client
+```
+
+Or run it as a standalone MCP server from the shell — ``indx mcp ai-ready/handbook.indx`` —
+and connect Claude Desktop, Cursor, or Mastra to it with no Python glue.
+
+Importing this package is safe on a bare ``pip install indx``: the framework adapters are
+imported lazily and each gates on its own optional extra (``indx[langchain]``,
+``indx[openai-agents]``, ``indx[pydantic-ai]``, ``indx[claude-agent]``, ``indx[mcp]`` — or
+``indx[agent]`` for all of them).
+"""
+
+from indx.agent.connector import KnowledgeConnector, connect
+from indx.agent.schema import (
+    GET_DOCUMENT_TOOL,
+    OVERVIEW_TOOL,
+    SEARCH_TOOL,
+    TOOLS,
+    DocumentCard,
+    DocumentDetail,
+    Hit,
+    SearchResults,
+    SpaceOverview,
+    ToolDef,
+)
+
+__all__ = [
+    "connect",
+    "KnowledgeConnector",
+    "Hit",
+    "SearchResults",
+    "DocumentCard",
+    "DocumentDetail",
+    "SpaceOverview",
+    "ToolDef",
+    "TOOLS",
+    "SEARCH_TOOL",
+    "OVERVIEW_TOOL",
+    "GET_DOCUMENT_TOOL",
+]

indx/agent/claude_agent.py

@@ -0,0 +1,62 @@
+"""Claude Agent SDK adapter: expose a knowledge space as an in-process MCP server.
+
+The Claude Agent SDK consumes tools as MCP servers. :func:`to_claude_mcp_server` builds an
+*in-process* SDK MCP server (no subprocess, no socket) from the canonical operations; hand it
+to ``ClaudeAgentOptions(mcp_servers={"indx": server})`` and the agent can search the space.
+
+The ``claude_agent_sdk`` package is the optional ``claude-agent`` extra, imported lazily and
+gated by :func:`~indx.utils.lazy.require_extra`; importing this module is always safe.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from indx.agent.connector import KnowledgeConnector
+from indx.agent.schema import GET_DOCUMENT_TOOL, OVERVIEW_TOOL, SEARCH_TOOL
+from indx.utils.lazy import require_extra
+
+
+def _text_result(payload: Any) -> dict[str, Any]:
+    """Wrap a JSON-able payload in the SDK's ``{"content": [{"type": "text", ...}]}`` shape."""
+    import json
+
+    return {"content": [{"type": "text", "text": json.dumps(payload, ensure_ascii=False)}]}
+
+
+def to_claude_mcp_server(connector: KnowledgeConnector, *, name: str = "indx") -> Any:
+    """Build an in-process Claude Agent SDK MCP server exposing the space's tools."""
+    require_extra("agent connector", "claude-agent", "claude-agent", "claude_agent_sdk")
+    from claude_agent_sdk import (  # type: ignore[import-not-found]  # optional extra: claude-agent
+        create_sdk_mcp_server,
+        tool,
+    )
+
+    @tool(  # type: ignore[untyped-decorator]
+        SEARCH_TOOL.name,
+        SEARCH_TOOL.description,
+        {"query": str, "k": int, "doc_type": str},
+    )
+    async def search(args: dict[str, Any]) -> dict[str, Any]:
+        return _text_result(
+            connector.call(
+                SEARCH_TOOL.name,
+                {
+                    "query": args["query"],
+                    "k": args.get("k", connector.default_k),
+                    "doc_type": args.get("doc_type"),
+                },
+            )
+        )
+
+    @tool(OVERVIEW_TOOL.name, OVERVIEW_TOOL.description, {"sample": int})  # type: ignore[untyped-decorator]
+    async def overview(args: dict[str, Any]) -> dict[str, Any]:
+        return _text_result(connector.call(OVERVIEW_TOOL.name, {"sample": args.get("sample", 10)}))
+
+    @tool(GET_DOCUMENT_TOOL.name, GET_DOCUMENT_TOOL.description, {"path_or_id": str})  # type: ignore[untyped-decorator]
+    async def get_document(args: dict[str, Any]) -> dict[str, Any]:
+        return _text_result(
+            connector.call(GET_DOCUMENT_TOOL.name, {"path_or_id": args["path_or_id"]})
+        )
+
+    return create_sdk_mcp_server(name=name, tools=[search, overview, get_document])

indx/agent/connector.py

@@ -0,0 +1,309 @@
+"""KnowledgeConnector — plug a knowledge space into any AI agent, USB-drive style.
+
+A ``.indx`` archive is a portable knowledge space: the "USB drive" you carry between
+machines and agents. :class:`KnowledgeConnector` is the plug. It wraps a
+:class:`~indx.core.knowledge_space.KnowledgeSpace` and exposes a tiny, stable set of
+agent operations — **search**, **overview**, **get_document** — plus one-call adapters that
+hand those operations to whichever agent framework you use:
+
+* :meth:`~KnowledgeConnector.langchain` / :meth:`~KnowledgeConnector.langchain_retriever`
+* :meth:`~KnowledgeConnector.openai`        (OpenAI Agents SDK)
+* :meth:`~KnowledgeConnector.pydantic_ai`   (Pydantic AI)
+* :meth:`~KnowledgeConnector.claude`        (Claude Agent SDK, in-process MCP server)
+* :meth:`~KnowledgeConnector.mcp`           (Model Context Protocol — Mastra & any client)
+
+For frameworks not covered, :meth:`openai_schema` / :meth:`anthropic_schema` emit raw
+tool specs and :meth:`call` dispatches a tool call by name — enough to wire the bare
+Chat Completions / Messages API by hand.
+
+This module imports **no vendor SDKs at top level**; every adapter is imported lazily inside
+its method and gated by :func:`~indx.utils.lazy.require_extra`, so ``import indx.agent`` is
+safe on a bare ``pip install indx`` (file-architecture §5, coding-standards §6.3).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from indx.agent.schema import (
+    GET_DOCUMENT_TOOL,
+    OVERVIEW_TOOL,
+    SEARCH_TOOL,
+    TOOLS,
+    DocumentCard,
+    DocumentDetail,
+    Hit,
+    SearchResults,
+    SpaceOverview,
+    ToolDef,
+)
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from indx.core.knowledge_space import KnowledgeSpace
+
+
+class KnowledgeConnector:
+    """An agent-ready handle on a single knowledge space.
+
+    Construct it directly from an in-memory space, or use :meth:`open` / the module-level
+    :func:`connect` to load a ``.indx`` archive (or an output directory) from disk.
+
+    Attributes:
+        name: A short identifier for the space, surfaced to the agent in tool descriptions
+            and used as the default MCP server name.
+        default_k: The number of hits :meth:`search` returns when ``k`` is unset.
+        with_context: When true, every :meth:`search` hit carries its neighbor chunks' text
+            in ``hit.context`` for wider grounding windows.
+    """
+
+    def __init__(
+        self,
+        space: KnowledgeSpace,
+        *,
+        name: str = "indx",
+        default_k: int = 5,
+        with_context: bool = False,
+    ) -> None:
+        self._space = space
+        self.name = name
+        self.default_k = default_k
+        self.with_context = with_context
+
+    @classmethod
+    def open(
+        cls,
+        source: str | Path | KnowledgeSpace,
+        *,
+        name: str | None = None,
+        default_k: int = 5,
+        with_context: bool = False,
+    ) -> KnowledgeConnector:
+        """Load a knowledge space from ``source`` and wrap it.
+
+        ``source`` may be an already-loaded :class:`KnowledgeSpace`, a path to a ``.indx``
+        archive, or an output directory containing one (the same inputs ``indx inspect`` /
+        ``indx query`` accept). ``name`` defaults to the archive's file stem.
+        """
+        from indx.core.knowledge_space import KnowledgeSpace
+
+        if isinstance(source, KnowledgeSpace):
+            space = source
+            label = name or "indx"
+        else:
+            # Reuse the CLI loader so the connector accepts every on-disk shape the CLI does
+            # (a .indx file, a directory holding one, or a jsonl output directory).
+            from indx.cli._render import load_space
+
+            path = Path(source)
+            space = load_space(path)
+            label = name or (path.stem if path.is_file() else path.name or "indx")
+
+        return cls(space, name=label, default_k=default_k, with_context=with_context)
+
+    @property
+    def space(self) -> KnowledgeSpace:
+        """The wrapped :class:`KnowledgeSpace` (read access for advanced callers)."""
+        return self._space
+
+    # ------------------------------------------------------------------ operations
+
+    def search(
+        self,
+        query: str,
+        k: int | None = None,
+        doc_type: str | None = None,
+        *,
+        with_context: bool | None = None,
+    ) -> SearchResults:
+        """Semantic search over the space; the backbone of the ``indx_search`` tool.
+
+        Routes through :meth:`KnowledgeSpace.search` (CLI ⇄ SDK parity), then flattens each hit
+        into a JSON-primitive :class:`~indx.agent.schema.Hit`. When ``doc_type`` is given,
+        results are filtered to that detected type, over-fetching first so a full ``k`` can
+        still come back.
+        """
+        k = k or self.default_k
+        want_context = self.with_context if with_context is None else with_context
+
+        raw = self._space.search(query, k=k * 5 if doc_type else k)
+
+        hits: list[Hit] = []
+        for hit in raw:
+            doc = self._space.document(hit.chunk.doc_id)
+            hit_type = (hit.source.type if hit.source else None) or (doc.doc_type if doc else None)
+            if doc_type and (hit_type or "unknown") != doc_type:
+                continue
+            hits.append(
+                Hit(
+                    chunk_id=hit.chunk.id,
+                    document_id=hit.chunk.doc_id,
+                    score=hit.score,
+                    text=hit.chunk.text,
+                    source=(hit.source.path if hit.source else (doc.path if doc else None)),
+                    folder=(hit.source.folder if hit.source else (doc.folder if doc else "")),
+                    doc_type=hit_type,
+                    topics=list(doc.topics) if doc else [],
+                    tags=list(doc.tags) if doc else [],
+                    context=[c.text for c in hit.neighbors] if want_context else [],
+                )
+            )
+            if len(hits) >= k:
+                break
+
+        return SearchResults(query=query, count=len(hits), hits=hits)
+
+    def overview(self, sample: int = 10) -> SpaceOverview:
+        """Summarize the space; the backbone of the ``indx_overview`` tool."""
+        stats = self._space.stats
+        cards = [self._card(doc) for doc in self._space.documents()[: max(sample, 0)]]
+        return SpaceOverview(
+            name=self.name,
+            documents=stats.documents,
+            chunks=stats.chunks,
+            relations=stats.relations,
+            embeddings=stats.embeddings,
+            embedding_model=self._space.manifest.embedding_model,
+            embedding_dim=stats.embed_dim,
+            types=dict(stats.types),
+            sample_documents=cards,
+        )
+
+    def get_document(self, path_or_id: str) -> DocumentDetail | None:
+        """Fetch one document's full text + metadata; the backbone of ``indx_get_document``.
+
+        Resolves ``path_or_id`` against document ids first, then exact paths, then a path
+        suffix match (so ``remote-work.md`` finds ``people/remote-work.md``). Returns ``None``
+        when nothing matches.
+        """
+        doc = self._space.document(path_or_id)
+        if doc is None:
+            docs = self._space.documents()
+            doc = next((d for d in docs if d.path == path_or_id), None)
+            if doc is None:
+                doc = next((d for d in docs if d.path.endswith(path_or_id)), None)
+        if doc is None:
+            return None
+
+        chunks = sorted(self._space.chunks_for(doc.id), key=lambda c: c.position)
+        card = self._card(doc)
+        return DocumentDetail(
+            **card.model_dump(),
+            chunk_count=len(chunks),
+            text="\n\n".join(c.text for c in chunks),
+        )
+
+    @staticmethod
+    def _card(doc: Any) -> DocumentCard:
+        return DocumentCard(
+            id=doc.id,
+            path=doc.path,
+            doc_type=doc.doc_type,
+            folder=doc.folder,
+            topics=list(doc.topics),
+            tags=list(doc.tags),
+            summary=doc.summary,
+        )
+
+    # ------------------------------------------------------------------ raw specs
+
+    def tools(self) -> list[ToolDef]:
+        """The canonical, framework-agnostic tool definitions for this space."""
+        return list(TOOLS)
+
+    def openai_schema(self) -> list[dict[str, Any]]:
+        """Tool specs in OpenAI Chat Completions / Responses ``tools=[...]`` shape."""
+        return [{"type": "function", "function": t.model_dump()} for t in self.tools()]
+
+    def anthropic_schema(self) -> list[dict[str, Any]]:
+        """Tool specs in Anthropic Messages API ``tools=[...]`` shape."""
+        return [
+            {"name": t.name, "description": t.description, "input_schema": t.parameters}
+            for t in self.tools()
+        ]
+
+    def call(self, name: str, arguments: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Dispatch a tool call by ``name`` and return a JSON-able result.
+
+        This is the single execution path every adapter and the MCP server funnel through, so
+        a tool behaves identically regardless of which framework invoked it. Unknown names
+        raise :class:`ValueError`.
+        """
+        args = arguments or {}
+        if name == SEARCH_TOOL.name:
+            return self.search(
+                query=args["query"],
+                k=args.get("k"),
+                doc_type=args.get("doc_type"),
+            ).model_dump(mode="json")
+        if name == OVERVIEW_TOOL.name:
+            return self.overview(sample=args.get("sample", 10)).model_dump(mode="json")
+        if name == GET_DOCUMENT_TOOL.name:
+            detail = self.get_document(args["path_or_id"])
+            if detail is None:
+                return {"error": f"no document matching {args['path_or_id']!r}"}
+            return detail.model_dump(mode="json")
+        raise ValueError(f"unknown tool {name!r}; known tools: {[t.name for t in TOOLS]}")
+
+    # ------------------------------------------------------------------ adapters
+
+    def langchain(self) -> list[Any]:
+        """Return LangChain ``StructuredTool``s for this space (needs ``indx[langchain]``)."""
+        from indx.agent.langchain import to_langchain_tools
+
+        return to_langchain_tools(self)
+
+    def langchain_retriever(self, k: int | None = None) -> Any:
+        """Return a LangChain ``BaseRetriever`` over this space (needs ``indx[langchain]``)."""
+        from indx.agent.langchain import to_langchain_retriever
+
+        return to_langchain_retriever(self, k=k or self.default_k)
+
+    def openai(self) -> list[Any]:
+        """Return OpenAI Agents SDK ``function_tool``s (needs ``indx[openai-agents]``)."""
+        from indx.agent.openai_agents import to_openai_agent_tools
+
+        return to_openai_agent_tools(self)
+
+    def pydantic_ai(self) -> list[Any]:
+        """Return Pydantic AI ``Tool``s for this space (needs ``indx[pydantic-ai]``)."""
+        from indx.agent.pydantic_ai import to_pydantic_ai_tools
+
+        return to_pydantic_ai_tools(self)
+
+    def claude(self, *, name: str | None = None) -> Any:
+        """Return an in-process Claude Agent SDK MCP server (needs ``indx[claude-agent]``)."""
+        from indx.agent.claude_agent import to_claude_mcp_server
+
+        return to_claude_mcp_server(self, name=name or self.name)
+
+    def mcp(self, *, name: str | None = None) -> Any:
+        """Return a ``FastMCP`` server exposing this space (needs ``indx[mcp]``)."""
+        from indx.agent.mcp import build_mcp_server
+
+        return build_mcp_server(self, name=name or self.name)
+
+    def serve(self, *, transport: str = "stdio", name: str | None = None) -> None:
+        """Run an MCP server over ``transport`` until interrupted (needs ``indx[mcp]``).
+
+        This is what ``indx mcp <archive>`` calls: it turns the knowledge space into a live
+        MCP endpoint that Claude Desktop, Mastra, Cursor, or any MCP client can connect to.
+        """
+        self.mcp(name=name).run(transport=transport)
+
+
+def connect(
+    source: str | Path | KnowledgeSpace,
+    *,
+    name: str | None = None,
+    default_k: int = 5,
+    with_context: bool = False,
+) -> KnowledgeConnector:
+    """Plug a knowledge space into an agent in one line — ``connect("space.indx")``.
+
+    A thin alias for :meth:`KnowledgeConnector.open`; the headline entry point of
+    :mod:`indx.agent`.
+    """
+    return KnowledgeConnector.open(
+        source, name=name, default_k=default_k, with_context=with_context
+    )

indx/agent/langchain.py

@@ -0,0 +1,106 @@
+"""LangChain adapter: expose a knowledge space as tools and a retriever.
+
+Two integration points, both built on :class:`~indx.agent.connector.KnowledgeConnector`:
+
+* :func:`to_langchain_tools` — ``StructuredTool``s an agent can call (search / overview /
+  get_document), the agentic path.
+* :func:`to_langchain_retriever` — a ``BaseRetriever`` that returns LangChain ``Document``s,
+  the classic RAG path (drop it into any retrieval chain).
+
+``langchain-core`` is the optional ``langchain`` extra, imported lazily and gated by
+:func:`~indx.utils.lazy.require_extra`; importing this module is always safe.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from indx.agent.connector import KnowledgeConnector
+from indx.agent.schema import GET_DOCUMENT_TOOL, OVERVIEW_TOOL, SEARCH_TOOL
+from indx.utils.lazy import require_extra
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from langchain_core.callbacks import (  # type: ignore[import-not-found]  # optional extra: langchain
+        CallbackManagerForRetrieverRun,
+    )
+    from langchain_core.documents import (  # type: ignore[import-not-found]  # optional extra: langchain
+        Document,
+    )
+    from langchain_core.tools import (  # type: ignore[import-not-found]  # optional extra: langchain
+        StructuredTool,
+    )
+
+
+def to_langchain_tools(connector: KnowledgeConnector) -> list[StructuredTool]:
+    """Build LangChain ``StructuredTool``s (search / overview / get_document) for the space."""
+    require_extra("agent connector", "langchain", "langchain", "langchain_core")
+    from langchain_core.tools import StructuredTool  # optional extra: langchain
+
+    def _search(query: str, k: int = 5, doc_type: str | None = None) -> dict[str, Any]:
+        return connector.call(SEARCH_TOOL.name, {"query": query, "k": k, "doc_type": doc_type})
+
+    def _overview(sample: int = 10) -> dict[str, Any]:
+        return connector.call(OVERVIEW_TOOL.name, {"sample": sample})
+
+    def _get_document(path_or_id: str) -> dict[str, Any]:
+        return connector.call(GET_DOCUMENT_TOOL.name, {"path_or_id": path_or_id})
+
+    return [
+        StructuredTool.from_function(
+            func=_search, name=SEARCH_TOOL.name, description=SEARCH_TOOL.description
+        ),
+        StructuredTool.from_function(
+            func=_overview, name=OVERVIEW_TOOL.name, description=OVERVIEW_TOOL.description
+        ),
+        StructuredTool.from_function(
+            func=_get_document,
+            name=GET_DOCUMENT_TOOL.name,
+            description=GET_DOCUMENT_TOOL.description,
+        ),
+    ]
+
+
+def to_langchain_retriever(connector: KnowledgeConnector, *, k: int = 5) -> Any:
+    """Build a LangChain ``BaseRetriever`` that returns ``Document``s from the space.
+
+    Each retrieved ``Document`` carries the chunk text as ``page_content`` and the hit's
+    provenance (source path, document type, score, topics, tags) as JSON-primitive
+    ``metadata`` — the same metadata shape the ``langchain`` output writer emits.
+    """
+    require_extra("agent connector", "langchain", "langchain", "langchain_core")
+    from langchain_core.documents import Document  # optional extra: langchain
+    from langchain_core.retrievers import (  # type: ignore[import-not-found]  # optional extra: langchain
+        BaseRetriever,
+    )
+
+    class IndxRetriever(BaseRetriever):  # type: ignore[misc]  # BaseRetriever is Any without the extra
+        """Retrieve indx knowledge-space chunks as LangChain ``Document``s."""
+
+        connector: Any
+        k: int = 5
+
+        def _get_relevant_documents(
+            self,
+            query: str,
+            *,
+            run_manager: CallbackManagerForRetrieverRun | None = None,
+        ) -> list[Document]:
+            results = self.connector.search(query, k=self.k)
+            return [
+                Document(
+                    id=hit.chunk_id,
+                    page_content=hit.text,
+                    metadata={
+                        "doc_id": hit.document_id,
+                        "score": hit.score,
+                        "source": hit.source,
+                        "folder": hit.folder,
+                        "doc_type": hit.doc_type,
+                        "topics": hit.topics,
+                        "tags": hit.tags,
+                    },
+                )
+                for hit in results.hits
+            ]
+
+    return IndxRetriever(connector=connector, k=k)

indx/agent/mcp.py

@@ -0,0 +1,72 @@
+"""MCP server: serve a knowledge space over the Model Context Protocol.
+
+MCP is the universal connector — Claude Desktop, Cursor, Mastra (TypeScript), and any other
+MCP client speak it, so one ``indx mcp <archive>`` command plugs a knowledge space into all
+of them, no Python glue on the client side. :func:`build_mcp_server` builds a ``FastMCP``
+server exposing the canonical search / overview / get_document tools;
+:meth:`KnowledgeConnector.serve` runs it.
+
+FastMCP does the heavy lifting: it derives each tool's JSON schema from the handler's typed
+signature and owns the transport loop. We prefer the standalone, batteries-included
+``fastmcp`` package (v2) and fall back to the ``FastMCP`` bundled in the official ``mcp`` SDK
+(v1) — either satisfies the ``indx[mcp]`` extra. Imports are lazy, so importing this module is
+always safe on a core-only install.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from indx.agent.connector import KnowledgeConnector
+from indx.errors import MissingExtraError
+
+
+def _load_fastmcp() -> Any:
+    """Return a ``FastMCP`` class, preferring the standalone ``fastmcp`` over the bundled one.
+
+    Raises :class:`MissingExtraError` (the standard ``pip install indx[mcp]`` message) if
+    neither is installed — mirroring :func:`~indx.utils.lazy.require_extra` for the
+    "either of two modules" case it can't express directly.
+    """
+    try:
+        from fastmcp import FastMCP  # type: ignore[import-not-found]  # optional extra: mcp
+
+        return FastMCP
+    except ModuleNotFoundError:
+        pass
+    try:
+        from mcp.server.fastmcp import (  # type: ignore[import-not-found]  # optional extra: mcp
+            FastMCP,
+        )
+
+        return FastMCP
+    except ModuleNotFoundError:
+        raise MissingExtraError(slot="agent connector", name="mcp", extra="mcp") from None
+
+
+def build_mcp_server(connector: KnowledgeConnector, *, name: str | None = None) -> Any:
+    """Build a ``FastMCP`` server exposing the space's tools (search/overview/get_document).
+
+    Tools are registered with ``add_tool`` (rather than the ``@server.tool`` decorator) so the
+    handler functions keep their static types — mypy stays strict over this module.
+    """
+    fast_mcp = _load_fastmcp()
+    server = fast_mcp(name or connector.name)
+
+    def indx_search(query: str, k: int = 5, doc_type: str | None = None) -> dict[str, Any]:
+        """Semantic search over the indx knowledge space."""
+        return connector.search(query, k=k, doc_type=doc_type).model_dump(mode="json")
+
+    def indx_overview(sample: int = 10) -> dict[str, Any]:
+        """Describe the knowledge space: counts, types, sample documents."""
+        return connector.overview(sample=sample).model_dump(mode="json")
+
+    def indx_get_document(path_or_id: str) -> dict[str, Any]:
+        """Fetch one document's full text and metadata by path or id."""
+        detail = connector.get_document(path_or_id)
+        return detail.model_dump(mode="json") if detail else {"error": "not found"}
+
+    server.add_tool(indx_search)
+    server.add_tool(indx_overview)
+    server.add_tool(indx_get_document)
+    return server