acex-mcp 1.0.0__tar.gz

acex_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: acex-mcp
+Version: 1.0.0
+Summary: ACE-X MCP Server - Model Context Protocol server for ACE-X
+License: AGPL-3.0
+Author: Johan Lahti
+Author-email: johan.lahti@acebit.se
+Requires-Python: >=3.13,<4.0
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: acex-client (>=4,<5)
+Requires-Dist: fastmcp (>=2.13.0.2,<3.0.0.0)
+Requires-Dist: httpx (>=0.28.0,<0.29.0)
+Requires-Dist: mcp (>=1.1.0,<2.0.0)
+Description-Content-Type: text/markdown
+
+# ACE-X MCP Server
+
+A Model Context Protocol server that gives AI assistants read-only access to
+ACE-X: the network devices it manages, the configuration each is intended to
+have, and the configuration snapshots actually collected from them.
+
+It holds no data and no credentials of its own. Every tool is a call to the
+ACE-X API made **as the caller**, so the backend authorizes each read against
+that user's own permissions.
+
+## Installation
+
+```bash
+pip install acex-mcp
+```
+
+## Tools
+
+All tools are read-only. Start with `find_nodes` — the `node_id` it returns is
+what every other tool takes.
+
+| Tool | What it answers |
+|---|---|
+| `find_nodes` | Which devices exist, filtered by hostname, site, region, role, vendor, OS or status |
+| `get_node` | One device: its identity plus the hardware it runs on |
+| `find_assets` | What physical hardware is in inventory, deployed or spare |
+| `list_sites` | Which sites exist |
+| `list_regions` | Which regions exist, and their sites |
+| `get_desired_config` | The configuration ACE-X intends a device to have, rendered as device commands |
+| `get_observed_config` | A configuration snapshot collected from a device — latest, at a past moment, or by id |
+| `get_running_config` | *Placeholder.* Explains that ACE-X cannot read a device live, and offers the newest snapshot |
+| `list_observed_configs` | A device's configuration history |
+| `diff_observed_configs` | What changed on a device between two snapshots |
+| `get_config_drift` | How a device differs from its intended configuration, compared per component |
+| `get_neighbors` | What is physically cabled to a device, per LLDP |
+
+`get_desired_config` and `get_observed_config` take a `section` argument that
+keeps only matching configuration blocks, so a question about one interface does
+not pull a three-thousand-line config into the model's context.
+
+## Resources and prompts
+
+| Resource | Contents |
+|---|---|
+| `acex://glossary` | desired vs observed vs running, and what users mean when they say "running config" |
+| `acex://entities` | Field-level entity reference, generated from the backend's own models |
+| `acex://capabilities` | What this server cannot do |
+| `acex://now` | Current UTC time, for resolving "yesterday at 19:00" into a timestamp |
+
+Prompts: `explain_config_change`, `assess_config_risk`,
+`assess_config_alignment` — each takes a `diff` and an optional `context`.
+
+## Configuration
+
+Only the backend URL is required. OIDC settings are discovered at startup from
+the backend's public `/api/v1/auth/config`, so authentication is configured in
+one place — the backend — and never duplicated here.
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `ACEX_API_URL` | `http://localhost:8080` | Backend base URL, **without** `/api/v1` |
+| `ACEX_VERIFY_SSL` | `true` | Verify TLS against the backend and the IdP |
+| `ACEX_MCP_TRANSPORT` | `http` | `http` or `stdio` |
+| `ACEX_MCP_HOST` | `0.0.0.0` | HTTP bind address |
+| `ACEX_MCP_PORT` | `8000` | HTTP port |
+| `ACEX_MCP_PATH` | `/mcp` | HTTP path |
+| `ACEX_MCP_REQUEST_TIMEOUT` | `60` | Seconds per backend request |
+| `ACEX_MCP_MAX_CONFIG_CHARS` | `24000` | Cap on config text per tool call |
+
+## Authentication
+
+The two transports authenticate differently, because only one of them has an
+inbound request to take a token from.
+
+**HTTP** — the server verifies the incoming bearer token against the backend's
+OIDC issuer, then forwards that same token to the ACE-X API on every tool call.
+Inbound verification is not a second layer of protection over the data (the
+backend authorizes every read regardless); it is what lets an external client
+discover it must log in, makes an expired token fail once at the boundary
+instead of becoming a series of tool errors, and identifies the caller in logs.
+
+**stdio** — there is no inbound request, so the process authenticates as the
+user through `acex_client`: `ACEX_CLIENT_ID` + `ACEX_CLIENT_SECRET` for a
+service identity, or an interactive browser login whose token is cached on disk.
+
+If the backend reports authentication disabled, this server also runs without
+it, so a Keycloak-less development stack works.
+
+## Usage
+
+### Running the server
+
+```bash
+python3 -m acex_mcp
+```
+
+Or via the console script, which does exactly the same thing:
+
+```bash
+acex-mcp
+```
+
+The Docker Compose stack builds and wires this automatically; the backend
+reaches it at `ACEX_AI_MCP_SERVER_URL=http://mcp-server:8000/mcp`.
+
+### Configuration for Claude Desktop
+
+Add to your `claude_desktop_config.json`. `stdio` is required — Claude Desktop
+spawns the process and talks to it over a pipe:
+
+```json
+{
+  "mcpServers": {
+    "acex": {
+      "command": "acex-mcp",
+      "env": {
+        "ACEX_MCP_TRANSPORT": "stdio",
+        "ACEX_API_URL": "https://acex.example.com"
+      }
+    }
+  }
+}
+```
+
+### Configuration for VS Code with Cline
+
+Add to your MCP settings, with the same two environment variables:
+
+```json
+{
+  "mcpServers": {
+    "acex": {
+      "command": "acex-mcp",
+      "args": [],
+      "env": {
+        "ACEX_MCP_TRANSPORT": "stdio",
+        "ACEX_API_URL": "https://acex.example.com"
+      }
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+cd mcp
+poetry install
+ACEX_API_URL=http://localhost:8080 poetry run python -m acex_mcp
+```
+
+## Testing
+
+```bash
+poetry run pytest
+```
+
+`tests/test_contract.py` guards against the failure that motivated this
+rewrite: tools that called endpoints which had moved, and described fields the
+API does not return. It checks that every client method the tools call still
+exists, and — when a backend is reachable — that every path behind them is
+still in its OpenAPI spec.
+
+Interactively, with the MCP Inspector:
+
+```bash
+npx @modelcontextprotocol/inspector acex-mcp
+```
+
+## License
+
+AGPL-3.0 - See [LICENSE](../LICENSE) for details.
+

