mcp-capability-router 0.1.0__tar.gz

mcp_capability_router-0.1.0/.env.example

@@ -0,0 +1,20 @@
+# Environment template. Copy to .env and fill in real values; .env is git-ignored.
+#
+# mcp-capability-router does not define its own model configuration surface.
+# Instantiate whichever LangChain-compatible chat model class your application already
+# uses (ChatOpenAI, ChatLiteLLM, ChatAnthropic, ...) directly in code, and configure it
+# with that class's own constructor arguments or the environment variables it documents.
+#
+# Example (see examples/create_agent_routing.py):
+#   from langchain_openai import ChatOpenAI
+#   model = ChatOpenAI(model="gpt-5.6-luna", base_url=..., api_key=...)
+
+# Used by the ChatOpenAI-based examples in this repository.
+EXPLABS_API_KEY=
+EXPLABS_BASE_URL=https://api.experientiallabs.ai/v1
+EXPLABS_MODEL=gpt-5.6-luna
+
+# Optional MCP application settings (adapt to your transport/client).
+MCP_SERVER_NAME=filesystem
+MCP_SERVER_COMMAND=npx
+MCP_SERVER_ROOT=

mcp_capability_router-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: CI
+on:
+  push:
+  pull_request:
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --extra dev
+      - run: uv run pytest
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pyrefly check
+      - run: uv run mkdocs build
+

mcp_capability_router-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# Virtual environments
+.venv/
+venv/
+
+# uv
+.python-version
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+
+# Docs build output
+site/
+
+# Playwright MCP output (snapshots written by @playwright/mcp when run locally)
+.playwright-mcp/
+
+# Environment secrets (never commit real values)
+.env
+.env.*
+!.env.example
+
+# Editor/OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

mcp_capability_router-0.1.0/.readthedocs.yaml

@@ -0,0 +1,14 @@
+version: 2
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+  jobs:
+    post_checkout:
+      - curl -LsSf https://astral.sh/uv/install.sh | sh
+    post_install:
+      - $HOME/.local/bin/uv sync --extra docs
+  commands:
+    build:
+      html: $HOME/.local/bin/uv run mkdocs build --site-dir $READTHEDOCS_OUTPUT/html
+

mcp_capability_router-0.1.0/LICENSE

@@ -0,0 +1,16 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

