azathoth-mcp 1.2.0__tar.gz

azathoth_mcp-1.2.0/LICENSE

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

azathoth_mcp-1.2.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: azathoth-mcp
+Version: 1.2.0
+Summary: Serve promoted Azathoth workflows as Model Context Protocol tools.
+Author: Eris Discordia Montano
+License: MIT
+Project-URL: Homepage, https://github.com/EldritchInc/azathoth
+Project-URL: Repository, https://github.com/EldritchInc/azathoth
+Project-URL: Issues, https://github.com/EldritchInc/azathoth/issues
+Project-URL: Documentation, https://github.com/EldritchInc/azathoth/blob/main/docs/mcp.md
+Keywords: artificial-intelligence,llm,mcp,model-context-protocol,workflow-optimization
+Classifier: Development Status :: 5 - Production/Stable
+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: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: azathoth-ai==1.2.*
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: pyjwt[crypto]<3,>=2.10
+Dynamic: license-file
+
+# Azathoth MCP
+
+Azathoth MCP serves promoted
+[Azathoth](https://github.com/EldritchInc/azathoth) workflows as
+[Model Context Protocol](https://modelcontextprotocol.io) tools, so an AI
+client such as Claude Desktop, an IDE or your own agent can call them.
+
+Only the workflows an operator lists are offered, each as one tool with the
+name and description the operator wrote. Every call runs the workflow's
+active production revision as a recorded, idempotent invocation, and returns
+the invocation's ID with its result, so what an agent did can be traced to
+its runs and evidence.
+
+It runs over stdio for a local client, or over Streamable HTTP for a team,
+as an OAuth 2.1 resource server in front of your organization's identity
+provider.
+
+[Serving Workflows Over MCP](https://github.com/EldritchInc/azathoth/blob/main/docs/mcp.md)
+shows how to expose a workflow, connect Claude Desktop, and serve a team
+behind your identity provider.
+
+Azathoth MCP is released with Azathoth, at the same version, and requires
+the same minor release of `azathoth-ai`. The design is recorded in
+[ADR 0111](https://github.com/EldritchInc/azathoth/blob/main/docs/adrs/0111-serve-promoted-workflows-over-mcp.md).
+
+## License
+
+MIT. See [LICENSE](https://github.com/EldritchInc/azathoth/blob/main/packages/azathoth-mcp/LICENSE).

azathoth_mcp-1.2.0/README.md

@@ -0,0 +1,28 @@
+# Azathoth MCP
+
+Azathoth MCP serves promoted
+[Azathoth](https://github.com/EldritchInc/azathoth) workflows as
+[Model Context Protocol](https://modelcontextprotocol.io) tools, so an AI
+client such as Claude Desktop, an IDE or your own agent can call them.
+
+Only the workflows an operator lists are offered, each as one tool with the
+name and description the operator wrote. Every call runs the workflow's
+active production revision as a recorded, idempotent invocation, and returns
+the invocation's ID with its result, so what an agent did can be traced to
+its runs and evidence.
+
+It runs over stdio for a local client, or over Streamable HTTP for a team,
+as an OAuth 2.1 resource server in front of your organization's identity
+provider.
+
+[Serving Workflows Over MCP](https://github.com/EldritchInc/azathoth/blob/main/docs/mcp.md)
+shows how to expose a workflow, connect Claude Desktop, and serve a team
+behind your identity provider.
+
+Azathoth MCP is released with Azathoth, at the same version, and requires
+the same minor release of `azathoth-ai`. The design is recorded in
+[ADR 0111](https://github.com/EldritchInc/azathoth/blob/main/docs/adrs/0111-serve-promoted-workflows-over-mcp.md).
+
+## License
+
+MIT. See [LICENSE](https://github.com/EldritchInc/azathoth/blob/main/packages/azathoth-mcp/LICENSE).

azathoth_mcp-1.2.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "azathoth-mcp"
+version = "1.2.0"
+description = "Serve promoted Azathoth workflows as Model Context Protocol tools."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+    { name = "Eris Discordia Montano" }
+]
+keywords = [
+    "artificial-intelligence",
+    "llm",
+    "mcp",
+    "model-context-protocol",
+    "workflow-optimization"
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed"
+]
+dependencies = [
+    "azathoth-ai==1.2.*",
+    "mcp>=2.3,<3",
+    "pyjwt[crypto]>=2.10,<3",
+]
+
+[project.scripts]
+azathoth-mcp = "azathoth_mcp.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/EldritchInc/azathoth"
+Repository = "https://github.com/EldritchInc/azathoth"
+Issues = "https://github.com/EldritchInc/azathoth/issues"
+Documentation = "https://github.com/EldritchInc/azathoth/blob/main/docs/mcp.md"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+azathoth_mcp = ["py.typed"]

azathoth_mcp-1.2.0/setup.cfg

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

azathoth_mcp-1.2.0/src/azathoth_mcp/__init__.py

@@ -0,0 +1,8 @@
+"""Azathoth MCP: serve promoted Azathoth workflows as Model Context Protocol tools (ADR 0111).
+
+This distribution is released in lockstep with `azathoth-ai`: it has the same
+version and requires the same minor release, so it may use Azathoth's Python
+API as it stands in that release.
+"""
+
+__version__ = "1.2.0"

azathoth_mcp-1.2.0/src/azathoth_mcp/__main__.py

@@ -0,0 +1,8 @@
+"""Run `azathoth-mcp` as `python -m azathoth_mcp`."""
+
+import sys
+
+from azathoth_mcp.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

azathoth_mcp-1.2.0/src/azathoth_mcp/access.py

@@ -0,0 +1,147 @@
+"""Who is calling, and what they may call (ADR 0111).
+
+A caller over stdio started the server with its own credentials, and may
+call everything the server offers. A caller over HTTP holds a token, and may
+call only what the token's scopes allow:
+
+- `azathoth:invoke:<tool>` for each exposed workflow's tool;
+- `azathoth:read` for `get_invocation`, which then returns only the
+  invocations recorded with the caller's own subject;
+- `azathoth:read:all` to read every invocation of an exposed workflow.
+
+The caller is recorded with every invocation, under `mcp` in its caller
+metadata, so `invocation show` names who made it.
+"""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, Field, JsonValue
+
+SCOPE_PREFIX = "azathoth:"
+
+READ_SCOPE = "azathoth:read"
+"""Read the invocations recorded with the caller's own subject."""
+
+READ_ALL_SCOPE = "azathoth:read:all"
+"""Read every invocation of an exposed workflow, whoever made it."""
+
+CALLER_METADATA_KEY = "mcp"
+"""Where an invocation's caller metadata records the MCP caller."""
+
+
+def invoke_scope(
+    tool: str,
+) -> str:
+    """Return the scope that allows calling one exposed workflow's tool."""
+
+    return f"azathoth:invoke:{tool}"
+
+
+class Transport(StrEnum):
+    """How a caller reaches the server."""
+
+    STDIO = "stdio"
+    HTTP = "http"
+
+
+class ToolAccessError(PermissionError):
+    """Raised when a caller's token does not allow a call."""
+
+
+class McpCaller(BaseModel):
+    """The client one call comes from.
+
+    `scopes` is what the caller's token grants, or `None` for a caller the
+    server does not authorize, over stdio or a loopback-only HTTP server.
+    `subject` and `client_id` come from the token, when there is one.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    transport: Transport
+    subject: str | None = Field(default=None, min_length=1)
+    client_id: str | None = Field(default=None, min_length=1)
+    scopes: frozenset[str] | None = None
+
+    def require(
+        self,
+        scope: str,
+    ) -> None:
+        """Refuse a call this caller's token does not allow.
+
+        Raises:
+            ToolAccessError: The caller is authorized, and its token does not
+                carry the scope.
+        """
+
+        if self.scopes is not None and scope not in self.scopes:
+            raise ToolAccessError(f'This call needs the scope "{scope}".')
+
+    @property
+    def reads_every_invocation(
+        self,
+    ) -> bool:
+        """Report whether this caller may read invocations other callers made."""
+
+        return self.scopes is None or READ_ALL_SCOPE in self.scopes
+
+    def may_read(
+        self,
+        caller_metadata: dict[str, JsonValue],
+    ) -> bool:
+        """Report whether this caller may read an invocation with this caller metadata.
+
+        A caller that reads every invocation may read any. Another may read
+        only one recorded over MCP with its own subject.
+        """
+
+        if self.reads_every_invocation:
+            return True
+
+        recorded = caller_metadata.get(CALLER_METADATA_KEY)
+
+        return (
+            self.subject is not None
+            and isinstance(recorded, dict)
+            and recorded.get("subject") == self.subject
+        )
+
+    def caller_metadata(
+        self,
+        tool: str,
+    ) -> dict[str, JsonValue]:
+        """Return the caller metadata one invocation of a tool records.
+
+        It holds the transport and the tool, and the token's subject and
+        client ID when there is a token. It never holds the token itself.
+        """
+
+        recorded: dict[str, JsonValue] = {
+            "transport": self.transport.value,
+            "tool": tool,
+        }
+
+        if self.subject is not None:
+            recorded["subject"] = self.subject
+
+        if self.client_id is not None:
+            recorded["client_id"] = self.client_id
+
+        return {CALLER_METADATA_KEY: recorded}
+
+
+STDIO_CALLER = McpCaller(transport=Transport.STDIO)
+"""The one caller of a server over stdio."""
+
+
+__all__ = [
+    "CALLER_METADATA_KEY",
+    "READ_ALL_SCOPE",
+    "READ_SCOPE",
+    "SCOPE_PREFIX",
+    "STDIO_CALLER",
+    "McpCaller",
+    "ToolAccessError",
+    "Transport",
+    "invoke_scope",
+]

azathoth_mcp-1.2.0/src/azathoth_mcp/authorization.py

@@ -0,0 +1,342 @@
+"""Authorizing HTTP callers: an OAuth 2.1 resource server (ADR 0111).
+
+The server issues no tokens and signs no one in; the organization's
+identity provider does. Every request carries a bearer token, a signed JWT,
+which the server accepts only when all of these hold:
+
+- it is signed, by an algorithm on the allow-list, with one of the
+  provider's published keys;
+- its issuer is the provider's;
+- its audience holds this server's own resource URL (RFC 8707), so a token
+  issued for another service is refused;
+- it has an expiry, and has not expired; with a maximum lifetime set, it
+  also says when it was issued, and lives no longer than that;
+- it names its subject.
+
+The token's scopes, from `scope` or `scp`, decide what the caller may call
+(`azathoth_mcp.access`). A token is never logged, never passed on, and never
+kept beyond its request.
+"""
+
+import asyncio
+import logging
+import re
+from collections.abc import Mapping
+from typing import Any, Protocol
+
+import httpx
+import jwt
+from mcp.server.auth.provider import AccessToken
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from azathoth_mcp.access import McpCaller, Transport
+
+DEFAULT_ALGORITHMS = ("RS256", "ES256")
+"""The signing algorithms accepted unless the operator names others."""
+
+ASYMMETRIC_ALGORITHMS = frozenset(
+    {"RS256", "RS384", "RS512", "PS256", "PS384", "PS512", "ES256", "ES384", "ES512", "EdDSA"}
+)
+"""The algorithms an operator may allow: public-key ones only, never `none` or HMAC."""
+
+DEFAULT_LEEWAY_SECONDS = 30
+"""How far apart the server's clock and the provider's may be."""
+
+DISCOVERY_PATHS = (
+    "/.well-known/openid-configuration",
+    "/.well-known/oauth-authorization-server",
+)
+"""Where an issuer's metadata names its keys, OpenID Connect's first (RFC 8414)."""
+
+HTTPS_URL = re.compile(r"https://[^\s/?#]+(?:/[^\s?#]*)?")
+
+LOOPBACK_HTTP_URL = re.compile(r"http://(?:127\.0\.0\.1|localhost|\[::1\])(?::\d+)?(?:/[^\s?#]*)?")
+
+logger = logging.getLogger(__name__)
+
+
+class AuthorizationConfigurationError(ValueError):
+    """Raised when the server cannot be set up to authorize its callers."""
+
+
+class AuthorizationSettings(BaseModel):
+    """How one server authorizes its HTTP callers.
+
+    `issuer` is the identity provider's issuer, exactly as its tokens carry
+    it. `resource` is this server's own URL, the one clients connect to and
+    tokens must name as their audience. Both are HTTPS, or HTTP on a loopback
+    address for testing.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    issuer: str
+    resource: str
+    jwks_url: str | None = None
+    algorithms: tuple[str, ...] = DEFAULT_ALGORITHMS
+    max_lifetime_seconds: int | None = Field(default=None, gt=0)
+    leeway_seconds: int = Field(default=DEFAULT_LEEWAY_SECONDS, ge=0)
+
+    @field_validator("issuer", "resource", "jwks_url")
+    @classmethod
+    def require_secure_url(
+        cls,
+        url: str | None,
+    ) -> str | None:
+        """Refuse a URL that is not HTTPS, unless it is HTTP on a loopback address."""
+
+        if url is None:
+            return None
+
+        if HTTPS_URL.fullmatch(url) is None and LOOPBACK_HTTP_URL.fullmatch(url) is None:
+            raise ValueError(
+                f"{url} must be an HTTPS URL, or an HTTP URL on a loopback address, "
+                "with no query or fragment."
+            )
+
+        return url
+
+    @field_validator("algorithms")
+    @classmethod
+    def require_public_key_algorithms(
+        cls,
+        algorithms: tuple[str, ...],
+    ) -> tuple[str, ...]:
+        """Refuse an empty allow-list, and any algorithm that is not public-key."""
+
+        if not algorithms:
+            raise ValueError("At least one signing algorithm must be allowed.")
+
+        refused = sorted(set(algorithms) - ASYMMETRIC_ALGORITHMS)
+
+        if refused:
+            raise ValueError(
+                "Only public-key signing algorithms may be allowed; not " + ", ".join(refused) + "."
+            )
+
+        return algorithms
+
+
+class SigningKeys(Protocol):
+    """Where a verifier finds the key that signed one token."""
+
+    def key_for(
+        self,
+        token: str,
+    ) -> Any:
+        """Return the public key that signed one token.
+
+        Raises:
+            jwt.PyJWTError: No published key signed it, or the keys cannot be read.
+        """
+
+        ...
+
+
+class PublishedKeys:
+    """An identity provider's published keys (its JWKS), cached and refreshed as keys rotate."""
+
+    def __init__(
+        self,
+        jwks_url: str,
+    ) -> None:
+        self._client = jwt.PyJWKClient(jwks_url, cache_keys=True, lifespan=300, timeout=10)
+
+    def key_for(
+        self,
+        token: str,
+    ) -> Any:
+        """Return the published key named by one token's `kid`."""
+
+        return self._client.get_signing_key_from_jwt(token).key
+
+
+def discover_jwks_url(
+    issuer: str,
+    *,
+    client: httpx.Client | None = None,
+) -> str:
+    """Return the URL of an issuer's published keys, from its metadata.
+
+    Raises:
+        AuthorizationConfigurationError: Neither metadata document can be
+            read, or neither names its keys.
+    """
+
+    owned = client is None
+    http = client if client is not None else httpx.Client(timeout=10)
+
+    try:
+        for path in DISCOVERY_PATHS:
+            try:
+                response = http.get(issuer.rstrip("/") + path)
+            except httpx.HTTPError:
+                continue
+
+            if response.status_code != 200:
+                continue
+
+            try:
+                metadata = response.json()
+            except ValueError:
+                continue
+
+            jwks_url = metadata.get("jwks_uri") if isinstance(metadata, dict) else None
+
+            if isinstance(jwks_url, str) and jwks_url:
+                return jwks_url
+    finally:
+        if owned:
+            http.close()
+
+    raise AuthorizationConfigurationError(
+        f"Cannot find the signing keys of {issuer}: neither its OpenID Connect nor its "
+        "OAuth metadata names a jwks_uri. Name them with --jwks-url."
+    )
+
+
+def token_scopes(
+    claims: Mapping[str, Any],
+) -> tuple[str, ...]:
+    """Return a token's scopes, from `scope` or, as some providers write it, `scp`.
+
+    Either may be one space-separated string or a list of strings.
+    """
+
+    for name in ("scope", "scp"):
+        value = claims.get(name)
+
+        if isinstance(value, str):
+            return tuple(value.split())
+
+        if isinstance(value, list) and all(isinstance(scope, str) for scope in value):
+            return tuple(value)
+
+    return ()
+
+
+def token_client_id(
+    claims: Mapping[str, Any],
+) -> str:
+    """Return the client a token was issued to, or an empty string if it names none."""
+
+    for name in ("client_id", "azp", "appid"):
+        value = claims.get(name)
+
+        if isinstance(value, str) and value:
+            return value
+
+    return ""
+
+
+class JwtTokenVerifier:
+    """Verify bearer tokens as signed JWTs, as the SDK's bearer middleware asks."""
+
+    def __init__(
+        self,
+        settings: AuthorizationSettings,
+        keys: SigningKeys,
+    ) -> None:
+        self._settings = settings
+        self._keys = keys
+
+    async def verify_token(
+        self,
+        token: str,
+    ) -> AccessToken | None:
+        """Return the access a valid token grants, or `None` for any other.
+
+        Why a token was refused is logged by kind, never with the token.
+        """
+
+        try:
+            claims = await asyncio.to_thread(self._claims, token)
+        except jwt.PyJWTError as exc:
+            logger.info("A bearer token was refused: %s.", type(exc).__name__)
+
+            return None
+
+        return AccessToken(
+            token=token,
+            client_id=token_client_id(claims),
+            scopes=list(token_scopes(claims)),
+            expires_at=int(claims["exp"]),
+            resource=self._settings.resource,
+            subject=str(claims["sub"]),
+            claims={"iss": claims["iss"]},
+        )
+
+    def _claims(
+        self,
+        token: str,
+    ) -> dict[str, Any]:
+        """Return one token's verified claims.
+
+        Raises:
+            jwt.PyJWTError: The token is not one this server accepts.
+        """
+
+        settings = self._settings
+        required = ["exp", "iss", "aud", "sub"]
+
+        if settings.max_lifetime_seconds is not None:
+            required.append("iat")
+
+        claims: dict[str, Any] = jwt.decode(
+            token,
+            self._keys.key_for(token),
+            algorithms=list(settings.algorithms),
+            audience=settings.resource,
+            issuer=settings.issuer,
+            leeway=settings.leeway_seconds,
+            options={"require": required},
+        )
+
+        if settings.max_lifetime_seconds is not None:
+            lifetime = int(claims["exp"]) - int(claims["iat"])
+
+            if lifetime > settings.max_lifetime_seconds:
+                raise jwt.InvalidTokenError("The token lives longer than this server allows.")
+
+        if not isinstance(claims["sub"], str) or not claims["sub"]:
+            raise jwt.MissingRequiredClaimError("sub")
+
+        return claims
+
+
+def http_caller(
+    access: AccessToken | None,
+) -> McpCaller:
+    """Return the caller one HTTP request comes from.
+
+    A request without a token reaches the server only when it runs without
+    authorization, on a loopback address; that caller may call everything,
+    as the local caller over stdio may.
+    """
+
+    if access is None:
+        return McpCaller(transport=Transport.HTTP)
+
+    return McpCaller(
+        transport=Transport.HTTP,
+        subject=access.subject or None,
+        client_id=access.client_id or None,
+        scopes=frozenset(access.scopes),
+    )
+
+
+__all__ = [
+    "ASYMMETRIC_ALGORITHMS",
+    "DEFAULT_ALGORITHMS",
+    "DEFAULT_LEEWAY_SECONDS",
+    "DISCOVERY_PATHS",
+    "AuthorizationConfigurationError",
+    "AuthorizationSettings",
+    "JwtTokenVerifier",
+    "PublishedKeys",
+    "SigningKeys",
+    "discover_jwks_url",
+    "http_caller",
+    "token_client_id",
+    "token_scopes",
+]