remarkable-mcp 0.1.3__py3-none-any.whl

remarkable_mcp/__init__.py

@@ -0,0 +1,17 @@
+"""
+reMarkable MCP Server
+
+An MCP server that provides access to reMarkable tablet data through the reMarkable Cloud API.
+"""
+
+__version__ = "0.1.0"
+
+
+def get_mcp():
+    """Get the MCP server instance. Only imports when called."""
+    from remarkable_mcp.server import mcp
+
+    return mcp
+
+
+__all__ = ["get_mcp", "__version__"]

remarkable_mcp/api.py

@@ -0,0 +1,116 @@
+"""
+reMarkable Cloud API client helpers.
+"""
+
+import os
+from pathlib import Path
+from typing import Any, Dict, List
+
+# Configuration - check env var first, then fall back to file
+REMARKABLE_TOKEN = os.environ.get("REMARKABLE_TOKEN")
+REMARKABLE_CONFIG_DIR = Path.home() / ".remarkable"
+REMARKABLE_TOKEN_FILE = REMARKABLE_CONFIG_DIR / "token"
+CACHE_DIR = REMARKABLE_CONFIG_DIR / "cache"
+
+
+def get_rmapi():
+    """Get or initialize the reMarkable API client."""
+    try:
+        from rmapy.api import Client
+
+        client = Client()
+
+        # If token is provided via environment, use it
+        if REMARKABLE_TOKEN:
+            # rmapy stores token in ~/.rmapi, we need to write it there
+            rmapi_file = Path.home() / ".rmapi"
+            rmapi_file.write_text(REMARKABLE_TOKEN)
+
+        # Renew/validate the token
+        client.renew_token()
+
+        return client
+    except ImportError:
+        raise RuntimeError("rmapy not installed. Run: uv add rmapy")
+    except Exception as e:
+        raise RuntimeError(f"Failed to initialize reMarkable client: {e}")
+
+
+def ensure_config_dir():
+    """Ensure configuration directory exists."""
+    REMARKABLE_CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CACHE_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def register_and_get_token(one_time_code: str) -> str:
+    """
+    Register with reMarkable using a one-time code and return the token.
+
+    Get a code from: https://my.remarkable.com/device/desktop/connect
+    """
+    import json as json_module
+    from uuid import uuid4
+
+    import requests
+
+    # Use the current remarkable API endpoint
+    # (rmapy uses an outdated one, this is from ddvk/rmapi)
+    device_token_url = "https://webapp-prod.cloud.remarkable.engineering/token/json/2/device/new"
+    uuid = str(uuid4())
+    body = {
+        "code": one_time_code,
+        "deviceDesc": "desktop-linux",
+        "deviceID": uuid,
+    }
+
+    try:
+        response = requests.post(device_token_url, json=body)
+
+        if response.status_code == 200 and response.text:
+            # Got a device token, save it in rmapy format
+            device_token = response.text.strip()
+
+            # rmapy expects a JSON file with devicetoken and usertoken
+            rmapi_file = Path.home() / ".rmapi"
+            token_data = {"devicetoken": device_token, "usertoken": ""}
+            rmapi_file.write_text(json_module.dumps(token_data))
+
+            return json_module.dumps(token_data)
+        else:
+            raise RuntimeError(
+                f"Registration failed (HTTP {response.status_code})\n\n"
+                "This usually means:\n"
+                "  1. The code has expired (codes are single-use and expire quickly)\n"
+                "  2. The code was already used\n"
+                "  3. The code was typed incorrectly\n\n"
+                "Get a new code from: https://my.remarkable.com/device/desktop/connect"
+            )
+    except requests.RequestException as e:
+        raise RuntimeError(f"Network error during registration: {e}")
+
+
+def get_items_by_id(collection) -> Dict[str, Any]:
+    """Build a lookup dict of items by ID."""
+    return {item.ID: item for item in collection}
+
+
+def get_items_by_parent(collection) -> Dict[str, List]:
+    """Build a lookup dict of items grouped by parent ID."""
+    items_by_parent: Dict[str, List] = {}
+    for item in collection:
+        parent = item.Parent if hasattr(item, "Parent") else ""
+        if parent not in items_by_parent:
+            items_by_parent[parent] = []
+        items_by_parent[parent].append(item)
+    return items_by_parent
+
+
+def get_item_path(item, items_by_id: Dict[str, Any]) -> str:
+    """Get the full path of an item."""
+    path_parts = [item.VissibleName]
+    parent_id = item.Parent if hasattr(item, "Parent") else ""
+    while parent_id and parent_id in items_by_id:
+        parent = items_by_id[parent_id]
+        path_parts.insert(0, parent.VissibleName)
+        parent_id = parent.Parent if hasattr(parent, "Parent") else ""
+    return "/" + "/".join(path_parts)

remarkable_mcp/extract.py