acex_mcp-1.0.0/README.md

@@ -0,0 +1,172 @@
+# ACE-X MCP Server
+
+A Model Context Protocol server that gives AI assistants read-only access to
+ACE-X: the network devices it manages, the configuration each is intended to
+have, and the configuration snapshots actually collected from them.
+
+It holds no data and no credentials of its own. Every tool is a call to the
+ACE-X API made **as the caller**, so the backend authorizes each read against
+that user's own permissions.
+
+## Installation
+
+```bash
+pip install acex-mcp
+```
+
+## Tools
+
+All tools are read-only. Start with `find_nodes` — the `node_id` it returns is
+what every other tool takes.
+
+| Tool | What it answers |
+|---|---|
+| `find_nodes` | Which devices exist, filtered by hostname, site, region, role, vendor, OS or status |
+| `get_node` | One device: its identity plus the hardware it runs on |
+| `find_assets` | What physical hardware is in inventory, deployed or spare |
+| `list_sites` | Which sites exist |
+| `list_regions` | Which regions exist, and their sites |
+| `get_desired_config` | The configuration ACE-X intends a device to have, rendered as device commands |
+| `get_observed_config` | A configuration snapshot collected from a device — latest, at a past moment, or by id |
+| `get_running_config` | *Placeholder.* Explains that ACE-X cannot read a device live, and offers the newest snapshot |
+| `list_observed_configs` | A device's configuration history |
+| `diff_observed_configs` | What changed on a device between two snapshots |
+| `get_config_drift` | How a device differs from its intended configuration, compared per component |
+| `get_neighbors` | What is physically cabled to a device, per LLDP |
+
+`get_desired_config` and `get_observed_config` take a `section` argument that
+keeps only matching configuration blocks, so a question about one interface does
+not pull a three-thousand-line config into the model's context.
+
+## Resources and prompts
+
+| Resource | Contents |
+|---|---|
+| `acex://glossary` | desired vs observed vs running, and what users mean when they say "running config" |
+| `acex://entities` | Field-level entity reference, generated from the backend's own models |
+| `acex://capabilities` | What this server cannot do |
+| `acex://now` | Current UTC time, for resolving "yesterday at 19:00" into a timestamp |
+
+Prompts: `explain_config_change`, `assess_config_risk`,
+`assess_config_alignment` — each takes a `diff` and an optional `context`.
+
+## Configuration
+
+Only the backend URL is required. OIDC settings are discovered at startup from
+the backend's public `/api/v1/auth/config`, so authentication is configured in
+one place — the backend — and never duplicated here.
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `ACEX_API_URL` | `http://localhost:8080` | Backend base URL, **without** `/api/v1` |
+| `ACEX_VERIFY_SSL` | `true` | Verify TLS against the backend and the IdP |
+| `ACEX_MCP_TRANSPORT` | `http` | `http` or `stdio` |
+| `ACEX_MCP_HOST` | `0.0.0.0` | HTTP bind address |
+| `ACEX_MCP_PORT` | `8000` | HTTP port |
+| `ACEX_MCP_PATH` | `/mcp` | HTTP path |
+| `ACEX_MCP_REQUEST_TIMEOUT` | `60` | Seconds per backend request |
+| `ACEX_MCP_MAX_CONFIG_CHARS` | `24000` | Cap on config text per tool call |
+
+## Authentication
+
+The two transports authenticate differently, because only one of them has an
+inbound request to take a token from.
+
+**HTTP** — the server verifies the incoming bearer token against the backend's
+OIDC issuer, then forwards that same token to the ACE-X API on every tool call.
+Inbound verification is not a second layer of protection over the data (the
+backend authorizes every read regardless); it is what lets an external client
+discover it must log in, makes an expired token fail once at the boundary
+instead of becoming a series of tool errors, and identifies the caller in logs.
+
+**stdio** — there is no inbound request, so the process authenticates as the
+user through `acex_client`: `ACEX_CLIENT_ID` + `ACEX_CLIENT_SECRET` for a
+service identity, or an interactive browser login whose token is cached on disk.
+
+If the backend reports authentication disabled, this server also runs without
+it, so a Keycloak-less development stack works.
+
+## Usage
+
+### Running the server
+
+```bash
+python3 -m acex_mcp
+```
+
+Or via the console script, which does exactly the same thing:
+
+```bash
+acex-mcp
+```
+
+The Docker Compose stack builds and wires this automatically; the backend
+reaches it at `ACEX_AI_MCP_SERVER_URL=http://mcp-server:8000/mcp`.
+
+### Configuration for Claude Desktop
+
+Add to your `claude_desktop_config.json`. `stdio` is required — Claude Desktop
+spawns the process and talks to it over a pipe:
+
+```json
+{
+  "mcpServers": {
+    "acex": {
+      "command": "acex-mcp",
+      "env": {
+        "ACEX_MCP_TRANSPORT": "stdio",
+        "ACEX_API_URL": "https://acex.example.com"
+      }
+    }
+  }
+}
+```
+
+### Configuration for VS Code with Cline
+
+Add to your MCP settings, with the same two environment variables:
+
+```json
+{
+  "mcpServers": {
+    "acex": {
+      "command": "acex-mcp",
+      "args": [],
+      "env": {
+        "ACEX_MCP_TRANSPORT": "stdio",
+        "ACEX_API_URL": "https://acex.example.com"
+      }
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+cd mcp
+poetry install
+ACEX_API_URL=http://localhost:8080 poetry run python -m acex_mcp
+```
+
+## Testing
+
+```bash
+poetry run pytest
+```
+
+`tests/test_contract.py` guards against the failure that motivated this
+rewrite: tools that called endpoints which had moved, and described fields the
+API does not return. It checks that every client method the tools call still
+exists, and — when a backend is reachable — that every path behind them is
+still in its OpenAPI spec.
+
+Interactively, with the MCP Inspector:
+
+```bash
+npx @modelcontextprotocol/inspector acex-mcp
+```
+
+## License
+
+AGPL-3.0 - See [LICENSE](../LICENSE) for details.

