salesflare-mcp-server 1.0.0

package/dist/tools/deals.js

@@ -0,0 +1,442 @@
+/**
+ * Deal tools for Salesflare MCP Server
+ *
+ * Implements CRUD operations for deals:
+ * - salesflare_deals_list: List deals with filtering and pagination
+ * - salesflare_deals_create: Create new deals
+ * - salesflare_deals_update: Update existing deals
+ * - salesflare_deals_delete: Delete deals
+ * - salesflare_deals_move_stage: Move deals between pipeline stages
+ *
+ * @module tools/deals
+ */
+import { SalesflareError, ErrorCode } from '../utils/errors.js';
+/**
+ * Deal tool definitions with JSON schemas
+ */
+const dealTools = [
+    {
+        name: 'salesflare_deals_list',
+        description: 'List deals from Salesflare CRM with optional filtering and pagination. ' +
+            'Supports filtering by status (open, won, lost), pipeline_id, assigned_user_id, stage_id, ' +
+            'min_value, max_value (in cents), and search. Returns paginated results with total count ' +
+            'and has_more indicator. Deal values are displayed in human-readable format.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                status: { type: 'string', enum: ['open', 'won', 'lost'], description: 'Filter by deal status' },
+                pipeline_id: { type: 'string', description: 'Filter by pipeline ID (UUID)' },
+                assigned_user_id: { type: 'string', description: 'Filter by assigned user ID (UUID)' },
+                stage_id: { type: 'string', description: 'Filter by stage ID (UUID)' },
+                min_value: { type: 'number', description: 'Minimum deal value in cents' },
+                max_value: { type: 'number', description: 'Maximum deal value in cents' },
+                search: { type: 'string', description: 'Free-text search across deal fields' },
+                page: { type: 'number', description: 'Page number (default: 1)' },
+                limit: { type: 'number', description: 'Items per page (default: 20, max: 100)' },
+            },
+        },
+    },
+    {
+        name: 'salesflare_deals_create',
+        description: 'Create a new deal in Salesflare CRM. ' +
+            'Name, value (in dollars), and pipeline_id are required. ' +
+            'Value will be converted to cents for API storage. ' +
+            'Optional fields include currency (default USD), stage_id, close_date, ' +
+            'assigned_user_id, company_id, contact_ids, and description.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Deal name (required)' },
+                value: { type: 'number', description: 'Deal value in dollars (required, will be converted to cents)' },
+                currency: { type: 'string', description: 'Currency code (3-letter ISO, default: USD)' },
+                pipeline_id: { type: 'string', description: 'Pipeline ID the deal belongs to (required, UUID)' },
+                stage_id: { type: 'string', description: 'Stage ID within the pipeline (optional, UUID)' },
+                close_date: { type: 'string', description: 'Expected close date (ISO 8601 format)' },
+                assigned_user_id: { type: 'string', description: 'Assigned user ID (optional, UUID)' },
+                company_id: { type: 'string', description: 'Associated company ID (optional, UUID)' },
+                contact_ids: { type: 'array', items: { type: 'string' }, description: 'Associated contact IDs (optional, UUID array)' },
+                description: { type: 'string', description: 'Deal description' },
+            },
+            required: ['name', 'value', 'pipeline_id'],
+        },
+    },
+    {
+        name: 'salesflare_deals_update',
+        description: 'Update an existing deal in Salesflare CRM. ' +
+            'Requires deal_id. All other fields are optional - only provided fields will be updated. ' +
+            'Value should be provided in dollars and will be converted to cents. ' +
+            'Status can be updated to open, won, or lost.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                deal_id: { type: 'string', description: 'Deal UUID to update' },
+                name: { type: 'string', description: 'Deal name' },
+                value: { type: 'number', description: 'Deal value in dollars (will be converted to cents)' },
+                currency: { type: 'string', description: 'Currency code (3-letter ISO)' },
+                pipeline_id: { type: 'string', description: 'Pipeline ID the deal belongs to' },
+                stage_id: { type: 'string', description: 'Stage ID within the pipeline' },
+                status: { type: 'string', enum: ['open', 'won', 'lost'], description: 'Deal status' },
+                close_date: { type: 'string', description: 'Expected close date (ISO 8601 format)' },
+                assigned_user_id: { type: 'string', description: 'Assigned user ID (UUID)' },
+                company_id: { type: 'string', description: 'Associated company ID (UUID)' },
+                contact_ids: { type: 'array', items: { type: 'string' }, description: 'Associated contact IDs (UUID array)' },
+                description: { type: 'string', description: 'Deal description' },
+            },
+            required: ['deal_id'],
+        },
+    },
+    {
+        name: 'salesflare_deals_delete',
+        description: 'Delete a deal from Salesflare CRM. ' +
+            'Requires deal_id. This action cannot be undone.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                deal_id: { type: 'string', description: 'Deal UUID to delete' },
+            },
+            required: ['deal_id'],
+        },
+    },
+    {
+        name: 'salesflare_deals_move_stage',
+        description: 'Move a deal to a different pipeline stage in Salesflare CRM. ' +
+            'Requires deal_id and stage_id. Returns the updated deal with new stage information.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                deal_id: { type: 'string', description: 'Deal UUID to move' },
+                stage_id: { type: 'string', description: 'Target stage ID (UUID)' },
+            },
+            required: ['deal_id', 'stage_id'],
+        },
+    },
+];
+/**
+ * Exported deal tools array for unified registration
+ */
+export { dealTools };
+/**
+ * Handle deal tool calls
+ *
+ * @param client - Salesflare API client
+ * @param name - Tool name
+ * @param args - Tool arguments
+ * @returns Tool response
+ */
+export async function handleDealsTool(client, name, args) {
+    switch (name) {
+        case 'salesflare_deals_list':
+            return await handleListDeals(client, args);
+        case 'salesflare_deals_create':
+            return await handleCreateDeal(client, args);
+        case 'salesflare_deals_update':
+            return await handleUpdateDeal(client, args);
+        case 'salesflare_deals_delete':
+            return await handleDeleteDeal(client, args);
+        case 'salesflare_deals_move_stage':
+            return await handleMoveDealStage(client, args);
+        default:
+            throw new SalesflareError({
+                code: ErrorCode.INVALID_INPUT,
+                message: `Unknown deal tool: ${name}`,
+                retryable: false,
+            });
+    }
+}
+/**
+ * Register deal-related tools with the MCP server
+ *
+ * @deprecated Use handleDealsTool instead for unified registration
+ * @param server - MCP Server instance
+ * @param client - Salesflare API client
+ */
+export function registerDealsTools(server, client) {
+    // This function is deprecated - use unified tool registration in server.ts
+    // Kept for backward compatibility
+}
+/**
+ * Convert dollars to cents for API storage
+ * Per D-22: User inputs dollars, API stores cents
+ */
+function dollarsToCents(dollars) {
+    return Math.round(dollars * 100);
+}
+/**
+ * Convert cents to dollars for display
+ */
+function centsToDollars(cents) {
+    return cents / 100;
+}
+/**
+ * Format currency value for human-readable display
+ * Example: 1000000 cents + 'USD' → '$10,000.00'
+ */
+function formatCurrency(valueInCents, currency = 'USD') {
+    const dollars = centsToDollars(valueInCents);
+    // Ensure currency is a string
+    const currencyCode = (currency || 'USD').toString();
+    // Format with appropriate locale based on currency
+    let locale = 'en-US';
+    let currencySymbol = '$';
+    switch (currencyCode.toUpperCase()) {
+        case 'EUR':
+            locale = 'de-DE';
+            currencySymbol = '€';
+            break;
+        case 'GBP':
+            locale = 'en-GB';
+            currencySymbol = '£';
+            break;
+        case 'JPY':
+            locale = 'ja-JP';
+            currencySymbol = '¥';
+            break;
+        default:
+            // USD and others use US format
+            locale = 'en-US';
+            currencySymbol = '$';
+    }
+    try {
+        return new Intl.NumberFormat(locale, {
+            style: 'currency',
+            currency: currencyCode.toUpperCase(),
+        }).format(dollars);
+    }
+    catch {
+        // Fallback for unsupported currency codes
+        return `${currencySymbol}${dollars.toFixed(2)}`;
+    }
+}
+/**
+ * Handle salesflare_deals_list tool call
+ * Implements filters per D-15 to D-20
+ */
+async function handleListDeals(client, params) {
+    // Build query parameters from filters
+    const queryParams = {};
+    if (params.status)
+        queryParams.status = params.status;
+    if (params.pipeline_id)
+        queryParams.pipeline_id = params.pipeline_id;
+    if (params.assigned_user_id)
+        queryParams.assigned_user_id = params.assigned_user_id;
+    if (params.stage_id)
+        queryParams.stage_id = params.stage_id;
+    if (params.min_value !== undefined)
+        queryParams.min_value = params.min_value;
+    if (params.max_value !== undefined)
+        queryParams.max_value = params.max_value;
+    if (params.search)
+        queryParams.search = params.search;
+    // Pagination
+    queryParams.page = params.page || 1;
+    queryParams.limit = params.limit || 20;
+    // Call Salesflare API
+    const response = await client.get('/opportunities', { params: queryParams });
+    // Handle different response formats
+    const items = response.items || (Array.isArray(response) ? response : []);
+    const total = response.total ?? items.length;
+    const page = (response.page ?? Number(params.page)) || 1;
+    const limit = (response.limit ?? Number(params.limit)) || 20;
+    // Transform to curated response format (D-10)
+    const deals = items.map((item) => ({
+        id: item.id,
+        name: item.name,
+        value: item.value,
+        currency: item.currency || 'USD',
+        pipeline_id: item.pipeline_id,
+        stage_id: item.stage_id,
+        status: item.status,
+        close_date: item.close_date,
+        assigned_user: item.assigned_user ? {
+            id: item.assigned_user.id,
+            name: item.assigned_user.name,
+        } : undefined,
+        company: item.company ? {
+            id: item.company.id,
+            name: item.company.name,
+        } : undefined,
+        contacts: item.contacts ? item.contacts.map((c) => ({
+            id: c.id,
+            name: c.name,
+        })) : undefined,
+        description: item.description,
+        created_at: item.created_at,
+        updated_at: item.updated_at,
+    }));
+    const listResponse = {
+        deals,
+        total,
+        page,
+        limit,
+        has_more: page * limit < total,
+    };
+    // Calculate total value for summary (use first deal's currency or default to USD)
+    const totalValueCents = deals.reduce((sum, deal) => sum + (deal.value || 0), 0);
+    const currency = deals.length > 0 ? deals[0].currency : 'USD';
+    const formattedTotalValue = formatCurrency(totalValueCents, currency);
+    // Generate human-readable summary
+    const summaryText = listResponse.deals.length === 0
+        ? 'No deals found matching the criteria.'
+        : `Found ${listResponse.total} deal(s) worth ${formattedTotalValue} total. ` +
+            `Showing page ${listResponse.page} with ${listResponse.deals.length} result(s).` +
+            (listResponse.has_more ? ` More pages available.` : '');
+    return {
+        content: [
+            { type: 'text', text: summaryText },
+            { type: 'text', text: JSON.stringify(listResponse, null, 2) },
+        ],
+    };
+}
+/**
+ * Handle salesflare_deals_create tool call
+ * Name, value, and pipeline_id are required per D-01
+ * Value converted from dollars to cents per D-22
+ */
+async function handleCreateDeal(client, params) {
+    // Convert value from dollars to cents for API
+    const valueInCents = dollarsToCents(params.value);
+    // Call Salesflare API to create deal
+    const response = await client.post('/deals', {
+        name: params.name,
+        value: valueInCents,
+        currency: params.currency || 'USD',
+        pipeline_id: params.pipeline_id,
+        stage_id: params.stage_id,
+        close_date: params.close_date,
+        assigned_user_id: params.assigned_user_id,
+        company_id: params.company_id,
+        contact_ids: params.contact_ids,
+        description: params.description,
+    });
+    // Transform to curated response format
+    const deal = {
+        id: response.id,
+        name: response.name,
+        value: response.value,
+        currency: response.currency || 'USD',
+        pipeline_id: response.pipeline_id,
+        stage_id: response.stage_id,
+        status: response.status,
+        close_date: response.close_date,
+        assigned_user: response.assigned_user ? {
+            id: response.assigned_user.id,
+            name: response.assigned_user.name,
+        } : undefined,
+        company: response.company ? {
+            id: response.company.id,
+            name: response.company.name,
+        } : undefined,
+        contacts: response.contacts ? response.contacts.map((c) => ({
+            id: c.id,
+            name: c.name,
+        })) : undefined,
+        description: response.description,
+        created_at: response.created_at,
+        updated_at: response.updated_at,
+    };
+    const formattedValue = formatCurrency(deal.value, deal.currency);
+    return {
+        content: [
+            { type: 'text', text: `Deal created: ${deal.name} (${formattedValue})` },
+            { type: 'text', text: JSON.stringify(deal, null, 2) },
+        ],
+    };
+}
+/**
+ * Transform API response to curated Deal format
+ * Shared transformation logic for create, update, and move_stage
+ */
+function transformDealResponse(response) {
+    return {
+        id: response.id,
+        name: response.name,
+        value: response.value,
+        currency: response.currency || 'USD',
+        pipeline_id: response.pipeline_id,
+        stage_id: response.stage_id,
+        status: response.status,
+        close_date: response.close_date,
+        assigned_user: response.assigned_user ? {
+            id: response.assigned_user.id,
+            name: response.assigned_user.name,
+        } : undefined,
+        company: response.company ? {
+            id: response.company.id,
+            name: response.company.name,
+        } : undefined,
+        contacts: response.contacts ? response.contacts.map((c) => ({
+            id: c.id,
+            name: c.name,
+        })) : undefined,
+        description: response.description,
+        created_at: response.created_at,
+        updated_at: response.updated_at,
+    };
+}
+/**
+ * Handle salesflare_deals_update tool call
+ * Partial update per D-25: only provided fields will be updated
+ * Value converted from dollars to cents if provided
+ */
+async function handleUpdateDeal(client, params) {
+    const { deal_id, ...updateData } = params;
+    // Check if at least one field is provided for update
+    const hasUpdateFields = Object.keys(updateData).length > 0;
+    if (!hasUpdateFields) {
+        return {
+            content: [
+                { type: 'text', text: 'Error [INVALID_INPUT]: At least one field must be provided for update.' },
+                { type: 'text', text: '{}' },
+            ],
+        };
+    }
+    // Convert value from dollars to cents if provided
+    if (typeof updateData.value === 'number') {
+        updateData.value = dollarsToCents(updateData.value);
+    }
+    // Call Salesflare API to update deal
+    const response = await client.patch(`/deals/${deal_id}`, updateData);
+    // Transform to curated response format
+    const deal = transformDealResponse(response);
+    const formattedValue = formatCurrency(deal.value, deal.currency);
+    return {
+        content: [
+            { type: 'text', text: `Deal updated: ${deal.name} (${formattedValue})` },
+            { type: 'text', text: JSON.stringify(deal, null, 2) },
+        ],
+    };
+}
+/**
+ * Handle salesflare_deals_delete tool call
+ * Per D-12: Returns confirmation only, no deal data
+ */
+async function handleDeleteDeal(client, params) {
+    // Call Salesflare API to delete deal
+    await client.delete(`/deals/${params.deal_id}`);
+    return {
+        content: [{ type: 'text', text: 'Deal deleted successfully.' }],
+    };
+}
+/**
+ * Handle salesflare_deals_move_stage tool call
+ * Wrapper around update per D-26: updates stage_id
+ * Returns updated deal with new stage per D-27
+ */
+async function handleMoveDealStage(client, params) {
+    // Call Salesflare API to update deal stage
+    const response = await client.patch(`/deals/${params.deal_id}`, {
+        stage_id: params.stage_id,
+    });
+    // Transform to curated response format
+    const deal = transformDealResponse(response);
+    const formattedValue = formatCurrency(deal.value, deal.currency);
+    // Get stage name if available
+    const stageName = deal.stage_id || 'new stage';
+    return {
+        content: [
+            { type: 'text', text: `Deal moved to stage: ${stageName} (${formattedValue})` },
+            { type: 'text', text: JSON.stringify(deal, null, 2) },
+        ],
+    };
+}

