parasut-node-sdk-mcp 1.0.0

package/packages/parasut-mcp-server/src/tools/products.ts

@@ -0,0 +1,320 @@
+/**
+ * Product Tools
+ *
+ * Tools for managing products and services.
+ */
+
+import { z } from 'zod';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { getClient } from '../client.js';
+import {
+  formatSuccess,
+  formatList,
+  formatCreated,
+  formatNotFound,
+  formatProductSummary,
+  type ToolResponse,
+} from '../utils/response.js';
+import { handleError } from '../utils/errors.js';
+
+// ============================================================================
+// Schemas
+// ============================================================================
+
+const SearchProductsSchema = z.object({
+  query: z.string().optional().describe('Search by name or code'),
+  category_id: z.string().optional().describe('Filter by category'),
+  page: z.number().int().min(1).default(1),
+  limit: z.number().int().min(1).max(100).default(100),
+});
+
+const GetProductSchema = z.object({
+  id: z.string().describe('Product ID'),
+});
+
+const CreateProductSchema = z.object({
+  name: z.string().min(1).describe('Product name'),
+  code: z.string().optional().describe('Product code/SKU'),
+  unit: z.string().default('Adet').describe('Unit (Adet, Kg, Lt, etc.)'),
+  list_price: z.number().optional().describe('List price'),
+  currency: z.enum(['TRL', 'USD', 'EUR', 'GBP']).default('TRL'),
+  vat_rate: z.number().min(0).max(100).default(20),
+  category_id: z.string().optional().describe('Category ID'),
+  barcode: z.string().optional().describe('Barcode'),
+});
+
+const UpdateProductSchema = z.object({
+  id: z.string().describe('Product ID'),
+  name: z.string().optional(),
+  code: z.string().optional(),
+  list_price: z.number().optional(),
+  vat_rate: z.number().optional(),
+});
+
+// ============================================================================
+// Tool Definitions
+// ============================================================================
+
+export const productTools: Tool[] = [
+  {
+    name: 'search_products',
+    description: `
+<usecase>
+Search for products and services.
+Use when: Finding products by name, code, or category for use in invoices.
+Do NOT use when: You have the product ID (use get_product instead).
+</usecase>
+
+<example>
+search_products(query="laptop")
+search_products(category_id="123")
+</example>
+
+<returns>
+List of products with: id, name, code, list_price, currency, vat_rate, unit.
+Use the ID in create_invoice lines.
+</returns>
+    `.trim(),
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Search by name or code' },
+        category_id: { type: 'string', description: 'Filter by category' },
+        page: { type: 'number', default: 1 },
+        limit: { type: 'number', default: 100 },
+      },
+    },
+  },
+  {
+    name: 'get_product',
+    description: `
+<usecase>
+Get detailed information about a product including inventory levels.
+Use when: You have a product ID and need full details or stock info.
+Do NOT use when: You don't have the ID yet (use search_products first).
+</usecase>
+
+<example>
+get_product(id="12345")
+</example>
+
+<returns>
+Full product: id, name, code, list_price, currency, vat_rate, unit, initial_stock_count, barcode.
+</returns>
+    `.trim(),
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Product ID' },
+      },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'create_product',
+    description: `
+<usecase>
+Create a new product or service.
+Use when: Adding a new product that can be reused across invoices.
+Do NOT use when: One-time line item (add directly to invoice lines instead).
+</usecase>
+
+<instructions>
+- name: Product name (required)
+- list_price: Default selling price
+- unit: Measurement unit (Adet, Kg, Lt, etc.)
+- vat_rate: VAT percentage
+- currency: Must be TRL, USD, EUR, or GBP
+</instructions>
+
+<example>
+create_product(name="Consulting Hour", list_price=500, unit="Saat", vat_rate=20)
+</example>
+
+<returns>
+Created product with: id, name, code.
+Use the ID in create_invoice lines for faster invoicing.
+</returns>
+    `.trim(),
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        code: { type: 'string' },
+        unit: { type: 'string', default: 'Adet' },
+        list_price: { type: 'number' },
+        currency: { type: 'string', enum: ['TRL', 'USD', 'EUR', 'GBP'], description: 'Currency. MUST be one of: TRL, USD, EUR, GBP' },
+        vat_rate: { type: 'number', default: 20 },
+        category_id: { type: 'string' },
+        barcode: { type: 'string' },
+      },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'update_product',
+    description: `
+<usecase>
+Update an existing product's information.
+Use when: Changing price, name, or other product details.
+Do NOT use when: Creating a new product (use create_product instead).
+</usecase>
+
+<example>
+update_product(id="12345", list_price=600)
+</example>
+
+<returns>
+Updated product with: id, name, and list of updated_fields.
+</returns>
+    `.trim(),
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string' },
+        name: { type: 'string' },
+        code: { type: 'string' },
+        list_price: { type: 'number' },
+        vat_rate: { type: 'number' },
+      },
+      required: ['id'],
+    },
+  },
+];
+
+// ============================================================================
+// Handlers
+// ============================================================================
+
+export async function handleSearchProducts(args: unknown): Promise<ToolResponse> {
+  try {
+    const params = SearchProductsSchema.parse(args);
+    const client = getClient();
+
+    const filter: Record<string, string> = {};
+    if (params.query) filter['name'] = params.query;
+    if (params.category_id) filter['category_id'] = params.category_id;
+
+    const response = await client.products.list({
+      filter,
+      page: { number: params.page, size: params.limit },
+    });
+
+    return formatList(response.data, {
+      totalCount: response.meta.total_count,
+      currentPage: response.meta.current_page,
+      totalPages: response.meta.total_pages,
+    }, {
+      itemFormatter: formatProductSummary,
+      nextSteps: [
+        { action: 'Get product details', example: 'get_product(id="<id>")' },
+        { action: 'Use in invoice', example: 'create_invoice(..., lines=[{product_id="<id>", ...}])' },
+      ],
+    });
+  } catch (error) {
+    return handleError(error, { operation: 'Search products', resourceType: 'Product' });
+  }
+}
+
+export async function handleGetProduct(args: unknown): Promise<ToolResponse> {
+  try {
+    const params = GetProductSchema.parse(args);
+    const client = getClient();
+
+    const response = await client.products.get(params.id, {
+      include: ['category', 'inventory_levels'],
+    });
+
+    if (!response.data) {
+      return formatNotFound('Product', params.id, [
+        { action: 'Search products', example: 'search_products()' },
+      ]);
+    }
+
+    const product = response.data;
+    return formatSuccess({
+      id: product.id,
+      name: product.attributes.name,
+      code: product.attributes.code,
+      list_price: product.attributes.list_price,
+      currency: product.attributes.currency,
+      vat_rate: product.attributes.vat_rate,
+      unit: product.attributes.unit,
+      initial_stock_count: product.attributes.initial_stock_count,
+      barcode: product.attributes.barcode,
+    }, {
+      summary: `Product: ${product.attributes.name}`,
+      nextSteps: [
+        { action: 'Check stock levels', example: `get_stock_levels(product_id="${product.id}")` },
+      ],
+    });
+  } catch (error) {
+    return handleError(error, { operation: 'Get product', resourceType: 'Product' });
+  }
+}
+
+export async function handleCreateProduct(args: unknown): Promise<ToolResponse> {
+  try {
+    const params = CreateProductSchema.parse(args);
+    const client = getClient();
+
+    const response = await client.products.create({
+      data: {
+        type: 'products',
+        attributes: {
+          name: params.name,
+          ...(params.code !== undefined && { code: params.code }),
+          unit: params.unit,
+          ...(params.list_price !== undefined && { list_price: params.list_price }),
+          currency: params.currency,
+          vat_rate: params.vat_rate,
+          ...(params.barcode !== undefined && { barcode: params.barcode }),
+        },
+        ...(params.category_id !== undefined && {
+          relationships: {
+            category: { data: { id: params.category_id, type: 'item_categories' } }
+          }
+        }),
+      },
+    });
+
+    return formatCreated('Product', {
+      id: response.data.id,
+      name: response.data.attributes.name,
+      code: response.data.attributes.code,
+    }, [
+      { action: 'Use in invoice', example: `create_invoice(..., lines=[{product_id="${response.data.id}", ...}])` },
+    ]);
+  } catch (error) {
+    return handleError(error, { operation: 'Create product', resourceType: 'Product' });
+  }
+}
+
+export async function handleUpdateProduct(args: unknown): Promise<ToolResponse> {
+  try {
+    const params = UpdateProductSchema.parse(args);
+    const client = getClient();
+
+    const attributes: Record<string, unknown> = {};
+    if (params.name !== undefined) attributes['name'] = params.name;
+    if (params.code !== undefined) attributes['code'] = params.code;
+    if (params.list_price !== undefined) attributes['list_price'] = params.list_price;
+    if (params.vat_rate !== undefined) attributes['vat_rate'] = params.vat_rate;
+
+    const response = await client.products.update(params.id, {
+      data: {
+        id: params.id,
+        type: 'products',
+        attributes,
+      },
+    });
+
+    return formatSuccess({
+      id: response.data.id,
+      name: response.data.attributes.name,
+      updated_fields: Object.keys(attributes),
+    }, { summary: 'Product updated' });
+  } catch (error) {
+    return handleError(error, { operation: 'Update product', resourceType: 'Product' });
+  }
+}

