Contacts Manager Plugin

A comprehensive contact management plugin for OpenCode with Apple Contacts integration. Supports contact CRUD operations, search, export, import, group management, and duplicate detection.

Features

• Contact Management: Create, read, update, and delete contacts
• Search & Filter: Search contacts by name, email, phone, or company
• Export Options: Export to vCard, CSV, or JSON formats
• Import Support: Import contacts from vCard, CSV, or JSON
• Group Management: Create and manage contact groups
• Duplicate Detection: Find and manage duplicate contacts
• Apple Contacts Integration: Native integration with macOS Contacts app

Platform Support

• macOS: Full support with Apple Contacts integration
• Other Platforms: Limited functionality (returns not_supported status)

Quick Start

1. Test Connection

cd pets/contacts
opencode run "test contacts connection"

2. List Contacts

opencode run "list first 10 contacts"

3. Search Contacts

opencode run "search for contacts named John"

Available Tools

Core Operations

• contacts-test-connection - Test plugin connection and platform compatibility
• contacts-list - List all contacts with optional filtering
• contacts-get - Get detailed information about a specific contact
• contacts-search - Search for contacts by name, email, phone, or company
• contacts-create - Create a new contact
• contacts-update - Update an existing contact
• contacts-delete - Delete a contact

Group Management

• contacts-groups-list - List all contact groups
• contacts-groups-create - Create a new contact group

Import/Export

• contacts-export - Export contacts in vCard, CSV, or JSON formats
• contacts-import - Import contacts from vCard, CSV, or JSON data

Utilities

• contacts-find-duplicates - Find potential duplicate contacts

Usage Examples

Basic Contact Operations

# Test connection
opencode run "test contacts connection"

# List contacts with pagination
opencode run "list 20 contacts with offset 10"

# Search contacts
opencode run "search for contacts with email gmail.com"

# Get specific contact
opencode run "get contact with ID 123"

Creating and Updating Contacts

# Create a new contact
opencode run "create contact John Doe with email [email protected] and phone +1234567890"

# Update a contact
opencode run "update contact 123 set company to Acme Corp and job title to Developer"

Export and Import

# Export all contacts to vCard
opencode run "export contacts to vCard format"

# Export work contacts to CSV
opencode run "export contacts to CSV format from group Work"

# Import contacts from vCard
opencode run "import contacts from vCard data"

Group Management

# List all groups
opencode run "list all contact groups"

# Create a new group
opencode run "create contact group Clients with description 'Important clients'"

Duplicate Management

# Find duplicate contacts
opencode run "find duplicate contacts"

Configuration

Environment Variables

Optional environment variables can be set in .env:

# Enable contact caching for better performance
CONTACTS_CACHE_ENABLED=true

# Request timeout in milliseconds
CONTACTS_TIMEOUT=30000

# Include contact photos in exports
CONTACTS_INCLUDE_PHOTOS=false

Permissions (macOS)

On macOS, you may need to grant Contacts app permissions:

1. Open System Preferences > Security & Privacy > Privacy
2. Select "Contacts" from the left sidebar
3. Add your terminal or code editor to the allowed applications

Data Formats

Contact Structure

interface Contact {
  id: string
  firstName?: string
  lastName?: string
  middleName?: string
  company?: string
  jobTitle?: string
  phones: ContactPhone[]
  emails: ContactEmail[]
  addresses: ContactAddress[]
  birthday?: string
  notes?: string
  groups: string[]
  // ... other fields
}

Export Formats

vCard (.vcf): Standard vCard format compatible with most contact applications CSV: Comma-separated values with contact fields as columns JSON: Structured JSON format for programmatic use

Error Handling

All operations return structured JSON responses:

{
  "success": true,
  "data": { ... },
  "message": "Operation completed successfully"
}

{
  "success": false,
  "error": "Error message",
  "details": { ... }
}

Development

Building

cd pets/contacts
pets build

Testing

# Test connection
npm run test:connection

# Test listing
npm run test:list

# Test search
npm run test:search

Limitations

• Apple Contacts integration only works on macOS
• Contact photos require additional permissions
• Large contact lists may need pagination
• Import functionality requires properly formatted data

Troubleshooting

Permission Issues

If you get permission errors on macOS:

1. Check System Preferences > Security & Privacy > Privacy > Contacts
2. Ensure your terminal/editor has Contacts access
3. Restart your terminal/editor after granting permissions

Connection Issues

If the connection test fails:

1. Verify you're running on macOS
2. Check that the Contacts app is accessible
3. Ensure no other apps are locking the Contacts database

Performance Issues

For large contact databases:

1. Use pagination with limit and offset parameters
2. Enable caching with CONTACTS_CACHE_ENABLED=true
3. Use specific search queries instead of listing all contacts

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

This plugin is part of the OpenPets ecosystem and follows the same license terms.