package/dist/tools/pipeline.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Pipeline tools for Salesflare MCP Server
+ *
+ * Implements pipeline operations:
+ * - salesflare_pipeline_list_stages: List pipeline stages
+ * - salesflare_pipeline_get_overview: Get pipeline statistics
+ *
+ * @module tools/pipeline
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { SalesflareClient } from '../client/salesflare-client.js';
+/**
+ * Pipeline tool definitions with JSON schemas
+ */
+declare const pipelineTools: Tool[];
+/**
+ * Exported pipeline tools array for unified registration
+ */
+export { pipelineTools };
+/**
+ * Handle pipeline tool calls
+ *
+ * @param client - Salesflare API client
+ * @param name - Tool name
+ * @param args - Tool arguments
+ * @returns Tool response
+ */
+export declare function handlePipelineTool(client: SalesflareClient, name: string, args: unknown): Promise<{
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+}>;
+/**
+ * Register pipeline-related tools with the MCP server
+ *
+ * @deprecated Use handlePipelineTool instead for unified registration
+ * @param server - MCP Server instance
+ * @param client - Salesflare API client
+ */
+export declare function registerPipelineTools(server: Server, client: SalesflareClient): void;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/tools/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/tools/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAGL,IAAI,EACL,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAWlE;;GAEG;AACH,QAAA,MAAM,aAAa,EAAE,IAAI,EA0BxB,CAAC;AAEF;;GAEG;AACH,OAAO,EAAE,aAAa,EAAE,CAAC;AAEzB;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC,CAe7D;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAGpF"}