claw-ea CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

claw-ea is a Python MCP (Model Context Protocol) server that helps medical professionals automatically archive messages from social media channels (Feishu, WeCom, Telegram, etc.) into Obsidian notes, Apple Calendar, and Apple Reminders. It runs as an external MCP server connected to OpenClaw via MCPorter, but is designed to work with any MCP client (Claude Desktop, Cursor, etc.).

Architecture

Agent vs Tool Boundary (Critical Design Principle)

The MCP server only provides side-effect tools — tools that write files, call system APIs, or read system state. All "understanding" tasks (message classification, image comprehension, approval dialog formatting) are handled by the calling agent's LLM, NOT by our tools.

MCP Tools (11 total)

Core workflow (called by agent after it classifies the message):

• ocr_image — Local OCR only (macOS Vision framework). Agent's multimodal LLM handles image understanding directly; this tool is the fallback when the LLM lacks vision.
• save_attachment — Saves file to date-organized attachment directory. Two modes: file_path (local path, preferred — uses shutil.copy2) or file_content (base64). Dedup: skips if identical file exists.
• convert_to_markdown — Converts files (PDF, docx, pptx, xlsx, CSV, HTML, images, plaintext) to Markdown via configurable converter chains (docling → markitdown → mineru → lmstudio → vision_ocr → passthrough). Returns temp file path for create_obsidian_note's raw_body_path. Fallback: if primary converter fails or output is garbled, automatically tries the next in chain. Plaintext files (.txt, .md, .rst, .log) use a passthrough converter. File-type routing: images/PDF are NOT routed here by default — the agent reads them directly with its multimodal vision, summarizes, and keeps the original as an embedded attachment (![[file]]); this tool is only a fallback when the agent lacks vision. Office docs docx/pptx/xlsx go through MinerU (offline, local, default; docling fallback); csv/html route to markitdown/docling instead. Other types: agent picks the extraction, but the original is always archived via save_attachment.
• create_obsidian_note — Creates Markdown note with YAML frontmatter in Obsidian vault. Supports raw_body_path to embed converted Markdown content. Dedup via content hash (first 8 chars in filename); returns existing path if duplicate.
• create_calendar_event — Creates event in Apple Calendar via pyobjc EventKit. Returns event ID.
• delete_calendar_event — Deletes an event from Apple Calendar by event ID. Agent should confirm with user first.
• create_reminder — Creates reminder in Apple Reminders via pyobjc EventKit. Returns reminder ID.
• delete_reminder — Deletes a reminder from Apple Reminders by reminder ID. Agent should confirm with user first.