Affinity MCP Workflows

1. ✅ Read xaffinity://data-model using read-xaffinity-resource
2. ✅ Run discover-commands for your specific task
3. ✅ State what you learned from each step before continuing

Example:

"I read the data-model resource and learned that list entries have custom fields
accessed via fields.<Name>. I ran discover-commands for 'interaction' and found
that interaction ls supports --type all to fetch all types in one call, and
--days to limit the time range. Now I'll proceed with..."

IMPORTANT: Write Operations Only After Explicit User Request

Only use tools or prompts that modify CRM data when the user explicitly asks to do so.

Write operations include:

• Tools: execute-write-command
• Prompts: log-interaction-and-update-workflow, change-status, log-call, log-message

Read-only operations (search, lookup, briefings) can be used proactively to help the user. But never create, update, or delete CRM records unless the user specifically requests it.

Full Scan Protection

The MCP gateway enforces pagination limits to prevent unbounded data scans:

Affected commands: list export, list ls, person ls, company ls, opportunity ls, note ls, reminder ls, interaction ls, field history

To fetch more than 10000 records: Use cursor pagination with --cursor flag.

Available Tools

CLI Gateway (Primary Interface)

The CLI Gateway provides full access to the xaffinity CLI:

Usage pattern:

1. Discover the right command: discover-commands(query: "create person", category: "write")
2. Execute it: execute-write-command(command: "person create", argv: ["--first-name", "John", "--last-name", "Doe"])

Utility Tools

Destructive Commands

Commands that delete data require double confirmation:

1. Look up the entity first using execute-read-command to show what will be deleted
2. Ask the user in your response by showing them the entity details and requesting confirmation
3. Wait for user's next message - do NOT proceed until they explicitly confirm
4. Only after user confirms should you execute with confirm: true

Example flow:

User: "Delete person 123"
You: execute-read-command(command: "person get", argv: ["123"])
You: "This will permanently delete John Smith (ID: 123, email: [email protected]).
      Type 'yes' to confirm deletion."
[Stop here and wait for user's response]

User: "yes"
You: execute-write-command(command: "person delete", argv: ["123"], confirm: true)

Query vs CLI Commands: When to Use What

Use query tool for:

• Any operation needing relationships (persons at a company, companies for a person)
• Any operation needing computed data (interaction dates, unreplied messages)
• Pipeline analysis with aggregations or groupBy
• Complex filtering with AND/OR conditions
• List entry operations that need associated entities

Use individual CLI commands for:

• Simple lookups: person get 123, company get 456
• Quick searches: person ls --query "John", company ls --query "Acme"
• Metadata: list ls, field ls --list-id <id>
• Write operations: All creates, updates, deletes

Query Examples (Preferred for Complex Operations)

⚠️ STOP: Did you complete the pre-flight checklist? The syntax below may be outdated. Run discover-commands first to verify current syntax and available flags.

⚠️ For queries with expand or include, ALWAYS use dryRun: true first to see estimated API calls. These cause N+1 API calls (one per record) and can be slow or timeout.

// STEP 1: Preview any expand/include query with dryRun first
{"query": {"from": "listEntries", "where": {"path": "listName", "op": "eq", "value": "Dealflow"}, "expand": ["interactionDates"], "limit": 100}, "dryRun": true}

// STEP 2: If API calls look reasonable (<200), run without dryRun
{"from": "listEntries", "where": {"path": "listName", "op": "eq", "value": "Dealflow"}, "expand": ["interactionDates"], "limit": 100}

// Pipeline with field values and unreplied email detection
{"from": "listEntries", "where": {"path": "listName", "op": "eq", "value": "Dealflow"}, "select": ["entityName", "fields.Status", "fields.Owner"], "expand": ["unreplied"]}

// Persons with their companies and interaction history summary
{"from": "persons", "where": {"path": "email", "op": "contains", "value": "@acme.com"}, "include": ["companies"], "expand": ["interactionDates"]}

// Pipeline summary by status (aggregation) - no expand, no dryRun needed
{"from": "listEntries", "where": {"path": "listName", "op": "eq", "value": "Dealflow"}, "groupBy": "fields.Status", "aggregate": {"count": {"count": true}}}

// List entries with associated persons and interactions (parameterized include)
{"from": "listEntries", "where": {"path": "listName", "op": "eq", "value": "Dealflow"}, "include": [{"interactions": {"limit": 50, "days": 180}}, "persons"]}

Common CLI Commands

⚠️ Reminder: Run discover-commands first. The commands below are examples - actual syntax and flags may differ.

Use discover-commands to find commands, then execute-read-command or execute-write-command to run them.

Search & Lookup (Simple Operations)

Note: For list exports needing relationships or computed data, use query instead of list export.

Entity Details

Write Operations

MCP Prompts (Guided Workflows)

These prompts provide guided multi-step workflows. Suggest them when appropriate.

Note: Prompts marked with (write) modify CRM data - only use when user explicitly requests.

How to Invoke Prompts

Prompts are invoked with arguments. Example:

• prepare-briefing(entityName: "John Smith", meetingType: "demo")
• warm-intro(targetName: "Jane Doe", context: "partnership discussion")
• log-interaction-and-update-workflow(personName: "Alice", interactionType: "call", summary: "Discussed pricing")

Resources

Access dynamic data via xaffinity:// URIs using read-xaffinity-resource:

Common Workflow Patterns

Combine the tools above to handle multi-step tasks:

• Before a meeting: get-entity-dossier for full context, or prepare-briefing prompt
• After a call: execute-write-command to log interaction, query to find list entry, entry field to update status — or log-interaction-and-update-workflow prompt
• Finding warm intros: person ls → relationship-strength ls, or warm-intro prompt
• Pipeline review: query with aggregation + expand, or pipeline-review prompt

⚠️ Complete the pre-flight checklist before using any pattern.

Tips

• Entity types: person, company, opportunity
• Interaction types: call, meeting, email, chat-message (or chat)
• Dossier is comprehensive: get-entity-dossier returns relationship strength, interactions, notes, and list memberships in one call
• Use names directly: Most commands accept names instead of IDs (e.g., person ls --query "John")
• Finding entities in a list: Use query with filters:

  {"from": "listEntries", "where": {"and": [{"path": "listName", "op": "eq", "value": "Dealflow"}, {"path": "entityName", "op": "contains", "value": "Acme"}]}}
  

• Output formats: The format parameter controls result format:
  • toon (default for query): 40% fewer tokens, best for bulk queries
  • markdown: Best for LLM comprehension when analyzing data
  • json: Full structure with envelope - supports cursor pagination for large results
  • csv: For spreadsheet export
  • All formats support cursor pagination when results are truncated (use nextCursor to resume)

Troubleshooting

If tools aren't working or returning unexpected results:

Enable Debug Mode

# Enable (persistent, works with any MCP client)
mkdir -p ~/.config/xaffinity-mcp && touch ~/.config/xaffinity-mcp/debug

# Restart the MCP client (Claude Desktop: Cmd+Q, reopen)

# Disable when done
rm ~/.config/xaffinity-mcp/debug

View Logs

Claude Desktop: tail -f ~/Library/Logs/Claude/mcp-server-*.log

Debug logs show component prefixes like [xaffinity:tool:1.2.3] to identify which component produced each message.

Common Issues