{"_id":"@alludium/affinity-mcp-server","_rev":"8-76b5987b01b2cd3a2095adddc98a3b47","name":"@alludium/affinity-mcp-server","dist-tags":{"latest":"1.0.4"},"versions":{"1.0.0":{"name":"@alludium/affinity-mcp-server","version":"1.0.0","keywords":["mcp","affinity","crm","model-context-protocol"],"author":{"name":"Alludium"},"license":"MIT","_id":"@alludium/affinity-mcp-server@1.0.0","maintainers":[{"name":"donal_alludium","email":"donal@alludium.ai"}],"homepage":"https://github.com/alludium/affinity-mcp-server#readme","bugs":{"url":"https://github.com/alludium/affinity-mcp-server/issues"},"bin":{"affinity-mcp":"dist/index.js"},"dist":{"shasum":"ee21e978c18b434606eda0a897027203ba241cb1","tarball":"https://registry.npmjs.org/@alludium/affinity-mcp-server/-/affinity-mcp-server-1.0.0.tgz","fileCount":71,"integrity":"sha512-vEYEzM8Y0p9Bqyx+KGyjfUKEuPAG4F/NfnLMzrcJkXwsLNpZlYWPZjhNX5ZXQo6/fvEkWxqkkUFVgTUDnNAb+g==","signatures":[{"sig":"MEYCIQDrLWDKVhct/Xqs2zQKO+Hdem+KoTwlkIxbBwZrbT4CYAIhAOtI/raeCSGB4N1vMqVM4+H2xU7WwVHUTy081pCEhfdM","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":370882},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"3c0dfc78aef20887ad4d5891670fb2fe56c16ade","scripts":{"dev":"tsx src/index.ts","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit"},"_npmUser":{"name":"donal_alludium","email":"donal@alludium.ai"},"repository":{"url":"git+https://github.com/alludium/affinity-mcp-server.git","type":"git"},"_npmVersion":"10.9.2","description":"MCP server for Affinity CRM API","directories":{},"_nodeVersion":"22.17.1","dependencies":{"zod":"^3.23.8","dotenv":"^17.2.3","@modelcontextprotocol/sdk":"~1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","typescript":"^5.7.2","@types/node":"^22.10.1"},"_npmOperationalInternal":{"tmp":"tmp/affinity-mcp-server_1.0.0_1764931893749_0.30818617749595223","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@alludium/affinity-mcp-server","version":"1.0.1","keywords":["mcp","affinity","crm","model-context-protocol"],"author":{"name":"Alludium"},"license":"MIT","_id":"@alludium/affinity-mcp-server@1.0.1","maintainers":[{"name":"donal_alludium","email":"donal@alludium.ai"}],"homepage":"https://github.com/alludium/affinity-mcp-server#readme","bugs":{"url":"https://github.com/alludium/affinity-mcp-server/issues"},"bin":{"affinity-mcp":"dist/index.js"},"dist":{"shasum":"a9a4a946dcd1e3ee26627e36c93b20e8deae669a","tarball":"https://registry.npmjs.org/@alludium/affinity-mcp-server/-/affinity-mcp-server-1.0.1.tgz","fileCount":71,"integrity":"sha512-YPoTMAGo2X10DDMatACKJ4vtldPSbzuaLmljA0s8JuNj889nzEebCnhnmpxryY0JNzCdOpHC82vkVCt+LVqcmw==","signatures":[{"sig":"MEYCIQDK3bgzaWvKlt8snpN66p73WQcJMfo4plqHHIq6ssE2rwIhAOpl8vYH1XpgmDgwnF6+JlnuitUMctsvZPB8zYAec3yo","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":378893},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"533e330e25a45c658886c3112cce09839e21f439","scripts":{"dev":"tsx src/index.ts","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit"},"_npmUser":{"name":"donal_alludium","email":"donal@alludium.ai"},"repository":{"url":"git+https://github.com/alludium/affinity-mcp-server.git","type":"git"},"_npmVersion":"10.9.2","description":"MCP server for Affinity CRM API","directories":{},"_nodeVersion":"22.17.1","dependencies":{"zod":"^3.23.8","dotenv":"^17.2.3","@modelcontextprotocol/sdk":"~1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","typescript":"^5.7.2","@types/node":"^22.10.1"},"_npmOperationalInternal":{"tmp":"tmp/affinity-mcp-server_1.0.1_1764932274327_0.6559440223305999","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@alludium/affinity-mcp-server","version":"1.0.2","keywords":["mcp","affinity","crm","model-context-protocol"],"author":{"name":"Alludium"},"license":"MIT","_id":"@alludium/affinity-mcp-server@1.0.2","maintainers":[{"name":"donal_alludium","email":"donal@alludium.ai"}],"homepage":"https://github.com/alludium/affinity-mcp-server#readme","bugs":{"url":"https://github.com/alludium/affinity-mcp-server/issues"},"bin":{"affinity-mcp":"dist/index.js"},"dist":{"shasum":"f87be45d976ec97a62cf6f8f747fab49e2671cd3","tarball":"https://registry.npmjs.org/@alludium/affinity-mcp-server/-/affinity-mcp-server-1.0.2.tgz","fileCount":71,"integrity":"sha512-wJWH85zJlnmAQk9UnweQ5t7eL1db7ELUXBqBHBg+jeF5vQMwWUfFpb8mZT281qsxx7e5ll0RfmzpkJrOR38f1g==","signatures":[{"sig":"MEYCIQDFsrLsfFa4V6CJzO0EDbI0S3eObGnXOgUtu6PsB8CIqAIhAJgpbvlb5YcOcbkGtYB+XTkCYk0dEJPpo+7yOInONi77","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":379101},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"92a3813cf31b7c0366f820c8bd51ec70a8356676","scripts":{"dev":"tsx src/index.ts","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit"},"_npmUser":{"name":"donal_alludium","email":"donal@alludium.ai"},"repository":{"url":"git+https://github.com/alludium/affinity-mcp-server.git","type":"git"},"_npmVersion":"10.9.2","description":"MCP server for Affinity CRM API","directories":{},"_nodeVersion":"22.17.1","dependencies":{"zod":"^3.23.8","dotenv":"^17.2.3","@modelcontextprotocol/sdk":"~1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","typescript":"^5.7.2","@types/node":"^22.10.1"},"_npmOperationalInternal":{"tmp":"tmp/affinity-mcp-server_1.0.2_1764933756449_0.3388368139859461","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@alludium/affinity-mcp-server","version":"1.0.3","keywords":["mcp","affinity","crm","model-context-protocol"],"author":{"name":"Alludium"},"license":"MIT","_id":"@alludium/affinity-mcp-server@1.0.3","maintainers":[{"name":"donal_alludium","email":"donal@alludium.ai"},{"name":"markalludium","email":"mark@alludium.ai"}],"homepage":"https://github.com/alludium/affinity-mcp-server#readme","bugs":{"url":"https://github.com/alludium/affinity-mcp-server/issues"},"bin":{"affinity-mcp":"dist/index.js"},"dist":{"shasum":"3f1fe45c78ca1a6ae878badcabcb1081bd29330f","tarball":"https://registry.npmjs.org/@alludium/affinity-mcp-server/-/affinity-mcp-server-1.0.3.tgz","fileCount":83,"integrity":"sha512-pMc/P1x/FkIOuQYtYCmjWEgwAIp9jsRAhZZxHs9/H6L7ZsaZIzBUHIYRDCvgBpvgYr89zK6MNwPJBBvvXnIMfg==","signatures":[{"sig":"MEYCIQC+SVa5YuFVKJb0/5G62wETGvhInEvexDVFNJSDAMMkFwIhALhdnylh7L/wpSa+ORLrmua1bJZZi1Alv9LvfTaTMk7w","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":491522},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"705bd22dc0f8ce23a043b49dd8310553462e325a","scripts":{"dev":"tsx src/index.ts","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit"},"_npmUser":{"name":"donal_alludium","email":"donal@alludium.ai"},"repository":{"url":"git+https://github.com/alludium/affinity-mcp-server.git","type":"git"},"_npmVersion":"10.9.2","description":"MCP server for Affinity CRM API","directories":{},"_nodeVersion":"22.17.1","dependencies":{"zod":"^3.23.8","dotenv":"^17.2.3","@modelcontextprotocol/sdk":"~1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","typescript":"^5.7.2","@types/node":"^22.10.1"},"_npmOperationalInternal":{"tmp":"tmp/affinity-mcp-server_1.0.3_1765209780869_0.6936118399799609","host":"s3://npm-registry-packages-npm-production"}},"1.0.4":{"name":"@alludium/affinity-mcp-server","version":"1.0.4","description":"MCP server for Affinity CRM API","type":"module","main":"dist/index.js","bin":{"affinity-mcp":"dist/index.js"},"repository":{"type":"git","url":"git+https://github.com/alludium/affinity-mcp-server.git"},"scripts":{"build":"tsc","start":"node dist/index.js","dev":"tsx src/index.ts","typecheck":"tsc --noEmit","test":"npm run build && node --test tests/*.test.mjs"},"keywords":["mcp","affinity","crm","model-context-protocol"],"author":{"name":"Alludium"},"license":"MIT","dependencies":{"@modelcontextprotocol/sdk":"~1.0.0","dotenv":"^17.2.3","zod":"^3.23.8"},"devDependencies":{"@types/node":"^22.10.1","tsx":"^4.19.2","typescript":"^5.7.2"},"engines":{"node":">=18.0.0"},"_id":"@alludium/affinity-mcp-server@1.0.4","gitHead":"00ac7a369183abac82ee3830db5059cc0a1a8e69","types":"./dist/index.d.ts","bugs":{"url":"https://github.com/alludium/affinity-mcp-server/issues"},"homepage":"https://github.com/alludium/affinity-mcp-server#readme","_nodeVersion":"22.16.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-aKnkv4WRzY+7xuQrCAwM2RYFEJJUjy66BMqZkVoZcRIoofb5rn+pSAks4n3tRshFmEdmHGyZHCZdb24AUTSKvw==","shasum":"8870ca8b46908f73ef87aee97a29ce3b3ca4190e","tarball":"https://registry.npmjs.org/@alludium/affinity-mcp-server/-/affinity-mcp-server-1.0.4.tgz","fileCount":83,"unpackedSize":499476,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAV6yi+T6J09KIqWOsPtgAfvQaA9paoMcEP/D+uFXyodAiAQpGnvPJtNkf2ffIAFSIlPiPSq/ZTXsdQeyrQN3TEqeQ=="}]},"_npmUser":{"name":"john-alludium","email":"john@alludium.ai"},"directories":{},"maintainers":[{"name":"donal_alludium","email":"donal@alludium.ai"},{"name":"markalludium","email":"mark@alludium.ai"},{"name":"john-alludium","email":"john@alludium.ai"},{"name":"jubernunes","email":"juber@alludium.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/affinity-mcp-server_1.0.4_1787671548802_0.331412793406596"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-05T10:51:33.606Z","modified":"2026-08-25T15:25:49.126Z","1.0.0":"2025-12-05T10:51:33.902Z","1.0.1":"2025-12-05T10:57:54.494Z","1.0.2":"2025-12-05T11:22:36.649Z","1.0.3":"2025-12-08T16:03:01.045Z","1.0.4":"2026-08-25T15:25:48.958Z"},"bugs":{"url":"https://github.com/alludium/affinity-mcp-server/issues"},"author":{"name":"Alludium"},"license":"MIT","homepage":"https://github.com/alludium/affinity-mcp-server#readme","keywords":["mcp","affinity","crm","model-context-protocol"],"repository":{"type":"git","url":"git+https://github.com/alludium/affinity-mcp-server.git"},"description":"MCP server for Affinity CRM API","maintainers":[{"name":"donal_alludium","email":"donal@alludium.ai"},{"name":"markalludium","email":"mark@alludium.ai"},{"name":"john-alludium","email":"john@alludium.ai"},{"name":"jubernunes","email":"juber@alludium.ai"}],"readme":"# Affinity MCP Server\n\nAn MCP (Model Context Protocol) server for the [Affinity CRM](https://www.affinity.co/) API. This server enables LLMs to interact with Affinity data including companies, persons, lists, opportunities, notes, pipeline management, field data inspection, change history, and network intelligence.\n\n## What's New\n\n**Latest Updates:**\n- 🔍 **Field Data Access** - Get all custom field values for any entity\n- 📊 **Audit Trail** - Track field change history (who changed what when)\n- 📚 **Schema Discovery** - Discover all person and organization field definitions\n- 🤝 **Network Intelligence** - Find team connections to prospects for warm introductions\n\n## Features\n\n- **28 Tools** for comprehensive Affinity access\n- **Read-Only Focus** - All tools are read-only except note creation (safe for AI agents)\n- **Dual API Support** - Uses both V1 and V2 Affinity APIs for full functionality\n- **Field Data Access** - Complete field values, change history, and schema discovery\n- **Network Intelligence** - Relationship strength mapping for warm introductions\n- **Pagination** - Cursor-based pagination for large datasets\n- **Response Formats** - JSON and Markdown output options\n- **Rate Limiting** - Automatic handling of API rate limits with retry\n- **Request Timeout** - 30-second timeout prevents hung requests\n- **Error Handling** - Clear, actionable error messages\n- **Character Limits** - Automatic truncation to prevent oversized responses\n\n## Tools Overview\n\n### Authentication\n| Tool | Description |\n|------|-------------|\n| `affinity_whoami` | Verify authentication and get current user info, permissions |\n\n### Companies (4 tools)\n| Tool | Description |\n|------|-------------|\n| `affinity_list_companies` | List companies with optional field data (V2) |\n| `affinity_get_company` | Get company details by ID (V2) |\n| `affinity_search_companies` | Search companies by name or domain (V1) |\n| `affinity_create_company` | Create a new company (V1) |\n\n### Persons (4 tools)\n| Tool | Description |\n|------|-------------|\n| `affinity_list_persons` | List persons with optional field data (V2) |\n| `affinity_get_person` | Get person details by ID (V2) |\n| `affinity_search_persons` | Search persons by email, name (V1) |\n| `affinity_create_person` | Create a new person (V1) |\n\n### Lists & Pipelines (6 tools)\n| Tool | Description |\n|------|-------------|\n| `affinity_list_lists` | Discover available lists |\n| `affinity_get_list` | Get single list metadata |\n| `affinity_get_list_entries` | Get entries from any list |\n| `affinity_get_list_fields` | Get field definitions for a list |\n| `affinity_get_swimlanes` | Get pipeline stages (Status field values) |\n| `affinity_get_companies_in_swimlane` | Get companies at a specific pipeline stage |\n\n### Opportunities (2 tools)\n| Tool | Description |\n|------|-------------|\n| `affinity_list_opportunities` | List opportunities |\n| `affinity_get_opportunity` | Get opportunity details by ID |\n\n### Notes (4 tools)\n| Tool | Description |\n|------|-------------|\n| `affinity_list_company_notes` | List notes for a company (V2 BETA) |\n| `affinity_list_person_notes` | List notes for a person (V2 BETA) |\n| `affinity_list_opportunity_notes` | List notes for an opportunity (V2 BETA) |\n| `affinity_add_note` | Create a note attached to entities (V1) |\n\n### Enhanced Details (2 tools)\n| Tool | Description |\n|------|-------------|\n| `affinity_get_company_lists` | Get lists containing a company |\n| `affinity_get_company_list_entries` | Get list entry data for a company |\n\n### Field Data & Audit (2 tools - V1 API)\n| Tool | Description |\n|------|-------------|\n| `affinity_get_field_values` | Get all field values for an entity (person, organization, opportunity, or list entry) |\n| `affinity_get_field_value_changes` | Get change history for a field (audit trail, who changed what when) |\n\n### Schema Discovery (2 tools - V1 API)\n| Tool | Description |\n|------|-------------|\n| `affinity_get_persons_fields` | Get all global person field definitions (schema discovery) |\n| `affinity_get_organizations_fields` | Get all global organization field definitions (schema discovery) |\n\n### Network Intelligence (1 tool - V1 API)\n| Tool | Description |\n|------|-------------|\n| `affinity_get_relationship_strengths` | Find who on your team has the strongest connections to external contacts (warm intro intelligence) |\n\n## Installation\n\nNo installation required when using `npx` (see Usage below).\n\n### Optional: Global Install\n\n```bash\nnpm install -g @alludium/affinity-mcp-server\n```\n\n### Optional: From Source\n\n```bash\ngit clone https://github.com/alludium/affinity-mcp-server.git\ncd affinity-mcp-server\nnpm install\nnpm run build\n```\n\n## Configuration\n\nSet your Affinity API key as an environment variable:\n\n```bash\nexport AFFINITY_API_KEY=your_api_key_here\n```\n\nWhen using with Claude Desktop or Claude Code, set the key in the MCP server configuration's `env` block (see Usage section below).\n\n### Getting an API Key\n\n1. Log into Affinity web app\n2. Go to Settings\n3. Generate an API key (requires \"Generate an API key\" permission)\n4. Copy the key - it won't be shown again!\n\n## Usage\n\n### With Claude Desktop\n\nAdd to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"affinity\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@alludium/affinity-mcp-server\"],\n      \"env\": {\n        \"AFFINITY_API_KEY\": \"your_api_key_here\"\n      }\n    }\n  }\n}\n```\n\n### With Claude Code\n\nAdd to your Claude Code MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"affinity\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@alludium/affinity-mcp-server\"],\n      \"env\": {\n        \"AFFINITY_API_KEY\": \"your_api_key_here\"\n      }\n    }\n  }\n}\n```\n\n### Development Mode\n\n```bash\n# Run with tsx for development\nAFFINITY_API_KEY=your_key npm run dev\n```\n\n## Tools Reference\n\n### affinity_whoami\n\nVerify authentication and get current user info.\n\n```\nNo parameters required\n```\n\n**Returns:** User info, organization details, API key permissions\n\n---\n\n### affinity_list_companies\n\nList companies with optional field data.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `ids` | number[] | Filter by specific company IDs |\n| `fieldTypes` | string[] | Field types: \"enriched\", \"global\" |\n| `fieldIds` | string[] | Specific field IDs to return |\n| `limit` | number | Results per page (max 100) |\n| `cursor` | string | Pagination cursor |\n| `responseFormat` | string | \"json\" or \"markdown\" |\n\n---\n\n### affinity_get_company\n\nGet detailed info about a single company.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `companyId` | string | Yes | Company ID (numeric) |\n| `fieldTypes` | string[] | No | Field types: \"enriched\", \"global\" |\n| `fieldIds` | string[] | No | Specific field IDs to return |\n| `responseFormat` | string | No | \"json\" or \"markdown\" |\n\n---\n\n### affinity_search_companies\n\nSearch for companies by name or domain (V1 API).\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `term` | string | Search term: company name or domain |\n| `withInteractionDates` | boolean | Include first/last interaction timestamps |\n| `withInteractionPersons` | boolean | Include persons involved in interactions |\n| `withOpportunities` | boolean | Include opportunity IDs |\n| `pageSize` | number | Items per page (max 500) |\n| `pageToken` | string | Pagination token |\n| `responseFormat` | string | \"json\" or \"markdown\" |\n\n---\n\n### affinity_create_company\n\nCreate a new company/organization (V1 API).\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `name` | string | Yes | Company name |\n| `domain` | string | No | Primary domain |\n| `domains` | string[] | No | Additional domains |\n| `responseFormat` | string | No | \"json\" or \"markdown\" |\n\n---\n\n### affinity_list_persons\n\nList persons/contacts with optional field data.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `ids` | number[] | Filter by specific person IDs |\n| `fieldTypes` | string[] | Field types: \"enriched\", \"global\", \"relationship-intelligence\" |\n| `fieldIds` | string[] | Specific field IDs to return |\n| `limit` | number | Results per page (max 100) |\n| `cursor` | string | Pagination cursor |\n| `responseFormat` | string | \"json\" or \"markdown\" |\n\n---\n\n### affinity_get_person\n\nGet detailed info about a single person.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `personId` | string | Yes | Person ID (numeric) |\n| `fieldTypes` | string[] | No | Field types to include |\n| `fieldIds` | string[] | No | Specific field IDs to return |\n| `responseFormat` | string | No | \"json\" or \"markdown\" |\n\n---\n\n### affinity_search_persons\n\nSearch for persons by email, first name, or last name (V1 API).\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `term` | string | Search term: email, first name, or last name |\n| `withInteractionDates` | boolean | Include first/last interaction timestamps |\n| `withInteractionPersons` | boolean | Include persons involved in interactions |\n| `withOpportunities` | boolean | Include opportunity IDs |\n| `withCurrentOrganizations` | boolean | Include current organization IDs |\n| `pageSize` | number | Items per page (max 500) |\n| `pageToken` | string | Pagination token |\n| `responseFormat` | string | \"json\" or \"markdown\" |\n\n---\n\n### affinity_create_person\n\nCreate a new person (V1 API).\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `firstName` | string | Yes | First name |\n| `lastName` | string | Yes | Last name |\n| `emails` | string[] | No | Email addresses (first becomes primary) |\n| `organizationIds` | number[] | No | Organization IDs to associate |\n| `responseFormat` | string | No | \"json\" or \"markdown\" |\n\n---\n\n### affinity_list_lists\n\nGet all lists in the workspace.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `limit` | number | Results per page (max 100) |\n| `cursor` | string | Pagination cursor |\n| `responseFormat` | string | \"json\" or \"markdown\" |\n\n**Returns:** All lists with their IDs, names, types, and ownership info\n\n---\n\n### affinity_get_list\n\nGet metadata for a single list.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `listId` | string | Yes | List ID (numeric) |\n| `responseFormat` | string | No | \"json\" or \"markdown\" |\n\n---\n\n### affinity_get_list_entries\n\nGet entries from a specific list.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `listId` | string | Yes | List ID (numeric) |\n| `fieldTypes` | string[] | No | Field types: \"enriched\", \"global\", \"list\" |\n| `fieldIds` | string[] | No | Specific field IDs to return |\n| `limit` | number | No | Results per page (max 100) |\n| `cursor` | string | No | Pagination cursor |\n| `responseFormat` | string | No | \"json\" or \"markdown\" |\n\n---\n\n### affinity_get_list_fields\n\nGet field definitions for a list.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `listId` | string | Yes | List ID (numeric) |\n| `cursor` | string | No | Pagination cursor |\n| `limit` | number | No | Items per page (max 100) |\n| `responseFormat` | string | No | \"json\" or \"markdown\" |\n\n---\n\n### affinity_get_swimlanes\n\nGet pipeline stages (swimlanes) for a list.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `listId` | string | Yes | List ID (numeric) |\n| `responseFormat` | string | No | \"json\" or \"markdown\" |\n\n**Returns:** Status field ID and all swimlane stages with IDs, names, ranks, colors\n\n---\n\n### affinity_get_companies_in_swimlane\n\nGet companies at a specific pipeline stage.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `listId` | string | Yes | List ID (numeric) |\n| `swimlaneId` | string | Yes | Swimlane/stage ID (from affinity_get_swimlanes) |\n| `cursor` | string | No | Pagination cursor |\n| `limit` | number | No | Items per page (max 100) |\n| `responseFormat` | string | No | \"json\" or \"markdown\" |\n\n---\n\n### affinity_list_opportunities\n\nList opportunities from Affinity.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `ids` | number[] | Filter by specific opportunity IDs |\n| `limit` | number | Results per page (max 100) |\n| `cursor` | string | Pagination cursor |\n| `responseFormat` | string | \"json\" or \"markdown\" |\n\n---\n\n### affinity_get_opportunity\n\nGet details about a single opportunity.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `opportunityId` | string | Yes | Opportunity ID (numeric) |\n| `responseFormat` | string | No | \"json\" or \"markdown\" |\n\n---\n\n### affinity_list_company_notes\n\nList notes attached to a company (V2 BETA).\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `companyId` | string | Yes | Company ID (numeric) |\n| `cursor` | string | No | Pagination cursor |\n| `limit` | number | No | Items per page (max 100) |\n| `responseFormat` | string | No | \"json\" or \"markdown\" |\n\n---\n\n### affinity_list_person_notes\n\nList notes attached to a person (V2 BETA).\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `personId` | string | Yes | Person ID (numeric) |\n| `cursor` | string | No | Pagination cursor |\n| `limit` | number | No | Items per page (max 100) |\n| `responseFormat` | string | No | \"json\" or \"markdown\" |\n\n---\n\n### affinity_list_opportunity_notes\n\nList notes attached to an opportunity (V2 BETA).\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `opportunityId` | string | Yes | Opportunity ID (numeric) |\n| `cursor` | string | No | Pagination cursor |\n| `limit` | number | No | Items per page (max 100) |\n| `responseFormat` | string | No | \"json\" or \"markdown\" |\n\n---\n\n### affinity_add_note\n\nCreate a note attached to companies, persons, or opportunities (V1 API).\n\n**Note:** Notes are add-only. Edit and delete are not supported.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | Note content (plain text or HTML) |\n| `companyIds` | number[] | No* | Company IDs to attach note to |\n| `personIds` | number[] | No* | Person IDs to attach note to |\n| `opportunityIds` | number[] | No* | Opportunity IDs to attach note to |\n| `contentType` | string | No | \"text\" (default) or \"html\" |\n| `responseFormat` | string | No | \"json\" or \"markdown\" |\n\n*At least one of `companyIds`, `personIds`, or `opportunityIds` is required.\n\n---\n\n### affinity_get_company_lists\n\nGet lists containing a specific company.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `companyId` | string | Yes | Company ID (numeric) |\n| `cursor` | string | No | Pagination cursor |\n| `limit` | number | No | Items per page (max 100) |\n| `responseFormat` | string | No | \"json\" or \"markdown\" |\n\n---\n\n### affinity_get_company_list_entries\n\nGet full list entry data for a company across all lists.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `companyId` | string | Yes | Company ID (numeric) |\n| `cursor` | string | No | Pagination cursor |\n| `limit` | number | No | Items per page (max 100) |\n| `responseFormat` | string | No | \"json\" or \"markdown\" |\n\n---\n\n### affinity_get_field_values\n\nGet all field values for a specific entity (V1 API).\n\n**Use Case:** Complete entity inspection - see all custom field data.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `person_id` | number | One required* | Get field values for this person |\n| `organization_id` | number | One required* | Get field values for this organization |\n| `opportunity_id` | number | One required* | Get field values for this opportunity |\n| `list_entry_id` | number | One required* | Get field values for this list entry (includes list-specific fields) |\n| `responseFormat` | string | No | \"json\" or \"markdown\" |\n\n*Exactly ONE entity parameter must be provided.\n\n**Returns:** All field values including global fields and list-specific fields (pipeline data, deal amounts, stages, etc.)\n\n---\n\n### affinity_get_field_value_changes\n\nGet change history for a specific field (V1 API).\n\n**Use Case:** Audit trail, accountability, track deal progression.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `field_id` | number | Yes | Field to track changes for |\n| `action_type` | number | No | Filter: 0=Create, 1=Update, 2=Delete |\n| `person_id` | number | No | Filter to specific person |\n| `organization_id` | number | No | Filter to specific organization |\n| `list_entry_id` | number | No | Filter to specific list entry |\n| `page_size` | number | No | Results per page (max 500) |\n| `responseFormat` | string | No | \"json\" or \"markdown\" |\n\n**Returns:** Change history showing who changed what and when, with timestamps and user details.\n\n**Note:** Not all fields support change tracking. Status fields (Ranked Dropdown) typically support tracking.\n\n---\n\n### affinity_get_persons_fields\n\nGet all global person field definitions (V1 API).\n\n**Use Case:** Schema discovery - understand what person fields exist in the CRM.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `responseFormat` | string | No | \"json\" or \"markdown\" |\n\n**Returns:** Complete schema including field IDs, names, types, dropdown options, enrichment sources.\n\n---\n\n### affinity_get_organizations_fields\n\nGet all global organization field definitions (V1 API).\n\n**Use Case:** Schema discovery - understand what organization fields exist in the CRM.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `responseFormat` | string | No | \"json\" or \"markdown\" |\n\n**Returns:** Complete schema including field IDs, names, types, dropdown options, enrichment sources (Crunchbase, Dealroom, etc.).\n\n---\n\n### affinity_get_relationship_strengths\n\nFind who on your team has the strongest connections to an external contact (V1 API).\n\n**Use Case:** Warm introduction intelligence - \"Who should make the intro to this prospect?\"\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `external_id` | number | Yes | External person ID to find connections to |\n| `internal_id` | number | No | Filter to specific internal team member |\n| `page_size` | number | No | Results per page (max 500) |\n| `responseFormat` | string | No | \"json\" or \"markdown\" |\n\n**Returns:** Array of relationships with strength scores (0.0-1.0):\n- 0.8-1.0: Very Strong (ideal for warm intros)\n- 0.6-0.8: Strong (good for introductions)\n- 0.4-0.6: Moderate (may be useful)\n- 0.0-0.4: Weak (limited connection)\n\n**Limitation:** Can only query \"who knows this person\", not \"who does this person know\" or \"who knows this company\".\n\n## Rate Limits\n\n- **900 requests per minute** per user\n- Automatic retry with backoff on 429 responses\n- Rate limit headers tracked for monitoring\n\n## Error Handling\n\nThe server returns clear, actionable error messages:\n\n- **401**: Check your API key\n- **403**: Use `affinity_whoami` to check permissions\n- **404**: Resource not found\n- **429**: Rate limited, wait and retry\n\n## Development\n\n```bash\n# Type check\nnpm run typecheck\n\n# Build\nnpm run build\n\n# Run in dev mode\nnpm run dev\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}