MCP (Protocolo de contexto de modelo) de Python Apple

Una implementación de Python del servidor que maneja las interacciones con aplicaciones macOS como Contactos, Notas, Correo, Mensajes, Recordatorios, Calendario y Mapas usando FastMCP.

Características

• Interactúe con aplicaciones nativas de macOS a través de AppleScript

• Operaciones asincrónicas para un mejor rendimiento

• Manejo integral de errores

• Interfaces de tipos seguros que utilizan modelos de Pydantic

• Amplia cobertura de pruebas

• Diseño modular para una fácil ampliación

Related MCP server: macnotes-mcp

Aplicaciones compatibles

• Contactos

• Notas

• Correo

• Mensajes

• Recordatorios

• Calendario

• Mapas

Instalación

1. Clonar el repositorio:

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

2. Crear un entorno virtual:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Instalar dependencias:

pip install -r requirements.txt

4. Instalar dependencias de prueba (opcional):

pip install -r requirements-test.txt

Uso

Ejemplo básico

from apple_mcp import FastMCP, Context

# Initialize FastMCP server
mcp = FastMCP("Apple MCP")

# Use the tools
@mcp.tool()
def find_contact(name: str) -> List[Contact]:
    """Search for contacts by name"""
    # Implementation here
    pass

# Run the server
if __name__ == "__main__":
    mcp.run()

Uso de módulos individuales

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

# Initialize modules
contacts = ContactsModule()
notes = NotesModule()

# Use the modules
async def main():
    # Find a contact
    contact = await contacts.find_contact("John")
    
    # Create a note
    await notes.create_note(
        title="Meeting Notes",
        body="Discussion points...",
        folder_name="Work"
    )

# Run the async code
import asyncio
asyncio.run(main())

Pruebas

Ejecute el conjunto de pruebas:

pytest

Ejecutar pruebas con cobertura:

pytest --cov=utils tests/

Ejecutar archivo de prueba específico:

pytest tests/test_contacts.py

Documentación de la API

Módulo de contactos

• find_contact(name: str) -> List[Contact] : Busca contactos por nombre

• get_all_contacts() -> List[Contact] : Obtener todos los contactos

• create_contact(name: str, phones: List[str]) -> Contact : Crea un nuevo contacto

Módulo de notas

• find_note(query: str) -> List[Note] : Buscar notas

• create_note(title: str, body: str, folder_name: str) -> Note : Crea una nueva nota

• get_all_notes() -> List[Note] : Obtener todas las notas

Módulo de correo

• send_email(to: str, subject: str, body: str) -> str : Enviar un correo electrónico

• search_emails(query: str) -> List[Email] : Buscar correos electrónicos

• get_unread_mails() -> List[Email] : Obtener correos electrónicos no leídos

Módulo de mensajes

• send_message(to: str, content: str) -> bool : Enviar un iMessage

• read_messages(phone_number: str) -> List[Message] : Leer mensajes

• schedule_message(to: str, content: str, scheduled_time: str) -> Dict : Programar un mensaje

Módulo de recordatorios

• create_reminder(name: str, list_name: str, notes: str, due_date: str) -> Dict : Crea un recordatorio

• search_reminders(query: str) -> List[Dict] : Recordatorios de búsqueda

• get_all_reminders() -> List[Dict] : Obtener todos los recordatorios

Módulo de calendario

• create_event(title: str, start_date: str, end_date: str, location: str, notes: str) -> Dict : Crea un evento

• search_events(query: str) -> List[Dict] : Buscar eventos

• get_events() -> List[Dict] : Obtener todos los eventos

Módulo de mapas

• search_locations(query: str) -> List[Location] : Buscar ubicaciones

• get_directions(from_address: str, to_address: str, transport_type: str) -> str : Obtener direcciones

• save_location(name: str, address: str) -> Dict : Guardar una ubicación en favoritos

Contribuyendo

1. Bifurcar el repositorio

2. Crear una rama de características

3. Confirme sus cambios

4. Empujar hacia la rama

5. Crear una solicitud de extracción

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.