asap-protocol 0.3.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

asap/mcp/server.py

@@ -0,0 +1,333 @@
+"""MCP server implementation (spec 2025-11-25).
+
+Runs over stdio: reads JSON-RPC messages (one per line) from stdin,
+dispatches to handlers, writes responses to stdout.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import io
+import inspect
+import json
+import sys
+from collections.abc import Callable
+from typing import Any, cast
+
+import jsonschema
+
+from asap.mcp.protocol import (
+    INVALID_PARAMS,
+    INTERNAL_ERROR,
+    METHOD_NOT_FOUND,
+    MCP_PROTOCOL_VERSION,
+    PARSE_ERROR,
+    CallToolRequestParams,
+    CallToolResult,
+    Implementation,
+    InitializeResult,
+    JSONRPCError,
+    JSONRPCErrorResponse,
+    JSONRPCNotification,
+    JSONRPCRequest,
+    JSONRPCResponse,
+    ListToolsResult,
+    TextContent,
+    Tool,
+)
+from asap.observability import get_logger, is_debug_mode
+
+logger = get_logger(__name__)
+
+_INTERNAL_TOOL_ERROR_MESSAGE = "Internal tool error"
+
+EMPTY_INPUT_SCHEMA: dict[str, Any] = {"type": "object", "additionalProperties": False}
+
+
+class MCPServer:
+    """MCP server with stdio transport and tools support.
+
+    Register tools with register_tool(), then run with serve_stdio().
+    Supports initialize, tools/list, and tools/call per MCP 2025-11-25.
+    """
+
+    def __init__(
+        self,
+        name: str = "asap-mcp-server",
+        version: str = "1.0.0",
+        title: str | None = None,
+        description: str | None = None,
+        instructions: str | None = None,
+    ) -> None:
+        """Initialize the MCP server.
+
+        Args:
+            name: Server programmatic name.
+            version: Server version string.
+            title: Optional human-readable title.
+            description: Optional description.
+            instructions: Optional instructions for the client/LLM.
+        """
+        self._server_info = Implementation(
+            name=name,
+            version=version,
+            title=title or name,
+            description=description,
+        )
+        self._instructions = instructions
+        self._tools: dict[str, tuple[Callable[..., Any], dict[str, Any], str, str | None]] = {}
+        self._request_id_counter = 0
+
+    def register_tool(
+        self,
+        name: str,
+        func: Callable[..., Any],
+        schema: dict[str, Any],
+        *,
+        description: str = "",
+        title: str | None = None,
+    ) -> None:
+        """Register a tool that can be invoked via tools/call.
+
+        Args:
+            name: Unique tool name (e.g. "echo", "get_weather").
+            func: Callable that receives keyword arguments from the client.
+                  May be sync or async; return value is converted to text for
+                  the result content. The framework passes raw arguments as
+                  keyword dict; each tool must validate its own inputs.
+            schema: JSON Schema for the tool's parameters (inputSchema).
+                    Use EMPTY_INPUT_SCHEMA for no parameters.
+            description: Human-readable description (required by spec).
+            title: Optional display title.
+        """
+        input_schema = schema if schema else EMPTY_INPUT_SCHEMA
+        self._tools[name] = (
+            func,
+            input_schema,
+            description or f"Tool {name}",
+            title,
+        )
+
+    def _get_capabilities(self) -> dict[str, Any]:
+        """Server capabilities for initialize result."""
+        caps: dict[str, Any] = {}
+        if self._tools:
+            caps["tools"] = {"listChanged": True}
+        return caps
+
+    def _handle_initialize(self, params: dict[str, Any] | None) -> dict[str, Any]:
+        """Handle initialize request; return InitializeResult as dict."""
+        result = InitializeResult(
+            protocolVersion=MCP_PROTOCOL_VERSION,
+            capabilities=self._get_capabilities(),
+            serverInfo=self._server_info,
+            instructions=self._instructions,
+        )
+        return result.model_dump(by_alias=True, exclude_none=True)
+
+    def _handle_tools_list(self, params: dict[str, Any] | None) -> dict[str, Any]:
+        """Handle tools/list; return ListToolsResult as dict."""
+        tools_list: list[Tool] = []
+        for name, (_, input_schema, description, title) in self._tools.items():
+            tools_list.append(
+                Tool(
+                    name=name,
+                    description=description,
+                    inputSchema=input_schema,
+                    title=title,
+                )
+            )
+        result = ListToolsResult(tools=tools_list)
+        return result.model_dump(by_alias=True, exclude_none=True)
+
+    async def _handle_tools_call(self, params: dict[str, Any]) -> dict[str, Any]:
+        """Handle tools/call; execute tool and return CallToolResult as dict.
+
+        Raises:
+            ValueError: With code INVALID_PARAMS for malformed params or tool
+                argument mismatch (e.g. missing or invalid keyword arguments).
+        """
+        try:
+            parsed = CallToolRequestParams(**params)
+        except Exception as e:
+            raise ValueError(f"Invalid params: {e}") from e
+
+        if parsed.name not in self._tools:
+            return CallToolResult(
+                content=[
+                    TextContent(text=f"Unknown tool: {parsed.name}").model_dump(by_alias=True)
+                ],
+                isError=True,
+            ).model_dump(by_alias=True, exclude_none=True)
+
+        func, input_schema, _desc, _title = self._tools[parsed.name]
+        try:
+            jsonschema.validate(instance=parsed.arguments, schema=input_schema)
+        except jsonschema.ValidationError as e:
+            raise ValueError(f"Invalid arguments: {e.message}") from e
+
+        try:
+            if inspect.iscoroutinefunction(func):
+                out = await func(**parsed.arguments)
+            else:
+                loop = asyncio.get_running_loop()
+                out = await loop.run_in_executor(None, lambda: func(**parsed.arguments))
+        except TypeError as e:
+            raise ValueError(f"Tool argument mismatch: {e}") from e
+        except Exception as e:
+            logger.exception("mcp.tool.error", tool=parsed.name, error=str(e))
+            message = str(e) if is_debug_mode() else _INTERNAL_TOOL_ERROR_MESSAGE
+            return CallToolResult(
+                content=[TextContent(text=message).model_dump(by_alias=True)],
+                isError=True,
+            ).model_dump(by_alias=True, exclude_none=True)
+
+        if isinstance(out, str):
+            text = out
+        elif isinstance(out, dict):
+            text = json.dumps(out)
+        else:
+            text = str(out)
+        return CallToolResult(
+            content=[TextContent(text=text).model_dump(by_alias=True)],
+            isError=False,
+        ).model_dump(by_alias=True, exclude_none=True)
+
+    async def _dispatch_request(self, req: JSONRPCRequest) -> str | None:
+        """Dispatch a JSON-RPC request; return response line or None for notification."""
+        method = req.method
+        params = req.params or {}
+        rid = req.id
+
+        if method == "initialize":
+            result = self._handle_initialize(params)
+            return json.dumps(JSONRPCResponse(id=rid, result=result).model_dump(by_alias=True))
+
+        if method == "tools/list":
+            result = self._handle_tools_list(params)
+            return json.dumps(JSONRPCResponse(id=rid, result=result).model_dump(by_alias=True))
+
+        if method == "tools/call":
+            try:
+                result = await self._handle_tools_call(params)
+            except ValueError as e:
+                return json.dumps(
+                    JSONRPCErrorResponse(
+                        id=rid,
+                        error=JSONRPCError(code=INVALID_PARAMS, message=str(e)),
+                    ).model_dump(by_alias=True)
+                )
+            return json.dumps(JSONRPCResponse(id=rid, result=result).model_dump(by_alias=True))
+
+        if method == "ping":
+            return json.dumps(JSONRPCResponse(id=rid, result={}).model_dump(by_alias=True))
+
+        return json.dumps(
+            JSONRPCErrorResponse(
+                id=rid,
+                error=JSONRPCError(code=METHOD_NOT_FOUND, message=f"Method not found: {method}"),
+            ).model_dump(by_alias=True)
+        )
+
+    def _dispatch_notification(self, notif: JSONRPCNotification) -> None:
+        """Handle notification (no response)."""
+        if notif.method == "notifications/initialized":
+            logger.debug("mcp.initialized", message="Client sent initialized")
+        elif notif.method == "notifications/cancelled":
+            logger.debug("mcp.cancelled", params=notif.params)
+        else:
+            logger.debug("mcp.notification", method=notif.method, params=notif.params)
+
+    async def serve_stdio(
+        self,
+        stdin: io.TextIOBase | None = None,
+        stdout: io.TextIOBase | None = None,
+    ) -> None:
+        """Run the server over stdio (stdin/stdout). Blocks until stdin closes.
+
+        Requests are processed sequentially: one request is handled at a time.
+        Long-running tool calls will block other requests (e.g. ping, cancel)
+        until they complete.
+
+        Args:
+            stdin: Optional input stream (default: sys.stdin).
+            stdout: Optional output stream (default: sys.stdout).
+        """
+        _stdin = stdin if stdin is not None else sys.stdin
+        _stdout = stdout if stdout is not None else sys.stdout
+        loop = asyncio.get_running_loop()
+        queue: asyncio.Queue[dict[str, Any] | None] = asyncio.Queue(maxsize=128)
+
+        def read_stdin() -> dict[str, Any] | None:
+            try:
+                line = _stdin.readline()
+            except (EOFError, OSError) as e:
+                logger.debug("mcp.transport.closed", reason=str(e))
+                return None
+            if not line:
+                return None
+            line = line.rstrip("\n\r")
+            if not line:
+                return None
+            try:
+                data = json.loads(line)
+                if not isinstance(data, dict):
+                    return {
+                        "jsonrpc": "2.0",
+                        "id": None,
+                        "error": {"code": PARSE_ERROR, "message": "Parse error"},
+                    }
+                return cast("dict[str, Any]", data)
+            except json.JSONDecodeError:
+                return {
+                    "jsonrpc": "2.0",
+                    "id": None,
+                    "error": {"code": PARSE_ERROR, "message": "Parse error"},
+                }
+
+        async def producer() -> None:
+            while True:
+                raw = await loop.run_in_executor(None, read_stdin)
+                await queue.put(raw)
+                if raw is None:
+                    break
+
+        async def consumer() -> None:
+            while True:
+                raw = await queue.get()
+                if raw is None:
+                    break
+                if (
+                    isinstance(raw, dict)
+                    and "method" not in raw
+                    and raw.get("error", {}).get("code") == PARSE_ERROR
+                ):
+                    _stdout.write(json.dumps(raw) + "\n")
+                    _stdout.flush()
+                    continue
+                if "id" in raw and raw.get("method"):
+                    try:
+                        req = JSONRPCRequest(**raw)
+                        response_line = await self._dispatch_request(req)
+                        if response_line:
+                            _stdout.write(response_line + "\n")
+                            _stdout.flush()
+                    except Exception as e:
+                        logger.exception("mcp.request_error", error=str(e))
+                        rid = raw.get("id")
+                        err = JSONRPCErrorResponse(
+                            id=rid,
+                            error=JSONRPCError(code=INTERNAL_ERROR, message=str(e)),
+                        )
+                        _stdout.write(json.dumps(err.model_dump(by_alias=True)) + "\n")
+                        _stdout.flush()
+                else:
+                    try:
+                        notif = JSONRPCNotification(**raw)
+                        self._dispatch_notification(notif)
+                    except Exception as e:
+                        logger.debug("mcp.notification_error", error=str(e))
+
+        await asyncio.gather(producer(), consumer())
+
+    run_stdio = serve_stdio

asap/mcp/server_runner.py

@@ -0,0 +1,40 @@
+"""Entry point to run the MCP server over stdio.
+
+Used by the demo and by clients that launch the server as a subprocess.
+
+Example:
+    python -m asap.mcp.server_runner
+
+Then send JSON-RPC messages (one per line) to stdin; read responses from stdout.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import sys
+
+
+def main() -> None:
+    """Run MCP server with echo tool on stdio."""
+    from asap.mcp.server import MCPServer
+
+    server = MCPServer(
+        name="asap-mcp-demo",
+        version="1.0.0",
+        description="ASAP MCP demo server with echo tool",
+    )
+    server.register_tool(
+        "echo",
+        lambda message: message,
+        {"type": "object", "properties": {"message": {"type": "string"}}, "required": ["message"]},
+        description="Echo back the given message",
+        title="Echo",
+    )
+    with contextlib.suppress(BrokenPipeError, KeyboardInterrupt):
+        asyncio.run(server.run_stdio())
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

