easy-mcp-kit 0.1.0__py3-none-any.whl

easy_mcp/__init__.py

@@ -0,0 +1,62 @@
+"""easy_mcp — build secure MCP (Model Context Protocol) servers from plain
+Python functions.
+
+Quickstart::
+
+    from easy_mcp import MCPServer
+
+    server = MCPServer(port=8000)
+
+    @server.tool
+    def add(a: int, b: int) -> int:
+        \"\"\"Add two numbers.\"\"\"
+        return a + b
+
+    server.run()
+"""
+
+from .decorators import ToolDefinition
+from .exceptions import (
+    AuthenticationError,
+    AuthorizationError,
+    EasyMCPError,
+    PayloadTooLargeError,
+    ProtocolError,
+    RateLimitError,
+    SchemaError,
+    SessionLimitError,
+    ToolError,
+    ToolRegistrationError,
+    ValidationError,
+)
+from .security.auth import APIKeyAuth, ClientIdentity
+from .security.ratelimit import SlidingWindowRateLimiter
+from .server import PROTOCOL_VERSION, MCPServer
+from .transport.base import ClientContext, Transport
+from .transport.sse import SSETransport
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "APIKeyAuth",
+    "AuthenticationError",
+    "AuthorizationError",
+    "ClientContext",
+    "ClientIdentity",
+    "EasyMCPError",
+    "MCPServer",
+    "PROTOCOL_VERSION",
+    "PayloadTooLargeError",
+    "ProtocolError",
+    "RateLimitError",
+    "SSETransport",
+    "SchemaError",
+    "SessionLimitError",
+    "SlidingWindowRateLimiter",
+    "ToolDefinition",
+    "ToolError",
+    "ToolRegistrationError",
+    "Transport",
+    "ValidationError",
+    "__version__",
+]

easy_mcp/decorators.py

