Python Apple MCP (模型上下文协议)

一个 Python 实现的服务端，用于处理与 macOS 应用程序（如通讯录、备忘录、邮件、信息、提醒事项、日历和地图）的交互，使用 FastMCP。

特性

• 通过 AppleScript 与 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

# 初始化 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

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

# 使用模块
async def main():
    # 查找联系人
    contact = await contacts.find_contact("John")
    
    # 创建一个备忘录
    await notes.create_note(
        title="会议记录",
        body="讨论要点...",
        folder_name="工作"
    )

# 运行异步代码
import asyncio
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_unread_mails() -> List[Email]: 获取未读邮件

Messages 模块

• send_message(to: str, content: str) -> bool: 发送 iMessage
• read_messages(phone_number: str) -> List[Message]: 读取消息
• schedule_message(to: str, content: str, scheduled_time: str) -> Dict: 安排消息

Reminders 模块

• create_reminder(name: str, list_name: str, notes: str, due_date: str) -> Dict: 创建一个提醒事项
• search_reminders(query: str) -> List[Dict]: 搜索提醒事项
• get_all_reminders() -> List[Dict]: 获取所有提醒事项

Calendar 模块

• create_event(title: str, start_date: str, end_date: str, location: str, notes: str) -> Dict: 创建一个事件
• search_events(query: str) -> List[Dict]: 搜索事件
• get_events() -> List[Dict]: 获取所有事件

Maps 模块

• search_locations(query: str) -> List[Location]: 搜索位置
• get_directions(from_address: str, to_address: str, transport_type: str) -> str: 获取路线
• save_location(name: str, address: str) -> Dict: 将位置保存到收藏夹

贡献

1. Fork 仓库
2. 创建一个特性分支
3. 提交你的更改
4. 推送到分支
5. 创建一个 Pull Request

许可证

该项目根据 MIT 许可证授权 - 有关详细信息，请参阅 LICENSE 文件。