appmcp 0.1.0__py3-none-any.whl

appmcp/__init__.py

@@ -0,0 +1,18 @@
+from .application import AppMCP
+from .context import MCPContext
+from .decorators import prompt, resource, tool
+from .dependencies import Depends
+from .security import BearerAuth, Identity, OAuthAuth
+
+__version__ = "0.1.0"
+__all__ = [
+    "AppMCP",
+    "MCPContext",
+    "tool",
+    "resource",
+    "prompt",
+    "Depends",
+    "BearerAuth",
+    "OAuthAuth",
+    "Identity",
+]

appmcp/adapters/__init__.py

@@ -0,0 +1,5 @@
+from .base import MCPBackend
+from .fastmcp import FastMCPAdapter, FastMCPBackend
+from .official_sdk import OfficialSDKBackend
+
+__all__ = ["MCPBackend", "FastMCPAdapter", "FastMCPBackend", "OfficialSDKBackend"]

appmcp/adapters/base.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from ..definitions import Definition
+
+
+class MCPBackend(Protocol):
+    def add_tool(self, definition: Definition) -> None: ...
+    def add_resource(self, definition: Definition) -> None: ...
+    def add_prompt(self, definition: Definition) -> None: ...
+    def create_asgi_app(self, path: str = "/", **options: Any) -> Any: ...
+    async def call_tool(self, name: str, arguments: dict[str, Any]) -> Any: ...

appmcp/adapters/fastmcp.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..definitions import Definition
+
+
+class FastMCPBackend:
+    """FastMCP 3 adapter. FastMCP is imported only when this backend is created."""
+
+    def __init__(self, name: str, **options: Any) -> None:
+        try:
+            from fastmcp import FastMCP
+        except ImportError as exc:
+            raise ImportError("FastMCP is required: pip install appmcp") from exc
+        self.server = FastMCP(name=name, **options)
+
+    def add_tool(self, definition: Definition) -> None:
+        kwargs = {"name": definition.name, "description": definition.description}
+        if definition.read_only:
+            kwargs["annotations"] = {"readOnlyHint": True}
+        self.server.tool(**kwargs)(definition.callable)
+
+    def add_resource(self, definition: Definition) -> None:
+        self.server.resource(
+            definition.uri, name=definition.name, description=definition.description
+        )(definition.callable)
+
+    def add_prompt(self, definition: Definition) -> None:
+        self.server.prompt(name=definition.name, description=definition.description)(
+            definition.callable
+        )
+
+    def create_asgi_app(self, path: str = "/", **options: Any) -> Any:
+        return self.server.http_app(path=path, **options)
+
+    async def call_tool(self, name: str, arguments: dict[str, Any]) -> Any:
+        return await self.server.call_tool(name, arguments)
+
+
+FastMCPAdapter = FastMCPBackend

appmcp/adapters/official_sdk.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..definitions import Definition
+
+
+class OfficialSDKBackend:
+    """Adapter for the official SDK's FastMCP compatibility surface.
+
+    Kept separate from the default FastMCP 3 engine so applications can opt in
+    and compatibility changes remain contained when official SDK v2 stabilizes.
+    """
+
+    def __init__(self, name: str, **options: Any):
+        try:
+            from mcp.server.fastmcp import FastMCP
+        except ImportError as exc:
+            raise ImportError("OfficialSDKBackend requires the 'mcp' Python package") from exc
+        self.server = FastMCP(name, **options)
+
+    def add_tool(self, definition: Definition) -> None:
+        self.server.tool(name=definition.name, description=definition.description)(
+            definition.callable
+        )
+
+    def add_resource(self, definition: Definition) -> None:
+        self.server.resource(
+            definition.uri, name=definition.name, description=definition.description
+        )(definition.callable)
+
+    def add_prompt(self, definition: Definition) -> None:
+        self.server.prompt(name=definition.name, description=definition.description)(
+            definition.callable
+        )
+
+    def create_asgi_app(self, path: str = "/", **options: Any) -> Any:
+        if hasattr(self.server, "streamable_http_app"):
+            return self.server.streamable_http_app()
+        if hasattr(self.server, "http_app"):
+            return self.server.http_app(path=path)
+        raise RuntimeError("Installed official MCP SDK does not provide an ASGI HTTP transport")
+
+    async def call_tool(self, name: str, arguments: dict[str, Any]) -> Any:
+        manager = getattr(self.server, "_tool_manager", None)
+        if manager is None:
+            raise RuntimeError("Installed official MCP SDK has no in-process tool manager")
+        return await manager.call_tool(name, arguments)

