Apple Macos Native Applications

🚀 Python Apple MCP (模型上下文協議)

Python Apple MCP 是一個藉助 FastMCP 處理 macOS 應用（如聯繫人、筆記、郵件、信息、提醒事項、日曆和地圖）的 Python 服務器實現方案，能有效提升對 macOS 應用的操作效率與便捷性。

🚀 快速開始

Python Apple MCP 可助力你輕鬆與 macOS 原生應用進行交互。以下是快速上手的步驟：

1. 克隆倉庫：

git clone https://github.com/jxnl/python-apple-mcp.git
cd python-apple-mcp

2. 創建虛擬環境：

python -m venv venv
source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate

3. 安裝依賴項：

pip install -r requirements.txt

4. 安裝測試依賴（可選）：

pip install -r requirements-test.txt

✨ 主要特性

• 📱 使用 Apple 腳本與 macOS 原生應用交互，實現無縫對接。
• ⚙️ 異步操作以提升性能，讓程序運行更高效。
• 🛡️ 全面錯誤處理，保障程序穩定運行。
• 🧰 類型安全接口，使用 Pydantic 模型，增強代碼的健壯性。
• 🧪 豐富的測試覆蓋率，確保代碼質量。
• 🧩 模塊化設計，便於擴展，滿足不同需求。

📦 支持的應用程序

• Contacts（聯繫人）
• Notes（筆記）
• Mail（郵件）
• Messages（信息）
• Reminders（提醒事項）
• Calendar（日曆）
• Maps（地圖）

💻 使用示例

基礎用法

from apple_mcp import FastMCP, Context
from typing import List
from utils.contacts import Contact

# 初始化 FastMCP 服務器
mcp = FastMCP("Apple MCP")

# 使用工具
@mcp.tool()
def find_contact(name: str) -> List[Contact]:
    """按名稱搜索聯繫人"""
    # 實現代碼在此處
    pass

# 運行服務器
if __name__ == "__main__":
    mcp.run()

高級用法

from utils.contacts import ContactsModule
from utils.notes import NotesModule
import asyncio

# 初始化模塊
contacts = ContactsModule()
notes = NotesModule()

# 使用模塊
async def main():
    # 查找聯繫人
    contact = await contacts.find_contact("John")
    
    # 創建筆記
    await notes.create_note(
        title="會議記錄",
        body="討論要點...",
        folder_name="工作"
    )

# 運行異步代碼
asyncio.run(main())

📚 測試

運行測試套件

pytest

使用覆蓋運行測試

pytest --cov=utils tests/

運行特定測試文件

pytest tests/test_contacts.py

📄 API 文檔

Contacts 模塊（聯繫人）

• find_contact(name: str) -> List[Contact]：按名稱搜索聯繫人。
• get_all_contacts() -> List[Contact]：獲取所有聯繫人。
• create_contact(name: str, phones: List[str]) -> Contact：創建新聯繫人。

Notes 模塊（筆記）

• find_note(query: str) -> List[Note]：搜索筆記。
• create_note(title: str, body: str, folder_name: str) -> Note：創建新筆記。
• get_all_notes() -> List[Note]：獲取所有筆記。

Mail 模塊（郵件）

• send_email(to: str, subject: str, body: str) -> str：發送電子郵件。
• search_emails(query: str) -> List[Email]：搜索郵件。
• get_all_emails() -> List[Email]：獲取所有郵件。

Messages 模塊（信息）

• send_message(to: str, text: str) -> Message：發送消息。
• search_messages(query: str) -> List[Message]：搜索消息。
• get_all_messages() -> List[Message]：獲取所有消息。

Reminders 模塊（提醒事項）

• create_reminder(title: str, due_date: datetime) -> Reminder：創建提醒。
• search_reminders(query: str) -> List[Reminder]：搜索提醒。
• get_all_reminders() -> List[Reminder]：獲取所有提醒。

Calendar 模塊（日曆）

• create_event(title: str, start_date: datetime, end_date: datetime) -> Event：創建事件。
• search_events(query: str) -> List[Event]：搜索事件。
• get_all_events() -> List[Event]：獲取所有事件。

Maps 模塊（地圖）

• get_directions(start: Location, end: Location) -> Directions：獲取路線。
• search_places(name: str) -> List[Place]：搜索地點。
• get_map_image(bounds: Bounds) -> bytes：獲取地圖圖像。

🤝 貢獻指南

歡迎貢獻！請參考項目倉庫中的 CONTRIBUTING.md 文件。

📄 許可證

此項目受 MIT License 保護。