engrava-mcp 0.5.0__tar.gz

engrava_mcp-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sovantica
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

engrava_mcp-0.5.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: engrava-mcp
+Version: 0.5.0
+Summary: Model Context Protocol server for Engrava — expose an agent memory database to any MCP client over stdio.
+Author-email: Sovantica <hello@sovantica.ai>
+License: MIT
+Project-URL: Homepage, https://engrava.ai
+Project-URL: Documentation, https://github.com/sovantica/engrava-mcp
+Project-URL: Repository, https://github.com/sovantica/engrava-mcp
+Project-URL: Issues, https://github.com/sovantica/engrava-mcp/issues
+Keywords: mcp,model-context-protocol,ai-agents,agent-memory,graph-memory,engrava,llm,stdio-server
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: engrava<0.6,>=0.5
+Requires-Dist: mcp<2,>=1.27
+Requires-Dist: engrava[vec]<0.6,>=0.5
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: openai
+Requires-Dist: engrava[embeddings-openai]<0.6,>=0.5; extra == "openai"
+Provides-Extra: ollama
+Requires-Dist: engrava[embeddings-ollama]<0.6,>=0.5; extra == "ollama"
+Provides-Extra: hf
+Requires-Dist: engrava[embeddings-hf]<0.6,>=0.5; extra == "hf"
+Provides-Extra: local
+Requires-Dist: engrava[embeddings-local]<0.6,>=0.5; extra == "local"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Requires-Dist: mypy>=1.11.0; extra == "dev"
+Requires-Dist: ruff>=0.7.0; extra == "dev"
+Dynamic: license-file
+
+# Engrava MCP
+
+**The [Model Context Protocol](https://modelcontextprotocol.io) server for
+[Engrava](https://github.com/sovantica/engrava)** — expose an agent memory
+database to any MCP client (Claude Desktop, Claude Code, Cursor, Windsurf,
+VS Code, …) over stdio.
+
+`engrava-mcp` is a standalone, runnable package that consumes Engrava's public
+API. It is the one way to run Engrava as a memory server; the `engrava` library
+itself ships no MCP code.
+
+```bash
+uvx engrava-mcp        # run the server (no install step)
+# or
+pip install engrava-mcp
+engrava-mcp            # spawned by your MCP client over stdio
+```
+
+Installing `engrava-mcp` pulls in `engrava` transitively, so you also get the
+`import engrava` library in the same environment.
+
+## Compatibility
+
+`engrava-mcp` follows Engrava's version: **`engrava-mcp X.Y.z` targets `engrava X.Y`**
+and requires `engrava >=X.Y,<X.(Y+1)`. This is a one-way version mirror for legibility —
+**not** a lockstep: Engrava releases on its own cadence, and `engrava-mcp` patch releases
+are independent.
+
+| engrava-mcp | Works with engrava |
+|---|---|
+| `0.5.x` | `>=0.5,<0.6` |
+
+The dependency range is the source of truth. Normal installs resolve a compatible
+`engrava` automatically; if you pin `engrava` yourself, keep it within that range. If no
+matching `engrava-mcp` exists yet for a newer `engrava` (e.g. a fresh `engrava 0.6`), that
+pairing is **not yet verified/supported** — not broken; stay on a supported pair until a
+matching `engrava-mcp` ships.
+
+## Which package do I want?
+
+| Goal | Install |
+|---|---|
+| Build on the Engrava Python API (memory DB in your own code) | `pip install engrava` |
+| Run Engrava as a memory server for an MCP client | `uvx engrava-mcp` (or `pip install engrava-mcp`) |
+
+There is no third option.
+
+## Migrating from `engrava[mcp]`
+
+The server used to ship inside Engrava as the `engrava[mcp]` extra and an
+in-`engrava` `engrava-mcp` command. As of Engrava 0.5.0 it lives here instead.
+
+| Before | After |
+|---|---|
+| `pip install "engrava[mcp]"` | `pip install engrava-mcp` (or `uvx engrava-mcp`) |
+| `engrava-mcp` (installed by engrava) | `engrava-mcp` (installed by this package) |
+| client `mcp.json`: `"command": "engrava-mcp"` | client `mcp.json`: `"command": "uvx", "args": ["engrava-mcp"]` |
+
+- **Watch out:** `pip install "engrava[mcp]"` against Engrava 0.5 **does not
+  fail** — pip ignores the now-unknown extra and quietly installs bare
+  `engrava`, so it can look like the server installed when it did not. Install
+  `engrava-mcp` instead.
+- Update any pinned requirement strings (`engrava[mcp]>=...`) to depend on
+  `engrava-mcp`, not just reinstall.
+- **Your store configuration is unchanged** — the same `engrava.yaml` / env vars
+  work exactly as before (see [Configuration](#configuration)).
+
+## Configuration
+
+The server resolves its store from environment variables, in priority order:
+
+| Variable | Meaning |
+|---|---|
+| `ENGRAVA_MCP_CONFIG` | Path to an `engrava.yaml`. Built with the full configuration — embedding provider, vector backend, journal, TTL. **Recommended.** |
+| `ENGRAVA_DB_PATH` | Path to a bare SQLite database file. Zero-config quick-start; no embedding provider is configured, so semantic (vector) search is inert — full-text search, the graph, MindQL, and the audit trail still work. |
+| `ENGRAVA_MCP_READ_ONLY` | When set to `1` / `true` / `yes`, the write tools are not registered, so the server exposes a read-only surface. |
+
+**Recommended:** give the MCP server the same `engrava.yaml` your application
+uses. The `yaml` is the only place to declare an embedding provider (and its
+model / key), which the server needs to embed a *new query* at search time for
+semantic search. With only `ENGRAVA_DB_PATH` set, the server logs a startup
+warning that semantic search is inert and points you at `ENGRAVA_MCP_CONFIG`.
+
+### Example `engrava.yaml`
+
+```yaml
+db_path: ./memory.db
+embeddings:
+  provider: openai            # or: ollama, sentence-transformer, huggingface
+  model: text-embedding-3-small
+  api_key: ${OPENAI_API_KEY}
+```
+
+## Client setup
+
+Point your MCP client at the server over stdio. For example, a typical
+`mcp.json` entry:
+
+```json
+{
+  "mcpServers": {
+    "engrava": {
+      "command": "uvx",
+      "args": ["engrava-mcp"],
+      "env": {
+        "ENGRAVA_MCP_CONFIG": "/absolute/path/to/engrava.yaml"
+      }
+    }
+  }
+}
+```
+
+Use `ENGRAVA_DB_PATH` instead of `ENGRAVA_MCP_CONFIG` for the zero-config
+quick-start, and add `"ENGRAVA_MCP_READ_ONLY": "1"` for an app-writes /
+agent-reads deployment.
+
+### Running without uvx
+
+```bash
+engrava-mcp                  # console script
+python -m engrava_mcp        # module run
+python -m engrava_mcp.server # module run (server module directly)
+```
+
+## Optional providers
+
+The default install supports the vector backend and HTTP-based embedding
+providers (OpenAI / Ollama) once configured in the `yaml`. Heavier providers are
+opt-in extras that mirror Engrava's own extras:
+
+```bash
+uvx --from "engrava-mcp[local]"  engrava-mcp   # sentence-transformers (local model)
+uvx --from "engrava-mcp[hf]"     engrava-mcp   # HuggingFace Inference API
+uvx --from "engrava-mcp[openai]" engrava-mcp   # OpenAI-compatible embeddings deps
+uvx --from "engrava-mcp[ollama]" engrava-mcp   # Ollama embeddings deps
+```
+
+## The surface
+
+- **Tools (11):** `get_thought`, `search_memory`, `search_keywords`,
+  `list_memory`, `query_memory`, `memory_stats` (read); `store_thought`,
+  `update_thought`, `link_thoughts`, `delete_thought`, `delete_edge` (write,
+  gated by `ENGRAVA_MCP_READ_ONLY`).
+- **Resources (3):** `engrava://thought/{thought_id}`, `engrava://stats`,
+  `engrava://recent`.
+- **Prompts (3):** `summarize_recent_memory`, `find_related`, `reflect_on_topic`.
+
+`query_memory` accepts only MindQL `FIND` queries; raw SQL and every other
+command are rejected.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check src/ tests/
+ruff format --check src/ tests/
+mypy --strict src/
+pytest --cov --cov-fail-under=90
+```
+
+## License
+
+MIT

engrava_mcp-0.5.0/README.md

@@ -0,0 +1,163 @@
+# Engrava MCP
+
+**The [Model Context Protocol](https://modelcontextprotocol.io) server for
+[Engrava](https://github.com/sovantica/engrava)** — expose an agent memory
+database to any MCP client (Claude Desktop, Claude Code, Cursor, Windsurf,
+VS Code, …) over stdio.
+
+`engrava-mcp` is a standalone, runnable package that consumes Engrava's public
+API. It is the one way to run Engrava as a memory server; the `engrava` library
+itself ships no MCP code.
+
+```bash
+uvx engrava-mcp        # run the server (no install step)
+# or
+pip install engrava-mcp
+engrava-mcp            # spawned by your MCP client over stdio
+```
+
+Installing `engrava-mcp` pulls in `engrava` transitively, so you also get the
+`import engrava` library in the same environment.
+
+## Compatibility
+
+`engrava-mcp` follows Engrava's version: **`engrava-mcp X.Y.z` targets `engrava X.Y`**
+and requires `engrava >=X.Y,<X.(Y+1)`. This is a one-way version mirror for legibility —
+**not** a lockstep: Engrava releases on its own cadence, and `engrava-mcp` patch releases
+are independent.
+
+| engrava-mcp | Works with engrava |
+|---|---|
+| `0.5.x` | `>=0.5,<0.6` |
+
+The dependency range is the source of truth. Normal installs resolve a compatible
+`engrava` automatically; if you pin `engrava` yourself, keep it within that range. If no
+matching `engrava-mcp` exists yet for a newer `engrava` (e.g. a fresh `engrava 0.6`), that
+pairing is **not yet verified/supported** — not broken; stay on a supported pair until a
+matching `engrava-mcp` ships.
+
+## Which package do I want?
+
+| Goal | Install |
+|---|---|
+| Build on the Engrava Python API (memory DB in your own code) | `pip install engrava` |
+| Run Engrava as a memory server for an MCP client | `uvx engrava-mcp` (or `pip install engrava-mcp`) |
+
+There is no third option.
+
+## Migrating from `engrava[mcp]`
+
+The server used to ship inside Engrava as the `engrava[mcp]` extra and an
+in-`engrava` `engrava-mcp` command. As of Engrava 0.5.0 it lives here instead.
+
+| Before | After |
+|---|---|
+| `pip install "engrava[mcp]"` | `pip install engrava-mcp` (or `uvx engrava-mcp`) |
+| `engrava-mcp` (installed by engrava) | `engrava-mcp` (installed by this package) |
+| client `mcp.json`: `"command": "engrava-mcp"` | client `mcp.json`: `"command": "uvx", "args": ["engrava-mcp"]` |
+
+- **Watch out:** `pip install "engrava[mcp]"` against Engrava 0.5 **does not
+  fail** — pip ignores the now-unknown extra and quietly installs bare
+  `engrava`, so it can look like the server installed when it did not. Install
+  `engrava-mcp` instead.
+- Update any pinned requirement strings (`engrava[mcp]>=...`) to depend on
+  `engrava-mcp`, not just reinstall.
+- **Your store configuration is unchanged** — the same `engrava.yaml` / env vars
+  work exactly as before (see [Configuration](#configuration)).
+
+## Configuration
+
+The server resolves its store from environment variables, in priority order:
+
+| Variable | Meaning |
+|---|---|
+| `ENGRAVA_MCP_CONFIG` | Path to an `engrava.yaml`. Built with the full configuration — embedding provider, vector backend, journal, TTL. **Recommended.** |
+| `ENGRAVA_DB_PATH` | Path to a bare SQLite database file. Zero-config quick-start; no embedding provider is configured, so semantic (vector) search is inert — full-text search, the graph, MindQL, and the audit trail still work. |
+| `ENGRAVA_MCP_READ_ONLY` | When set to `1` / `true` / `yes`, the write tools are not registered, so the server exposes a read-only surface. |
+
+**Recommended:** give the MCP server the same `engrava.yaml` your application
+uses. The `yaml` is the only place to declare an embedding provider (and its
+model / key), which the server needs to embed a *new query* at search time for
+semantic search. With only `ENGRAVA_DB_PATH` set, the server logs a startup
+warning that semantic search is inert and points you at `ENGRAVA_MCP_CONFIG`.
+
+### Example `engrava.yaml`
+
+```yaml
+db_path: ./memory.db
+embeddings:
+  provider: openai            # or: ollama, sentence-transformer, huggingface
+  model: text-embedding-3-small
+  api_key: ${OPENAI_API_KEY}
+```
+
+## Client setup
+
+Point your MCP client at the server over stdio. For example, a typical
+`mcp.json` entry:
+
+```json
+{
+  "mcpServers": {
+    "engrava": {
+      "command": "uvx",
+      "args": ["engrava-mcp"],
+      "env": {
+        "ENGRAVA_MCP_CONFIG": "/absolute/path/to/engrava.yaml"
+      }
+    }
+  }
+}
+```
+
+Use `ENGRAVA_DB_PATH` instead of `ENGRAVA_MCP_CONFIG` for the zero-config
+quick-start, and add `"ENGRAVA_MCP_READ_ONLY": "1"` for an app-writes /
+agent-reads deployment.
+
+### Running without uvx
+
+```bash
+engrava-mcp                  # console script
+python -m engrava_mcp        # module run
+python -m engrava_mcp.server # module run (server module directly)
+```
+
+## Optional providers
+
+The default install supports the vector backend and HTTP-based embedding
+providers (OpenAI / Ollama) once configured in the `yaml`. Heavier providers are
+opt-in extras that mirror Engrava's own extras:
+
+```bash
+uvx --from "engrava-mcp[local]"  engrava-mcp   # sentence-transformers (local model)
+uvx --from "engrava-mcp[hf]"     engrava-mcp   # HuggingFace Inference API
+uvx --from "engrava-mcp[openai]" engrava-mcp   # OpenAI-compatible embeddings deps
+uvx --from "engrava-mcp[ollama]" engrava-mcp   # Ollama embeddings deps
+```
+
+## The surface
+
+- **Tools (11):** `get_thought`, `search_memory`, `search_keywords`,
+  `list_memory`, `query_memory`, `memory_stats` (read); `store_thought`,
+  `update_thought`, `link_thoughts`, `delete_thought`, `delete_edge` (write,
+  gated by `ENGRAVA_MCP_READ_ONLY`).
+- **Resources (3):** `engrava://thought/{thought_id}`, `engrava://stats`,
+  `engrava://recent`.
+- **Prompts (3):** `summarize_recent_memory`, `find_related`, `reflect_on_topic`.
+
+`query_memory` accepts only MindQL `FIND` queries; raw SQL and every other
+command are rejected.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check src/ tests/
+ruff format --check src/ tests/
+mypy --strict src/
+pytest --cov --cov-fail-under=90
+```
+
+## License
+
+MIT

engrava_mcp-0.5.0/pyproject.toml

@@ -0,0 +1,112 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "engrava-mcp"
+version = "0.5.0"
+description = "Model Context Protocol server for Engrava — expose an agent memory database to any MCP client over stdio."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.11"
+authors = [{name = "Sovantica", email = "hello@sovantica.ai"}]
+keywords = [
+    "mcp", "model-context-protocol", "ai-agents", "agent-memory",
+    "graph-memory", "engrava", "llm", "stdio-server",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    # Same-minor range on engrava's public API (engrava guarantees no breaking
+    # change within an X.Y.x patch range). 0.5.0 is the first release that ships
+    # engrava as a pure library with the public API this server consumes.
+    "engrava>=0.5,<0.6",
+    # Cap the MCP SDK major so a future incompatible release can't silently
+    # break `uvx engrava-mcp`; widen only after testing a new major. mcp>=1.27
+    # transitively constrains pydantic>=2.11,<3 (the floor engrava also targets).
+    "mcp>=1.27,<2",
+    # Default bundle for the bare `uvx engrava-mcp` (the registry one-click):
+    # the vector backend plus the http-based embedding providers' dependency,
+    # so semantic search and OpenAI/Ollama embeddings work out of the box once
+    # an embedding provider is declared in engrava.yaml. Heavy local providers
+    # (torch / sentence-transformers, HuggingFace Hub) stay opt-in extras.
+    "engrava[vec]>=0.5,<0.6",
+    "httpx>=0.27.0",
+]
+
+[project.optional-dependencies]
+# Mirror engrava's embedding-provider extras so users can install the matching
+# provider dependencies alongside the server, e.g.
+# `uvx --from "engrava-mcp[local]" engrava-mcp`.
+openai = ["engrava[embeddings-openai]>=0.5,<0.6"]
+ollama = ["engrava[embeddings-ollama]>=0.5,<0.6"]
+hf = ["engrava[embeddings-hf]>=0.5,<0.6"]
+local = ["engrava[embeddings-local]>=0.5,<0.6"]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "pytest-cov>=5.0.0",
+    "mypy>=1.11.0",
+    "ruff>=0.7.0",
+]
+
+[project.scripts]
+engrava-mcp = "engrava_mcp.server:main"
+
+[project.urls]
+Homepage = "https://engrava.ai"
+Documentation = "https://github.com/sovantica/engrava-mcp"
+Repository = "https://github.com/sovantica/engrava-mcp"
+Issues = "https://github.com/sovantica/engrava-mcp/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+engrava_mcp = ["py.typed"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "D203",
+    "D213",
+    "COM812",
+    "ISC001",
+    "D107",
+    "TC001",
+    "PLR0913",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101", "PLR2004", "D", "SLF001", "PT011", "B017", "FBT", "PLC0415", "ARG001", "ARG002"]
+
+[tool.mypy]
+strict = true
+warn_return_any = true
+disallow_untyped_defs = true
+no_implicit_reexport = true
+# Type-check assuming the 3.11 floor (matches requires-python), so 3.12-only
+# syntax can't leak into a package that claims to install on 3.11.
+python_version = "3.11"
+
+[[tool.mypy.overrides]]
+module = "httpx.*"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

engrava_mcp-0.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

engrava_mcp-0.5.0/src/engrava_mcp/__init__.py

@@ -0,0 +1,28 @@
+"""Model Context Protocol server for engrava.
+
+Exposes engrava's public read API as MCP tools over stdio, so MCP-aware
+agents can fetch thoughts, search memory, and run structured queries.
+The server is a standalone API consumer — it registers no engrava hooks,
+manifests, or extensions.
+
+Run it with ``python -m engrava_mcp`` or the ``engrava-mcp`` console
+script.
+"""
+
+from __future__ import annotations
+
+from engrava_mcp._compat import incompatible_engrava_message
+
+try:
+    from engrava_mcp.server import build_server, main
+except ImportError as exc:  # pragma: no cover - raw trigger is un-triggerable in-process
+    # The server consumes engrava's PUBLIC API. A missing symbol here means an
+    # incompatible `engrava` is installed. We check API *presence*, not a
+    # version number, on purpose: engrava's source version lags its released
+    # version (a dev/editable install reports the pre-release number), so a
+    # numeric `>=0.5` assert would false-positive. Re-raise with an actionable
+    # message and preserve the original error. The message logic itself is
+    # covered by tests in ``tests/test_compat.py``.
+    raise ImportError(incompatible_engrava_message(exc)) from exc
+
+__all__ = ["build_server", "main"]

engrava_mcp-0.5.0/src/engrava_mcp/__main__.py

@@ -0,0 +1,12 @@
+"""``python -m engrava_mcp`` entry point.
+
+Delegates to :func:`engrava_mcp.server.main`, which builds the MCP server
+and serves it over stdio.
+"""
+
+from __future__ import annotations
+
+from engrava_mcp.server import main
+
+if __name__ == "__main__":
+    main()

engrava_mcp-0.5.0/src/engrava_mcp/_compat.py

@@ -0,0 +1,125 @@
+"""Engrava compatibility helpers for the MCP server.
+
+The server consumes engrava's PUBLIC API. Two compatibility concerns live
+here so they are unit-testable in isolation from the import machinery and
+the running server:
+
+* :func:`incompatible_engrava_message` builds the actionable message the
+  package raises when the engrava public API cannot be imported at all (a
+  hard, fatal incompatibility caught in :mod:`engrava_mcp`'s ``__init__``).
+* :func:`warn_if_engrava_out_of_range` emits a soft, non-fatal warning at
+  startup when the *installed* engrava version falls outside the range this
+  server is tested against. It never raises: a dev/editable engrava reports
+  a pre-release number whose public API is in practice compatible, and the
+  install-time dependency range is the real gate.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import warnings
+
+#: Lowest engrava version (inclusive) this server is tested against.
+#: Keep in sync with the ``engrava>=0.5,<0.6`` requirement in ``pyproject.toml``.
+ENGRAVA_MIN_VERSION = (0, 5)
+
+#: Lowest engrava version (exclusive) that is out of range — the next minor.
+#: Keep in sync with the ``engrava>=0.5,<0.6`` requirement in ``pyproject.toml``.
+ENGRAVA_MAX_VERSION_EXCLUSIVE = (0, 6)
+
+#: Human-readable supported range, used in user-facing messages. Keep in sync
+#: with the ``engrava>=0.5,<0.6`` requirement in ``pyproject.toml``.
+ENGRAVA_SUPPORTED_RANGE = ">=0.5,<0.6"
+
+
+class EngravaVersionWarning(UserWarning):
+    """Warn that the installed engrava version is outside the tested range.
+
+    Emitted by :func:`warn_if_engrava_out_of_range` at server startup. It is
+    a warning, never an error: behaviour with an untested engrava version is
+    unverified rather than known-broken.
+    """
+
+
+def incompatible_engrava_message(exc: BaseException) -> str:
+    """Build the actionable message for an unimportable engrava public API.
+
+    The server consumes engrava's PUBLIC API. A missing symbol when importing
+    it means an incompatible ``engrava`` is installed. This builds a message
+    that names the dependency, states the supported range, tells the operator
+    how to recover, and preserves the original error for diagnosis.
+
+    Args:
+        exc: The original import-time exception to quote in the message.
+
+    Returns:
+        An actionable, single-string error message.
+
+    """
+    return (
+        "engrava-mcp could not load the engrava public API it depends on. "
+        "This usually means an incompatible 'engrava' is installed — engrava-mcp "
+        f"requires engrava {ENGRAVA_SUPPORTED_RANGE}. Reinstall engrava-mcp "
+        "(which pulls a compatible engrava) or align your engrava version. "
+        f"Original import error: {exc}"
+    )
+
+
+def _parse_major_minor(version: str) -> tuple[int, int] | None:
+    """Parse the leading ``major.minor`` pair from a version string.
+
+    Args:
+        version: A version string, e.g. ``"0.5.2"`` or ``"0.6.0rc1"``.
+
+    Returns:
+        The ``(major, minor)`` tuple, or ``None`` if it cannot be parsed.
+
+    """
+    parts = version.split(".")
+    if len(parts) < 2:  # noqa: PLR2004 - a version needs at least major.minor
+        return None
+    try:
+        major = int(parts[0])
+    except ValueError:
+        return None
+    # Strip any pre-release/build suffix on the minor segment (e.g. "6rc1").
+    minor_digits = ""
+    for char in parts[1]:
+        if not char.isdigit():
+            break
+        minor_digits += char
+    if not minor_digits:
+        return None
+    return (major, int(minor_digits))
+
+
+def warn_if_engrava_out_of_range() -> None:
+    """Warn if the installed engrava version is outside the tested range.
+
+    Reads the installed engrava version via :func:`importlib.metadata.version`
+    and, if its ``major.minor`` is outside the supported range
+    (:data:`ENGRAVA_SUPPORTED_RANGE`), emits an :class:`EngravaVersionWarning`.
+    It never raises: an unparseable or missing version, or an out-of-range one,
+    only warns. Call this once at startup, not at module import, to avoid noise
+    on every ``import engrava_mcp``.
+    """
+    try:
+        installed = importlib.metadata.version("engrava")
+    except importlib.metadata.PackageNotFoundError:
+        # No distribution metadata (unusual in practice). The install-time
+        # dependency range is the real gate; stay silent rather than warn on a
+        # missing-metadata edge that does not imply incompatibility.
+        return
+
+    parsed = _parse_major_minor(installed)
+    if parsed is None:
+        return
+
+    if not (ENGRAVA_MIN_VERSION <= parsed < ENGRAVA_MAX_VERSION_EXCLUSIVE):
+        warnings.warn(
+            f"Installed engrava version {installed} is outside engrava-mcp's "
+            f"tested range ({ENGRAVA_SUPPORTED_RANGE}); behaviour is unverified. "
+            "Align your engrava version if you hit unexpected results.",
+            EngravaVersionWarning,
+            stacklevel=2,
+        )