appmcp/application.py

@@ -0,0 +1,264 @@
+from __future__ import annotations
+
+import functools
+import inspect
+import logging
+import uuid
+from collections.abc import Callable
+from typing import Any, get_type_hints
+
+from .audit import AuditLogger
+from .context import MCPContext
+from .decorators import prompt as prompt_decorator
+from .decorators import resource as resource_decorator
+from .decorators import tool as tool_decorator
+from .definitions import Definition
+from .dependencies import DependencyContainer, Depends
+from .exceptions import AppMCPError
+from .integrations.asgi import mount_asgi, request_scope
+from .registry import Registry
+from .security import InMemoryRateLimiter, SecurityPolicy
+from .sessions import MemorySessionStore
+from .settings import Settings
+from .telemetry import Telemetry
+
+
+class AppMCP:
+    def __init__(
+        self,
+        app: Any = None,
+        *,
+        name: str = "AppMCP",
+        path: str = "/mcp",
+        auth: Any = None,
+        default_deny: bool = False,
+        expose_errors: bool = False,
+        backend: Any = None,
+        session_store: Any = None,
+        audit: AuditLogger | None = None,
+        middleware: list[Callable] | None = None,
+        telemetry: Telemetry | None = None,
+        auto_mount: bool = True,
+    ) -> None:
+        self.name = name
+        self.settings = Settings(path=path, default_deny=default_deny, expose_errors=expose_errors)
+        self.app = app
+        self.auth = auth
+        self.registry = Registry()
+        self.dependencies = DependencyContainer()
+        self.policy = SecurityPolicy(default_deny=default_deny)
+        self.rate_limiter = InMemoryRateLimiter()
+        self.session_store = session_store or MemorySessionStore()
+        self.audit = audit or AuditLogger()
+        self.middleware = list(middleware or [])
+        self.telemetry = telemetry or Telemetry()
+        self.backend = backend
+        self._mounted_app = None
+        if app is not None and auto_mount:
+            self.mount(app, path=path)
+
+    @classmethod
+    def from_app(cls, app: Any, **kwargs: Any) -> AppMCP:
+        return cls(app, **kwargs)
+
+    @staticmethod
+    def depends(key: str) -> Depends:
+        return Depends(key)
+
+    def provide(self, key: str, provider: Any) -> AppMCP:
+        self.dependencies.provide(key, provider)
+        return self
+
+    def _register(self, target: Any, namespace: str | None = None) -> Definition:
+        definition = self.registry.register(target, namespace)
+        definition.callable = self._transport_callable(definition)
+        if self.backend is not None:
+            getattr(self.backend, f"add_{definition.kind}")(definition)
+        return definition
+
+    def tool(self, *args: Any, **kwargs: Any):
+        def register(fn):
+            tool_decorator(*args, **kwargs)(fn)
+            self._register(fn)
+            return fn
+
+        return register
+
+    def resource(self, uri: str, **kwargs: Any):
+        def register(fn):
+            resource_decorator(uri, **kwargs)(fn)
+            self._register(fn)
+            return fn
+
+        return register
+
+    def prompt(self, *args: Any, **kwargs: Any):
+        def register(fn):
+            prompt_decorator(*args, **kwargs)(fn)
+            self._register(fn)
+            return fn
+
+        return register
+
+    def include(self, instance: Any, namespace: str | None = None) -> AppMCP:
+        for definition in self.registry.include(instance, namespace):
+            definition.callable = self._transport_callable(definition)
+            if self.backend is not None:
+                getattr(self.backend, f"add_{definition.kind}")(definition)
+        return self
+
+    include_instance = include
+
+    def use(self, middleware: Callable) -> AppMCP:
+        self.middleware.append(middleware)
+        return self
+
+    def _ensure_backend(self):
+        if self.backend is None:
+            from .adapters.fastmcp import FastMCPBackend
+
+            self.backend = FastMCPBackend(self.name)
+            for definition in self.registry.all():
+                getattr(self.backend, f"add_{definition.kind}")(definition)
+        return self.backend
+
+    def mount(self, app: Any = None, *, path: str | None = None) -> Any:
+        app = app or self.app
+        if app is None:
+            raise ValueError("mount() requires an ASGI application")
+        self.app = app
+        path = path or self.settings.path
+        mcp_app = self._ensure_backend().create_asgi_app(
+            path="/",
+            json_response=self.settings.json_response,
+            stateless_http=self.settings.stateless_http,
+        )
+        self._mounted_app = mount_asgi(app, mcp_app, path)
+        return self._mounted_app
+
+    def asgi_app(self, *, path: str = "/") -> Any:
+        return self._ensure_backend().create_asgi_app(
+            path=path,
+            json_response=self.settings.json_response,
+            stateless_http=self.settings.stateless_http,
+        )
+
+    async def _context(
+        self, *, headers=None, user=None, scopes=(), confirmed=False, session=None, metadata=None
+    ) -> MCPContext:
+        scope = request_scope.get() or {}
+        raw_headers = scope.get("headers", ())
+        scope_headers = {k.decode("latin1"): v.decode("latin1") for k, v in raw_headers}
+        headers = {**scope_headers, **(headers or {})}
+        if self.auth is not None and user is None:
+            identity = await self.auth.authenticate(headers)
+            if identity:
+                user, scopes = identity.user, identity.scopes
+        request_id = next(
+            (v for k, v in headers.items() if k.lower() == "x-request-id"), str(uuid.uuid4())
+        )
+        return MCPContext(
+            user=user,
+            headers=headers,
+            request_id=request_id,
+            session=session,
+            app=self.app,
+            services=self.dependencies,
+            logger=logging.getLogger(f"appmcp.{self.name}"),
+            scopes=frozenset(scopes),
+            confirmed=confirmed,
+            metadata=metadata or {},
+        )
+
+    async def call_tool(self, name: str, arguments: dict[str, Any], **context: Any) -> Any:
+        return await self.call("tool", name, arguments, **context)
+
+    async def call(self, kind: str, name: str, arguments: dict[str, Any], **context: Any) -> Any:
+        definition = self.registry.get(kind, name)
+        ctx = await self._context(**context)
+        await self.policy.check(definition, ctx)
+        await self.rate_limiter.check(definition, ctx)
+        kwargs = dict(arguments)
+        signature = inspect.signature(
+            definition.metadata.get("original_callable", definition.callable)
+        )
+        try:
+            hints = get_type_hints(
+                definition.metadata.get("original_callable", definition.callable)
+            )
+        except (NameError, TypeError):
+            hints = {}
+        for parameter in signature.parameters.values():
+            if parameter.name in kwargs:
+                continue
+            annotation = hints.get(parameter.name, parameter.annotation)
+            if (
+                annotation is MCPContext
+                or parameter.name == "ctx"
+                and parameter.default is inspect.Parameter.empty
+            ):
+                kwargs[parameter.name] = ctx
+            elif isinstance(parameter.default, Depends):
+                kwargs[parameter.name] = await self.dependencies.resolve(parameter.default.key, ctx)
+
+        async def invoke():
+            value = definition.metadata["original_callable"](**kwargs)
+            return await value if inspect.isawaitable(value) else value
+
+        handler = invoke
+        for middleware in reversed(self.middleware):
+            next_handler = handler
+
+            async def handler(middleware=middleware, next_handler=next_handler):
+                value = middleware(definition, ctx, kwargs, next_handler)
+                return await value if inspect.isawaitable(value) else value
+
+        error = None
+        try:
+            with self.telemetry.span(f"appmcp.{kind}.{name}"):
+                return await handler()
+        except Exception as exc:
+            error = exc
+            if self.settings.expose_errors or isinstance(exc, AppMCPError):
+                raise
+            raise AppMCPError("Operation failed") from exc
+        finally:
+            await self.audit.record(name, ctx, arguments, error)
+
+    def _transport_callable(self, definition: Definition):
+        original = definition.callable
+        definition.metadata["original_callable"] = original
+        signature = inspect.signature(original)
+        try:
+            hints = get_type_hints(original)
+        except (NameError, TypeError):
+            hints = {}
+        public = [
+            p
+            for p in signature.parameters.values()
+            if p.annotation is not MCPContext
+            and not isinstance(p.default, Depends)
+            and p.name != "ctx"
+        ]
+        public = [p for p in public if hints.get(p.name, p.annotation) is not MCPContext]
+
+        @functools.wraps(original)
+        async def wrapper(**kwargs):
+            return await self.call(definition.kind, definition.name, kwargs)
+
+        wrapper.__signature__ = signature.replace(parameters=public)  # type: ignore[attr-defined]
+        return wrapper
+
+    def test_client(self, **kwargs: Any):
+        from .testing import TestClient
+
+        return TestClient(self, **kwargs)
+
+    def inspect(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "path": self.settings.path,
+            "tools": [d.name for d in self.registry.all("tool")],
+            "resources": [{"name": d.name, "uri": d.uri} for d in self.registry.all("resource")],
+            "prompts": [d.name for d in self.registry.all("prompt")],
+        }

