金大哥 - Apple macOS Native Applications MCP 详情

article

README

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

Python Apple MCP 是一个使用 FastMCP 处理 macOS 应用（如 Contacts、Notes、Mail、Messages、Reminders、Calendar 和 Maps）的 Python 服务器实现，可与 macOS 原生应用高效交互。

🚀 快速开始

Python Apple MCP 借助 Apple 脚本与 macOS 原生应用交互，为开发者提供了便捷的方式来操作这些应用。下面将详细介绍如何快速上手。

✨ 主要特性

原生交互：使用 Apple 脚本与 macOS 原生应用交互，无缝对接系统功能。
性能优化：采用异步操作以提升性能，确保高效处理任务。
错误处理：具备全面错误处理机制，保障程序稳定运行。
类型安全：提供类型安全接口，使用 Pydantic 模型，增强代码可靠性。
测试完备：拥有丰富的测试覆盖率，保证代码质量。
易于扩展：模块化设计，便于开发者根据需求进行扩展。

📦 安装指南

按照以下步骤完成项目的安装：

克隆仓库：

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

创建虚拟环境：

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

安装依赖项：

pip install -r requirements.txt

安装测试依赖（可选）：

pip install -r requirements-test.txt

💻 使用示例

基础用法

from apple_mcp import FastMCP, Context
from typing import List
from models.contact 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 保护。

Apple macOS Native Applications