@@ -0,0 +1,183 @@
+"""
+Text extraction helpers for reMarkable documents.
+"""
+
+import json
+import tempfile
+import zipfile
+from difflib import SequenceMatcher
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+def find_similar_documents(query: str, documents: List, limit: int = 5) -> List[str]:
+    """Find documents with similar names for 'did you mean' suggestions."""
+    query_lower = query.lower()
+    scored = []
+    for doc in documents:
+        name = doc.VissibleName
+        # Use sequence matcher for fuzzy matching
+        ratio = SequenceMatcher(None, query_lower, name.lower()).ratio()
+        # Boost partial matches
+        if query_lower in name.lower():
+            ratio += 0.3
+        scored.append((name, ratio))
+
+    scored.sort(key=lambda x: x[1], reverse=True)
+    return [name for name, score in scored[:limit] if score > 0.3]
+
+
+def extract_text_from_rm_file(rm_file_path: Path) -> List[str]:
+    """
+    Extract typed text from a .rm file using rmscene.
+
+    This extracts text that was typed via Type Folio or on-screen keyboard.
+    Does NOT require OCR - text is stored natively in v6 .rm files.
+    """
+    try:
+        from rmscene import read_blocks
+        from rmscene.scene_items import Text
+        from rmscene.scene_tree import SceneTree
+
+        with open(rm_file_path, "rb") as f:
+            tree = SceneTree()
+            for block in read_blocks(f):
+                tree.add_block(block)
+
+        text_lines = []
+
+        # Extract text from the scene tree
+        for item in tree.root.children.values():
+            if hasattr(item, "value") and isinstance(item.value, Text):
+                text_obj = item.value
+                if hasattr(text_obj, "items"):
+                    for text_item in text_obj.items:
+                        if hasattr(text_item, "value") and text_item.value:
+                            text_lines.append(str(text_item.value))
+
+        return text_lines
+
+    except ImportError:
+        return []  # rmscene not available
+    except Exception:
+        # Log but don't fail - file might be older format
+        return []
+
+
+def extract_text_from_document_zip(zip_path: Path, include_ocr: bool = False) -> Dict[str, Any]:
+    """
+    Extract all text content from a reMarkable document zip.
+
+    Returns:
+        {
+            "typed_text": [...],      # From rmscene parsing
+            "highlights": [...],       # From PDF annotations
+            "handwritten_text": [...], # From OCR (if enabled)
+            "pages": int
+        }
+    """
+    result: Dict[str, Any] = {
+        "typed_text": [],
+        "highlights": [],
+        "handwritten_text": None,
+        "pages": 0,
+    }
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tmpdir_path = Path(tmpdir)
+
+        with zipfile.ZipFile(zip_path, "r") as zf:
+            zf.extractall(tmpdir_path)
+
+        rm_files = list(tmpdir_path.glob("**/*.rm"))
+        result["pages"] = len(rm_files)
+
+        # Extract typed text from .rm files using rmscene
+        for rm_file in rm_files:
+            text_lines = extract_text_from_rm_file(rm_file)
+            result["typed_text"].extend(text_lines)
+
+        # Extract text from .txt and .md files
+        for txt_file in tmpdir_path.glob("**/*.txt"):
+            try:
+                content = txt_file.read_text(errors="ignore")
+                if content.strip():
+                    result["typed_text"].append(content)
+            except Exception:
+                pass
+
+        for md_file in tmpdir_path.glob("**/*.md"):
+            try:
+                content = md_file.read_text(errors="ignore")
+                if content.strip():
+                    result["typed_text"].append(content)
+            except Exception:
+                pass
+
+        # Extract from .content files (metadata with text)
+        for content_file in tmpdir_path.glob("**/*.content"):
+            try:
+                data = json.loads(content_file.read_text())
+                if "text" in data:
+                    result["typed_text"].append(data["text"])
+            except Exception:
+                pass
+
+        # Extract PDF highlights
+        for json_file in tmpdir_path.glob("**/*.json"):
+            try:
+                data = json.loads(json_file.read_text())
+                if isinstance(data, dict) and "highlights" in data:
+                    for h in data.get("highlights", []):
+                        if "text" in h and h["text"]:
+                            result["highlights"].append(h["text"])
+            except Exception:
+                pass
+
+        # OCR for handwritten content (optional)
+        if include_ocr and rm_files:
+            result["handwritten_text"] = extract_handwriting_ocr(rm_files)
+
+    return result
+
+
+def extract_handwriting_ocr(rm_files: List[Path]) -> Optional[List[str]]:
+    """
+    Extract handwritten text using OCR.
+    Requires optional OCR dependencies (pytesseract, rmc).
+    """
+    try:
+        import subprocess
+
+        import pytesseract
+        from PIL import Image
+
+        ocr_results = []
+
+        for rm_file in rm_files:
+            # Use rmc to convert .rm to PNG
+            with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as tmp_png:
+                try:
+                    result = subprocess.run(
+                        ["rmc", "-t", "png", "-o", tmp_png.name, str(rm_file)],
+                        capture_output=True,
+                        timeout=30,
+                    )
+                    if result.returncode == 0:
+                        img = Image.open(tmp_png.name)
+                        text = pytesseract.image_to_string(img)
+                        if text.strip():
+                            ocr_results.append(text.strip())
+                except subprocess.TimeoutExpired:
+                    pass
+                except FileNotFoundError:
+                    # rmc not installed
+                    return None
+                finally:
+                    Path(tmp_png.name).unlink(missing_ok=True)
+
+        return ocr_results if ocr_results else None
+
+    except ImportError:
+        # OCR dependencies not installed
+        return None

remarkable_mcp/prompts.py