appmcp/audit.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import inspect
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any
+
+
+@dataclass
+class AuditEvent:
+    operation: str
+    user: Any
+    arguments: dict[str, Any]
+    success: bool
+    error: str | None
+    timestamp: datetime
+
+
+class AuditLogger:
+    def __init__(self, sink: Callable[[AuditEvent], Any] | None = None) -> None:
+        self.sink = sink
+
+    async def record(
+        self,
+        operation: str,
+        context: Any,
+        arguments: dict[str, Any],
+        error: Exception | None = None,
+    ) -> None:
+        event = AuditEvent(
+            operation,
+            context.user,
+            arguments,
+            error is None,
+            str(error) if error else None,
+            datetime.now(timezone.utc),
+        )
+        if self.sink:
+            result = self.sink(event)
+            if inspect.isawaitable(result):
+                await result
+        else:
+            logging.getLogger("appmcp.audit").info("%s", event)

appmcp/cli.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import argparse
+import importlib
+import json
+from typing import Any
+
+from .application import AppMCP
+from .config import config_json
+
+
+def load_object(reference: str) -> Any:
+    try:
+        module_name, object_path = reference.split(":", 1)
+    except ValueError as exc:
+        raise ValueError("Application reference must look like package.module:object") from exc
+    value = importlib.import_module(module_name)
+    for part in object_path.split("."):
+        value = getattr(value, part)
+    return value
+
+
+def find_appmcp(value: Any) -> AppMCP:
+    if isinstance(value, AppMCP):
+        return value
+    for candidate in vars(importlib.import_module(value.__module__)).values():
+        if isinstance(candidate, AppMCP) and (
+            candidate.app is value or value is candidate._mounted_app
+        ):
+            return candidate
+    raise ValueError("No AppMCP instance is associated with that application")
+
+
+def inspect_command(reference: str) -> int:
+    info = find_appmcp(load_object(reference)).inspect()
+    print(f"Application: {info['name']}\nMCP path: {info['path']}\n")
+    for heading, key in (("Tools", "tools"), ("Resources", "resources"), ("Prompts", "prompts")):
+        print(f"{heading}:")
+        for item in info[key]:
+            print(f"  {item['uri'] if isinstance(item, dict) else item}")
+    return 0
+
+
+def dev_command(reference: str, host: str, port: int) -> int:
+    try:
+        import uvicorn
+    except ImportError as exc:
+        raise SystemExit("Development server requires: pip install appmcp[fastapi]") from exc
+    uvicorn.run(reference, host=host, port=port, factory=False)
+    return 0
+
+
+def test_command(reference: str) -> int:
+    mcp = find_appmcp(load_object(reference))
+    info = mcp.inspect()
+    print(json.dumps(info, indent=2))
+    print("Registration validation passed")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="appmcp")
+    sub = parser.add_subparsers(dest="command", required=True)
+    inspect_parser = sub.add_parser("inspect", help="List exposed capabilities")
+    inspect_parser.add_argument("application")
+    dev = sub.add_parser("dev", help="Run an ASGI development server")
+    dev.add_argument("application")
+    dev.add_argument("--host", default="127.0.0.1")
+    dev.add_argument("--port", type=int, default=8000)
+    test = sub.add_parser("test", help="Validate capability registration")
+    test.add_argument("application")
+    config = sub.add_parser("config", help="Generate MCP client configuration")
+    config.add_argument("client", choices=["claude", "cursor", "vscode"])
+    config.add_argument("application")
+    config.add_argument("--url", default="http://127.0.0.1:8000/mcp")
+    args = parser.parse_args(argv)
+    if args.command == "inspect":
+        return inspect_command(args.application)
+    if args.command == "dev":
+        return dev_command(args.application, args.host, args.port)
+    if args.command == "test":
+        return test_command(args.application)
+    mcp = find_appmcp(load_object(args.application))
+    print(config_json(args.client, url=args.url, name=mcp.name))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

