# Contalist

> Contalist is a contact management application for professionals and small businesses. It helps users store contacts, organize them with tags and groups, track interactions, and work with contacts inside other tools (Trello, Asana).

Contalist provides a web app, a REST API (`/api/v1`), and an MCP (Model Context Protocol) server that lets AI agents manage contacts on a user's behalf.

## Product

- Contacts with standard fields plus custom fields and custom forms
- Tags and groups for organizing contacts
- Notes and an activity timeline (emails, calls, form submissions, tag/group changes)
- Relationships between contacts (spouse, coworker, supervisor, custom types)
- Organizations (companies) with linked contacts
- Message templates with mail merge
- Web forms, tasks, file storage, Google Contacts sync
- Trello Power-Up and Asana app for working with contacts in those tools

## AI Integration (MCP)

- MCP endpoint: `POST /mcp` (see `/mcp` in a browser for setup instructions)
- Authentication: OAuth 2.1 with PKCE (preferred) or a static API key as a Bearer token
  - Discovery: `GET /.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`
  - Authorization flow: `/oauth/authorize`, `/oauth/token`, `/oauth/register`, `/oauth/revoke`
- MCP tools:
  - `contacts` — list/search/get/create/update/delete/upsert/find_duplicates/bulk_upsert/history (supports custom fields)
  - `tags` — list/add/remove tags, list contacts by tag
  - `groups` — list/create/add/remove groups, list group members
  - `notes` — list/add/update/delete contact notes
  - `relations` — list/add/remove relationships between contacts
  - `organizations` — list/get/create/update/delete organizations, list org contacts
  - `templates` — list message templates, render one for a contact (merge preview)
- MCP prompts (skills): onboard_contact, find_contact, update_contact, contact_cleanup, contact_summary

## API

- REST API v1 under `/api/v1` (session or API-token auth): contacts, tags, groups, organizations, relations, interactions, connected apps