nornweave 0.1.2__py3-none-any.whl

nornweave/huginn/server.py

@@ -0,0 +1,202 @@
+"""MCP server setup (Huginn & Muninn).
+
+This module provides the FastMCP server that exposes NornWeave email capabilities
+to AI agents via the Model Context Protocol.
+
+Supports three transports:
+- stdio: For Claude Desktop, Cursor, and local CLI usage (default)
+- sse: For web-based MCP clients and browser integrations
+- http: For remote/cloud deployments and LangChain integration
+"""
+
+from typing import Any, Literal
+
+from fastmcp import FastMCP
+
+from nornweave.huginn.client import NornWeaveClient
+from nornweave.huginn.resources import get_recent_threads, get_thread_content
+from nornweave.muninn.tools import create_inbox, search_email, send_email, wait_for_reply
+
+# Create the FastMCP server
+mcp = FastMCP(
+    name="nornweave",
+    version="0.1.2",
+    instructions="Email capabilities for AI agents - create inboxes, send emails, search messages",
+)
+
+# Global client instance (created on first use)
+_client: NornWeaveClient | None = None
+
+
+def _get_client() -> NornWeaveClient:
+    """Get or create the NornWeave API client."""
+    global _client
+    if _client is None:
+        _client = NornWeaveClient()
+    return _client
+
+
+# -----------------------------------------------------------------------------
+# Resources (Read-only data access)
+# -----------------------------------------------------------------------------
+
+
+@mcp.resource("email://inbox/{inbox_id}/recent")
+async def resource_recent_threads(inbox_id: str) -> str:
+    """Get recent threads for an inbox.
+
+    Returns the 10 most recent thread summaries with id, subject,
+    last_message_at, message_count, and participants.
+    """
+    client = _get_client()
+    return await get_recent_threads(client, inbox_id)
+
+
+@mcp.resource("email://thread/{thread_id}")
+async def resource_thread_content(thread_id: str) -> str:
+    """Get thread content in Markdown format.
+
+    Returns the full thread conversation formatted as Markdown,
+    optimized for LLM context windows.
+    """
+    client = _get_client()
+    return await get_thread_content(client, thread_id)
+
+
+@mcp.tool()
+async def tool_create_inbox(name: str, username: str) -> dict[str, Any]:
+    """Create a new inbox.
+
+    Provision a new email address for the agent.
+
+    Args:
+        name: Display name for the inbox (e.g., "Support Bot")
+        username: Local part of email address (e.g., "support" becomes support@yourdomain.com)
+
+    Returns:
+        Created inbox with id, email_address, and name.
+    """
+    client = _get_client()
+    return await create_inbox(client, name=name, username=username)
+
+
+@mcp.tool()
+async def tool_send_email(
+    inbox_id: str,
+    recipient: str,
+    subject: str,
+    body: str,
+    thread_id: str | None = None,
+) -> dict[str, Any]:
+    """Send an email.
+
+    Send an email from an inbox. The body content should be in Markdown format
+    and will be automatically converted to HTML.
+
+    Args:
+        inbox_id: The inbox ID to send from
+        recipient: Email address to send to
+        subject: Email subject line
+        body: Email body in Markdown format
+        thread_id: Optional thread ID if this is a reply to an existing thread
+
+    Returns:
+        Send response with message_id, thread_id, and status.
+    """
+    client = _get_client()
+    return await send_email(
+        client,
+        inbox_id=inbox_id,
+        recipient=recipient,
+        subject=subject,
+        body=body,
+        thread_id=thread_id,
+    )
+
+
+@mcp.tool()
+async def tool_search_email(query: str, inbox_id: str, limit: int = 10) -> dict[str, Any]:
+    """Search for emails.
+
+    Find relevant messages in an inbox by query text.
+
+    Args:
+        query: Search query (e.g., "invoice", "meeting request")
+        inbox_id: Inbox to search in
+        limit: Maximum number of results (default: 10, max: 100)
+
+    Returns:
+        Search results with matching messages containing id, thread_id, content, created_at.
+    """
+    client = _get_client()
+    return await search_email(client, query=query, inbox_id=inbox_id, limit=min(limit, 100))
+
+
+@mcp.tool()
+async def tool_wait_for_reply(thread_id: str, timeout_seconds: int = 300) -> dict[str, Any]:
+    """Wait for a reply in a thread (experimental).
+
+    Block execution until a new email arrives in the specified thread.
+    Useful for synchronous agent workflows that need to wait for responses.
+
+    Args:
+        thread_id: Thread ID to wait on
+        timeout_seconds: Maximum wait time in seconds (default: 300 / 5 minutes)
+
+    Returns:
+        If reply received: {"received": true, "message": {...}}
+        If timeout: {"received": false, "timeout": true, "waited_seconds": N}
+
+    Note:
+        This is an experimental feature that uses polling. It may not be suitable
+        for all use cases and could incur additional API calls.
+    """
+    client = _get_client()
+    return await wait_for_reply(client, thread_id=thread_id, timeout_seconds=timeout_seconds)
+
+
+# -----------------------------------------------------------------------------
+# Server Entry Points
+# -----------------------------------------------------------------------------
+
+
+def serve(
+    transport: Literal["stdio", "sse", "http"] = "stdio",
+    host: str = "0.0.0.0",
+    port: int = 3000,
+) -> None:
+    """Run the MCP server.
+
+    Args:
+        transport: Transport type - "stdio" (default), "sse", or "http"
+        host: Host to bind for SSE/HTTP transports (default: 0.0.0.0)
+        port: Port for SSE/HTTP transports (default: 3000)
+    """
+    if transport == "stdio":
+        mcp.run()
+    elif transport == "sse":
+        mcp.run(transport="sse", host=host, port=port)
+    elif transport == "http":
+        mcp.run(transport="streamable-http", host=host, port=port)
+    else:
+        raise ValueError(f"Unknown transport: {transport}")
+
+
+def serve_stdio() -> None:
+    """Run MCP server with stdio transport (for MCP entry point)."""
+    serve(transport="stdio")
+
+
+def serve_sse(host: str = "0.0.0.0", port: int = 3000) -> None:
+    """Run MCP server with SSE transport."""
+    serve(transport="sse", host=host, port=port)
+
+
+def serve_http(host: str = "0.0.0.0", port: int = 3000) -> None:
+    """Run MCP server with HTTP transport."""
+    serve(transport="http", host=host, port=port)
+
+
+# For MCP entry point discovery
+if __name__ == "__main__":
+    serve_stdio()