appmcp/config.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def generate_config(client: str, *, url: str, name: str = "appmcp") -> dict[str, Any]:
+    client = client.lower()
+    server = {"url": url, "transport": "streamable-http"}
+    if client in {"claude", "cursor", "vscode"}:
+        return {"mcpServers": {name: server}}
+    raise ValueError(f"Unsupported client {client!r}; choose claude, cursor, or vscode")
+
+
+def config_json(client: str, *, url: str, name: str = "appmcp") -> str:
+    return json.dumps(generate_config(client, url=url, name=name), indent=2)

appmcp/context.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class MCPContext:
+    user: Any = None
+    headers: Mapping[str, str] = field(default_factory=dict)
+    request_id: str = ""
+    session: Any = None
+    app: Any = None
+    services: Any = None
+    logger: logging.Logger = field(default_factory=lambda: logging.getLogger("appmcp"))
+    scopes: frozenset[str] = field(default_factory=frozenset)
+    confirmed: bool = False
+    metadata: dict[str, Any] = field(default_factory=dict)

appmcp/decorators.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from .definitions import Exposure
+
+F = TypeVar("F", bound=Callable[..., Any])
+MARKER = "__appmcp_exposure__"
+
+
+def _decorate(kind: str, **options: Any):
+    exposure = Exposure(kind=kind, **options)
+
+    def wrapper(fn: F) -> F:
+        setattr(fn, MARKER, exposure)
+        return fn
+
+    return wrapper
+
+
+def tool(
+    name: str | None = None,
+    *,
+    description: str | None = None,
+    scopes: list[str] | tuple[str, ...] = (),
+    rate_limit: str | None = None,
+    read_only: bool = False,
+    confirmation_required: bool = False,
+    enabled: bool | Callable[[Any], bool] = True,
+    **metadata: Any,
+):
+    return _decorate(
+        "tool",
+        name=name,
+        description=description,
+        scopes=tuple(scopes),
+        rate_limit=rate_limit,
+        read_only=read_only,
+        confirmation_required=confirmation_required,
+        enabled=enabled,
+        metadata=metadata,
+    )
+
+
+def resource(
+    uri: str,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+    scopes: list[str] | tuple[str, ...] = (),
+    enabled: bool | Callable[[Any], bool] = True,
+    **metadata: Any,
+):
+    return _decorate(
+        "resource",
+        name=name,
+        uri=uri,
+        description=description,
+        scopes=tuple(scopes),
+        enabled=enabled,
+        metadata=metadata,
+    )
+
+
+def prompt(
+    name: str | None = None,
+    *,
+    description: str | None = None,
+    scopes: list[str] | tuple[str, ...] = (),
+    enabled: bool | Callable[[Any], bool] = True,
+    **metadata: Any,
+):
+    return _decorate(
+        "prompt",
+        name=name,
+        description=description,
+        scopes=tuple(scopes),
+        enabled=enabled,
+        metadata=metadata,
+    )
+
+
+def get_exposure(value: Any) -> Exposure | None:
+    return getattr(value, MARKER, None) or getattr(getattr(value, "__func__", None), MARKER, None)

appmcp/definitions.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Exposure:
+    kind: str
+    name: str | None = None
+    description: str | None = None
+    uri: str | None = None
+    scopes: tuple[str, ...] = ()
+    rate_limit: str | None = None
+    read_only: bool = False
+    confirmation_required: bool = False
+    enabled: bool | Callable[[Any], bool] = True
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Definition:
+    kind: str
+    name: str
+    callable: Callable[..., Any]
+    description: str = ""
+    uri: str | None = None
+    scopes: tuple[str, ...] = ()
+    rate_limit: str | None = None
+    read_only: bool = False
+    confirmation_required: bool = False
+    enabled: bool | Callable[[Any], bool] = True
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+ToolDefinition = Definition
+ResourceDefinition = Definition
+PromptDefinition = Definition