@@ -0,0 +1,175 @@
+"""Tool registration: the ``@server.tool`` decorator machinery and registry."""
+
+from __future__ import annotations
+
+import inspect
+import logging
+import re
+import threading
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from .exceptions import SchemaError, ToolRegistrationError
+from .schema import build_input_schema, parse_docstring
+
+logger = logging.getLogger("easy_mcp.registry")
+
+_TOOL_NAME_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_-]{0,63}$")
+
+
+@dataclass(frozen=True, slots=True)
+class ToolDefinition:
+    """Everything the server knows about one registered tool."""
+
+    name: str
+    description: str
+    fn: Callable[..., Any]
+    input_schema: dict[str, Any]
+    is_async: bool
+    requires_auth: bool = False
+    scopes: frozenset[str] = frozenset()
+    tags: tuple[str, ...] = ()
+    category: str | None = None
+    examples: tuple[Mapping[str, Any], ...] = ()
+    timeout: float | None = None
+    max_calls_per_session: int | None = None
+
+    def to_mcp(self) -> dict[str, Any]:
+        """Serialize this tool for a ``tools/list`` response."""
+        entry: dict[str, Any] = {
+            "name": self.name,
+            "description": self.description,
+            "inputSchema": self.input_schema,
+        }
+        meta: dict[str, Any] = {}
+        if self.tags:
+            meta["tags"] = list(self.tags)
+        if self.category:
+            meta["category"] = self.category
+        if self.examples:
+            meta["examples"] = [dict(example) for example in self.examples]
+        if meta:
+            # `_meta` is MCP's designated slot for implementation metadata.
+            entry["_meta"] = {"easy_mcp": meta}
+        return entry
+
+
+def build_tool(
+    fn: Callable[..., Any],
+    *,
+    name: str | None = None,
+    description: str | None = None,
+    requires_auth: bool = False,
+    scopes: Iterable[str] = (),
+    tags: Iterable[str] = (),
+    category: str | None = None,
+    examples: Iterable[Mapping[str, Any]] = (),
+    timeout: float | None = None,
+    max_calls_per_session: int | None = None,
+) -> ToolDefinition:
+    """Introspect *fn* and produce a :class:`ToolDefinition`.
+
+    Args:
+        fn: The plain (or async) Python function to expose.
+        name: Override for the tool name (defaults to ``fn.__name__``).
+        description: Override for the description (defaults to the docstring
+            summary line).
+        requires_auth: Mark the tool as callable only by authenticated clients.
+        scopes: Scopes an API key must hold to call the tool.  A non-empty
+            value implies ``requires_auth``.
+        tags: Free-form labels surfaced to clients in tool metadata.
+        category: Optional grouping label surfaced in tool metadata.
+        examples: Example invocations, e.g. ``({"arguments": {...}},)``.
+        timeout: Per-tool execution timeout in seconds (overrides the server
+            default).
+        max_calls_per_session: Cap on how often one session may call the tool.
+
+    Raises:
+        ToolRegistrationError: If the function cannot be exposed safely.
+    """
+    if not callable(fn):
+        raise ToolRegistrationError(f"@tool target must be callable, got {type(fn).__name__}")
+    tool_name = name or getattr(fn, "__name__", "")
+    if not _TOOL_NAME_RE.match(tool_name or ""):
+        raise ToolRegistrationError(
+            f"invalid tool name {tool_name!r}: use 1-64 chars [A-Za-z0-9_-], "
+            "starting with a letter"
+        )
+    if timeout is not None and timeout <= 0:
+        raise ToolRegistrationError("timeout must be positive")
+    if max_calls_per_session is not None and max_calls_per_session < 1:
+        raise ToolRegistrationError("max_calls_per_session must be >= 1")
+
+    summary, param_docs = parse_docstring(inspect.getdoc(fn))
+    tool_description = (description or summary).strip()
+    if not tool_description:
+        # LLM clients pick tools by their descriptions; a tool without one is
+        # effectively invisible to them.
+        logger.warning(
+            "tool %r has no description; add a docstring or description=", tool_name
+        )
+        tool_description = tool_name
+
+    try:
+        input_schema = build_input_schema(fn, param_docs)
+    except SchemaError as exc:
+        raise ToolRegistrationError(f"cannot register tool {tool_name!r}: {exc}") from exc
+
+    scope_set = frozenset(scopes)
+    return ToolDefinition(
+        name=tool_name,
+        description=tool_description,
+        fn=fn,
+        input_schema=input_schema,
+        is_async=inspect.iscoroutinefunction(fn),
+        # A scope requirement implies the tool is protected.
+        requires_auth=bool(requires_auth or scope_set),
+        scopes=scope_set,
+        tags=tuple(tags),
+        category=category,
+        examples=tuple(dict(example) for example in examples),
+        timeout=timeout,
+        max_calls_per_session=max_calls_per_session,
+    )
+
+
+class ToolRegistry:
+    """Thread-safe, deterministic registry of tool definitions."""
+
+    def __init__(self) -> None:
+        self._tools: dict[str, ToolDefinition] = {}
+        self._lock = threading.Lock()
+
+    def register(self, tool: ToolDefinition, *, replace: bool = False) -> None:
+        """Add a tool; refuses silent overwrites unless ``replace=True``."""
+        with self._lock:
+            if tool.name in self._tools and not replace:
+                raise ToolRegistrationError(f"a tool named {tool.name!r} is already registered")
+            self._tools[tool.name] = tool
+
+    def unregister(self, name: str) -> ToolDefinition:
+        """Remove and return a tool by name."""
+        with self._lock:
+            try:
+                return self._tools.pop(name)
+            except KeyError:
+                raise ToolRegistrationError(f"no tool named {name!r} is registered") from None
+
+    def get(self, name: str) -> ToolDefinition | None:
+        """Look up a tool by name, or ``None``."""
+        with self._lock:
+            return self._tools.get(name)
+
+    def list(self) -> list[ToolDefinition]:
+        """Tools sorted by name, so ``tools/list`` output is reproducible."""
+        with self._lock:
+            return sorted(self._tools.values(), key=lambda tool: tool.name)
+
+    def __contains__(self, name: object) -> bool:
+        with self._lock:
+            return name in self._tools
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._tools)