asap/models/__init__.py

@@ -12,6 +12,8 @@ from asap.models.constants import (
     AGENT_URN_PATTERN,
     ASAP_PROTOCOL_VERSION,
     DEFAULT_TIMEOUT_SECONDS,
+    MAX_ENVELOPE_AGE_SECONDS,
+    MAX_FUTURE_TOLERANCE_SECONDS,
     MAX_TASK_DEPTH,
 )
 
@@ -88,6 +90,8 @@ __all__ = [
     "AGENT_URN_PATTERN",
     "ASAP_PROTOCOL_VERSION",
     "DEFAULT_TIMEOUT_SECONDS",
+    "MAX_ENVELOPE_AGE_SECONDS",
+    "MAX_FUTURE_TOLERANCE_SECONDS",
     "MAX_TASK_DEPTH",
     # Enums
     "MessageRole",

asap/models/base.py

@@ -42,11 +42,8 @@ class ASAPBaseModel(BaseModel):
         # Allow populating fields by both name and alias
         populate_by_name=True,
         # JSON Schema configuration
-        # Use enum values (not names) in schema
         use_enum_values=False,
-        # Validate default values
         validate_default=True,
-        # Validate assignments (only relevant if frozen=False)
         validate_assignment=True,
         # JSON Schema extras for better documentation
         json_schema_extra={

asap/models/constants.py

@@ -11,5 +11,80 @@ DEFAULT_TIMEOUT_SECONDS = 600
 MAX_TASK_DEPTH = 10  # Maximum nesting level for subtasks
 MAX_REQUEST_SIZE = 10 * 1024 * 1024  # 10MB maximum request size
 
-# URN patterns
+# Timestamp validation constants for replay attack prevention
+MAX_ENVELOPE_AGE_SECONDS = 300  # 5 minutes
+"""Maximum age of an envelope timestamp before it is considered stale.
+
+This prevents replay attacks by rejecting envelopes that are too old.
+The 5-minute window balances security (preventing old message replays)
+with practical network latency and clock skew tolerance.
+"""
+
+MAX_FUTURE_TOLERANCE_SECONDS = 30  # 30 seconds
+"""Maximum future timestamp tolerance to account for clock skew.
+
+Envelopes with timestamps more than 30 seconds in the future are rejected
+to prevent attacks using artificially future-dated messages. This tolerance
+accounts for reasonable clock synchronization differences between systems.
+"""
+
+NONCE_TTL_SECONDS = MAX_ENVELOPE_AGE_SECONDS * 2  # 10 minutes by default
+"""Time-to-live for nonce values in seconds.
+
+Nonces are stored with a TTL of 2x the maximum envelope age to ensure they
+expire after the envelope would have been rejected anyway. This provides a
+safety margin for edge cases where an envelope might be processed near the
+age limit, while preventing the nonce store from growing unbounded.
+
+The 2x multiplier ensures that:
+- Nonces remain valid for the full envelope validation window
+- Nonces expire shortly after envelopes would be rejected, preventing unbounded growth
+- There's a buffer for clock skew and processing delays
+"""
+
+# URN patterns and limits
 AGENT_URN_PATTERN = r"^urn:asap:agent:[a-z0-9-]+(?::[a-z0-9-]+)?$"
+MAX_URN_LENGTH = 256
+"""Maximum length for agent URNs to prevent abuse and ensure consistent storage."""
+
+# Authentication schemes
+SUPPORTED_AUTH_SCHEMES = frozenset({"bearer", "basic"})
+"""Supported authentication schemes for agent access.
+
+Currently supports:
+- bearer: Bearer token authentication (RFC 6750)
+- basic: HTTP Basic authentication (RFC 7617)
+
+Future support planned:
+- oauth2: OAuth 2.0 authentication flow
+- hmac: HMAC-based authentication
+"""
+
+# Retry and backoff constants
+DEFAULT_BASE_DELAY = 1.0
+"""Default base delay in seconds for exponential backoff.
+
+This is the initial delay before the first retry attempt. Subsequent retries
+will use exponential backoff: base_delay * (2 ** attempt) + jitter.
+"""
+
+DEFAULT_MAX_DELAY = 60.0
+"""Maximum delay in seconds for exponential backoff.
+
+This caps the maximum delay between retry attempts, preventing excessively
+long waits while still providing exponential backoff for transient failures.
+"""
+
+DEFAULT_CIRCUIT_BREAKER_THRESHOLD = 5
+"""Default threshold for circuit breaker pattern.
+
+Number of consecutive failures required before opening the circuit breaker
+and preventing further requests to a failing endpoint.
+"""
+
+DEFAULT_CIRCUIT_BREAKER_TIMEOUT = 60.0
+"""Default timeout in seconds before circuit breaker transitions from OPEN to HALF_OPEN.
+
+After this timeout, the circuit breaker will allow a test request to determine
+if the service has recovered before closing the circuit.
+"""

asap/models/entities.py

@@ -14,15 +14,20 @@ This module defines the fundamental entities used in agent-to-agent communicatio
 - AuthScheme: Authentication configuration for agent access
 """
 
-import re
 from datetime import datetime
 from typing import Any
 
 from packaging.version import InvalidVersion, Version
-from pydantic import Field, field_validator
+from pydantic import Field, field_validator, model_validator
 
+from asap.errors import UnsupportedAuthSchemeError
 from asap.models.base import ASAPBaseModel
-from asap.models.constants import AGENT_URN_PATTERN, ASAP_PROTOCOL_VERSION
+from asap.models.constants import (
+    ASAP_PROTOCOL_VERSION,
+    MAX_TASK_DEPTH,
+    SUPPORTED_AUTH_SCHEMES,
+)
+from asap.models.validators import validate_agent_urn
 from asap.models.enums import MessageRole, TaskStatus
 from asap.models.types import (
     AgentURN,
@@ -36,6 +41,27 @@ from asap.models.types import (
 )
 
 
+def _validate_auth_scheme(auth: "AuthScheme") -> None:
+    """Validate that all authentication schemes are supported.
+
+    Checks each scheme in auth.schemes against SUPPORTED_AUTH_SCHEMES
+    and raises UnsupportedAuthSchemeError if any scheme is invalid.
+
+    Args:
+        auth: AuthScheme instance to validate
+
+    Raises:
+        UnsupportedAuthSchemeError: If any scheme is not supported
+    """
+    for scheme in auth.schemes:
+        scheme_lower = scheme.lower()
+        if scheme_lower not in SUPPORTED_AUTH_SCHEMES:
+            raise UnsupportedAuthSchemeError(
+                scheme=scheme,
+                supported_schemes=SUPPORTED_AUTH_SCHEMES,
+            )
+
+
 class Skill(ASAPBaseModel):
     """A specific capability that an agent can perform.
 
@@ -169,6 +195,12 @@ class Agent(ASAPBaseModel):
     manifest_uri: str = Field(..., description="URL to agent's manifest")
     capabilities: list[str] = Field(..., min_length=1, description="Agent capability strings")
 
+    @field_validator("id")
+    @classmethod
+    def validate_urn_format(cls, v: str) -> str:
+        """Validate agent ID URN format and length."""
+        return validate_agent_urn(v)
+
 
 class Manifest(ASAPBaseModel):
     """Self-describing metadata about an agent's capabilities.
@@ -216,10 +248,8 @@ class Manifest(ASAPBaseModel):
     @field_validator("id")
     @classmethod
     def validate_urn_format(cls, v: str) -> str:
-        """Validate that agent ID follows URN format."""
-        if not re.match(AGENT_URN_PATTERN, v):
-            raise ValueError(f"Agent ID must follow URN format 'urn:asap:agent:{{name}}', got: {v}")
-        return v
+        """Validate that agent ID follows URN format and length limits."""
+        return validate_agent_urn(v)
 
     @field_validator("version")
     @classmethod
@@ -231,6 +261,20 @@ class Manifest(ASAPBaseModel):
             raise ValueError(f"Invalid semantic version '{v}': {e}") from e
         return v
 
+    @model_validator(mode="after")
+    def validate_auth_schemes(self) -> "Manifest":
+        """Validate that all authentication schemes are supported.
+
+        Raises:
+            UnsupportedAuthSchemeError: If any scheme in auth.schemes is not supported
+
+        Returns:
+            Self (for method chaining)
+        """
+        if self.auth is not None:
+            _validate_auth_scheme(self.auth)
+        return self
+
 
 class Conversation(ASAPBaseModel):
     """A context for related interactions between agents.
@@ -275,6 +319,7 @@ class Task(ASAPBaseModel):
         conversation_id: ID of the conversation this task belongs to
         parent_task_id: Optional ID of parent task (for subtasks)
         status: Current task status (submitted, working, completed, etc.)
+        depth: Nesting depth (0 = root); must be ≤ MAX_TASK_DEPTH to prevent infinite recursion
         progress: Optional progress information (percent, message, ETA)
         created_at: Timestamp when the task was created (UTC)
         updated_at: Timestamp of last status update (UTC)
@@ -295,6 +340,12 @@ class Task(ASAPBaseModel):
     conversation_id: ConversationID = Field(..., description="Parent conversation ID")
     parent_task_id: TaskID | None = Field(default=None, description="Parent task ID for subtasks")
     status: TaskStatus = Field(..., description="Task status (submitted, working, etc.)")
+    depth: int = Field(
+        0,
+        ge=0,
+        le=MAX_TASK_DEPTH,
+        description="Nesting depth for subtasks (0 = root); prevents infinite recursion",
+    )
     progress: dict[str, Any] | None = Field(
         default=None, description="Progress info (percent, message, ETA)"
     )

asap/models/envelope.py

@@ -12,6 +12,7 @@ from pydantic import Field, field_validator, model_validator
 from asap.models.base import ASAPBaseModel
 from asap.models.ids import generate_id
 from asap.models.types import AgentURN
+from asap.models.validators import validate_agent_urn
 
 
 class Envelope(ASAPBaseModel):
@@ -65,7 +66,13 @@ class Envelope(ASAPBaseModel):
         default=None, description="Optional trace ID for distributed tracing"
     )
     extensions: dict[str, Any] | None = Field(
-        default=None, description="Optional custom extensions"
+        default=None,
+        description=(
+            "Optional custom extensions. "
+            "Can include a 'nonce' field (string) for replay attack prevention. "
+            "If provided, the nonce must be unique within the TTL window (typically 10 minutes). "
+            "Duplicate nonces will be rejected by the validation layer."
+        ),
     )
 
     @field_validator("id", mode="before")
@@ -84,6 +91,12 @@ class Envelope(ASAPBaseModel):
             return datetime.now(timezone.utc)
         return v
 
+    @field_validator("sender", "recipient")
+    @classmethod
+    def validate_sender_recipient_urn(cls, v: str) -> str:
+        """Validate sender/recipient URN format and length."""
+        return validate_agent_urn(v)
+
     @model_validator(mode="after")
     def validate_response_correlation(self) -> "Envelope":
         """Validate that response payloads have correlation_id for request tracking."""

asap/models/ids.py

@@ -2,9 +2,12 @@
 
 ULIDs (Universally Unique Lexicographically Sortable Identifiers) provide:
 - 128-bit compatibility with UUID
-- Lexicographic sorting by timestamp
+- Lexicographic sorting by creation time when timestamps differ (millisecond precision)
 - Canonically encoded as 26-character string (Crockford's Base32)
-- Monotonically increasing within the same millisecond
+
+Note: Order is guaranteed only across different milliseconds. Two ULIDs generated
+within the same millisecond share the same timestamp prefix; their lexicographic
+order is then determined by the random component and may not match generation order.
 """
 
 from datetime import datetime
@@ -18,7 +21,8 @@ def generate_id() -> str:
     Returns:
         A 26-character ULID string that is:
         - Globally unique
-        - Lexicographically sortable by creation time
+        - Lexicographically sortable by creation time when generated in different
+          milliseconds (within the same millisecond, order is not guaranteed)
         - URL-safe (uses Crockford's Base32 alphabet)
 
     Example:
@@ -26,7 +30,7 @@ def generate_id() -> str:
         >>> len(id1)
         26
         >>> id2 = generate_id()
-        >>> id1 < id2  # Sortable by time
+        >>> id1 < id2  # True when timestamps differ (e.g. different ms)
         True
     """
     return str(ULID())