asap-protocol 0.5.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/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

@@ -42,8 +42,10 @@ The 2x multiplier ensures that:
 - There's a buffer for clock skew and processing delays
 """
 
-# URN patterns
+# 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"})

asap/models/entities.py

@@ -14,7 +14,6 @@ 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
 
@@ -23,7 +22,12 @@ 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, SUPPORTED_AUTH_SCHEMES
+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,
@@ -191,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.
@@ -238,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
@@ -311,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)
@@ -331,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):
@@ -90,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())

asap/models/parts.py

@@ -14,6 +14,10 @@ from pydantic import Discriminator, Field, TypeAdapter, field_validator
 from asap.models.base import ASAPBaseModel
 from asap.models.types import MIMEType
 
+# Security: reject URIs that could lead to path traversal or local file access
+PATH_TRAVERSAL_PATTERN = re.compile(r"\.\.")
+FILE_URI_PREFIX = "file://"
+
 
 class TextPart(ASAPBaseModel):
     """Plain text content part.
@@ -70,7 +74,7 @@ class FilePart(ASAPBaseModel):
 
     Attributes:
         type: Discriminator field, always "file"
-        uri: File URI (can be asap://, file://, https://, or data: URI)
+        uri: File URI (asap://, https://, or data:; file:// and path traversal rejected)
         mime_type: MIME type of the file (e.g., "application/pdf")
         inline_data: Optional base64-encoded inline file data
 
@@ -91,12 +95,38 @@ class FilePart(ASAPBaseModel):
     """
 
     type: Literal["file"] = Field(..., description="Part type discriminator")
-    uri: str = Field(..., description="File URI (asap://, file://, https://, data:)")
+    uri: str = Field(
+        ...,
+        description="File URI (asap://, https://, data:; file:// and .. rejected)",
+    )
     mime_type: MIMEType = Field(..., description="MIME type (e.g., application/pdf)")
     inline_data: str | None = Field(
         default=None, description="Optional base64-encoded inline file data"
     )
 
+    @field_validator("uri")
+    @classmethod
+    def validate_uri(cls, v: str) -> str:
+        """Validate URI: reject path traversal and suspicious file:// URIs.
+
+        Rejects URIs containing '..' (path traversal) and file:// URIs
+        to prevent reading arbitrary server paths from user-supplied input.
+
+        Args:
+            v: URI string to validate
+
+        Returns:
+            The same URI if valid
+
+        Raises:
+            ValueError: If URI contains path traversal or is a file:// URI
+        """
+        if PATH_TRAVERSAL_PATTERN.search(v):
+            raise ValueError(f"URI must not contain path traversal (..): {v!r}")
+        if v.strip().lower().startswith(FILE_URI_PREFIX):
+            raise ValueError("file:// URIs are not allowed for security (path traversal risk)")
+        return v
+
     @field_validator("mime_type")
     @classmethod
     def validate_mime_type(cls, v: str) -> str:
@@ -201,7 +231,7 @@ Example:
     >>> # Deserializes to FilePart
     >>> file_part = Part.validate_python({
     ...     "type": "file",
-    ...     "uri": "file://test.pdf",
+    ...     "uri": "https://example.com/doc.pdf",
     ...     "mime_type": "application/pdf"
     ... })
 """

asap/models/validators.py

@@ -0,0 +1,16 @@
+"""Shared validators for ASAP protocol models."""
+
+import re
+
+from asap.models.constants import AGENT_URN_PATTERN, MAX_URN_LENGTH
+
+_AGENT_URN_RE = re.compile(AGENT_URN_PATTERN)
+
+
+def validate_agent_urn(v: str) -> str:
+    """Validate agent URN format and length (pattern + max length)."""
+    if len(v) > MAX_URN_LENGTH:
+        raise ValueError(f"Agent URN must be at most {MAX_URN_LENGTH} characters, got {len(v)}")
+    if not _AGENT_URN_RE.match(v):
+        raise ValueError(f"Agent ID must follow URN format 'urn:asap:agent:{{name}}', got: {v}")
+    return v

asap/observability/__init__.py

@@ -25,6 +25,9 @@ from asap.observability.logging import (
     clear_context,
     configure_logging,
     get_logger,
+    is_debug_log_mode,
+    is_debug_mode,
+    sanitize_for_logging,
 )
 from asap.observability.metrics import (
     MetricsCollector,
@@ -38,6 +41,9 @@ __all__ = [
     "configure_logging",
     "get_logger",
     "get_metrics",
+    "is_debug_log_mode",
+    "is_debug_mode",
     "reset_metrics",
     "MetricsCollector",
+    "sanitize_for_logging",
 ]

asap/observability/dashboards/README.md

@@ -0,0 +1,24 @@
+# ASAP Grafana Dashboards
+
+Pre-built dashboards for ASAP Protocol observability. Use with Prometheus scraping the `/asap/metrics` endpoint.
+
+## Dashboards
+
+- **asap-red.json** – RED metrics (Request rate, Error rate, Duration/latency) for ASAP requests.
+- **asap-detailed.json** – Topology, state machine transitions, and circuit breaker status.
+
+## Setup
+
+1. Configure a Prometheus datasource in Grafana (scrape ASAP server at `http://<asap-host>:<port>/asap/metrics`).
+2. **Provisioning**: Copy the JSON files to Grafana's provisioning path, e.g.:
+   - Copy to `<grafana provisioning dir>/dashboards/asap/` and set the provisioning config to load from that directory.
+   - Or import manually: Grafana UI → Dashboards → Import → Upload JSON file.
+3. Select the Prometheus datasource when prompted.
+
+## Metrics used
+
+- `asap_requests_total` – Total requests (labels: `payload_type`, `status`).
+- `asap_requests_error_total` – Failed requests.
+- `asap_request_duration_seconds` – Request latency histogram.
+- `asap_state_transitions_total` – State machine transitions (labels: `from_status`, `to_status`).
+- `asap_circuit_breaker_open` – Circuit open state (if exposed by client metrics).