mcp_capability_router-0.1.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.5
+Name: mcp-capability-router
+Version: 0.1.0
+Summary: Async capability routing runtime for LangChain, LangGraph, and MCP adapters.
+License:                                  Apache License
+                                   Version 2.0, January 2004
+                                http://www.apache.org/licenses/
+        
+           Licensed under the Apache License, Version 2.0 (the "License");
+           you may not use this file except in compliance with the License.
+           You may obtain a copy of the License at
+        
+               http://www.apache.org/licenses/LICENSE-2.0
+        
+           Unless required by applicable law or agreed to in writing, software
+           distributed under the License is distributed on an "AS IS" BASIS,
+           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+           See the License for the specific language governing permissions and
+           limitations under the License.
+        
+License-File: LICENSE
+Requires-Python: <3.13,>=3.12
+Requires-Dist: aiolimiter>=1.1
+Requires-Dist: langchain-core>=0.3
+Requires-Dist: refresh-engine>=0.1.0
+Requires-Dist: tenacity>=9.1
+Provides-Extra: agents
+Requires-Dist: deepagents>=0.1; extra == 'agents'
+Requires-Dist: langchain>=1.0; extra == 'agents'
+Provides-Extra: dev
+Requires-Dist: asyncpg>=0.31.0; extra == 'dev'
+Requires-Dist: black>=24.8; extra == 'dev'
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: langchain-mcp-adapters>=0.1; extra == 'dev'
+Requires-Dist: langgraph>=0.2; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
+Requires-Dist: mkdocstrings[python]>=0.26; extra == 'dev'
+Requires-Dist: prometheus-client>=0.26.0; extra == 'dev'
+Requires-Dist: pyrefly>=0.18; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: python-dotenv>=1.0; extra == 'dev'
+Requires-Dist: qdrant-client>=1.19.1; extra == 'dev'
+Requires-Dist: rank-bm25>=0.2.2; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
+Provides-Extra: examples
+Requires-Dist: asyncpg>=0.31.0; extra == 'examples'
+Requires-Dist: prometheus-client>=0.26.0; extra == 'examples'
+Requires-Dist: python-dotenv>=1.0; extra == 'examples'
+Requires-Dist: qdrant-client>=1.19.1; extra == 'examples'
+Requires-Dist: rank-bm25>=0.2.2; extra == 'examples'
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2; extra == 'langgraph'
+Provides-Extra: mcp
+Requires-Dist: langchain-mcp-adapters>=0.1; extra == 'mcp'
+Provides-Extra: openai
+Requires-Dist: langchain-openai>=0.3; extra == 'openai'
+Requires-Dist: openai>=1.0; extra == 'openai'
+Provides-Extra: swarm
+Requires-Dist: langgraph-swarm>=0.1; extra == 'swarm'
+Description-Content-Type: text/markdown
+
+# MCP Capability Router
+
+[![CI](https://github.com/smuniharish/mcp-capabilty-router/actions/workflows/ci.yml/badge.svg)](https://github.com/smuniharish/mcp-capabilty-router/actions/workflows/ci.yml)
+[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/release/python-3120/)
+[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-mkdocs--material-blueviolet)](docs/index.md)
+
+**An async-first, runtime-isolated capability routing layer for LangChain, LangGraph, and
+`langchain-mcp-adapters`.**
+
+Model Context Protocol (MCP) servers can expose hundreds or thousands of tools, resources, and
+prompts. Loading all of that into an agent's context on every turn is slow, expensive, and drowns
+out the model's ability to pick the right capability. `mcp-capability-router` sits between your
+agent and your MCP servers: it discovers and indexes capability metadata cheaply, retrieves only
+the handful relevant to a query, and connects to a server lazily -- only when an operation
+actually needs it.
+
+## Why this exists
+
+Connect an agent to a handful of MCP servers and the naive approach -- fetch every tool, resource,
+and prompt from every server at startup and hand the whole catalog to the model -- works fine.
+Connect it to a dozen servers, or a handful of servers that each expose hundreds of tools, and that
+same approach quietly breaks in three ways at once:
+
+1. **Every turn pays for capabilities that are never used.** Tool schemas alone can dwarf the
+   actual conversation, burning context budget and latency before the model has read a single
+   user message, and a bigger tool list makes the model *worse* at picking the right one, not
+   better.
+2. **Every server connection becomes a shared point of failure.** One slow or flaky MCP server,
+   connected at startup, blocks or degrades every agent that touches the process -- and most
+   teams end up hand-rolling retry loops, circuit breakers, and rate limiters around each
+   server's adapter, ad hoc, in application code that has nothing to do with agent logic.
+3. **The registry and the transport get welded together.** Swapping an in-memory tool list for
+   Postgres, or a keyword search for vector retrieval, means touching the same code that owns
+   connections, retries, and health -- so most implementations never get swapped at all.
+
+`mcp-capability-router` exists to make the *scalable* path the default path, without reinventing
+MCP transport or agent orchestration:
+
+- **Discover cheaply, load lazily.** Registering a server stores a factory, not a connection.
+  Discovery indexes metadata for tools, resources, and prompts -- all three as first-class,
+  equally-routable capabilities -- so a registry can hold thousands of records while an agent
+  turn only ever touches the handful `retrieve()` actually returns. A server connection is opened
+  only when `execute`, `read_resource`, or `get_prompt` needs one.
+- **Borrow resilience instead of reinventing it.** Retry, rate limiting, circuit breaking,
+  bulkheads, timeouts, and fallbacks are wired in by default, on top of maintained libraries --
+  [`refresh-engine`](https://pypi.org/project/refresh-engine/) for per-server discovery
+  reconciliation, [`tenacity`](https://pypi.org/project/tenacity/) for retries, and
+  [`aiolimiter`](https://pypi.org/project/aiolimiter/) for rate limiting -- so one misbehaving
+  server degrades gracefully instead of taking the whole agent down, and nobody has to hand-write
+  that logic per adapter again.
+- **Keep every seam swappable.** The capability registry, the retriever, and the metrics hook are
+  small, explicit protocols, isolated from connection and lifecycle handling. Start with the
+  built-in in-memory registry and keyword retriever, then drop in Postgres, Qdrant, Ollama
+  embeddings, or Prometheus later -- with zero changes to `MCPRuntime` or the resilience pipeline.
+- **Stay a router, not a runtime.** This project owns capability discovery, retrieval, and
+  lifecycle policy only. Transport, authentication, and the MCP client itself stay with
+  `langchain-mcp-adapters` or your own adapter; model calls and agent orchestration stay with
+  LangChain, LangGraph, `langgraph-swarm`, or DeepAgents. Nothing here competes with those layers.
+
+## Installation
+
+This package is not yet published to PyPI. Install it from source:
+
+```bash
+git clone https://github.com/smuniharish/mcp-capabilty-router.git
+cd mcp-capabilty-router
+pip install .
+```
+
+Optional extras add integration-specific dependencies as needed:
+
+```bash
+pip install ".[mcp]"       # langchain-mcp-adapters
+pip install ".[langgraph]" # LangGraph
+pip install ".[agents]"    # LangChain create_agent, DeepAgents
+pip install ".[swarm]"     # langgraph-swarm
+```
+
+Requires Python 3.12.
+
+## Quickstart
+
+```python
+import asyncio
+from mcp_capability_router import CapabilityType, MCPRuntime
+
+async def main():
+    async with MCPRuntime() as runtime:
+        await runtime.register_server("filesystem", my_filesystem_adapter_factory)
+        await runtime.refresh_server("filesystem")
+
+        candidates = await runtime.retrieve("read a file", type=CapabilityType.TOOL, limit=5)
+        result = await runtime.execute(candidates[0].capability_id, {"path": "notes.txt"})
+        print(result)
+
+asyncio.run(main())
+```
+
+See [Getting started](docs/guides/getting-started.md) for wiring in a real
+`langchain-mcp-adapters` client, and [Examples](docs/examples/overview.md) for runnable scripts
+covering real MCP servers, LangGraph/DeepAgents/`langgraph-swarm` integrations, and pluggable
+registries, retrievers, and metrics backends.
+
+## Documentation
+
+Full documentation -- architecture, concepts, guides, operations, API reference, and
+troubleshooting -- lives in [`docs/`](docs/index.md) and is built with MkDocs Material.
+
+## Contributing
+
+```powershell
+uv sync --extra dev
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run pyrefly check
+uv run mkdocs build
+```
+
+## License
+
+Apache License 2.0 -- see [LICENSE](LICENSE).
+

mcp_capability_router-0.1.0/README.md

@@ -0,0 +1,124 @@
+# MCP Capability Router
+
+[![CI](https://github.com/smuniharish/mcp-capabilty-router/actions/workflows/ci.yml/badge.svg)](https://github.com/smuniharish/mcp-capabilty-router/actions/workflows/ci.yml)
+[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/release/python-3120/)
+[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-mkdocs--material-blueviolet)](docs/index.md)
+
+**An async-first, runtime-isolated capability routing layer for LangChain, LangGraph, and
+`langchain-mcp-adapters`.**
+
+Model Context Protocol (MCP) servers can expose hundreds or thousands of tools, resources, and
+prompts. Loading all of that into an agent's context on every turn is slow, expensive, and drowns
+out the model's ability to pick the right capability. `mcp-capability-router` sits between your
+agent and your MCP servers: it discovers and indexes capability metadata cheaply, retrieves only
+the handful relevant to a query, and connects to a server lazily -- only when an operation
+actually needs it.
+
+## Why this exists
+
+Connect an agent to a handful of MCP servers and the naive approach -- fetch every tool, resource,
+and prompt from every server at startup and hand the whole catalog to the model -- works fine.
+Connect it to a dozen servers, or a handful of servers that each expose hundreds of tools, and that
+same approach quietly breaks in three ways at once:
+
+1. **Every turn pays for capabilities that are never used.** Tool schemas alone can dwarf the
+   actual conversation, burning context budget and latency before the model has read a single
+   user message, and a bigger tool list makes the model *worse* at picking the right one, not
+   better.
+2. **Every server connection becomes a shared point of failure.** One slow or flaky MCP server,
+   connected at startup, blocks or degrades every agent that touches the process -- and most
+   teams end up hand-rolling retry loops, circuit breakers, and rate limiters around each
+   server's adapter, ad hoc, in application code that has nothing to do with agent logic.
+3. **The registry and the transport get welded together.** Swapping an in-memory tool list for
+   Postgres, or a keyword search for vector retrieval, means touching the same code that owns
+   connections, retries, and health -- so most implementations never get swapped at all.
+
+`mcp-capability-router` exists to make the *scalable* path the default path, without reinventing
+MCP transport or agent orchestration:
+
+- **Discover cheaply, load lazily.** Registering a server stores a factory, not a connection.
+  Discovery indexes metadata for tools, resources, and prompts -- all three as first-class,
+  equally-routable capabilities -- so a registry can hold thousands of records while an agent
+  turn only ever touches the handful `retrieve()` actually returns. A server connection is opened
+  only when `execute`, `read_resource`, or `get_prompt` needs one.
+- **Borrow resilience instead of reinventing it.** Retry, rate limiting, circuit breaking,
+  bulkheads, timeouts, and fallbacks are wired in by default, on top of maintained libraries --
+  [`refresh-engine`](https://pypi.org/project/refresh-engine/) for per-server discovery
+  reconciliation, [`tenacity`](https://pypi.org/project/tenacity/) for retries, and
+  [`aiolimiter`](https://pypi.org/project/aiolimiter/) for rate limiting -- so one misbehaving
+  server degrades gracefully instead of taking the whole agent down, and nobody has to hand-write
+  that logic per adapter again.
+- **Keep every seam swappable.** The capability registry, the retriever, and the metrics hook are
+  small, explicit protocols, isolated from connection and lifecycle handling. Start with the
+  built-in in-memory registry and keyword retriever, then drop in Postgres, Qdrant, Ollama
+  embeddings, or Prometheus later -- with zero changes to `MCPRuntime` or the resilience pipeline.
+- **Stay a router, not a runtime.** This project owns capability discovery, retrieval, and
+  lifecycle policy only. Transport, authentication, and the MCP client itself stay with
+  `langchain-mcp-adapters` or your own adapter; model calls and agent orchestration stay with
+  LangChain, LangGraph, `langgraph-swarm`, or DeepAgents. Nothing here competes with those layers.
+
+## Installation
+
+This package is not yet published to PyPI. Install it from source:
+
+```bash
+git clone https://github.com/smuniharish/mcp-capabilty-router.git
+cd mcp-capabilty-router
+pip install .
+```
+
+Optional extras add integration-specific dependencies as needed:
+
+```bash
+pip install ".[mcp]"       # langchain-mcp-adapters
+pip install ".[langgraph]" # LangGraph
+pip install ".[agents]"    # LangChain create_agent, DeepAgents
+pip install ".[swarm]"     # langgraph-swarm
+```
+
+Requires Python 3.12.
+
+## Quickstart
+
+```python
+import asyncio
+from mcp_capability_router import CapabilityType, MCPRuntime
+
+async def main():
+    async with MCPRuntime() as runtime:
+        await runtime.register_server("filesystem", my_filesystem_adapter_factory)
+        await runtime.refresh_server("filesystem")
+
+        candidates = await runtime.retrieve("read a file", type=CapabilityType.TOOL, limit=5)
+        result = await runtime.execute(candidates[0].capability_id, {"path": "notes.txt"})
+        print(result)
+
+asyncio.run(main())
+```
+
+See [Getting started](docs/guides/getting-started.md) for wiring in a real
+`langchain-mcp-adapters` client, and [Examples](docs/examples/overview.md) for runnable scripts
+covering real MCP servers, LangGraph/DeepAgents/`langgraph-swarm` integrations, and pluggable
+registries, retrievers, and metrics backends.
+
+## Documentation
+
+Full documentation -- architecture, concepts, guides, operations, API reference, and
+troubleshooting -- lives in [`docs/`](docs/index.md) and is built with MkDocs Material.
+
+## Contributing
+
+```powershell
+uv sync --extra dev
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run pyrefly check
+uv run mkdocs build
+```
+
+## License
+
+Apache License 2.0 -- see [LICENSE](LICENSE).
+

mcp_capability_router-0.1.0/docs/architecture/decisions.md

@@ -0,0 +1,53 @@
+# Architecture decision records
+
+## ADR-001: adapter-owned MCP connectivity
+
+**Context.** Applications already choose their MCP transport, authentication configuration, and
+client implementation. Reimplementing those concerns in the router would introduce a second MCP
+client stack and split ownership of connection failures and credentials.
+
+**Decision.** The runtime delegates transport, authentication, and protocol details to
+`langchain-mcp-adapters` or an application-provided adapter. It owns registration, discovery
+reconciliation, retrieval, loading, and lifecycle coordination. A
+`MultiServerMCPClient` can be registered directly with `register_mcp_client`; no
+Playwright-, filesystem-, or transport-specific client exists in this package.
+
+**Consequences.** The router stays interoperable with the official adapter and does not own
+server processes, credentials, or an MCP protocol implementation. Applications must configure
+and diagnose their selected client and transport.
+
+## ADR-002: capabilities are first-class
+
+**Context.** MCP exposes tools, resources, and prompts. Treating only tools as routable loses
+useful server functionality; flattening their behavior risks calling an operation with the wrong
+semantics.
+
+**Decision.** Tools, resources, and prompts share the `Capability` contract but retain
+type-specific semantics. Retrieval and registry operations accept all three types, while
+execution APIs guard the requested capability type.
+
+**Consequences.** Selection can use one metadata and retrieval model, while `execute`,
+`read_resource`, and `get_prompt` remain explicit about the requested operation.
+
+## ADR-003: instance-scoped mutable state
+
+**Context.** A process can host multiple agents or tenants that must not share cached
+capabilities, connections, limits, or health state.
+
+**Decision.** Registries, loaders, refresh tasks, circuit breakers, locks, and health are owned
+by a runtime instance. There are no process-global caches or connection managers.
+
+**Consequences.** Tests are deterministic and independent application boundaries can coexist in
+one process. Callers must create and close a runtime for each intended isolation boundary.
+
+## ADR-004: lazy connection and explicit refresh
+
+**Context.** Connecting to every configured server at startup is expensive and may expose a
+large, irrelevant capability set to an agent.
+
+**Decision.** Server registration stores a factory only. Discovery is explicit and a successful
+refresh reconciles metadata with the latest server response.
+
+**Consequences.** Startup remains lazy and agents can retrieve a small candidate set instead of
+receiving every configured capability. A failed discovery leaves the last successfully
+reconciled metadata intact; applications must schedule refreshes appropriate to their servers.

mcp_capability_router-0.1.0/docs/architecture/overview.md

@@ -0,0 +1,51 @@
+# Architecture overview
+
+```mermaid
+flowchart LR
+  App[LangChain / LangGraph application] --> Runtime[MCPRuntime]
+  Runtime --> Registry[Capability registry]
+  Runtime --> Route[Retrieve / query]
+  Runtime --> Life[Lazy server lifecycle]
+  Life --> Adapter[Application-owned adapter]
+  Adapter --> MCP[MCP server]
+  Route --> JIT[Load or execute selected capability]
+```
+
+Each runtime instance owns its servers, registry, caches, locks, semaphores, and background
+tasks. No mutable process-wide singleton is used. Metadata discovery is separate from loading:
+many records can remain in the registry while only a handful are selected for an agent.
+
+## Request lifecycle
+
+```mermaid
+sequenceDiagram
+  participant App
+  participant Runtime
+  participant Registry
+  participant Adapter
+  participant Server
+  App->>Runtime: register_server(id, factory)
+  Note over Runtime,Adapter: No connection is made
+  App->>Runtime: refresh_server(id)
+  Runtime->>Adapter: connect()
+  Adapter->>Server: list tools/resources/prompts
+  Runtime->>Registry: upsert metadata and remove stale IDs
+  App->>Runtime: retrieve(query)
+  Runtime->>Registry: list metadata
+  Registry-->>Runtime: ranked capabilities
+  App->>Runtime: execute(capability_id)
+  Runtime->>Adapter: call_tool(...)
+  Adapter->>Server: MCP request
+  Server-->>App: result
+```
+
+## Isolation and extension points
+
+* Create one `MCPRuntime` per tenant, agent, or policy boundary; do not share mutable runtimes
+  between unrelated applications.
+* Pass an implementation of `CapabilityRegistry` when metadata must live in a database or another
+  process. The protocol is intentionally small.
+* Implement the async adapter shape, or wrap an adapter from `langchain-mcp-adapters`. The router
+  never opens a transport itself.
+* `retrieve` is deterministic term matching. Applications can apply a model, policy, or graph
+  node after retrieval and before execution.

mcp_capability_router-0.1.0/docs/concepts/overview.md

@@ -0,0 +1,60 @@
+# Concepts
+
+```mermaid
+flowchart LR
+    subgraph Metadata["Registry: cheap to hold, even at 10k+ capabilities"]
+        T[Tool records]
+        R[Resource records]
+        P[Prompt records]
+    end
+    Metadata --> Retrieve[retrieve / query: filter + rank]
+    Retrieve --> Selected[Small selected candidate set]
+    Selected --> Loaded[load / execute / read_resource / get_prompt]
+```
+
+Tools, Resources, and Prompts are routed through the identical retrieve -> select -> load/execute
+path as siblings of one `Capability` model -- none of the three is a special case bolted on
+afterward. Holding 10,000+ metadata records in the registry stays cheap because retrieval indexes
+and filters that metadata; only the handful of capabilities an agent actually selects are ever
+loaded or invoked.
+
+## Capabilities
+
+`Tool`, `Resource`, and `Prompt` are immutable capability records. Every record has a stable
+`capability_id` (`<server>:<kind>:<name-or-uri>`), `server_id`, `name`, description, metadata,
+and availability. Resources additionally have a URI; prompts have argument names; tools may have
+an input schema.
+
+## Discovery, retrieval, and execution
+
+* **Discovery** connects and reconciles metadata via a per-server
+  [`refresh_engine.RefreshEngine`](https://pypi.org/project/refresh-engine/). It can be explicit
+  (`refresh_server`, which accepts `mode=`/`resource_ids=` for `FULL`/`INCREMENTAL`/`TARGETED`/
+  `DEPENDENCY_AWARE` reconciliation) or runtime-managed through a per-server `RefreshPolicy`;
+  startup remains lazy unless `on_register=True`. See [refresh](../operations/refresh.md) for
+  the full reconciliation contract.
+* **Retrieval** (`retrieve` or `query`) filters by type/server and ranks matching terms. It does
+  not call an MCP capability.
+* **Loading** (`load`) resolves a selected capability for an application cache.
+* **Operations** (`execute`, `read_resource`, `get_prompt`) connect on demand and invoke the
+  corresponding adapter method.
+
+`query(...)` searches existing metadata first. After a miss, it automatically refreshes servers
+registered with `RefreshPolicy(on_query_miss=True)`, then searches again. The explicit
+`refresh_servers=[...]` hint remains available for one-off query-scoped refreshes.
+
+## Lifecycle and resilience
+
+Registration stores a factory or adapter but does not connect, and builds that server's
+`RefreshEngine`. `connect` is idempotent per server, and `reconnect` closes and creates a fresh
+adapter. A runtime context manager stops every scheduler and policy task, closes every server's
+`RefreshEngine`, then closes adapters, registry resources, and loader caches. `max_concurrency`
+bounds operations through the runtime bulkhead.
+
+## Registry contract
+
+`InMemoryRegistry` is the default. A custom `CapabilityRegistry` must implement `upsert_many`,
+`remove_missing`, `remove`, `get`, `list`, and `close`. `remove` deletes one capability by ID and
+backs incremental/dependency-aware refresh; `remove_missing` stays for bulk reconciliation and
+`unregister_server`. Discovery happens outside registry locks, making network latency
+independent from metadata lock duration.