@@ -0,0 +1,134 @@
+"""
+MCP Prompts for reMarkable tablet workflows.
+
+Pre-built prompts to help users get started with common tasks.
+"""
+
+from remarkable_mcp.server import mcp
+
+
+@mcp.prompt(
+    name="summarize_recent",
+    title="Summarize Recent Notes",
+    description="Get an AI summary of your recent reMarkable notes",
+)
+def summarize_recent_prompt() -> list:
+    """Prompt to summarize recent documents."""
+    return [
+        {
+            "role": "user",
+            "content": (
+                "Please check my recent reMarkable documents using remarkable_recent() "
+                "and provide a summary of what I've been working on. "
+                "For any documents that look interesting, read their content "
+                "with remarkable_read() and give me key highlights."
+            ),
+        }
+    ]
+
+
+@mcp.prompt(
+    name="find_notes",
+    title="Find Notes About a Topic",
+    description="Search your reMarkable tablet for notes on a specific topic",
+)
+def find_notes_prompt(topic: str) -> list:
+    """Prompt to find notes about a topic."""
+    return [
+        {
+            "role": "user",
+            "content": (
+                f"Search my reMarkable tablet for any notes about '{topic}'. "
+                f"Use remarkable_browse(query='{topic}') to find relevant documents, "
+                "then use remarkable_read() to extract and summarize the content. "
+                "Please organize the information you find."
+            ),
+        }
+    ]
+
+
+@mcp.prompt(
+    name="daily_review",
+    title="Daily Notes Review",
+    description="Review what you worked on today in your reMarkable tablet",
+)
+def daily_review_prompt() -> list:
+    """Prompt for daily review of notes."""
+    return [
+        {
+            "role": "user",
+            "content": (
+                "Please do a daily review of my reMarkable notes:\n\n"
+                "1. Use remarkable_recent(limit=5, include_preview=True) to see "
+                "what I worked on recently\n"
+                "2. For documents modified today, read the full content\n"
+                "3. Summarize the key points and any action items\n"
+                "4. Suggest any follow-up tasks based on my notes"
+            ),
+        }
+    ]
+
+
+@mcp.prompt(
+    name="export_document",
+    title="Export Document Content",
+    description="Extract and format content from a specific document",
+)
+def export_document_prompt(document_name: str) -> list:
+    """Prompt to export a specific document."""
+    return [
+        {
+            "role": "user",
+            "content": (
+                f"Please extract all the content from my reMarkable document "
+                f"'{document_name}' using remarkable_read('{document_name}'). "
+                "Then format it nicely as markdown, preserving the structure "
+                "and any important formatting."
+            ),
+        }
+    ]
+
+
+@mcp.prompt(
+    name="organize_library",
+    title="Organize My Library",
+    description="Get suggestions for organizing your reMarkable library",
+)
+def organize_library_prompt() -> list:
+    """Prompt for library organization suggestions."""
+    return [
+        {
+            "role": "user",
+            "content": (
+                "Please help me organize my reMarkable library:\n\n"
+                "1. Use remarkable_browse('/') to see my current folder structure\n"
+                "2. Use remarkable_recent(limit=20) to see my active documents\n"
+                "3. Identify any documents that might be misplaced or could be "
+                "better organized\n"
+                "4. Suggest a folder structure that would help me stay organized\n\n"
+                "Note: This server is read-only, so just provide recommendations - "
+                "I'll reorganize manually on my tablet."
+            ),
+        }
+    ]
+
+
+@mcp.prompt(
+    name="meeting_notes",
+    title="Extract Meeting Notes",
+    description="Find and extract meeting notes from your reMarkable",
+)
+def meeting_notes_prompt(meeting_keyword: str = "meeting") -> list:
+    """Prompt to find and extract meeting notes."""
+    return [
+        {
+            "role": "user",
+            "content": (
+                f"Find all my meeting notes on my reMarkable tablet:\n\n"
+                f"1. Search for documents with remarkable_browse(query='{meeting_keyword}')\n"
+                "2. Read the content of each meeting notes document\n"
+                "3. Extract key decisions, action items, and attendees mentioned\n"
+                "4. Create a consolidated summary of all meetings"
+            ),
+        }
+    ]

remarkable_mcp/resources.py

