lime-mcp-server-sdk 0.2.0__tar.gz

lime_mcp_server_sdk-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Ruff
+        if: matrix.python-version == '3.12'
+        run: ruff check src tests
+      - name: Mypy
+        if: matrix.python-version == '3.12'
+        run: mypy src/lime_mcp_server
+      - name: Pytest
+        run: pytest --cov=lime_mcp_server --cov-fail-under=100

lime_mcp_server_sdk-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,22 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

lime_mcp_server_sdk-0.2.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.venv/

lime_mcp_server_sdk-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mawyxx
+
+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.

lime_mcp_server_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: lime-mcp-server-sdk
+Version: 0.2.0
+Summary: JWT verification for LIME MCP resource servers
+Project-URL: Homepage, https://github.com/Mawyxx/lime-mcp-server-sdk
+Project-URL: Repository, https://github.com/Mawyxx/lime-mcp-server-sdk
+Author: Mawyxx
+License-Expression: MIT
+License-File: LICENSE
+Keywords: jwt,lime,mcp,oauth,resource-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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: cryptography<45,>=42.0
+Requires-Dist: httpx<0.28,>=0.27
+Requires-Dist: pyjwt<3,>=2.8
+Provides-Extra: dev
+Requires-Dist: mypy<2.0,>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov<6.0,>=5.0; extra == 'dev'
+Requires-Dist: pytest<9.0,>=8.0; extra == 'dev'
+Requires-Dist: respx<0.22,>=0.21; extra == 'dev'
+Requires-Dist: ruff<1.0,>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# lime-mcp-server-sdk
+
+JWT verification for **LIME MCP resource servers** ([ADR 0081](https://github.com/Mawyxx/LIME)).
+
+Install:
+
+```bash
+pip install lime-mcp-server-sdk
+```
+
+## Quick start
+
+```python
+from lime_mcp_server import TokenVerifier
+
+verifier = TokenVerifier()  # defaults: https://lime.pics, aud=mcp
+result = verifier.verify(bearer_token)
+if result.is_valid:
+    agent_uuid = result.agent_id  # alias for claims["sub"]
+```
+
+MCP OAuth JWT identity is claim **`sub`** (UUID). There is no separate `agent_id` claim.
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LIME_BASE_URL` | `https://lime.pics` | LIME origin for OAuth metadata + JWKS |
+| `LIME_OAUTH_AUDIENCE` | `mcp` | Expected JWT `aud` |
+| `LIME_JWKS_CACHE_TTL_SECONDS` | `3600` | Metadata + JWKS cache TTL |
+| `LIME_JWT_VERIFY_LEEWAY_SECONDS` | `120` | Clock skew leeway |
+| `LIME_JWKS_MIN_REFRESH_SECONDS` | `60` | Min interval between forced JWKS refresh |
+
+## Development
+
+Monorepo workspace: `sdk/lime-mcp-server-sdk/` (gitignored). Standalone repo: [github.com/Mawyxx/lime-mcp-server-sdk](https://github.com/Mawyxx/lime-mcp-server-sdk).
+
+```bash
+cd sdk/lime-mcp-server-sdk
+pip install -e ".[dev]"
+ruff check src tests
+mypy src/lime_mcp_server
+pytest --cov=lime_mcp_server --cov-fail-under=100
+```
+
+Live integration (optional):
+
+```bash
+LIME_MCP_SERVER_INTEGRATION=1 LIME_AGENT_TOKEN=at_... pytest tests/integration/ -v
+```
+
+## Publish (standalone repo)
+
+From monorepo workspace (after local QA):
+
+```bash
+cd sdk/lime-mcp-server-sdk
+git push -u origin main
+git tag v0.2.0
+git push origin v0.2.0
+```
+
+GitHub Actions on tag `v*` publishes to PyPI. One-time setup:
+
+1. Create project `lime-mcp-server-sdk` on [pypi.org](https://pypi.org/manage/projects/)
+2. PyPI → **Publishing** → **Add a new pending publisher**:
+   - Owner: `Mawyxx`, repo: `lime-mcp-server-sdk`, workflow: `publish.yml`, environment: `pypi`
+3. GitHub repo → **Settings → Environments** → create **`pypi`**
+4. Push tag: `git push origin v0.2.0` (or re-tag and force-push)
+
+Until PyPI is live, install from GitHub:
+
+```bash
+pip install "lime-mcp-server-sdk @ git+https://github.com/Mawyxx/lime-mcp-server-sdk.git@v0.2.0"
+```
+
+## Changelog
+
+### 0.2.0
+
+- Remove framework adapters (`LimeMcpTokenVerifier`, `[mcp]` extra). Core-only wheel.
+
+### 0.1.0
+
+- Initial release: `TokenVerifier`, `TokenValidationResult`, JWKS cache.

lime_mcp_server_sdk-0.2.0/README.md

@@ -0,0 +1,85 @@
+# lime-mcp-server-sdk
+
+JWT verification for **LIME MCP resource servers** ([ADR 0081](https://github.com/Mawyxx/LIME)).
+
+Install:
+
+```bash
+pip install lime-mcp-server-sdk
+```
+
+## Quick start
+
+```python
+from lime_mcp_server import TokenVerifier
+
+verifier = TokenVerifier()  # defaults: https://lime.pics, aud=mcp
+result = verifier.verify(bearer_token)
+if result.is_valid:
+    agent_uuid = result.agent_id  # alias for claims["sub"]
+```
+
+MCP OAuth JWT identity is claim **`sub`** (UUID). There is no separate `agent_id` claim.
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LIME_BASE_URL` | `https://lime.pics` | LIME origin for OAuth metadata + JWKS |
+| `LIME_OAUTH_AUDIENCE` | `mcp` | Expected JWT `aud` |
+| `LIME_JWKS_CACHE_TTL_SECONDS` | `3600` | Metadata + JWKS cache TTL |
+| `LIME_JWT_VERIFY_LEEWAY_SECONDS` | `120` | Clock skew leeway |
+| `LIME_JWKS_MIN_REFRESH_SECONDS` | `60` | Min interval between forced JWKS refresh |
+
+## Development
+
+Monorepo workspace: `sdk/lime-mcp-server-sdk/` (gitignored). Standalone repo: [github.com/Mawyxx/lime-mcp-server-sdk](https://github.com/Mawyxx/lime-mcp-server-sdk).
+
+```bash
+cd sdk/lime-mcp-server-sdk
+pip install -e ".[dev]"
+ruff check src tests
+mypy src/lime_mcp_server
+pytest --cov=lime_mcp_server --cov-fail-under=100
+```
+
+Live integration (optional):
+
+```bash
+LIME_MCP_SERVER_INTEGRATION=1 LIME_AGENT_TOKEN=at_... pytest tests/integration/ -v
+```
+
+## Publish (standalone repo)
+
+From monorepo workspace (after local QA):
+
+```bash
+cd sdk/lime-mcp-server-sdk
+git push -u origin main
+git tag v0.2.0
+git push origin v0.2.0
+```
+
+GitHub Actions on tag `v*` publishes to PyPI. One-time setup:
+
+1. Create project `lime-mcp-server-sdk` on [pypi.org](https://pypi.org/manage/projects/)
+2. PyPI → **Publishing** → **Add a new pending publisher**:
+   - Owner: `Mawyxx`, repo: `lime-mcp-server-sdk`, workflow: `publish.yml`, environment: `pypi`
+3. GitHub repo → **Settings → Environments** → create **`pypi`**
+4. Push tag: `git push origin v0.2.0` (or re-tag and force-push)
+
+Until PyPI is live, install from GitHub:
+
+```bash
+pip install "lime-mcp-server-sdk @ git+https://github.com/Mawyxx/lime-mcp-server-sdk.git@v0.2.0"
+```
+
+## Changelog
+
+### 0.2.0
+
+- Remove framework adapters (`LimeMcpTokenVerifier`, `[mcp]` extra). Core-only wheel.
+
+### 0.1.0
+
+- Initial release: `TokenVerifier`, `TokenValidationResult`, JWKS cache.

lime_mcp_server_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lime-mcp-server-sdk"
+version = "0.2.0"
+description = "JWT verification for LIME MCP resource servers"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Mawyxx" }]
+keywords = ["lime", "mcp", "jwt", "oauth", "resource-server"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "PyJWT>=2.8,<3",
+    "cryptography>=42.0,<45",
+    "httpx>=0.27,<0.28",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0,<9.0",
+    "pytest-cov>=5.0,<6.0",
+    "ruff>=0.6,<1.0",
+    "mypy>=1.11,<2.0",
+    "respx>=0.21,<0.22",
+]
+
+[project.urls]
+Homepage = "https://github.com/Mawyxx/lime-mcp-server-sdk"
+Repository = "https://github.com/Mawyxx/lime-mcp-server-sdk"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lime_mcp_server"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.12"
+mypy_path = "src"
+packages = ["lime_mcp_server"]
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+addopts = "-ra"
+markers = [
+    "integration: live LIME network tests (LIME_MCP_SERVER_INTEGRATION=1)",
+]
+
+[tool.coverage.run]
+branch = false
+source = ["lime_mcp_server"]
+
+[tool.coverage.report]
+fail_under = 100
+show_missing = true
+exclude_lines = [
+    "pragma: no cover",
+]

lime_mcp_server_sdk-0.2.0/src/lime_mcp_server/__init__.py

@@ -0,0 +1,28 @@
+"""LIME MCP resource server SDK — JWT verification via Core JWKS."""
+
+from __future__ import annotations
+
+from lime_mcp_server._cache import JwksCache
+from lime_mcp_server._config import LimeConfig
+from lime_mcp_server._envelope import FORBIDDEN_MCP_CLAIMS, unwrap_lime_data
+from lime_mcp_server._jwt import verify_mcp_access_token
+from lime_mcp_server._types import TokenValidationResult
+from lime_mcp_server._verifier import TokenVerifier
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "FORBIDDEN_MCP_CLAIMS",
+    "JwksCache",
+    "LimeConfig",
+    "TokenValidationResult",
+    "TokenVerifier",
+    "jwks_cache_ttl_seconds",
+    "unwrap_lime_data",
+    "verify_mcp_access_token",
+]
+
+
+def jwks_cache_ttl_seconds() -> int:
+    """Default JWKS cache TTL from environment (compatibility helper)."""
+    return LimeConfig().cache_ttl

lime_mcp_server_sdk-0.2.0/src/lime_mcp_server/_cache.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from lime_mcp_server._config import LimeConfig
+from lime_mcp_server._envelope import JWKS_PATH, METADATA_PATH, unwrap_lime_data
+
+logger = logging.getLogger("lime.mcp_server")
+
+
+@dataclass(frozen=True, slots=True)
+class JwksSnapshot:
+    keys: list[dict[str, Any]]
+    issuer: str
+    fetched_at: float
+
+
+class JwksCache:
+    """Thread-safe JWKS + OAuth metadata cache with stale fallback."""
+
+    def __init__(
+        self,
+        config: LimeConfig,
+        *,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._config = config
+        self._lock = threading.Lock()
+        self._snapshot: JwksSnapshot | None = None
+        self._last_forced_refresh_at: float = 0.0
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(
+            timeout=config.http_timeout,
+            trust_env=False,
+            headers={
+                "Accept": "application/json",
+                "User-Agent": config.user_agent,
+            },
+        )
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def warm(self) -> None:
+        """Prefetch metadata and JWKS (non-fatal on failure)."""
+        try:
+            self.refresh(force=True)
+        except Exception:
+            logger.warning("JWKS cache warmup failed", exc_info=True)
+
+    def invalidate(self) -> None:
+        with self._lock:
+            self._snapshot = None
+
+    def refresh(self, *, force: bool = False) -> None:
+        """Refresh metadata + JWKS from LIME."""
+        now = time.monotonic()
+        with self._lock:
+            if force:
+                elapsed = now - self._last_forced_refresh_at
+                if elapsed < self._config.min_refresh_seconds:
+                    if self._snapshot is not None:
+                        return
+                self._last_forced_refresh_at = now
+            self._snapshot = self._fetch_snapshot()
+
+    def get_jwks(self, kid: str | None) -> tuple[list[dict[str, Any]], str]:
+        """Return JWKS keys and issuer; refresh on TTL expiry or kid mismatch."""
+        snapshot = self._current_snapshot()
+        if snapshot is None or self._is_expired(snapshot):
+            try:
+                self.refresh(force=False)
+            except Exception as exc:
+                if snapshot is not None:
+                    logger.warning("JWKS refresh failed, using stale cache: %s", exc)
+                    return snapshot.keys, snapshot.issuer
+                raise
+            snapshot = self._current_snapshot()
+            if snapshot is None:
+                raise RuntimeError("JWKS cache unavailable after refresh")
+
+        if kid is not None and not any(key.get("kid") == kid for key in snapshot.keys):
+            try:
+                self.refresh(force=True)
+            except Exception as exc:
+                logger.warning("JWKS kid-mismatch refresh failed: %s", exc)
+                if not any(key.get("kid") == kid for key in snapshot.keys):
+                    raise
+            snapshot = self._current_snapshot()
+            if snapshot is None:
+                raise RuntimeError("JWKS cache unavailable after kid refresh")
+
+        return snapshot.keys, snapshot.issuer
+
+    def _current_snapshot(self) -> JwksSnapshot | None:
+        with self._lock:
+            return self._snapshot
+
+    def _is_expired(self, snapshot: JwksSnapshot) -> bool:
+        return (time.monotonic() - snapshot.fetched_at) >= self._config.cache_ttl
+
+    def _fetch_snapshot(self) -> JwksSnapshot:
+        metadata = self._fetch_metadata()
+        issuer = str(metadata.get("issuer", "")).strip()
+        if not issuer:
+            raise ValueError("metadata missing issuer")
+        jwks_uri = str(metadata.get("jwks_uri", ""))
+        keys = self._fetch_jwks(jwks_uri)
+        return JwksSnapshot(keys=keys, issuer=issuer, fetched_at=time.monotonic())
+
+    def _fetch_metadata(self) -> dict[str, Any]:
+        response = self._client.get(f"{self._config.base_url}{METADATA_PATH}")
+        if response.status_code != 200:
+            raise RuntimeError(f"oauth metadata HTTP {response.status_code}")
+        try:
+            body = response.json()
+        except ValueError as exc:
+            raise ValueError("metadata response must be JSON object") from exc
+        if not isinstance(body, dict):
+            raise ValueError("metadata response must be JSON object")
+        return unwrap_lime_data(body)
+
+    def _fetch_jwks(self, jwks_uri: str) -> list[dict[str, Any]]:
+        base = self._config.base_url
+        if jwks_uri.startswith(base):
+            path = jwks_uri[len(base) :]
+        elif jwks_uri.startswith("http"):
+            raise ValueError("cross-origin jwks_uri fetch not supported")
+        elif jwks_uri:
+            path = jwks_uri
+        else:
+            path = JWKS_PATH
+
+        response = self._client.get(f"{base}{path}")
+        if response.status_code != 200:
+            raise RuntimeError(f"jwks HTTP {response.status_code}")
+        try:
+            body = response.json()
+        except ValueError as exc:
+            raise ValueError("jwks response must be JSON object") from exc
+        if not isinstance(body, dict):
+            raise ValueError("jwks response must be JSON object")
+        data = unwrap_lime_data(body)
+        keys = data.get("keys")
+        if not isinstance(keys, list) or not keys:
+            raise ValueError("jwks missing keys")
+        return keys

lime_mcp_server_sdk-0.2.0/src/lime_mcp_server/_config.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+
+def _env_int(name: str, default: str) -> int:
+    return int(os.environ.get(name, default))
+
+
+@dataclass(frozen=True, slots=True)
+class LimeConfig:
+    """Configuration for MCP JWT verification against LIME Core JWKS."""
+
+    base_url: str = field(
+        default_factory=lambda: os.environ.get("LIME_BASE_URL", "https://lime.pics").rstrip("/"),
+    )
+    audience: str = field(
+        default_factory=lambda: os.environ.get("LIME_OAUTH_AUDIENCE", "mcp"),
+    )
+    cache_ttl: int = field(
+        default_factory=lambda: _env_int("LIME_JWKS_CACHE_TTL_SECONDS", "3600"),
+    )
+    leeway_seconds: int = field(
+        default_factory=lambda: _env_int("LIME_JWT_VERIFY_LEEWAY_SECONDS", "120"),
+    )
+    min_refresh_seconds: int = field(
+        default_factory=lambda: _env_int("LIME_JWKS_MIN_REFRESH_SECONDS", "60"),
+    )
+    allowed_algorithms: tuple[str, ...] = ("RS256",)
+    user_agent: str = field(
+        default_factory=lambda: os.environ.get("LIME_VERIFY_USER_AGENT", "curl/8.5.0"),
+    )
+    http_timeout: float = 30.0

lime_mcp_server_sdk-0.2.0/src/lime_mcp_server/_envelope.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import Any
+
+METADATA_PATH = "/api/v1/modules/oauth/.well-known/oauth-authorization-server"
+JWKS_PATH = "/api/v1/core/.well-known/jwks.json"
+
+FORBIDDEN_MCP_CLAIMS = frozenset({"user_id", "passport_version", "request_id"})
+
+
+def unwrap_lime_data(body: dict[str, Any]) -> dict[str, Any]:
+    """Unwrap LIME API envelope ``{ ok, data }``."""
+    if not body.get("ok"):
+        raise ValueError("LIME envelope not ok")
+    data = body.get("data")
+    if not isinstance(data, dict):
+        raise ValueError("LIME envelope missing data object")
+    return data

lime_mcp_server_sdk-0.2.0/src/lime_mcp_server/_jwt.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from typing import Any, cast
+
+import jwt
+from jwt.algorithms import RSAAlgorithm
+
+from lime_mcp_server._envelope import FORBIDDEN_MCP_CLAIMS
+
+
+def verify_mcp_access_token(
+    token: str,
+    *,
+    issuer: str,
+    audience: str,
+    jwks_keys: list[dict[str, Any]],
+    leeway_seconds: int = 120,
+    allowed_algorithms: tuple[str, ...] = ("RS256",),
+) -> dict[str, Any]:
+    """Verify RS256 MCP access token against pre-fetched JWKS keys."""
+    header = jwt.get_unverified_header(token)
+    kid = header.get("kid")
+    matching = [key for key in jwks_keys if key.get("kid") == kid]
+    if not matching:
+        raise jwt.InvalidTokenError(f"no jwks key for kid={kid!r}")
+    public_key = cast(Any, RSAAlgorithm.from_jwk(matching[0]))
+    claims = jwt.decode(
+        token,
+        public_key,
+        algorithms=list(allowed_algorithms),
+        issuer=issuer,
+        audience=audience,
+        leeway=leeway_seconds,
+    )
+    for forbidden in FORBIDDEN_MCP_CLAIMS:
+        if forbidden in claims:
+            raise jwt.InvalidTokenError(f"forbidden claim: {forbidden}")
+    sub = claims.get("sub")
+    if not isinstance(sub, str) or not sub.strip():
+        raise jwt.InvalidTokenError("missing sub claim")
+    return claims

lime_mcp_server_sdk-0.2.0/src/lime_mcp_server/_types.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class TokenValidationResult:
+    """Structured outcome of MCP JWT verification."""
+
+    is_valid: bool
+    claims: dict[str, Any] | None = None
+    error: str | None = None
+
+    @property
+    def agent_id(self) -> str | None:
+        """Agent UUID from ``sub`` claim (MCP OAuth has no separate ``agent_id`` claim)."""
+        if self.is_valid and self.claims:
+            sub = self.claims.get("sub")
+            if isinstance(sub, str) and sub.strip():
+                return sub
+        return None