alysis-code 0.13.0__py3-none-any.whl

alysis_code/mcp/prompts.py

@@ -0,0 +1,329 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..runtime_kind import RuntimeKind, normalize_runtime_kind
+from .errors import McpProtocolError
+from .models import PromptsMode
+from .untrusted_content import build_untrusted_mcp_text_block
+
+_PROMPT_ENABLED_RUNTIME_KINDS = frozenset(
+    {
+        RuntimeKind.INTERACTIVE_CHAT,
+        RuntimeKind.ONE_SHOT,
+        RuntimeKind.FORGE_EXEC,
+    }
+)
+_INLINE_PROMPT_TEXT_CHAR_LIMIT = 12_000
+
+
+class McpPromptNormalizationError(ValueError, McpProtocolError):
+    def __init__(
+        self,
+        message: str = "",
+        *,
+        server_id: str | None = None,
+        method: str | None = None,
+        cause: BaseException | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.server_id = server_id
+        self.method = method
+        self.cause = cause
+
+
+@dataclass(frozen=True)
+class McpPromptArgument:
+    name: str
+    description: str | None
+    required: bool
+    raw_payload: dict[str, Any] = field(repr=False)
+
+    def as_payload(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "name": self.name,
+            "required": self.required,
+        }
+        if self.description:
+            payload["description"] = self.description
+        return payload
+
+
+@dataclass(frozen=True)
+class McpListedPrompt:
+    name: str
+    title: str | None
+    description: str | None
+    arguments: tuple[McpPromptArgument, ...]
+    raw_payload: dict[str, Any] = field(repr=False)
+
+    def as_payload(self, *, server_id: str) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "server_id": server_id,
+            "name": self.name,
+            "arguments": [argument.as_payload() for argument in self.arguments],
+        }
+        if self.title:
+            payload["title"] = self.title
+        if self.description:
+            payload["description"] = self.description
+        return payload
+
+
+@dataclass(frozen=True)
+class McpPromptMessage:
+    role: str
+    content: tuple[dict[str, Any], ...]
+    content_summary: str
+    text: str | None = None
+    raw_payload: dict[str, Any] = field(repr=False, default_factory=dict)
+
+    def as_payload(self, *, server_id: str, prompt_name: str) -> dict[str, Any]:
+        content_items: list[dict[str, Any]] = []
+        for item in self.content:
+            payload_item = dict(item)
+            item_text = payload_item.get("text")
+            mime_type = payload_item.get("mime_type")
+            if isinstance(item_text, str):
+                payload_item["text"] = build_untrusted_mcp_text_block(
+                    source_type="prompt_get",
+                    server_id=server_id,
+                    source_name=prompt_name,
+                    text=item_text,
+                    mime_type=mime_type if isinstance(mime_type, str) else None,
+                )
+            content_items.append(payload_item)
+        payload: dict[str, Any] = {
+            "role": self.role,
+            "content_summary": self.content_summary,
+            "content": content_items,
+        }
+        if self.text is not None:
+            payload["text"] = build_untrusted_mcp_text_block(
+                source_type="prompt_get",
+                server_id=server_id,
+                source_name=prompt_name,
+                text=self.text,
+            )
+        return payload
+
+
+@dataclass(frozen=True)
+class McpGetPromptResult:
+    description: str | None
+    messages: tuple[McpPromptMessage, ...]
+    content_summary: str
+    text: str
+    raw_payload: dict[str, Any] = field(repr=False)
+
+
+def prompts_runtime_supported(runtime_kind: RuntimeKind | str) -> bool:
+    return normalize_runtime_kind(runtime_kind) in _PROMPT_ENABLED_RUNTIME_KINDS
+
+
+def prompts_mode_enabled(
+    *,
+    prompts_mode: PromptsMode,
+    runtime_kind: RuntimeKind | str,
+) -> bool:
+    return prompts_mode == "listed_get_only" and prompts_runtime_supported(runtime_kind)
+
+
+def _require_object(value: Any, *, context: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise McpPromptNormalizationError(f"{context} must be an object.")
+    return value
+
+
+def _require_string(value: Any, *, context: str) -> str:
+    if not isinstance(value, str):
+        raise McpPromptNormalizationError(f"{context} must be a string.")
+    cleaned = value.strip()
+    if not cleaned:
+        raise McpPromptNormalizationError(f"{context} cannot be empty.")
+    return cleaned
+
+
+def _optional_string(value: Any, *, context: str) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise McpPromptNormalizationError(f"{context} must be a string when present.")
+    cleaned = value.strip()
+    return cleaned or None
+
+
+def _normalize_prompt_arguments(value: Any, *, context: str) -> tuple[McpPromptArgument, ...]:
+    if value is None:
+        return ()
+    if not isinstance(value, list):
+        raise McpPromptNormalizationError(f"{context} must be an array when present.")
+    normalized: list[McpPromptArgument] = []
+    seen_names: set[str] = set()
+    for index, raw_item in enumerate(value):
+        payload = _require_object(raw_item, context=f"{context}[{index}]")
+        name = _require_string(payload.get("name"), context=f"{context}[{index}].name")
+        name_key = name.casefold()
+        if name_key in seen_names:
+            raise McpPromptNormalizationError(
+                f"{context} contains repeated argument name {name!r}."
+            )
+        seen_names.add(name_key)
+        required = payload.get("required", False)
+        if not isinstance(required, bool):
+            raise McpPromptNormalizationError(
+                f"{context}[{index}].required must be a boolean when present."
+            )
+        normalized.append(
+            McpPromptArgument(
+                name=name,
+                description=_optional_string(
+                    payload.get("description"),
+                    context=f"{context}[{index}].description",
+                ),
+                required=required,
+                raw_payload=dict(payload),
+            )
+        )
+    return tuple(normalized)
+
+
+def _normalize_prompt_content_items(
+    value: Any, *, context: str
+) -> tuple[tuple[dict[str, Any], ...], str]:
+    raw_items = value if isinstance(value, list) else [value]
+    normalized: list[dict[str, Any]] = []
+    summaries: list[str] = []
+    for index, raw_item in enumerate(raw_items):
+        payload = _require_object(raw_item, context=f"{context}[{index}]")
+        item_type = _require_string(payload.get("type"), context=f"{context}[{index}].type")
+        normalized_item: dict[str, Any] = {"type": item_type}
+        summary = f"{item_type} item omitted"
+        mime_type = _optional_string(
+            payload.get("mimeType"),
+            context=f"{context}[{index}].mimeType",
+        )
+        if mime_type:
+            normalized_item["mime_type"] = mime_type
+            summary = f"{mime_type} {summary}"
+        if item_type == "text":
+            text = _require_string(payload.get("text"), context=f"{context}[{index}].text")
+            inline_text = text
+            truncated = False
+            if len(inline_text) > _INLINE_PROMPT_TEXT_CHAR_LIMIT:
+                inline_text = inline_text[:_INLINE_PROMPT_TEXT_CHAR_LIMIT]
+                truncated = True
+            summary = f"text({len(text)} chars)"
+            if mime_type:
+                summary = f"{mime_type} {summary}"
+            if truncated:
+                summary += f", truncated to {_INLINE_PROMPT_TEXT_CHAR_LIMIT} chars"
+            normalized_item["text"] = inline_text
+        else:
+            uri = _optional_string(payload.get("uri"), context=f"{context}[{index}].uri")
+            if uri:
+                normalized_item["uri"] = uri
+            resource = payload.get("resource")
+            if isinstance(resource, dict):
+                resource_uri = _optional_string(
+                    resource.get("uri"),
+                    context=f"{context}[{index}].resource.uri",
+                )
+                if resource_uri:
+                    normalized_item["resource_uri"] = resource_uri
+        normalized_item["summary"] = summary
+        normalized.append(normalized_item)
+        summaries.append(summary)
+    return tuple(normalized), ", ".join(summaries) or "no content"
+
+
+def normalize_list_prompts_result(
+    result: dict[str, Any],
+) -> tuple[tuple[McpListedPrompt, ...], str | None]:
+    prompts = result.get("prompts")
+    if not isinstance(prompts, list):
+        raise McpPromptNormalizationError("prompts/list result.prompts must be an array.")
+    normalized: list[McpListedPrompt] = []
+    for index, raw_item in enumerate(prompts):
+        payload = _require_object(raw_item, context=f"prompts/list prompt[{index}]")
+        normalized.append(
+            McpListedPrompt(
+                name=_require_string(
+                    payload.get("name"), context=f"prompts/list prompt[{index}].name"
+                ),
+                title=_optional_string(
+                    payload.get("title"),
+                    context=f"prompts/list prompt[{index}].title",
+                ),
+                description=_optional_string(
+                    payload.get("description"),
+                    context=f"prompts/list prompt[{index}].description",
+                ),
+                arguments=_normalize_prompt_arguments(
+                    payload.get("arguments"),
+                    context=f"prompts/list prompt[{index}].arguments",
+                ),
+                raw_payload=dict(payload),
+            )
+        )
+    next_cursor = result.get("nextCursor")
+    if next_cursor is None:
+        return tuple(normalized), None
+    return tuple(normalized), _require_string(next_cursor, context="prompts/list nextCursor")
+
+
+def normalize_get_prompt_result(
+    result: dict[str, Any],
+    *,
+    expected_name: str,
+) -> McpGetPromptResult:
+    if "name" in result:
+        result_name = _require_string(result.get("name"), context="prompts/get result.name")
+        if result_name != expected_name:
+            raise McpPromptNormalizationError(
+                "prompts/get result.name must match the requested prompt name."
+            )
+    messages = result.get("messages")
+    if not isinstance(messages, list):
+        raise McpPromptNormalizationError("prompts/get result.messages must be an array.")
+    normalized_messages: list[McpPromptMessage] = []
+    text_parts: list[str] = []
+    summaries: list[str] = []
+    for index, raw_item in enumerate(messages):
+        payload = _require_object(raw_item, context=f"prompts/get messages[{index}]")
+        role = _require_string(payload.get("role"), context=f"prompts/get messages[{index}].role")
+        content_items, content_summary = _normalize_prompt_content_items(
+            payload.get("content"),
+            context=f"prompts/get messages[{index}].content",
+        )
+        text_parts.extend(
+            item["text"]
+            for item in content_items
+            if isinstance(item.get("text"), str) and str(item.get("text")).strip()
+        )
+        summaries.append(f"{role}: {content_summary}")
+        normalized_messages.append(
+            McpPromptMessage(
+                role=role,
+                content=content_items,
+                content_summary=content_summary,
+                text="\n\n".join(
+                    item["text"]
+                    for item in content_items
+                    if isinstance(item.get("text"), str) and str(item.get("text")).strip()
+                )
+                or None,
+                raw_payload=dict(payload),
+            )
+        )
+    return McpGetPromptResult(
+        description=_optional_string(
+            result.get("description"),
+            context="prompts/get result.description",
+        ),
+        messages=tuple(normalized_messages),
+        content_summary="; ".join(summaries) or "no messages",
+        text="\n\n".join(text_parts),
+        raw_payload=dict(result),
+    )

alysis_code/mcp/resources.py

@@ -0,0 +1,295 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..runtime_kind import RuntimeKind, normalize_runtime_kind
+from .errors import McpProtocolError
+from .models import ResourcesMode
+from .untrusted_content import _looks_like_binary_blob, build_untrusted_mcp_text_block
+
+_RESOURCE_ENABLED_RUNTIME_KINDS = frozenset(
+    {
+        RuntimeKind.INTERACTIVE_CHAT,
+        RuntimeKind.ONE_SHOT,
+        RuntimeKind.FORGE_EXEC,
+    }
+)
+_INLINE_RESOURCE_TEXT_CHAR_LIMIT = 12_000
+
+
+class McpResourceNormalizationError(ValueError, McpProtocolError):
+    def __init__(
+        self,
+        message: str = "",
+        *,
+        server_id: str | None = None,
+        method: str | None = None,
+        cause: BaseException | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.server_id = server_id
+        self.method = method
+        self.cause = cause
+
+
+@dataclass(frozen=True)
+class McpListedResource:
+    uri: str
+    name: str
+    description: str | None
+    mime_type: str | None
+    size: int | None
+    raw_payload: dict[str, Any] = field(repr=False)
+
+    def as_tool_payload(self, *, server_id: str) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "server_id": server_id,
+            "uri": self.uri,
+            "name": self.name,
+        }
+        if self.description:
+            payload["description"] = self.description
+        if self.mime_type:
+            payload["mime_type"] = self.mime_type
+        if self.size is not None:
+            payload["size"] = self.size
+        return payload
+
+
+@dataclass(frozen=True)
+class McpReadResourceContent:
+    uri: str
+    mime_type: str | None
+    content_summary: str
+    text: str | None = None
+    raw_payload: dict[str, Any] = field(repr=False, default_factory=dict)
+
+    def as_tool_payload(self, *, server_id: str, resource_uri: str) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "uri": self.uri,
+            "content_summary": self.content_summary,
+        }
+        if self.mime_type:
+            payload["mime_type"] = self.mime_type
+        if self.text is not None:
+            payload["text"] = build_untrusted_mcp_text_block(
+                source_type="resource_read",
+                server_id=server_id,
+                source_name=resource_uri,
+                text=self.text,
+                mime_type=self.mime_type,
+            )
+        return payload
+
+
+@dataclass(frozen=True)
+class McpReadResourceResult:
+    contents: tuple[McpReadResourceContent, ...]
+    content_summary: str
+    text: str
+    mime_type: str | None
+    raw_payload: dict[str, Any] = field(repr=False)
+
+
+def resources_runtime_supported(runtime_kind: RuntimeKind | str) -> bool:
+    return normalize_runtime_kind(runtime_kind) in _RESOURCE_ENABLED_RUNTIME_KINDS
+
+
+def resources_mode_enabled(
+    *,
+    resources_mode: ResourcesMode,
+    runtime_kind: RuntimeKind | str,
+) -> bool:
+    return resources_mode == "listed_read_only" and resources_runtime_supported(runtime_kind)
+
+
+def _require_object(value: Any, *, context: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise McpResourceNormalizationError(f"{context} must be an object.")
+    return value
+
+
+def _require_string(value: Any, *, context: str) -> str:
+    if not isinstance(value, str):
+        raise McpResourceNormalizationError(f"{context} must be a string.")
+    cleaned = value.strip()
+    if not cleaned:
+        raise McpResourceNormalizationError(f"{context} cannot be empty.")
+    return cleaned
+
+
+def _optional_string(value: Any, *, context: str) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise McpResourceNormalizationError(f"{context} must be a string when present.")
+    cleaned = value.strip()
+    return cleaned or None
+
+
+def _optional_size(value: Any, *, context: str) -> int | None:
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise McpResourceNormalizationError(
+            f"{context} must be a non-negative integer when present."
+        )
+    if value < 0:
+        raise McpResourceNormalizationError(f"{context} must be >= 0 when present.")
+    return int(value)
+
+
+def _mime_is_textual(mime_type: str | None) -> bool:
+    if mime_type is None:
+        return True
+    lowered = mime_type.strip().lower()
+    if not lowered:
+        return True
+    if lowered.startswith("text/"):
+        return True
+    return (
+        lowered == "application/json"
+        or lowered.endswith("+json")
+        or lowered == "application/xml"
+        or lowered.endswith("+xml")
+        or lowered in {"application/yaml", "application/x-yaml", "text/yaml"}
+        or lowered.endswith("+yaml")
+        or lowered in {"application/javascript", "application/x-javascript"}
+    )
+
+
+def _inline_text_payload(
+    *,
+    text: str,
+    mime_type: str | None,
+) -> tuple[str | None, str]:
+    if not _mime_is_textual(mime_type):
+        mime_label = mime_type or "non-text"
+        return None, f"{mime_label} text omitted ({len(text)} chars)"
+    if _looks_like_binary_blob(text):
+        return None, f"binary-like text omitted ({len(text)} chars)"
+    inline_text = text
+    truncated = False
+    if len(inline_text) > _INLINE_RESOURCE_TEXT_CHAR_LIMIT:
+        inline_text = inline_text[:_INLINE_RESOURCE_TEXT_CHAR_LIMIT]
+        truncated = True
+    summary_kind = "json text" if mime_type and "json" in mime_type.lower() else "text"
+    summary = f"{summary_kind}({len(text)} chars)"
+    if mime_type:
+        summary = f"{mime_type} {summary}"
+    if truncated:
+        summary += f", truncated to {_INLINE_RESOURCE_TEXT_CHAR_LIMIT} chars"
+    return inline_text, summary
+
+
+def normalize_list_resources_result(
+    result: dict[str, Any],
+) -> tuple[tuple[McpListedResource, ...], str | None]:
+    resources = result.get("resources")
+    if not isinstance(resources, list):
+        raise McpResourceNormalizationError("resources/list result.resources must be an array.")
+    normalized: list[McpListedResource] = []
+    for index, raw_item in enumerate(resources):
+        payload = _require_object(raw_item, context=f"resources/list resource[{index}]")
+        normalized.append(
+            McpListedResource(
+                uri=_require_string(
+                    payload.get("uri"), context=f"resources/list resource[{index}].uri"
+                ),
+                name=_require_string(
+                    payload.get("name"), context=f"resources/list resource[{index}].name"
+                ),
+                description=_optional_string(
+                    payload.get("description"),
+                    context=f"resources/list resource[{index}].description",
+                ),
+                mime_type=_optional_string(
+                    payload.get("mimeType"),
+                    context=f"resources/list resource[{index}].mimeType",
+                ),
+                size=_optional_size(
+                    payload.get("size"),
+                    context=f"resources/list resource[{index}].size",
+                ),
+                raw_payload=dict(payload),
+            )
+        )
+    next_cursor = result.get("nextCursor")
+    if next_cursor is None:
+        return tuple(normalized), None
+    return tuple(normalized), _require_string(next_cursor, context="resources/list nextCursor")
+
+
+def normalize_read_resource_result(
+    result: dict[str, Any],
+    *,
+    expected_uri: str,
+) -> McpReadResourceResult:
+    contents = result.get("contents")
+    if not isinstance(contents, list):
+        raise McpResourceNormalizationError("resources/read result.contents must be an array.")
+    normalized: list[McpReadResourceContent] = []
+    text_parts: list[str] = []
+    for index, raw_item in enumerate(contents):
+        payload = _require_object(raw_item, context=f"resources/read contents[{index}]")
+        item_uri = _optional_string(
+            payload.get("uri"), context=f"resources/read contents[{index}].uri"
+        )
+        resolved_uri = item_uri or expected_uri
+        if resolved_uri != expected_uri:
+            raise McpResourceNormalizationError(
+                f"resources/read contents[{index}].uri must match the requested resource URI."
+            )
+        mime_type = _optional_string(
+            payload.get("mimeType"),
+            context=f"resources/read contents[{index}].mimeType",
+        )
+        has_text = "text" in payload
+        has_blob = "blob" in payload
+        if has_text and has_blob:
+            raise McpResourceNormalizationError(
+                f"resources/read contents[{index}] cannot include both text and blob."
+            )
+        if not has_text and not has_blob:
+            raise McpResourceNormalizationError(
+                f"resources/read contents[{index}] must include text or blob."
+            )
+        inline_text: str | None = None
+        content_summary: str
+        if has_text:
+            raw_text = payload.get("text")
+            if not isinstance(raw_text, str):
+                raise McpResourceNormalizationError(
+                    f"resources/read contents[{index}].text must be a string."
+                )
+            inline_text, content_summary = _inline_text_payload(text=raw_text, mime_type=mime_type)
+            if inline_text is not None:
+                text_parts.append(inline_text)
+        else:
+            raw_blob = payload.get("blob")
+            if not isinstance(raw_blob, str):
+                raise McpResourceNormalizationError(
+                    f"resources/read contents[{index}].blob must be a string."
+                )
+            blob_summary = f"blob omitted ({len(raw_blob)} chars)"
+            if mime_type:
+                blob_summary = f"{mime_type} {blob_summary}"
+            content_summary = blob_summary
+        normalized.append(
+            McpReadResourceContent(
+                uri=resolved_uri,
+                mime_type=mime_type,
+                content_summary=content_summary,
+                text=inline_text,
+                raw_payload=dict(payload),
+            )
+        )
+    mime_type = next((item.mime_type for item in normalized if item.mime_type), None)
+    return McpReadResourceResult(
+        contents=tuple(normalized),
+        content_summary=", ".join(item.content_summary for item in normalized) or "no content",
+        text="\n\n".join(text_parts),
+        mime_type=mime_type,
+        raw_payload=dict(result),
+    )