salesflare-mcp-server 1.0.0

package/API.md

@@ -0,0 +1,691 @@
+# Salesflare MCP Server - API Reference
+
+Complete API reference for all MCP tools exposed by the Salesflare MCP Server.
+
+## Overview
+
+This MCP server provides 15 tools across 5 entity types, enabling LLMs to interact with Salesflare CRM data through natural language.
+
+## Authentication
+
+All tools require authentication via API key:
+
+```bash
+export SALESFLARE_API_KEY="your_api_key_here"
+```
+
+The API key is validated at server startup. All requests include the Authorization header:
+```
+Authorization: Bearer {SALESFLARE_API_KEY}
+```
+
+## Rate Limiting
+
+The Salesflare API has rate limits. The MCP server implements:
+- Automatic retry with exponential backoff for 429 responses
+- Maximum 3 retries before failing
+- Retryable error flag for LLM context
+
+## Common Response Format
+
+All tools return responses in MCP format:
+
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "Human-readable summary"
+    },
+    {
+      "type": "text",
+      "text": "{\"json\": \"data\"}"
+    }
+  ],
+  "isError": false
+}
+```
+
+## Contacts
+
+### salesflare_contacts_list
+
+List contacts from Salesflare CRM with optional filtering and pagination.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "filter": {
+      "type": "object",
+      "properties": {
+        "email": { "type": "string", "description": "Filter by exact email match" },
+        "name": { "type": "string", "description": "Filter by name (partial match)" },
+        "company_id": { "type": "string", "description": "Filter by associated company" },
+        "tags": { "type": "array", "items": { "type": "string" } },
+        "owner": { "type": "string", "description": "Filter by owner user ID" },
+        "domain": { "type": "string", "description": "Filter by email domain" },
+        "search": { "type": "string", "description": "Free-text search" }
+      }
+    },
+    "pagination": {
+      "type": "object",
+      "properties": {
+        "limit": { "type": "number", "minimum": 1, "maximum": 500, "default": 50 },
+        "cursor": { "type": "string", "description": "Pagination cursor" }
+      }
+    }
+  }
+}
+```
+
+**Output:** Array of Contact objects
+
+**Example:**
+```json
+{
+  "filter": { "email": "john@example.com" },
+  "pagination": { "limit": 10 }
+}
+```
+
+### salesflare_contacts_create
+
+Create a new contact in Salesflare.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "email": { "type": "string", "format": "email" },
+    "name": { "type": "string" },
+    "phone": { "type": "string" },
+    "company_id": { "type": "string" },
+    "tags": { "type": "array", "items": { "type": "string" } },
+    "owner": { "type": "string" }
+  },
+  "required": ["email"]
+}
+```
+
+**Output:** Created Contact object with generated ID
+
+### salesflare_contacts_update
+
+Update an existing contact.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "id": { "type": "string", "format": "uuid" },
+    "email": { "type": "string", "format": "email" },
+    "name": { "type": "string" },
+    "phone": { "type": "string" },
+    "company_id": { "type": "string" },
+    "tags": { "type": "array", "items": { "type": "string" } },
+    "owner": { "type": "string" }
+  },
+  "required": ["id"]
+}
+```
+
+**Output:** Updated Contact object
+
+### salesflare_contacts_delete
+
+Delete a contact by ID.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "id": { "type": "string", "format": "uuid" }
+  },
+  "required": ["id"]
+}
+```
+
+**Output:** Success confirmation
+
+## Companies
+
+### salesflare_companies_list
+
+List companies with filtering and pagination.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "filter": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string", "description": "Filter by name (partial match)" },
+        "industry": { "type": "string", "description": "Filter by industry (exact match)" },
+        "tags": { "type": "array", "items": { "type": "string" } },
+        "owner": { "type": "string" },
+        "search": { "type": "string", "description": "Free-text search" }
+      }
+    },
+    "pagination": {
+      "type": "object",
+      "properties": {
+        "limit": { "type": "number", "minimum": 1, "maximum": 500, "default": 50 },
+        "cursor": { "type": "string" }
+      }
+    }
+  }
+}
+```
+
+**Output:** Array of Company objects with contacts_count
+
+### salesflare_companies_create
+
+Create a new company.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "name": { "type": "string" },
+    "website": { "type": "string" },
+    "industry": { "type": "string" },
+    "address": {
+      "type": "object",
+      "properties": {
+        "street": { "type": "string" },
+        "city": { "type": "string" },
+        "state": { "type": "string" },
+        "postal_code": { "type": "string" },
+        "country": { "type": "string" }
+      }
+    },
+    "owner": { "type": "string" }
+  },
+  "required": ["name"]
+}
+```
+
+**Output:** Created Company object
+
+### salesflare_companies_update
+
+Update an existing company.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "id": { "type": "string", "format": "uuid" },
+    "name": { "type": "string" },
+    "website": { "type": "string" },
+    "industry": { "type": "string" },
+    "address": { "type": "object" },
+    "owner": { "type": "string" }
+  },
+  "required": ["id"]
+}
+```
+
+**Output:** Updated Company object
+
+### salesflare_companies_delete
+
+Delete a company by ID. **Note:** Unlinks associated contacts before deletion.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "id": { "type": "string", "format": "uuid" }
+  },
+  "required": ["id"]
+}
+```
+
+**Output:** Success confirmation with unlinked contacts count
+
+## Deals
+
+### salesflare_deals_list
+
+List deals with filtering and pagination.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "filter": {
+      "type": "object",
+      "properties": {
+        "status": { "type": "string", "enum": ["open", "won", "lost"] },
+        "pipeline_id": { "type": "string" },
+        "stage_id": { "type": "string" },
+        "assigned_user_id": { "type": "string" },
+        "min_value": { "type": "number", "description": "Minimum value in cents" },
+        "max_value": { "type": "number", "description": "Maximum value in cents" },
+        "search": { "type": "string" }
+      }
+    },
+    "pagination": {
+      "type": "object",
+      "properties": {
+        "limit": { "type": "number", "default": 50 },
+        "cursor": { "type": "string" }
+      }
+    }
+  }
+}
+```
+
+**Output:** Array of Deal objects with formatted value
+
+### salesflare_deals_create
+
+Create a new deal.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "name": { "type": "string" },
+    "value": { "type": "number", "description": "Value in dollars (converted to cents)" },
+    "currency": { "type": "string", "default": "USD" },
+    "pipeline_id": { "type": "string" },
+    "stage_id": { "type": "string" },
+    "close_date": { "type": "string", "format": "date" },
+    "assigned_user_id": { "type": "string" }
+  },
+  "required": ["name", "value"]
+}
+```
+
+**Output:** Created Deal object (value in cents)
+
+### salesflare_deals_update
+
+Update an existing deal.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "id": { "type": "string", "format": "uuid" },
+    "name": { "type": "string" },
+    "value": { "type": "number", "description": "Value in dollars" },
+    "status": { "type": "string", "enum": ["open", "won", "lost"] },
+    "close_date": { "type": "string", "format": "date" },
+    "assigned_user_id": { "type": "string" }
+  },
+  "required": ["id"]
+}
+```
+
+**Output:** Updated Deal object
+
+### salesflare_deals_delete
+
+Delete a deal by ID.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "id": { "type": "string", "format": "uuid" }
+  },
+  "required": ["id"]
+}
+```
+
+**Output:** Success confirmation
+
+### salesflare_deals_move_stage
+
+Move a deal to a different pipeline stage.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "id": { "type": "string", "format": "uuid" },
+    "stage_id": { "type": "string", "format": "uuid" }
+  },
+  "required": ["id", "stage_id"]
+}
+```
+
+**Output:** Updated Deal with new stage_id
+
+## Tasks
+
+### salesflare_tasks_list
+
+List tasks with filtering.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "filter": {
+      "type": "object",
+      "properties": {
+        "status": { "type": "string", "enum": ["open", "completed"] },
+        "assigned_user_id": { "type": "string" },
+        "due_date": { "type": "string", "format": "date" },
+        "overdue": { "type": "boolean" },
+        "related_contact_id": { "type": "string" },
+        "related_deal_id": { "type": "string" }
+      }
+    },
+    "pagination": {
+      "type": "object",
+      "properties": {
+        "limit": { "type": "number", "default": 50 },
+        "cursor": { "type": "string" }
+      }
+    }
+  }
+}
+```
+
+**Output:** Array of Task objects with is_overdue flag
+
+### salesflare_tasks_create
+
+Create a new task.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "description": { "type": "string" },
+    "due_date": { "type": "string", "format": "date" },
+    "assigned_user_id": { "type": "string" },
+    "related_contact_id": { "type": "string" },
+    "related_deal_id": { "type": "string" },
+    "status": { "type": "string", "enum": ["open", "completed"], "default": "open" }
+  },
+  "required": ["description"]
+}
+```
+
+**Output:** Created Task object
+
+### salesflare_tasks_update
+
+Update an existing task. **Note:** Setting status to "completed" automatically sets completed_at.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "id": { "type": "string", "format": "uuid" },
+    "description": { "type": "string" },
+    "due_date": { "type": "string", "format": "date" },
+    "assigned_user_id": { "type": "string" },
+    "status": { "type": "string", "enum": ["open", "completed"] }
+  },
+  "required": ["id"]
+}
+```
+
+**Output:** Updated Task object with completed_at if status changed to completed
+
+## Pipeline
+
+### salesflare_pipeline_list_stages
+
+List all pipeline stages across all pipelines.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {}
+}
+```
+
+**Output:** Array of PipelineStage objects
+
+```json
+{
+  "items": [
+    {
+      "id": "stage-uuid",
+      "name": "Prospecting",
+      "position": 1,
+      "pipeline_id": "pipeline-uuid",
+      "created_at": "2024-01-01T00:00:00Z"
+    }
+  ],
+  "total": 5
+}
+```
+
+### salesflare_pipeline_get_overview
+
+Get pipeline statistics and overview.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "pipeline_id": { "type": "string", "description": "Optional: specific pipeline ID" }
+  }
+}
+```
+
+**Output:** Pipeline statistics
+
+```json
+{
+  "pipeline": {
+    "id": "pipeline-uuid",
+    "name": "Sales Pipeline",
+    "currency": "USD"
+  },
+  "stages": [
+    {
+      "id": "stage-uuid",
+      "name": "Prospecting",
+      "position": 1,
+      "deals_count": 5,
+      "total_value": 500000
+    }
+  ],
+  "total_deals": 15,
+  "total_value": 2500000,
+  "currency": "USD"
+}
+```
+
+## Common Types
+
+### Contact
+```typescript
+{
+  id: string;
+  email: string;
+  name?: string;
+  phone?: string;
+  company_id?: string;
+  tags?: string[];
+  owner?: string;
+  created_at: string;
+  updated_at?: string;
+}
+```
+
+### Company
+```typescript
+{
+  id: string;
+  name: string;
+  website?: string;
+  industry?: string;
+  address?: Address;
+  contacts_count: number;
+  owner?: string;
+  created_at: string;
+}
+```
+
+### Deal
+```typescript
+{
+  id: string;
+  name: string;
+  value: number;        // In cents
+  currency: string;
+  pipeline_id: string;
+  stage_id: string;
+  status: "open" | "won" | "lost";
+  close_date?: string;
+  assigned_user_id?: string;
+  created_at: string;
+}
+```
+
+### Task
+```typescript
+{
+  id: string;
+  description: string;
+  status: "open" | "completed";
+  due_date?: string;
+  completed_at?: string;
+  assigned_user_id?: string;
+  related_contact_id?: string;
+  related_deal_id?: string;
+  is_overdue: boolean;
+  created_at: string;
+}
+```
+
+### PipelineStage
+```typescript
+{
+  id: string;
+  name: string;
+  position: number;
+  pipeline_id: string;
+  created_at: string;
+}
+```
+
+## Error Handling
+
+All errors follow the SalesflareError format:
+
+### Error Codes
+
+| Code | HTTP Status | Description | Retryable |
+|------|-------------|-------------|-----------|
+| `AUTH_INVALID` | 401 | Invalid or missing API key | ❌ |
+| `AUTH_EXPIRED` | 401 | Authentication expired | ❌ |
+| `NOT_FOUND` | 404 | Resource not found | ❌ |
+| `VALIDATION_ERROR` | 400 | Input validation failed | ❌ |
+| `RATE_LIMIT` | 429 | Rate limit exceeded | ✅ |
+| `NETWORK_ERROR` | - | Network connectivity issue | ✅ |
+| `SERVER_ERROR` | 500+ | Salesflare API error | ✅ |
+| `UNKNOWN_ERROR` | - | Unexpected error | ❌ |
+
+### Error Response Format
+
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "Error [VALIDATION_ERROR]: Invalid email format"
+    },
+    {
+      "type": "text",
+      "text": "{\"code\":\"VALIDATION_ERROR\",\"message\":\"Invalid email format\",\"retryable\":false}"
+    }
+  ],
+  "isError": true
+}
+```
+
+## Pagination
+
+All list tools support cursor-based pagination:
+
+**Request:**
+```json
+{
+  "pagination": {
+    "limit": 50,
+    "cursor": "next_page_token"
+  }
+}
+```
+
+**Response includes:**
+```json
+{
+  "items": [...],
+  "total": 150,
+  "has_more": true,
+  "next_cursor": "next_page_token"
+}
+```
+
+- **Default limit:** 50 items
+- **Maximum limit:** 500 items
+- **Cursor:** Opaque token from previous response
+
+## Value Formatting
+
+### Currency
+
+Deals use currency codes (ISO 4217): USD, EUR, GBP, etc.
+
+### Deal Values
+
+- **Input:** Dollars (e.g., 50000 for $50,000)
+- **API:** Cents (e.g., 5000000)
+- **Automatic conversion** between input and API
+
+**Example:**
+```json
+// Input
+{ "value": 50000, "currency": "USD" }
+
+// Stored as
+{ "value": 5000000, "currency": "USD", "formatted": "$50,000.00" }
+```
+
+## Testing
+
+Use the MCP Inspector to test all tools:
+
+```bash
+npm run inspector
+```
+
+See [INSPECTOR.md](INSPECTOR.md) for detailed testing scenarios.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.