Apple Macos Native Applications

🚀 Python Apple MCP (モデルコンテキストプロトコル)

このプロジェクトは、FastMCPを使用して、macOSのアプリケーション（Contacts、Notes、Mail、Messages、Reminders、Calendar、Mapsなど）を処理するPythonサーバーの実装です。

🚀 クイックスタート

このセクションでは、Python Apple MCPを使用するための基本的な手順を説明します。

✨ 主な機能

• Appleスクリプトを使用してmacOSのネイティブアプリとやり取りします。
• 非同期操作を行い、パフォーマンスを向上させます。
• 包括的なエラー処理を行います。
• Pydanticモデルを使用した型安全なインターフェースを提供します。
• 豊富なテストカバレッジを持ちます。
• 拡張しやすいモジュール化設計になっています。

📦 インストール

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

💻 使用例

基本的な使用法

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())

📚 ドキュメント

サポートされているアプリケーション

• Contacts（連絡先）
• Notes（メモ）
• Mail（メール）
• Messages（メッセージ）
• Reminders（リマインダー）
• Calendar（カレンダー）
• Maps（地図）

テスト

テストスイートを実行するには、以下のコマンドを実行します：

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：地図画像を取得します。

📄 ライセンス

このプロジェクトは MIT License の下で保護されています。

🔗 貢献について

貢献を歓迎します！詳細については、プロジェクトリポジトリの CONTRIBUTING.md ファイルを参照してください。