@@ -0,0 +1,130 @@
+"""
+MCP Resources for reMarkable tablet access.
+
+Dynamically registers recent documents as resources on startup.
+"""
+
+import json
+import logging
+import tempfile
+from pathlib import Path
+
+from remarkable_mcp.server import mcp
+
+logger = logging.getLogger(__name__)
+
+
+def register_document_resources():
+    """
+    Dynamically register recent documents as MCP resources.
+
+    Called on startup if API connection exists. Each recent document
+    becomes its own resource with URI like remarkable://doc/{name}.
+    """
+    try:
+        from rmapy.document import Document
+
+        from remarkable_mcp.api import get_item_path, get_items_by_id, get_rmapi
+        from remarkable_mcp.extract import extract_text_from_document_zip
+
+        client = get_rmapi()
+        collection = client.get_meta_items()
+        items_by_id = get_items_by_id(collection)
+
+        # Get documents sorted by modified date
+        documents = [item for item in collection if isinstance(item, Document)]
+        documents.sort(
+            key=lambda x: (
+                x.ModifiedClient if hasattr(x, "ModifiedClient") and x.ModifiedClient else ""
+            ),
+            reverse=True,
+        )
+
+        # Register each recent document as a resource
+        for doc in documents[:10]:
+            doc_name = doc.VissibleName
+            doc_modified = doc.ModifiedClient if hasattr(doc, "ModifiedClient") else None
+
+            # Create a closure to capture the document
+            def make_resource_fn(document):
+                def resource_fn() -> str:
+                    try:
+                        raw_doc = client.download(document)
+
+                        with tempfile.NamedTemporaryFile(suffix=".zip", delete=False) as tmp:
+                            tmp.write(raw_doc.content)
+                            tmp_path = Path(tmp.name)
+
+                        try:
+                            content = extract_text_from_document_zip(tmp_path, include_ocr=False)
+                        finally:
+                            tmp_path.unlink(missing_ok=True)
+
+                        # Combine all text content
+                        text_parts = []
+
+                        if content["typed_text"]:
+                            text_parts.extend(content["typed_text"])
+
+                        if content["highlights"]:
+                            text_parts.append("\n--- Highlights ---")
+                            text_parts.extend(content["highlights"])
+
+                        return "\n\n".join(text_parts) if text_parts else "(No text content found)"
+
+                    except Exception as e:
+                        return f"Error reading document: {e}"
+
+                return resource_fn
+
+            # Register the resource
+            resource_uri = f"remarkable://doc/{doc_name}"
+            description = f"Content from '{doc_name}'"
+            if doc_modified:
+                description += f" (modified: {doc_modified})"
+
+            mcp.resource(
+                resource_uri,
+                name=doc_name,
+                description=description,
+                mime_type="text/plain",
+            )(make_resource_fn(doc))
+
+        logger.info(f"Registered {min(len(documents), 10)} document resources")
+
+        # Also register a folder structure resource
+        @mcp.resource(
+            "remarkable://folders",
+            name="Folder Structure",
+            description="Your reMarkable folder hierarchy",
+            mime_type="application/json",
+        )
+        def folders_resource() -> str:
+            """Return folder structure as a resource."""
+            from rmapy.folder import Folder
+
+            try:
+                folders = []
+                for item in collection:
+                    if isinstance(item, Folder):
+                        folders.append(
+                            {
+                                "name": item.VissibleName,
+                                "path": get_item_path(item, items_by_id),
+                                "id": item.ID,
+                            }
+                        )
+
+                folders.sort(key=lambda x: x["path"])
+                return json.dumps({"folders": folders}, indent=2)
+
+            except Exception as e:
+                return json.dumps({"error": str(e)})
+
+    except Exception as e:
+        logger.warning(f"Could not register document resources: {e}")
+        logger.info("Resources will be available after authentication via remarkable_status()")
+
+
+# Register resources on module load (if API is available)
+register_document_resources()

remarkable_mcp/responses.py

@@ -0,0 +1,24 @@
+"""
+Response helpers for MCP tools.
+"""
+
+import json
+from typing import Any, Dict, List, Optional
+
+
+def make_response(data: Dict[str, Any], hint: str) -> str:
+    """Create a JSON response with a hint for the model."""
+    data["_hint"] = hint
+    return json.dumps(data, indent=2)
+
+
+def make_error(
+    error_type: str, message: str, suggestion: str, did_you_mean: Optional[List[str]] = None
+) -> str:
+    """Create an educational error response."""
+    error: Dict[str, Any] = {
+        "_error": {"type": error_type, "message": message, "suggestion": suggestion}
+    }
+    if did_you_mean:
+        error["_error"]["did_you_mean"] = did_you_mean
+    return json.dumps(error, indent=2)

remarkable_mcp/server.py

@@ -0,0 +1,20 @@
+"""
+reMarkable MCP Server initialization.
+"""
+
+from mcp.server.fastmcp import FastMCP
+
+# Initialize FastMCP server
+mcp = FastMCP("remarkable")
+
+# Import tools, resources, and prompts to register them
+from remarkable_mcp import (  # noqa: E402
+    prompts,  # noqa: F401
+    resources,  # noqa: F401
+    tools,  # noqa: F401
+)
+
+
+def run():
+    """Run the MCP server."""
+    mcp.run()

remarkable_mcp/tools.py