acex_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,32 @@
+[tool.poetry]
+name = "acex-mcp"
+version = "1.0.0"
+description = "ACE-X MCP Server - Model Context Protocol server for ACE-X"
+authors = ["Johan Lahti <johan.lahti@acebit.se>"]
+readme = "README.md"
+license = "AGPL-3.0"
+packages = [
+    { include = "acex_mcp", from = "src" }
+]
+
+[tool.poetry.dependencies]
+python = "^3.13"
+mcp = "^1.1.0"
+fastmcp = "^2.13.0.2"
+httpx = "^0.28.0"
+acex-client = "^4"
+
+[tool.poetry.scripts]
+acex-mcp = "acex_mcp.server:run"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0.0"
+pytest-asyncio = "^0.23.0"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

acex_mcp-1.0.0/src/acex_mcp/__init__.py

@@ -0,0 +1,8 @@
+"""ACE-X MCP Server - Model Context Protocol server for ACE-X."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("acex-mcp")
+except PackageNotFoundError:  # source tree without an install
+    __version__ = "0.0.0"

acex_mcp-1.0.0/src/acex_mcp/__main__.py

@@ -0,0 +1,10 @@
+"""Entry point for `python -m acex_mcp`.
+
+Delegates to the same run() the `acex-mcp` console script uses, so both ways
+of starting the server behave identically.
+"""
+
+from acex_mcp.server import run
+
+if __name__ == "__main__":
+    run()

acex_mcp-1.0.0/src/acex_mcp/app.py

@@ -0,0 +1,52 @@
+"""Assembly of the MCP server."""
+
+import logging
+
+from fastmcp import FastMCP
+
+from . import prompts, resources, tools
+from .auth import build_verifier
+from .config import settings
+from .middleware import CallerTokenMiddleware, ToolLoggingMiddleware
+
+INSTRUCTIONS = """\
+ACE-X is an infrastructure-as-code platform for network devices: it holds the
+configuration each device is intended to have, and snapshots of what has
+actually been collected from them.
+
+Start with find_nodes() to locate a device — every other tool takes the node_id
+it returns. Read the acex://glossary resource before answering configuration
+questions; ACE-X distinguishes desired configuration from observed snapshots,
+and the difference matters. All tools are read-only.
+"""
+
+
+def create_app() -> FastMCP:
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+
+    mcp = FastMCP(
+        "ACE-X",
+        instructions=INSTRUCTIONS,
+        auth=build_verifier(),
+    )
+
+    mcp.add_middleware(CallerTokenMiddleware())
+    mcp.add_middleware(ToolLoggingMiddleware())
+
+    tools.register_all(mcp)
+    resources.register(mcp)
+    prompts.register(mcp)
+
+    return mcp
+
+
+def run() -> None:
+    """Entry point for the `acex-mcp` command."""
+    mcp = create_app()
+    if settings.is_stdio:
+        mcp.run(transport="stdio")
+    else:
+        mcp.run(transport="http", host=settings.host, port=settings.port, path=settings.path)

acex_mcp-1.0.0/src/acex_mcp/auth.py

@@ -0,0 +1,73 @@
+"""Inbound authentication, configured from the backend.
+
+The backend is the only place OIDC is configured, so this server asks it rather
+than duplicating OIDC_* env vars: `GET /api/v1/auth/config` is public and
+reports the issuer (as `authority`) and the expected audience (as `client_id`).
+
+Note what this is *for*. It is not a second layer of protection over the data —
+the backend authorizes every read regardless. It exists so an external client
+gets a proper 401 pointing at the OAuth metadata and can start a login flow, so
+an expired token fails once at the boundary instead of becoming N tool errors
+fed to the model as prose, and so calls can be logged per user.
+"""
+
+import logging
+
+import httpx
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+from .config import settings
+
+logger = logging.getLogger("acex_mcp.auth")
+
+
+class AuthUnavailableError(RuntimeError):
+    """The backend could not be asked what the auth settings are."""
+
+
+def _discover(authority: str) -> str:
+    resp = httpx.get(
+        f"{authority.rstrip('/')}/.well-known/openid-configuration",
+        verify=settings.verify_ssl,
+        timeout=10,
+    )
+    resp.raise_for_status()
+    jwks_uri = resp.json().get("jwks_uri")
+    if not jwks_uri:
+        raise AuthUnavailableError(f"OIDC discovery at {authority} returned no jwks_uri")
+    return jwks_uri
+
+
+def build_verifier() -> JWTVerifier | None:
+    """Build a token verifier from the backend's auth config.
+
+    Returns None when the backend reports auth disabled — the server then runs
+    unauthenticated, mirroring the backend so a Keycloak-less dev stack works.
+
+    Raises AuthUnavailableError if the backend cannot be reached, so startup
+    fails loudly rather than silently serving without auth.
+    """
+    if settings.is_stdio:
+        # The transport is a pipe from a process the user started themselves;
+        # there is no inbound request to authenticate.
+        return None
+
+    try:
+        resp = httpx.get(f"{settings.api_url}/api/v1/auth/config", verify=settings.verify_ssl, timeout=10)
+        resp.raise_for_status()
+        config = resp.json()
+    except Exception as exc:
+        raise AuthUnavailableError(
+            f"Cannot read auth config from {settings.api_url} — refusing to start without knowing "
+            f"whether authentication is required: {exc}"
+        ) from exc
+
+    if not config.get("enabled"):
+        logger.warning("backend reports auth disabled — serving MCP without inbound authentication")
+        return None
+
+    authority = config["authority"]
+    audience = config.get("client_id")
+    verifier = JWTVerifier(jwks_uri=_discover(authority), issuer=authority, audience=audience)
+    logger.info("inbound auth enabled (issuer=%s, audience=%s)", authority, audience)
+    return verifier

acex_mcp-1.0.0/src/acex_mcp/backend.py

@@ -0,0 +1,96 @@
+"""The single path from a tool to the ACE-X backend.
+
+Two things matter here.
+
+**The MCP server holds no credentials of its own.** Over HTTP it forwards the
+caller's bearer token verbatim, so every read is authorized as that user by the
+backend. A service account would make this server a confused deputy: anyone who
+reached its port would get fleet-wide read access. Over stdio there is no
+inbound request, so the process authenticates as the user through acex_client's
+own env/browser flow instead.
+
+**The token is per-request, the connection pool is not.** One shared `Acex`
+instance keeps httpx's pool warm; the token travels in a ContextVar that
+`_ContextTokenAuth` reads on each request. `asyncio.to_thread` copies the
+current context, so the token set by the tool coroutine is visible to the
+synchronous client running in the worker thread.
+"""
+
+import asyncio
+import contextvars
+import logging
+from collections.abc import Callable
+from typing import Any
+
+from acex_client import Acex
+from acex_client.auth import AuthProvider, create_auth_provider
+
+from .config import settings
+from .errors import as_tool_error
+
+logger = logging.getLogger("acex_mcp.backend")
+
+_caller_token: contextvars.ContextVar[str | None] = contextvars.ContextVar("acex_caller_token", default=None)
+
+
+class _ContextTokenAuth(AuthProvider):
+    """Yields whichever token the current request put in context."""
+
+    def get_token(self) -> str:
+        return _caller_token.get() or ""
+
+
+def set_caller_token(token: str | None) -> None:
+    _caller_token.set(token)
+
+
+_client: Acex | None = None
+
+
+def client() -> Acex:
+    """The process-wide backend client, built on first use.
+
+    Construction is lazy because in HTTP mode it must not depend on the backend
+    being reachable at import time.
+    """
+    global _client
+    if _client is None:
+        auth: AuthProvider
+        if settings.is_stdio:
+            # No inbound request to borrow a token from — authenticate as the
+            # user running us (client-credentials env vars, or browser flow).
+            auth = create_auth_provider(f"{settings.api_url}/api/v1", settings.verify_ssl)
+        else:
+            auth = _ContextTokenAuth()
+        _client = Acex(
+            base_url=settings.api_url,
+            verify=settings.verify_ssl,
+            auth=auth,
+            timeout=settings.request_timeout,
+        )
+        logger.info("backend client ready (%s, transport=%s)", settings.api_url, settings.transport)
+    return _client
+
+
+async def call[T](fn: Callable[..., T], *args: Any, doing: str, **kwargs: Any) -> T:
+    """Run a synchronous acex_client call off the event loop.
+
+    acex_client is sync (httpx.Client), so calling it directly from a tool
+    coroutine would block every other in-flight request.
+    """
+    try:
+        return await asyncio.to_thread(fn, *args, **kwargs)
+    except Exception as exc:
+        logger.info("backend call failed while %s: %s", doing, exc)
+        raise as_tool_error(exc, doing=doing) from exc
+
+
+async def get_json(path: str, *, params: dict[str, Any] | None = None, doing: str) -> Any:
+    """Fetch a raw JSON body, bypassing acex_client's typed models.
+
+    Used only for `intent_diff`, whose `Diff` model carries a `component_type:
+    type[Any]` field that does not survive a JSON round-trip — validating the
+    response back into it would fail. Everything else goes through the typed
+    resource methods.
+    """
+    return await call(client().rest.request, "GET", path, params=params, doing=doing)