AGENTS.md — Guide for AI Agents

This guide explains how to use the @hasna/contacts MCP server effectively as an AI coding agent.

Setup

# Install globally
bun install -g @hasna/contacts

# Register with Claude Code
claude mcp add --transport stdio --scope user contacts -- contacts-mcp

After installing, restart Claude Code and verify with /mcp.

Core Workflow

Finding contacts

Start with search — don't list everything:

search_contacts({ query: "John" })
search_contacts({ query: "acme corp" })
list_contacts({ tag: "client", limit: 20 })

Creating a contact

Minimum required: at least one of first_name, last_name, or company_id.

create_contact({
  first_name: "Jane",
  last_name: "Doe",
  email: "jane@example.com",
  phone: "+1-555-0100",
  notes: "Met at conference 2026"
})

Adding structure

Use tags for grouping, relationships for linking people:

create_tag({ name: "client", color: "#3b82f6" })
add_tag_to_contact({ contact_id: "...", tag_id: "..." })
add_relationship({ contact_a_id: "...", contact_b_id: "...", relationship_type: "colleague" })

Bulk operations

Import from CSV or vCard when adding many contacts:

import_contacts({ format: "csv", data: "first_name,last_name,email\nJane,Doe,jane@example.com" })
import_contacts({ format: "vcf", data: "BEGIN:VCARD\n..." })

Export for backup or sharing:

export_contacts({ format: "json" })
export_contacts({ format: "vcf", tag: "client" })

All MCP Tools

Database Location

By default: ~/.contacts/contacts.db

Override with env var: CONTACTS_DB_PATH=/path/to/contacts.db contacts-mcp

Tips for Agents

• Always search before creating — avoid duplicate contacts
• Use get_stats at session start to understand the current database state
• Use notes generously — add context about how/when you met someone
• Tag consistently — agree on a tag taxonomy early (e.g., client, lead, colleague, vip)
• Merge duplicates when found — merge_contacts preserves all data from both contacts
• Log activities for important interactions — log_activity keeps a timeline per contact