@@ -0,0 +1,432 @@
+"""
+MCP Tools for reMarkable tablet access.
+
+All tools are read-only and idempotent - they only retrieve data from the
+reMarkable Cloud and do not modify any documents.
+"""
+
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+from mcp.types import ToolAnnotations
+
+from remarkable_mcp.api import (
+    REMARKABLE_TOKEN,
+    get_item_path,
+    get_items_by_id,
+    get_items_by_parent,
+    get_rmapi,
+)
+from remarkable_mcp.extract import (
+    extract_text_from_document_zip,
+    find_similar_documents,
+)
+from remarkable_mcp.responses import make_error, make_response
+from remarkable_mcp.server import mcp
+
+# Tool annotations for read-only operations
+READ_ONLY_ANNOTATIONS = ToolAnnotations(
+    title="Read-only reMarkable operation",
+    readOnlyHint=True,
+    destructiveHint=False,
+    idempotentHint=True,
+    openWorldHint=False,  # Private cloud account, not open world
+)
+
+
+@mcp.tool(annotations=READ_ONLY_ANNOTATIONS)
+def remarkable_read(document: str, include_ocr: bool = False) -> str:
+    """
+    <usecase>Read and extract text content from a reMarkable document.</usecase>
+    <instructions>
+    Extracts all readable text from a document:
+    - Typed text from Type Folio or on-screen keyboard (automatic)
+    - PDF/EPUB highlights and annotations (automatic)
+    - Handwritten text via OCR (if include_ocr=True, slower)
+
+    This is the recommended tool for getting document content.
+    </instructions>
+    <parameters>
+    - document: Document name or path (use remarkable_browse to find documents)
+    - include_ocr: Enable handwriting OCR (default: False, requires OCR extras)
+    </parameters>
+    <examples>
+    - remarkable_read("Meeting Notes")
+    - remarkable_read("Work/Project Plan", include_ocr=True)
+    </examples>
+    """
+    try:
+        from rmapy.document import Document
+
+        client = get_rmapi()
+        collection = client.get_meta_items()
+        items_by_id = get_items_by_id(collection)
+
+        # Find the document by name
+        documents = [item for item in collection if isinstance(item, Document)]
+        target_doc = None
+
+        for doc in documents:
+            if doc.VissibleName == document:
+                target_doc = doc
+                break
+
+        if not target_doc:
+            # Find similar documents for suggestion
+            similar = find_similar_documents(document, documents)
+            search_term = document.split()[0] if document else "notes"
+            return make_error(
+                error_type="document_not_found",
+                message=f"Document not found: '{document}'",
+                suggestion=(
+                    f"Try remarkable_browse(query='{search_term}') to search, "
+                    "or remarkable_browse('/') to list all files."
+                ),
+                did_you_mean=similar if similar else None,
+            )
+
+        # Download the document
+        raw_doc = client.download(target_doc)
+
+        with tempfile.NamedTemporaryFile(suffix=".zip", delete=False) as tmp:
+            tmp.write(raw_doc.content)
+            tmp_path = Path(tmp.name)
+
+        try:
+            # Extract text content
+            content = extract_text_from_document_zip(tmp_path, include_ocr=include_ocr)
+        finally:
+            tmp_path.unlink(missing_ok=True)
+
+        doc_path = get_item_path(target_doc, items_by_id)
+
+        result = {
+            "document": target_doc.VissibleName,
+            "path": doc_path,
+            "content": {
+                "typed_text": content["typed_text"],
+                "highlights": content["highlights"],
+                "handwritten_text": content["handwritten_text"],
+            },
+            "pages": content["pages"],
+            "modified": (
+                target_doc.ModifiedClient if hasattr(target_doc, "ModifiedClient") else None
+            ),
+        }
+
+        # Build contextual hint
+        folder_path = "/".join(doc_path.split("/")[:-1]) or "/"
+        hint_parts = ["Text extracted."]
+
+        if content["typed_text"]:
+            hint_parts.append(f"Found {len(content['typed_text'])} text segments.")
+        else:
+            hint_parts.append("No typed text found.")
+            if not include_ocr:
+                hint_parts.append("Try include_ocr=True for handwritten content.")
+
+        hint_parts.append(f"To see other files: remarkable_browse('{folder_path}').")
+
+        return make_response(result, " ".join(hint_parts))
+
+    except Exception as e:
+        return make_error(
+            error_type="read_failed",
+            message=str(e),
+            suggestion="Check remarkable_status() to verify your connection.",
+        )
+
+
+@mcp.tool(annotations=READ_ONLY_ANNOTATIONS)
+def remarkable_browse(path: str = "/", query: Optional[str] = None) -> str:
+    """
+    <usecase>Browse your reMarkable library or search for documents.</usecase>
+    <instructions>
+    Two modes:
+    1. Browse mode (default): List contents of a folder
+       - Use path="/" for root folder
+       - Use path="/FolderName" to navigate into folders
+    2. Search mode: Find documents by name
+       - Set query="search term" to search across all documents
+
+    Results include document names, types, and modification dates.
+    </instructions>
+    <parameters>
+    - path: Folder path to browse (default: "/" for root)
+    - query: Search term to find documents by name (optional, triggers search mode)
+    </parameters>
+    <examples>
+    - remarkable_browse()  # List root folder
+    - remarkable_browse("/Work")  # List Work folder
+    - remarkable_browse(query="meeting")  # Search for "meeting"
+    </examples>
+    """
+    try:
+        from rmapy.document import Document
+        from rmapy.folder import Folder
+
+        client = get_rmapi()
+        collection = client.get_meta_items()
+        items_by_id = get_items_by_id(collection)
+        items_by_parent = get_items_by_parent(collection)
+
+        # Search mode
+        if query:
+            query_lower = query.lower()
+            matches = []
+
+            for item in collection:
+                if query_lower in item.VissibleName.lower():
+                    matches.append(
+                        {
+                            "name": item.VissibleName,
+                            "path": get_item_path(item, items_by_id),
+                            "type": "folder" if isinstance(item, Folder) else "document",
+                            "modified": (
+                                item.ModifiedClient if hasattr(item, "ModifiedClient") else None
+                            ),
+                        }
+                    )
+
+            matches.sort(key=lambda x: x["name"])
+
+            result = {"mode": "search", "query": query, "count": len(matches), "results": matches}
+
+            if matches:
+                first_doc = next((m for m in matches if m["type"] == "document"), None)
+                if first_doc:
+                    hint = (
+                        f"Found {len(matches)} results. "
+                        f"To read a document: remarkable_read('{first_doc['name']}')."
+                    )
+                else:
+                    hint = (
+                        f"Found {len(matches)} folders. "
+                        f"To browse one: remarkable_browse('{matches[0]['path']}')."
+                    )
+            else:
+                hint = (
+                    f"No results for '{query}'. "
+                    "Try remarkable_browse('/') to see all files, "
+                    "or use a different search term."
+                )
+
+            return make_response(result, hint)
+
+        # Browse mode
+        if path == "/" or path == "":
+            target_parent = ""
+        else:
+            # Navigate to the folder
+            path_parts = [p for p in path.strip("/").split("/") if p]
+            current_parent = ""
+
+            for part in path_parts:
+                found = False
+                for item in items_by_parent.get(current_parent, []):
+                    if item.VissibleName == part and isinstance(item, Folder):
+                        current_parent = item.ID
+                        found = True
+                        break
+
+                if not found:
+                    # Folder not found - suggest alternatives
+                    available_folders = [
+                        item.VissibleName
+                        for item in items_by_parent.get(current_parent, [])
+                        if isinstance(item, Folder)
+                    ]
+                    return make_error(
+                        error_type="folder_not_found",
+                        message=f"Folder not found: '{part}'",
+                        suggestion=("Use remarkable_browse('/') to see root folder contents."),
+                        did_you_mean=(available_folders[:5] if available_folders else None),
+                    )
+
+            target_parent = current_parent
+
+        items = items_by_parent.get(target_parent, [])
+
+        folders = []
+        documents = []
+
+        for item in sorted(items, key=lambda x: x.VissibleName.lower()):
+            if isinstance(item, Folder):
+                folders.append({"name": item.VissibleName, "id": item.ID})
+            elif isinstance(item, Document):
+                documents.append(
+                    {
+                        "name": item.VissibleName,
+                        "id": item.ID,
+                        "modified": (
+                            item.ModifiedClient if hasattr(item, "ModifiedClient") else None
+                        ),
+                    }
+                )
+
+        result = {"mode": "browse", "path": path, "folders": folders, "documents": documents}
+
+        # Build helpful hint
+        hint_parts = [f"Found {len(folders)} folder(s) and {len(documents)} document(s)."]
+
+        if documents:
+            hint_parts.append(f"To read a document: remarkable_read('{documents[0]['name']}').")
+        if folders:
+            folder_path = f"{path.rstrip('/')}/{folders[0]['name']}"
+            hint_parts.append(f"To enter a folder: remarkable_browse('{folder_path}').")
+        if not folders and not documents:
+            hint_parts.append("This folder is empty.")
+
+        return make_response(result, " ".join(hint_parts))
+
+    except Exception as e:
+        return make_error(
+            error_type="browse_failed",
+            message=str(e),
+            suggestion="Check remarkable_status() to verify your connection.",
+        )
+
+
+@mcp.tool(annotations=READ_ONLY_ANNOTATIONS)
+def remarkable_recent(limit: int = 10, include_preview: bool = False) -> str:
+    """
+    <usecase>Get your most recently modified documents.</usecase>
+    <instructions>
+    Returns documents sorted by modification date (newest first).
+    Optionally includes a text preview of each document's content.
+
+    Use this to quickly find what you were working on recently.
+    </instructions>
+    <parameters>
+    - limit: Maximum documents to return (default: 10, max: 50)
+    - include_preview: Include first ~200 chars of text content (default: False)
+    </parameters>
+    <examples>
+    - remarkable_recent()  # Last 10 documents
+    - remarkable_recent(limit=5, include_preview=True)  # With content preview
+    </examples>
+    """
+    try:
+        from rmapy.document import Document
+
+        client = get_rmapi()
+        collection = client.get_meta_items()
+        items_by_id = get_items_by_id(collection)
+
+        # Clamp limit
+        limit = min(max(1, limit), 50)
+
+        # Get documents sorted by modified date
+        documents = [item for item in collection if isinstance(item, Document)]
+        documents.sort(
+            key=lambda x: (
+                x.ModifiedClient if hasattr(x, "ModifiedClient") and x.ModifiedClient else ""
+            ),
+            reverse=True,
+        )
+
+        results = []
+        for doc in documents[:limit]:
+            doc_info = {
+                "name": doc.VissibleName,
+                "path": get_item_path(doc, items_by_id),
+                "modified": (doc.ModifiedClient if hasattr(doc, "ModifiedClient") else None),
+            }
+
+            if include_preview:
+                # Download and extract preview
+                try:
+                    raw_doc = client.download(doc)
+                    with tempfile.NamedTemporaryFile(suffix=".zip", delete=False) as tmp:
+                        tmp.write(raw_doc.content)
+                        tmp_path = Path(tmp.name)
+
+                    try:
+                        content = extract_text_from_document_zip(tmp_path, include_ocr=False)
+                        preview_text = "\n".join(content["typed_text"])[:200]
+                        if len(preview_text) == 200:
+                            doc_info["preview"] = preview_text + "..."
+                        else:
+                            doc_info["preview"] = preview_text
+                    finally:
+                        tmp_path.unlink(missing_ok=True)
+                except Exception:
+                    doc_info["preview"] = None
+
+            results.append(doc_info)
+
+        result = {"count": len(results), "documents": results}
+
+        if results:
+            next_limit = min(limit * 2, 50)
+            hint = (
+                f"Showing {len(results)} recent documents. "
+                f"To read one: remarkable_read('{results[0]['name']}'). "
+                f"To see more: remarkable_recent(limit={next_limit})."
+            )
+        else:
+            hint = "No documents found. Use remarkable_browse('/') to check your library."
+
+        return make_response(result, hint)
+
+    except Exception as e:
+        return make_error(
+            error_type="recent_failed",
+            message=str(e),
+            suggestion="Check remarkable_status() to verify your connection.",
+        )
+
+
+@mcp.tool(annotations=READ_ONLY_ANNOTATIONS)
+def remarkable_status() -> str:
+    """
+    <usecase>Check connection status and authentication with reMarkable Cloud.</usecase>
+    <instructions>
+    Returns authentication status and diagnostic information.
+    Use this to verify your connection or troubleshoot issues.
+    </instructions>
+    <examples>
+    - remarkable_status()
+    </examples>
+    """
+    token_source = "environment variable" if REMARKABLE_TOKEN else "file (~/.rmapi)"
+
+    try:
+        from rmapy.document import Document
+
+        client = get_rmapi()
+        collection = client.get_meta_items()
+
+        doc_count = sum(1 for item in collection if isinstance(item, Document))
+
+        result = {
+            "authenticated": True,
+            "token_source": token_source,
+            "cloud_status": "connected",
+            "document_count": doc_count,
+        }
+
+        return make_response(
+            result,
+            (
+                f"Connected successfully. Found {doc_count} documents. "
+                "Use remarkable_browse() to see your files, "
+                "or remarkable_recent() for recent documents."
+            ),
+        )
+
+    except Exception as e:
+        error_msg = str(e)
+
+        result = {"authenticated": False, "error": error_msg, "token_source": token_source}
+
+        hint = (
+            "To authenticate: "
+            "1) Go to https://my.remarkable.com/device/browser/connect "
+            "2) Get a one-time code "
+            "3) Run: uv run python server.py --register YOUR_CODE "
+            "4) Add REMARKABLE_TOKEN to your MCP config."
+        )
+
+        return make_response(result, hint)