easy_mcp/exceptions.py

@@ -0,0 +1,112 @@
+"""Exception hierarchy and JSON-RPC error codes for easy_mcp.
+
+Two kinds of errors exist:
+
+* :class:`ProtocolError` subclasses map directly onto JSON-RPC error
+  responses.  Their messages are written to be safe to send to clients.
+* Everything else is an *internal* error.  Outside debug mode the server
+  never forwards its message or traceback to a client; it logs the full
+  detail server-side under a unique ``error_id`` instead.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# --- Standard JSON-RPC 2.0 error codes --------------------------------------
+PARSE_ERROR = -32700
+INVALID_REQUEST = -32600
+METHOD_NOT_FOUND = -32601
+INVALID_PARAMS = -32602
+INTERNAL_ERROR = -32603
+
+# --- easy_mcp error codes (JSON-RPC reserves -32000..-32099 for servers) -----
+AUTHENTICATION_REQUIRED = -32001
+FORBIDDEN = -32002
+RATE_LIMITED = -32003
+PAYLOAD_TOO_LARGE = -32004
+TOOL_TIMEOUT = -32005
+SESSION_LIMIT_EXCEEDED = -32006
+
+
+class EasyMCPError(Exception):
+    """Base class for every easy_mcp exception."""
+
+
+class ToolRegistrationError(EasyMCPError):
+    """A function could not be registered as a tool."""
+
+
+class SchemaError(ToolRegistrationError):
+    """A type annotation could not be converted to JSON Schema."""
+
+
+class ToolError(EasyMCPError):
+    """Raised *inside a tool* to return an intentional, safe error message.
+
+    Unlike arbitrary exceptions (which are sanitized down to an opaque
+    ``error_id``), the message of a ``ToolError`` is sent to the client
+    verbatim.  Only raise it with text you would show an end user.
+    """
+
+
+class ProtocolError(EasyMCPError):
+    """An error with a JSON-RPC error code, safe to serialize to clients."""
+
+    code: int = INVALID_REQUEST
+
+    def __init__(self, message: str, *, code: int | None = None, data: Any = None) -> None:
+        super().__init__(message)
+        if code is not None:
+            self.code = code
+        self.data = data
+
+
+class ValidationError(ProtocolError):
+    """Tool arguments failed schema validation."""
+
+    code = INVALID_PARAMS
+
+    def __init__(self, errors: list[str]) -> None:
+        self.errors = list(errors)
+        super().__init__(
+            "Invalid tool arguments: " + "; ".join(self.errors),
+            data={"errors": self.errors},
+        )
+
+
+class AuthenticationError(ProtocolError):
+    """The request needs a valid API key."""
+
+    code = AUTHENTICATION_REQUIRED
+
+
+class AuthorizationError(ProtocolError):
+    """The authenticated client lacks a scope the tool requires."""
+
+    code = FORBIDDEN
+
+
+class RateLimitError(ProtocolError):
+    """The client exceeded its request budget."""
+
+    code = RATE_LIMITED
+
+    def __init__(self, retry_after_seconds: float) -> None:
+        self.retry_after_seconds = retry_after_seconds
+        super().__init__(
+            f"Rate limit exceeded; retry in {retry_after_seconds:.1f}s",
+            data={"retry_after_seconds": round(retry_after_seconds, 3)},
+        )
+
+
+class PayloadTooLargeError(ProtocolError):
+    """The request body exceeded ``max_request_bytes``."""
+
+    code = PAYLOAD_TOO_LARGE
+
+
+class SessionLimitError(ProtocolError):
+    """A per-session tool usage limit was reached."""
+
+    code = SESSION_LIMIT_EXCEEDED

easy_mcp/logging.py

@@ -0,0 +1,69 @@
+"""Structured JSON logging and the security audit trail.
+
+All server logs go through the ``easy_mcp`` logger; audit events go through
+``easy_mcp.audit``.  Audit callers must never pass secrets — pass API-key
+*fingerprints* (see :func:`easy_mcp.security.auth.fingerprint`), never keys.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from datetime import UTC, datetime
+from typing import Any
+
+LOGGER_NAME = "easy_mcp"
+AUDIT_LOGGER_NAME = "easy_mcp.audit"
+
+
+class JSONLogFormatter(logging.Formatter):
+    """Format log records as single-line JSON objects."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        payload: dict[str, Any] = {
+            "timestamp": datetime.now(UTC)
+            .isoformat(timespec="milliseconds")
+            .replace("+00:00", "Z"),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+        }
+        event = getattr(record, "event", None)
+        if isinstance(event, dict):
+            payload["event"] = event
+        if record.exc_info:
+            # Tracebacks are for server-side logs only; the dispatcher never
+            # sends them to clients outside debug mode.
+            payload["exception"] = self.formatException(record.exc_info)
+        return json.dumps(payload, ensure_ascii=False, default=str)
+
+
+def configure_logging(*, debug: bool = False, json_logs: bool = True) -> logging.Logger:
+    """Attach a stderr handler to the ``easy_mcp`` logger (idempotent)."""
+    logger = logging.getLogger(LOGGER_NAME)
+    logger.setLevel(logging.DEBUG if debug else logging.INFO)
+    if not any(getattr(handler, "_easy_mcp", False) for handler in logger.handlers):
+        handler = logging.StreamHandler(sys.stderr)
+        handler._easy_mcp = True  # type: ignore[attr-defined]
+        if json_logs:
+            handler.setFormatter(JSONLogFormatter())
+        else:
+            handler.setFormatter(
+                logging.Formatter("%(asctime)s %(levelname)s %(name)s %(message)s")
+            )
+        logger.addHandler(handler)
+        logger.propagate = False
+    return logger
+
+
+def audit(event_type: str, **fields: Any) -> None:
+    """Emit a structured audit event.
+
+    Args:
+        event_type: Short machine-readable event name, e.g. ``tool_call``.
+        **fields: Event payload. Must not contain secrets.
+    """
+    logging.getLogger(AUDIT_LOGGER_NAME).info(
+        event_type, extra={"event": {"type": event_type, **fields}}
+    )

easy_mcp/schema.py

@@ -0,0 +1,246 @@
+"""Type-hint → JSON Schema conversion, docstring parsing, and validation.
+
+Only a deliberate subset of JSON Schema is generated and validated —
+``type`` (with strict bool/int separation), ``items``, ``properties`` /
+``required`` / ``additionalProperties``, ``enum`` and ``anyOf``.  Keeping the
+validator small and hand-written means there is no third-party dependency in
+the request path and its behavior is easy to audit.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+import re
+import types
+import typing
+from collections.abc import Callable
+from typing import Any
+
+from .exceptions import SchemaError, ValidationError
+
+_SCALARS: dict[type, str] = {str: "string", int: "integer", float: "number", bool: "boolean"}
+
+_SECTION_RE = re.compile(
+    r"^(args|arguments|parameters|returns?|raises?|yields?|examples?|notes?|attributes)\s*:\s*$",
+    re.IGNORECASE,
+)
+_PARAM_RE = re.compile(r"^\*{0,2}([A-Za-z_][A-Za-z0-9_]*)\s*(?:\([^)]*\))?\s*:\s*(.*)$")
+
+
+def parse_docstring(doc: str | None) -> tuple[str, dict[str, str]]:
+    """Split a docstring into ``(summary, {param_name: description})``.
+
+    Understands Google-style ``Args:`` sections.  The summary is the first
+    paragraph joined onto a single line — LLM clients choose tools by it.
+    """
+    if not doc:
+        return "", {}
+    lines = inspect.cleandoc(doc).splitlines()
+
+    summary_parts: list[str] = []
+    for line in lines:
+        stripped = line.strip()
+        if not stripped or _SECTION_RE.match(stripped):
+            break
+        summary_parts.append(stripped)
+
+    params: dict[str, str] = {}
+    in_args = False
+    current: str | None = None
+    for line in lines:
+        stripped = line.strip()
+        section = _SECTION_RE.match(stripped)
+        if section:
+            in_args = section.group(1).lower() in ("args", "arguments", "parameters")
+            current = None
+            continue
+        if not in_args:
+            continue
+        if not stripped:
+            current = None
+            continue
+        match = _PARAM_RE.match(stripped)
+        if match:
+            current = match.group(1)
+            params[current] = match.group(2).strip()
+        elif current is not None:
+            # Continuation line of the previous parameter's description.
+            params[current] = f"{params[current]} {stripped}".strip()
+    return " ".join(summary_parts), params
+
+
+def annotation_to_schema(annotation: Any) -> dict[str, Any]:
+    """Convert a Python type annotation into a JSON Schema fragment.
+
+    Supported: ``str``, ``int``, ``float``, ``bool``, ``list``/``list[T]``,
+    ``dict``/``dict[str, T]``, ``Optional``/unions, ``Literal`` and ``Any``.
+
+    Raises:
+        SchemaError: For any annotation outside the supported set.
+    """
+    if annotation is inspect.Parameter.empty:
+        raise SchemaError("parameter is missing a type annotation")
+    if annotation is None or annotation is type(None):
+        return {"type": "null"}
+    if annotation is Any:
+        return {}
+    origin = typing.get_origin(annotation)
+    if origin is None:
+        scalar = _SCALARS.get(annotation)
+        if scalar is not None:
+            return {"type": scalar}
+        if annotation is list:
+            return {"type": "array"}
+        if annotation is dict:
+            return {"type": "object"}
+        raise SchemaError(f"unsupported type annotation: {annotation!r}")
+    if origin is list:
+        args = typing.get_args(annotation)
+        if not args:
+            return {"type": "array"}
+        return {"type": "array", "items": annotation_to_schema(args[0])}
+    if origin is dict:
+        args = typing.get_args(annotation)
+        if not args:
+            return {"type": "object"}
+        key_type, value_type = args
+        if key_type is not str:
+            raise SchemaError("dict keys must be str for JSON compatibility")
+        return {"type": "object", "additionalProperties": annotation_to_schema(value_type)}
+    if origin is typing.Union or origin is types.UnionType:
+        return {"anyOf": [annotation_to_schema(arg) for arg in typing.get_args(annotation)]}
+    if origin is typing.Literal:
+        values = list(typing.get_args(annotation))
+        for value in values:
+            if not isinstance(value, (str, int, float, bool)):
+                raise SchemaError(f"Literal values must be JSON scalars, got {value!r}")
+        return {"enum": values}
+    raise SchemaError(f"unsupported type annotation: {annotation!r}")
+
+
+def build_input_schema(
+    fn: Callable[..., Any], param_docs: dict[str, str] | None = None
+) -> dict[str, Any]:
+    """Build a strict JSON Schema object for *fn*'s parameters.
+
+    Every parameter must have a supported type annotation.  ``*args`` /
+    ``**kwargs`` and positional-only parameters are rejected because tool
+    arguments arrive as a JSON object and are passed by keyword.
+    """
+    param_docs = param_docs or {}
+    signature = inspect.signature(fn)
+    try:
+        hints = typing.get_type_hints(fn)
+    except Exception as exc:  # unresolvable forward references etc.
+        raise SchemaError(f"could not resolve type hints: {exc}") from exc
+
+    properties: dict[str, Any] = {}
+    required: list[str] = []
+    for name, param in signature.parameters.items():
+        if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+            raise SchemaError("*args/**kwargs parameters are not supported")
+        if param.kind is inspect.Parameter.POSITIONAL_ONLY:
+            raise SchemaError("positional-only parameters are not supported")
+        annotation = hints.get(name, param.annotation)
+        try:
+            prop = annotation_to_schema(annotation)
+        except SchemaError as exc:
+            raise SchemaError(f"parameter '{name}': {exc}") from exc
+        if name in param_docs:
+            prop = {**prop, "description": param_docs[name]}
+        if param.default is inspect.Parameter.empty:
+            required.append(name)
+        else:
+            try:
+                json.dumps(param.default)
+            except (TypeError, ValueError):
+                pass  # non-JSON default: still optional, just not advertised
+            else:
+                prop = {**prop, "default": param.default}
+        properties[name] = prop
+
+    # additionalProperties: false makes unknown fields a hard error — clients
+    # cannot smuggle unexpected arguments into a tool call.
+    return {
+        "type": "object",
+        "properties": properties,
+        "required": required,
+        "additionalProperties": False,
+    }
+
+
+def validate_arguments(arguments: dict[str, Any], schema: dict[str, Any]) -> None:
+    """Validate *arguments* against *schema*.
+
+    Raises:
+        ValidationError: Listing every violation found (not just the first).
+    """
+    errors = _check(arguments, schema, "arguments")
+    if errors:
+        raise ValidationError(errors)
+
+
+def _type_ok(value: Any, expected: str) -> bool:
+    # bool is a subclass of int in Python, but JSON treats them as distinct
+    # types — so booleans are rejected wherever numbers are expected.
+    if expected == "boolean":
+        return isinstance(value, bool)
+    if expected == "integer":
+        return isinstance(value, int) and not isinstance(value, bool)
+    if expected == "number":
+        return isinstance(value, (int, float)) and not isinstance(value, bool)
+    if expected == "string":
+        return isinstance(value, str)
+    if expected == "null":
+        return value is None
+    return False
+
+
+def _check(value: Any, schema: dict[str, Any], path: str) -> list[str]:
+    if "enum" in schema:
+        allowed = schema["enum"]
+        if any(type(value) is type(option) and value == option for option in allowed):
+            return []
+        return [f"{path}: must be one of {allowed!r}"]
+    if "anyOf" in schema:
+        for option in schema["anyOf"]:
+            if not _check(value, option, path):
+                return []
+        return [f"{path}: does not match any allowed type"]
+    expected = schema.get("type")
+    if expected is None:
+        return []  # Any: accept everything
+    if expected == "array":
+        if not isinstance(value, list):
+            return [f"{path}: expected array, got {type(value).__name__}"]
+        items = schema.get("items")
+        if not items:
+            return []
+        errors: list[str] = []
+        for index, item in enumerate(value):
+            errors.extend(_check(item, items, f"{path}[{index}]"))
+        return errors
+    if expected == "object":
+        if not isinstance(value, dict):
+            return [f"{path}: expected object, got {type(value).__name__}"]
+        errors = []
+        properties = schema.get("properties", {})
+        additional = schema.get("additionalProperties", True)
+        for name in schema.get("required", []):
+            if name not in value:
+                errors.append(f"{path}.{name}: missing required parameter")
+        for key, item in value.items():
+            if not isinstance(key, str):
+                errors.append(f"{path}: object keys must be strings")
+                continue
+            if key in properties:
+                errors.extend(_check(item, properties[key], f"{path}.{key}"))
+            elif additional is False:
+                errors.append(f"{path}.{key}: unexpected parameter")
+            elif isinstance(additional, dict):
+                errors.extend(_check(item, additional, f"{path}.{key}"))
+        return errors
+    if not _type_ok(value, expected):
+        return [f"{path}: expected {expected}, got {type(value).__name__}"]
+    return []

easy_mcp/security/__init__.py

@@ -0,0 +1,13 @@
+"""Security primitives: authentication, authorization, and rate limiting."""
+
+from .auth import APIKeyAuth, ClientIdentity, authorize, fingerprint, visible
+from .ratelimit import SlidingWindowRateLimiter
+
+__all__ = [
+    "APIKeyAuth",
+    "ClientIdentity",
+    "SlidingWindowRateLimiter",
+    "authorize",
+    "fingerprint",
+    "visible",
+]