nornweave 0.1.2__py3-none-any.whl

nornweave/huginn/client.py

@@ -0,0 +1,296 @@
+"""HTTP client for NornWeave API.
+
+This module provides an async HTTP client for the MCP server to communicate
+with the NornWeave REST API.
+"""
+
+from typing import Any, cast
+
+import httpx
+
+from nornweave.huginn.config import get_mcp_settings
+
+
+class NornWeaveClient:
+    """Async HTTP client for NornWeave REST API."""
+
+    def __init__(
+        self,
+        api_url: str | None = None,
+        api_key: str | None = None,
+    ) -> None:
+        """Initialize the client.
+
+        Args:
+            api_url: Base URL for the NornWeave API. Defaults to NORNWEAVE_API_URL env var.
+            api_key: API key for authentication. Defaults to NORNWEAVE_API_KEY env var.
+        """
+        settings = get_mcp_settings()
+        self.api_url = (api_url or settings.api_url).rstrip("/")
+        self.api_key = api_key or settings.api_key
+        self._client: httpx.AsyncClient | None = None
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        """Get or create the HTTP client."""
+        if self._client is None:
+            headers: dict[str, str] = {}
+            if self.api_key:
+                headers["X-API-Key"] = self.api_key
+            self._client = httpx.AsyncClient(
+                base_url=self.api_url,
+                headers=headers,
+                timeout=30.0,
+            )
+        return self._client
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def __aenter__(self) -> NornWeaveClient:
+        """Enter async context."""
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        """Exit async context."""
+        await self.close()
+
+    # -------------------------------------------------------------------------
+    # Inbox Operations
+    # -------------------------------------------------------------------------
+
+    async def create_inbox(self, name: str, email_username: str) -> dict[str, Any]:
+        """Create a new inbox.
+
+        Args:
+            name: Display name for the inbox.
+            email_username: Local part of the email address.
+
+        Returns:
+            Created inbox with id, email_address, name.
+        """
+        client = await self._get_client()
+        response = await client.post(
+            "/v1/inboxes",
+            json={"name": name, "email_username": email_username},
+        )
+        response.raise_for_status()
+        return cast("dict[str, Any]", response.json())
+
+    async def get_inbox(self, inbox_id: str) -> dict[str, Any]:
+        """Get an inbox by ID.
+
+        Args:
+            inbox_id: The inbox ID.
+
+        Returns:
+            Inbox data.
+        """
+        client = await self._get_client()
+        response = await client.get(f"/v1/inboxes/{inbox_id}")
+        response.raise_for_status()
+        return cast("dict[str, Any]", response.json())
+
+    async def list_inboxes(self, limit: int = 50, offset: int = 0) -> dict[str, Any]:
+        """List all inboxes.
+
+        Args:
+            limit: Maximum number of inboxes to return.
+            offset: Number of inboxes to skip.
+
+        Returns:
+            List response with items and count.
+        """
+        client = await self._get_client()
+        response = await client.get(
+            "/v1/inboxes",
+            params={"limit": limit, "offset": offset},
+        )
+        response.raise_for_status()
+        return cast("dict[str, Any]", response.json())
+
+    # -------------------------------------------------------------------------
+    # Thread Operations
+    # -------------------------------------------------------------------------
+
+    async def get_thread(self, thread_id: str) -> dict[str, Any]:
+        """Get a thread with messages.
+
+        Args:
+            thread_id: The thread ID.
+
+        Returns:
+            Thread data with messages in LLM-ready format.
+        """
+        client = await self._get_client()
+        response = await client.get(f"/v1/threads/{thread_id}")
+        response.raise_for_status()
+        return cast("dict[str, Any]", response.json())
+
+    async def list_threads(
+        self,
+        inbox_id: str,
+        limit: int = 20,
+        offset: int = 0,
+    ) -> dict[str, Any]:
+        """List threads for an inbox.
+
+        Args:
+            inbox_id: The inbox ID.
+            limit: Maximum number of threads to return.
+            offset: Number of threads to skip.
+
+        Returns:
+            List response with thread summaries.
+        """
+        client = await self._get_client()
+        response = await client.get(
+            "/v1/threads",
+            params={"inbox_id": inbox_id, "limit": limit, "offset": offset},
+        )
+        response.raise_for_status()
+        return cast("dict[str, Any]", response.json())
+
+    # -------------------------------------------------------------------------
+    # Message Operations
+    # -------------------------------------------------------------------------
+
+    async def get_message(self, message_id: str) -> dict[str, Any]:
+        """Get a message by ID.
+
+        Args:
+            message_id: The message ID.
+
+        Returns:
+            Message data.
+        """
+        client = await self._get_client()
+        response = await client.get(f"/v1/messages/{message_id}")
+        response.raise_for_status()
+        return cast("dict[str, Any]", response.json())
+
+    async def list_messages(
+        self,
+        inbox_id: str,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> dict[str, Any]:
+        """List messages for an inbox.
+
+        Args:
+            inbox_id: The inbox ID.
+            limit: Maximum number of messages to return.
+            offset: Number of messages to skip.
+
+        Returns:
+            List response with messages.
+        """
+        client = await self._get_client()
+        response = await client.get(
+            "/v1/messages",
+            params={"inbox_id": inbox_id, "limit": limit, "offset": offset},
+        )
+        response.raise_for_status()
+        return cast("dict[str, Any]", response.json())
+
+    async def send_message(
+        self,
+        inbox_id: str,
+        to: list[str],
+        subject: str,
+        body: str,
+        reply_to_thread_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Send an outbound message.
+
+        Args:
+            inbox_id: The inbox ID to send from.
+            to: List of recipient email addresses.
+            subject: Email subject.
+            body: Markdown body content.
+            reply_to_thread_id: Thread ID if this is a reply.
+
+        Returns:
+            Send response with message_id, thread_id, status.
+        """
+        client = await self._get_client()
+        payload: dict[str, Any] = {
+            "inbox_id": inbox_id,
+            "to": to,
+            "subject": subject,
+            "body": body,
+        }
+        if reply_to_thread_id:
+            payload["reply_to_thread_id"] = reply_to_thread_id
+
+        response = await client.post("/v1/messages", json=payload)
+        response.raise_for_status()
+        return cast("dict[str, Any]", response.json())
+
+    # -------------------------------------------------------------------------
+    # Search Operations
+    # -------------------------------------------------------------------------
+
+    async def search_messages(
+        self,
+        query: str,
+        inbox_id: str,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> dict[str, Any]:
+        """Search messages by content.
+
+        Args:
+            query: Search query.
+            inbox_id: Inbox to search in.
+            limit: Maximum number of results.
+            offset: Number of results to skip.
+
+        Returns:
+            Search response with matching messages.
+        """
+        client = await self._get_client()
+        response = await client.post(
+            "/v1/search",
+            json={
+                "query": query,
+                "inbox_id": inbox_id,
+                "limit": limit,
+                "offset": offset,
+            },
+        )
+        response.raise_for_status()
+        return cast("dict[str, Any]", response.json())
+
+    # -------------------------------------------------------------------------
+    # Polling for wait_for_reply
+    # -------------------------------------------------------------------------
+
+    async def get_thread_message_count(self, thread_id: str) -> int:
+        """Get the current message count for a thread.
+
+        Args:
+            thread_id: The thread ID.
+
+        Returns:
+            Number of messages in the thread.
+        """
+        thread = await self.get_thread(thread_id)
+        return len(thread.get("messages", []))
+
+    async def get_latest_message(self, thread_id: str) -> dict[str, Any] | None:
+        """Get the latest message in a thread.
+
+        Args:
+            thread_id: The thread ID.
+
+        Returns:
+            The latest message or None if thread is empty.
+        """
+        thread = await self.get_thread(thread_id)
+        messages = thread.get("messages", [])
+        if not messages:
+            return None
+        return cast("dict[str, Any]", messages[-1])

nornweave/huginn/config.py

@@ -0,0 +1,52 @@
+"""MCP server configuration.
+
+Configuration is loaded from environment variables:
+- NORNWEAVE_API_URL: Base URL for the NornWeave REST API (default: http://localhost:8000)
+- NORNWEAVE_API_KEY: API key for authentication (optional)
+"""
+
+from functools import lru_cache
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class MCPSettings(BaseSettings):
+    """MCP server configuration from environment."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    # API connection
+    api_url: str = Field(
+        default="http://localhost:8000",
+        alias="NORNWEAVE_API_URL",
+        description="Base URL for the NornWeave REST API",
+    )
+    api_key: str = Field(
+        default="",
+        alias="NORNWEAVE_API_KEY",
+        description="API key for authentication (optional)",
+    )
+
+    # MCP server settings
+    mcp_host: str = Field(
+        default="0.0.0.0",
+        alias="NORNWEAVE_MCP_HOST",
+        description="Host to bind MCP server (SSE/HTTP transports)",
+    )
+    mcp_port: int = Field(
+        default=3000,
+        alias="NORNWEAVE_MCP_PORT",
+        description="Port for MCP server (SSE/HTTP transports)",
+    )
+
+
+@lru_cache
+def get_mcp_settings() -> MCPSettings:
+    """Get cached MCP settings instance."""
+    return MCPSettings()

nornweave/huginn/resources.py

@@ -0,0 +1,165 @@
+"""MCP resources: email://inbox/{id}/recent, email://thread/{id}.
+
+Resources provide read-only data access for AI agents.
+"""
+
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+if TYPE_CHECKING:
+    from nornweave.huginn.client import NornWeaveClient
+
+
+async def get_recent_threads(client: NornWeaveClient, inbox_id: str) -> str:
+    """Get recent threads for an inbox.
+
+    Resource URI: email://inbox/{inbox_id}/recent
+
+    Args:
+        client: NornWeave API client.
+        inbox_id: The inbox ID.
+
+    Returns:
+        JSON string with thread summaries.
+
+    Raises:
+        Exception: If inbox not found or API error.
+    """
+    import json
+
+    try:
+        # Get threads (limit to 10 most recent)
+        threads_response = await client.list_threads(inbox_id, limit=10)
+        threads = threads_response.get("items", [])
+
+        # Format thread summaries with message count
+        summaries = []
+        for thread in threads:
+            # Get thread details to count messages
+            try:
+                thread_detail = await client.get_thread(thread["id"])
+                message_count = len(thread_detail.get("messages", []))
+                participants = _extract_participants(thread_detail)
+            except httpx.HTTPStatusError:
+                message_count = 0
+                participants = []
+
+            summaries.append(
+                {
+                    "id": thread["id"],
+                    "subject": thread.get("subject", "(no subject)"),
+                    "last_message_at": thread.get("last_message_at"),
+                    "message_count": message_count,
+                    "participants": participants,
+                }
+            )
+
+        return json.dumps(summaries, indent=2, default=str)
+
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code == 404:
+            raise Exception(f"Inbox '{inbox_id}' not found") from e
+        raise Exception(f"API error: {e.response.status_code}") from e
+
+
+def _extract_participants(thread_detail: dict[str, Any]) -> list[str]:
+    """Extract unique participant email addresses from thread messages."""
+    participants: set[str] = set()
+    for message in thread_detail.get("messages", []):
+        author = message.get("author")
+        if author:
+            participants.add(author)
+    return sorted(participants)
+
+
+async def get_thread_content(client: NornWeaveClient, thread_id: str) -> str:
+    """Get thread content in Markdown format.
+
+    Resource URI: email://thread/{thread_id}
+
+    Args:
+        client: NornWeave API client.
+        thread_id: The thread ID.
+
+    Returns:
+        Markdown-formatted thread content optimized for LLM context.
+
+    Raises:
+        Exception: If thread not found or API error.
+    """
+    try:
+        thread = await client.get_thread(thread_id)
+        return format_thread_markdown(thread)
+
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code == 404:
+            raise Exception(f"Thread '{thread_id}' not found") from e
+        raise Exception(f"API error: {e.response.status_code}") from e
+
+
+def format_thread_markdown(thread: dict[str, Any]) -> str:
+    """Format thread data as Markdown for LLM context.
+
+    Args:
+        thread: Thread data with id, subject, and messages.
+
+    Returns:
+        Markdown-formatted thread content.
+    """
+    lines: list[str] = []
+
+    # Thread subject as heading
+    subject = thread.get("subject", "(no subject)")
+    lines.append(f"## Thread: {subject}")
+    lines.append("")
+
+    messages = thread.get("messages", [])
+    if not messages:
+        lines.append("*No messages in this thread.*")
+        return "\n".join(lines)
+
+    for i, message in enumerate(messages):
+        if i > 0:
+            lines.append("---")
+            lines.append("")
+
+        # Message metadata
+        author = message.get("author", "unknown")
+        timestamp = message.get("timestamp")
+        role = message.get("role", "user")
+
+        # Format date
+        date_str = _format_timestamp(timestamp) if timestamp else "unknown date"
+
+        # Role indicator for context
+        role_indicator = "→" if role == "assistant" else "←"
+
+        lines.append(f"**From:** {author} {role_indicator}")
+        lines.append(f"**Date:** {date_str}")
+        lines.append("")
+
+        # Message content
+        content = message.get("content", "")
+        if content:
+            lines.append(content)
+        else:
+            lines.append("*(empty message)*")
+
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def _format_timestamp(timestamp: str) -> str:
+    """Format ISO timestamp to human-readable format."""
+    from datetime import datetime
+
+    try:
+        # Handle ISO format with timezone
+        if "T" in timestamp:
+            dt = datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
+            return dt.strftime("%Y-%m-%d %H:%M")
+        return timestamp
+    except (ValueError, TypeError):
+        return str(timestamp)