remarkable_mcp-0.1.3.dist-info/METADATA

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: remarkable-mcp
+Version: 0.1.3
+Summary: MCP server for accessing reMarkable tablet data
+Author: Sam Morrow
+License: MIT
+License-File: LICENSE
+Keywords: mcp,notes,remarkable,sync,tablet
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: pytesseract>=0.3.10
+Requires-Dist: rmapy>=0.3.0
+Requires-Dist: rmc>=0.3.0
+Requires-Dist: rmscene>=0.6.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# reMarkable MCP Server
+
+An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server for accessing your reMarkable tablet data through the reMarkable Cloud.
+
+<!-- mcp-name: io.github.sammorrowdrums/remarkable -->
+
+## Quick Install
+
+[![Install with UVX in VS Code](https://img.shields.io/badge/VS_Code-UVX-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=remarkable&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22token%22%2C%22description%22%3A%22reMarkable%20API%20token%20(run%20uvx%20remarkable-mcp%20--register%20CODE%20to%20get%20one)%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22remarkable-mcp%22%5D%2C%22env%22%3A%7B%22REMARKABLE_TOKEN%22%3A%22%24%7Binput%3Atoken%7D%22%7D%7D) [![Install with UVX in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-UVX-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=remarkable&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22token%22%2C%22description%22%3A%22reMarkable%20API%20token%20(run%20uvx%20remarkable-mcp%20--register%20CODE%20to%20get%20one)%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22remarkable-mcp%22%5D%2C%22env%22%3A%7B%22REMARKABLE_TOKEN%22%3A%22%24%7Binput%3Atoken%7D%22%7D%7D&quality=insiders)
+
+## What It Does
+
+- Read typed text directly from notebooks (v3+ software, no OCR needed)
+- Browse and search your document library
+- Access recent files with content previews
+- OCR for handwritten content via pytesseract
+- MCP resources and prompts for deeper integration
+
+## Installation
+
+### Using uvx (Recommended)
+
+```bash
+# Get your reMarkable token
+uvx remarkable-mcp --register YOUR_ONE_TIME_CODE
+```
+
+Click the **Quick Install** badges above, or configure manually.
+
+### From Source
+
+```bash
+git clone https://github.com/SamMorrowDrums/remarkable-mcp.git
+cd remarkable-mcp
+uv sync
+uv run python server.py --register YOUR_ONE_TIME_CODE
+```
+
+## Setup
+
+### 1. Get a One-Time Code
+
+Go to [my.remarkable.com/device/desktop/connect](https://my.remarkable.com/device/desktop/connect) and generate a code.
+
+### 2. Convert to Token
+
+```bash
+uvx remarkable-mcp --register YOUR_CODE
+```
+
+### 3. Configure MCP
+
+**VS Code** — Add to `.vscode/mcp.json`:
+
+```json
+{
+  "inputs": [
+    {
+      "type": "promptString",
+      "id": "remarkable-token",
+      "description": "reMarkable API Token",
+      "password": true
+    }
+  ],
+  "servers": {
+    "remarkable": {
+      "command": "uvx",
+      "args": ["remarkable-mcp"],
+      "env": {
+        "REMARKABLE_TOKEN": "${input:remarkable-token}"
+      }
+    }
+  }
+}
+```
+
+Your token is stored securely using VS Code's input system with `password: true`.
+
+**Claude Desktop** — Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "remarkable": {
+      "command": "uvx",
+      "args": ["remarkable-mcp"],
+      "env": {
+        "REMARKABLE_TOKEN": "your-token-from-step-2"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `remarkable_read` | Extract text from a document |
+| `remarkable_browse` | List files or search by name |
+| `remarkable_recent` | Get recently modified documents |
+| `remarkable_status` | Check connection status |
+
+All tools are read-only and return structured JSON with hints for next actions.
+
+## Resources
+
+Recent documents are automatically registered as MCP resources on startup (if authenticated). Each document becomes available at `remarkable://doc/{name}`.
+
+| URI | Description |
+|-----|-------------|
+| `remarkable://doc/{name}` | Content of a recent document |
+| `remarkable://folders` | Complete folder hierarchy |
+
+## Prompts
+
+`summarize_recent` · `find_notes` · `daily_review` · `export_document` · `organize_library` · `meeting_notes`
+
+## Usage
+
+```python
+remarkable_read("Meeting Notes - Nov 2025")
+remarkable_browse("/")
+remarkable_browse(query="meeting")
+remarkable_recent(limit=5, include_preview=True)
+```
+
+## Text Extraction
+
+**Typed text** from v3+ notebooks is extracted natively via `rmscene` — no OCR required.
+
+**Handwritten content** uses pytesseract for OCR. Make sure Tesseract is installed on your system:
+
+```bash
+# macOS
+brew install tesseract
+
+# Ubuntu/Debian
+sudo apt-get install tesseract-ocr
+
+# Arch
+sudo pacman -S tesseract
+```
+
+PDF highlights and annotations are also extracted.
+
+## Design
+
+Intent-based tools that map to what you actually want to do. Responses include hints for logical next steps. Errors explain what went wrong and how to fix it. Four tools cover most use cases.
+
+## Authentication
+
+Set `REMARKABLE_TOKEN` in your MCP config (recommended), or the server will fall back to `~/.rmapi`.
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest test_server.py -v
+uv run ruff check .
+uv run ruff format .
+```
+
+### Project Structure
+
+```
+remarkable-mcp/
+├── server.py           # Entry point
+├── remarkable_mcp/     # Main package
+│   ├── server.py       # FastMCP server
+│   ├── api.py          # Cloud API helpers
+│   ├── extract.py      # Text extraction
+│   ├── tools.py        # MCP tools
+│   ├── resources.py    # MCP resources
+│   └── prompts.py      # MCP prompts
+└── test_server.py      # Tests
+```
+
+## License
+
+MIT
+
+---
+
+Built with [rmapy](https://github.com/subutux/rmapy), [rmscene](https://github.com/ricklupton/rmscene), and inspiration from [Scrybble](https://github.com/Scrybbling-together/scrybble).

remarkable_mcp-0.1.3.dist-info/RECORD

@@ -0,0 +1,13 @@
+remarkable_mcp/__init__.py,sha256=UMORz2IRP8uSmd19rVdRC3-axmGV7r9orEtep4nCRVo,328
+remarkable_mcp/api.py,sha256=lHgi0oR7q9AaHd5r4x2ZO5pAv5Tg9elE-7KTg6o0QW4,4023
+remarkable_mcp/extract.py,sha256=ymOPy-7wwRufLqjUI68xqOL_0ha3PZhXHHqT-d-XtIQ,6132
+remarkable_mcp/prompts.py,sha256=RaVMbjHeWkHcZCgPbfMO-Dp6uAcU7eYyQ6eHODEhnpk,4572
+remarkable_mcp/resources.py,sha256=Vt9q_wLSfIkFDwz43HQ-tJpOBdW3y5XULihAttAmuXk,4557
+remarkable_mcp/responses.py,sha256=lWzR1S-uyumq1EE7MORTAij7nXL8OWr2Vnd0KcOws3o,687
+remarkable_mcp/server.py,sha256=bVrMGpOGY5rBEaBeQTc1C8FMH6Z0JGSpxpBo8f_pKZc,383
+remarkable_mcp/tools.py,sha256=UI342rftabE310GAPlwF4gs8aFC-J1buVuD7iiT0JEA,15440
+remarkable_mcp-0.1.3.dist-info/METADATA,sha256=36wkRzx_ASOGvBa3WYNLC3nRXY4s5cppY90VE4DkD-E,6598
+remarkable_mcp-0.1.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+remarkable_mcp-0.1.3.dist-info/entry_points.txt,sha256=u7Cq0gv3lSJ2gfmxevurtFQdFxzInISM4OWH9Kye13Q,47
+remarkable_mcp-0.1.3.dist-info/licenses/LICENSE,sha256=AFH_vQYJYLgWL0eKYRDSJwbpnvL12LTkSHBWbnKYEt4,1067
+remarkable_mcp-0.1.3.dist-info/RECORD,,

remarkable_mcp-0.1.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

remarkable_mcp-0.1.3.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+remarkable-mcp = server:main

remarkable_mcp-0.1.3.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sam Morrow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.