package/packages/parasut-mcp-server/src/utils/errors.ts

@@ -0,0 +1,296 @@
+/**
+ * Error Handling Utilities
+ *
+ * Converts SDK errors to MCP tool responses with recovery guidance.
+ * Every error should teach the user how to fix the problem.
+ */
+
+import {
+  ParasutApiError,
+  ParasutAuthError,
+  ParasutNotFoundError,
+  ParasutRateLimitError,
+  ParasutValidationError,
+  ParasutNetworkError,
+} from '@yigitkonur/parasut-node-sdk';
+import type { ToolResponse } from './response.js';
+
+export interface NextStep {
+  action: string;
+  example?: string;
+}
+
+export interface ErrorMetadata {
+  error_code: string;
+  recoverable: boolean;
+  retry_after_ms?: number;
+}
+
+/**
+ * Converts any error to an MCP tool error response.
+ * Provides context-specific recovery guidance.
+ */
+export function handleError(
+  error: unknown,
+  context?: {
+    operation?: string;
+    resourceType?: string;
+    suggestions?: NextStep[];
+  }
+): ToolResponse {
+  // Handle SDK errors
+  if (error instanceof ParasutNotFoundError) {
+    return handleNotFoundError(error, context);
+  }
+
+  if (error instanceof ParasutValidationError) {
+    return handleValidationError(error, context);
+  }
+
+  if (error instanceof ParasutAuthError) {
+    return handleAuthError(error);
+  }
+
+  if (error instanceof ParasutRateLimitError) {
+    return handleRateLimitError(error);
+  }
+
+  if (error instanceof ParasutNetworkError) {
+    return handleNetworkError(error);
+  }
+
+  if (error instanceof ParasutApiError) {
+    return handleApiError(error, context);
+  }
+
+  // Handle unknown errors
+  return handleUnknownError(error, context);
+}
+
+function handleNotFoundError(
+  error: ParasutNotFoundError,
+  context?: { resourceType?: string; suggestions?: NextStep[] }
+): ToolResponse {
+  const resourceType = context?.resourceType ?? 'Resource';
+  const suggestions = context?.suggestions ?? [];
+
+  const parts: string[] = [
+    `Error: ${resourceType} not found.`,
+    '',
+    'Possible causes:',
+    '- The ID may be incorrect or misspelled',
+    '- The resource may have been deleted',
+    '- You may not have access to this resource',
+  ];
+
+  if (suggestions.length > 0) {
+    parts.push('', 'Try:');
+    for (const step of suggestions) {
+      if (step.example) {
+        parts.push(`- ${step.action}: ${step.example}`);
+      } else {
+        parts.push(`- ${step.action}`);
+      }
+    }
+  }
+
+  // Include original error details if available
+  if (error.errors?.length) {
+    parts.push('', 'Details:');
+    for (const err of error.errors) {
+      parts.push(`- ${err.title}: ${err.detail}`);
+    }
+  }
+
+  return {
+    content: [{ type: 'text', text: parts.join('\n') }],
+    isError: true,
+  };
+}
+
+function handleValidationError(
+  error: ParasutValidationError,
+  context?: { operation?: string }
+): ToolResponse {
+  const operation = context?.operation ?? 'Operation';
+
+  const parts: string[] = [
+    `Error: ${operation} failed due to validation errors.`,
+    '',
+    'Issues found:',
+  ];
+
+  if (error.errors?.length) {
+    for (const err of error.errors) {
+      parts.push(`- ${err.title}: ${err.detail}`);
+    }
+  } else {
+    parts.push('- Unknown validation error');
+  }
+
+  parts.push(
+    '',
+    'Fix: Check the parameter values and try again.',
+    'Common issues:',
+    '- Required fields are missing',
+    '- Values are in wrong format (e.g., date should be YYYY-MM-DD)',
+    '- Referenced IDs (contact, product) do not exist'
+  );
+
+  return {
+    content: [{ type: 'text', text: parts.join('\n') }],
+    isError: true,
+  };
+}
+
+function handleAuthError(_error: ParasutAuthError): ToolResponse {
+  const parts: string[] = [
+    'Error: Authentication failed.',
+    '',
+    'Possible causes:',
+    '- Your credentials may be incorrect',
+    '- Your OAuth token may have expired',
+    '- Your account may not have access to this resource',
+    '',
+    'Fix: Check your Paraşüt credentials and try again.',
+    '',
+    'Required environment variables:',
+    '- PARASUT_COMPANY_ID',
+    '- PARASUT_CLIENT_ID',
+    '- PARASUT_CLIENT_SECRET',
+    '- PARASUT_USERNAME',
+    '- PARASUT_PASSWORD',
+  ];
+
+  return {
+    content: [{ type: 'text', text: parts.join('\n') }],
+    isError: true,
+  };
+}
+
+function handleRateLimitError(error: ParasutRateLimitError): ToolResponse {
+  const retryAfterMs = error.retryAfterMs ?? 10000;
+  const retryAfter = Math.ceil(retryAfterMs / 1000);
+
+  const parts: string[] = [
+    'Error: Rate limit exceeded.',
+    '',
+    `Limit: The API allows 10 requests per 10 seconds.`,
+    `Retry in: ${retryAfter} seconds`,
+    '',
+    'Recommendation:',
+    '- Wait a few seconds before retrying',
+    '- Consider batching multiple operations',
+    '- Use search filters to reduce the number of requests',
+  ];
+
+  return {
+    content: [{ type: 'text', text: parts.join('\n') }],
+    isError: true,
+    metadata: {
+      error_code: 'RATE_LIMITED',
+      recoverable: true,
+      retry_after_ms: retryAfterMs,
+    } as ErrorMetadata,
+  };
+}
+
+function handleNetworkError(error: ParasutNetworkError): ToolResponse {
+  const parts: string[] = [
+    'Error: Network connection failed.',
+    '',
+    'Possible causes:',
+    '- No internet connection',
+    '- Paraşüt API is temporarily unavailable',
+    '- DNS resolution failed',
+    '',
+    'Fix: Check your internet connection and try again.',
+    '',
+    'If the problem persists:',
+    '- Check https://status.parasut.com for service status',
+    '- Try again in a few minutes',
+  ];
+
+  if (error.cause) {
+    parts.push('', `Technical details: ${String(error.cause)}`);
+  }
+
+  return {
+    content: [{ type: 'text', text: parts.join('\n') }],
+    isError: true,
+  };
+}
+
+function handleApiError(
+  error: ParasutApiError,
+  context?: { operation?: string }
+): ToolResponse {
+  const operation = context?.operation ?? 'API request';
+
+  const parts: string[] = [
+    `Error: ${operation} failed (HTTP ${error.status}).`,
+    '',
+  ];
+
+  if (error.errors?.length) {
+    parts.push('Details:');
+    for (const err of error.errors) {
+      parts.push(`- ${err.title}: ${err.detail}`);
+    }
+  } else {
+    parts.push(`Status: ${error.status}`);
+    parts.push(`Message: ${error.message}`);
+  }
+
+  parts.push('', 'If this error persists, check:');
+  parts.push('- The resource IDs are correct');
+  parts.push('- You have the necessary permissions');
+  parts.push('- The data format matches the API requirements');
+
+  return {
+    content: [{ type: 'text', text: parts.join('\n') }],
+    isError: true,
+  };
+}
+
+function handleUnknownError(
+  error: unknown,
+  context?: { operation?: string }
+): ToolResponse {
+  const operation = context?.operation ?? 'Operation';
+  const message =
+    error instanceof Error ? error.message : 'An unknown error occurred';
+
+  const parts: string[] = [
+    `Error: ${operation} failed unexpectedly.`,
+    '',
+    `Details: ${message}`,
+    '',
+    'This may be a bug. If the problem persists:',
+    '- Check the parameters are correct',
+    '- Try the operation again',
+    '- Report the issue if it continues',
+  ];
+
+  return {
+    content: [{ type: 'text', text: parts.join('\n') }],
+    isError: true,
+  };
+}
+
+/**
+ * Wraps an async handler with error handling.
+ * Converts all errors to proper MCP tool responses.
+ */
+export function withErrorHandling<T extends unknown[], R>(
+  handler: (...args: T) => Promise<R>,
+  context?: { operation?: string; resourceType?: string }
+): (...args: T) => Promise<R | ToolResponse> {
+  return async (...args: T) => {
+    try {
+      return await handler(...args);
+    } catch (err) {
+      return handleError(err, context);
+    }
+  };
+}