nornweave/models/__init__.py

@@ -0,0 +1,113 @@
+"""Domain models: Inbox, Thread, Message, Event, Attachment."""
+
+from nornweave.models.attachment import (
+    Attachment,
+    AttachmentCreate,
+    AttachmentDisposition,
+    AttachmentMeta,
+    AttachmentResponse,
+    AttachmentUpload,
+    SendAttachment,
+)
+from nornweave.models.event import (
+    BounceEvent,
+    ComplaintEvent,
+    DeliveryEvent,
+    Event,
+    EventCreate,
+    EventType,
+    ListEventsResponse,
+    MessageBouncedEvent,
+    MessageComplainedEvent,
+    MessageDeliveredEvent,
+    MessageReceivedEvent,
+    MessageRejectedEvent,
+    MessageSentEvent,
+    Recipient,
+    RejectEvent,
+    SendEvent,
+    WebhookEvent,
+)
+from nornweave.models.inbox import Inbox, InboxBase, InboxCreate
+from nornweave.models.message import (
+    ListMessagesResponse,
+    Message,
+    MessageBase,
+    MessageCreate,
+    MessageDirection,
+    MessageInCreate,
+    MessageItem,
+    ReplyToMessageRequest,
+    SendMessageRequest,
+    SendMessageResponse,
+    UpdateMessageRequest,
+)
+from nornweave.models.thread import (
+    ListThreadsResponse,
+    Thread,
+    ThreadBase,
+    ThreadCreate,
+    ThreadItem,
+    ThreadSummary,
+    UpdateThreadRequest,
+)
+
+# Rebuild models with forward references now that all models are imported.
+# This is necessary because some models have circular references (e.g., Thread->Message,
+# Message->Attachment, MessageReceivedEvent->Message) which cannot be resolved at module load time.
+Message.model_rebuild()
+Thread.model_rebuild()
+MessageReceivedEvent.model_rebuild()
+
+__all__ = [
+    # Attachment models
+    "Attachment",
+    "AttachmentCreate",
+    "AttachmentDisposition",
+    "AttachmentMeta",
+    "AttachmentResponse",
+    "AttachmentUpload",
+    # Event models
+    "BounceEvent",
+    "ComplaintEvent",
+    "DeliveryEvent",
+    "Event",
+    "EventCreate",
+    "EventType",
+    # Inbox models
+    "Inbox",
+    "InboxBase",
+    "InboxCreate",
+    "ListEventsResponse",
+    # Message models
+    "ListMessagesResponse",
+    # Thread models
+    "ListThreadsResponse",
+    "Message",
+    "MessageBase",
+    "MessageBouncedEvent",
+    "MessageComplainedEvent",
+    "MessageCreate",
+    "MessageDeliveredEvent",
+    "MessageDirection",
+    "MessageInCreate",
+    "MessageItem",
+    "MessageReceivedEvent",
+    "MessageRejectedEvent",
+    "MessageSentEvent",
+    "Recipient",
+    "RejectEvent",
+    "ReplyToMessageRequest",
+    "SendAttachment",
+    "SendEvent",
+    "SendMessageRequest",
+    "SendMessageResponse",
+    "Thread",
+    "ThreadBase",
+    "ThreadCreate",
+    "ThreadItem",
+    "ThreadSummary",
+    "UpdateMessageRequest",
+    "UpdateThreadRequest",
+    "WebhookEvent",
+]

nornweave/models/attachment.py

@@ -0,0 +1,136 @@
+"""Attachment models for email attachments.
+
+Attachment models for file handling in messages.
+"""
+
+import base64
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, Field
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+
+class AttachmentDisposition(str, Enum):
+    """Content disposition of attachment."""
+
+    INLINE = "inline"
+    ATTACHMENT = "attachment"
+
+
+class AttachmentBase(BaseModel):
+    """Base attachment fields shared across models."""
+
+    filename: str | None = Field(None, description="Filename of attachment")
+    content_type: str | None = Field(None, description="MIME content type")
+    content_disposition: AttachmentDisposition | None = Field(
+        None, description="Content disposition (inline or attachment)"
+    )
+    content_id: str | None = Field(
+        None, description="Content-ID for inline attachments (cid: references)"
+    )
+
+
+class Attachment(AttachmentBase):
+    """
+    Full attachment model for storage and API responses.
+    """
+
+    attachment_id: str = Field(..., description="Unique ID of attachment")
+    size: int = Field(..., description="Size of attachment in bytes")
+
+    model_config = {"extra": "forbid"}
+
+
+class AttachmentResponse(AttachmentBase):
+    """
+    Attachment response with download URL.
+
+    API response model with download URL.
+    """
+
+    attachment_id: str
+    size: int
+    download_url: str = Field(..., description="URL to download the attachment")
+    expires_at: datetime = Field(..., description="Time at which the download URL expires")
+
+    model_config = {"extra": "forbid"}
+
+
+class SendAttachment(BaseModel):
+    """
+    Attachment for outbound emails.
+
+    Attachment payload for outbound messages.
+    """
+
+    filename: str | None = None
+    content_type: str | None = None
+    content_disposition: AttachmentDisposition | None = None
+    content_id: str | None = Field(None, description="For inline attachments")
+    content: str | None = Field(None, description="Base64 encoded content of attachment")
+    url: str | None = Field(None, description="URL to the attachment (alternative to content)")
+
+    model_config = {"extra": "forbid"}
+
+    def get_content_bytes(self) -> bytes | None:
+        """Decode base64 content to bytes."""
+        if self.content:
+            return base64.b64decode(self.content)
+        return None
+
+
+class AttachmentUpload(BaseModel):
+    """Attachment upload for outbound emails via API."""
+
+    filename: str = Field(..., min_length=1, max_length=255)
+    content_type: str = Field(..., min_length=1)
+    content_base64: str = Field(..., description="Base64-encoded file content")
+    disposition: AttachmentDisposition = Field(default=AttachmentDisposition.ATTACHMENT)
+    content_id: str | None = Field(None, description="For inline attachments")
+
+    model_config = {"extra": "forbid"}
+
+    def get_content_bytes(self) -> bytes:
+        """Decode base64 content to bytes."""
+        return base64.b64decode(self.content_base64)
+
+    @property
+    def size_bytes(self) -> int:
+        """Calculate size from base64 content."""
+        return len(self.get_content_bytes())
+
+
+class AttachmentCreate(BaseModel):
+    """Internal model for creating attachments in storage."""
+
+    message_id: str
+    filename: str
+    content_type: str
+    size_bytes: int
+    disposition: AttachmentDisposition = AttachmentDisposition.ATTACHMENT
+    content_id: str | None = None
+    content: bytes | None = None
+    storage_path: str | None = None
+    storage_backend: str | None = None
+
+    model_config = {"extra": "forbid", "arbitrary_types_allowed": True}
+
+
+class AttachmentMeta(BaseModel):
+    """
+    Lightweight attachment metadata for listing/display without content.
+
+    Used in thread summaries and message listings.
+    """
+
+    attachment_id: str
+    filename: str | None
+    content_type: str | None
+    size: int
+    disposition: AttachmentDisposition = AttachmentDisposition.ATTACHMENT
+    content_id: str | None = None
+
+    model_config = {"extra": "forbid"}