Model Context Protocol (MCP)

// MCP tool naming examples
get_customer_by_email
search_products_by_category
calculate_shipping_cost_for_order
send_notification_to_user

// Bad: Vague tool definition
mcp.registerTool(
    'get_data',
    {
        title: 'Get Data',
        description: 'Get data.',  // ❌ Too vague!
        inputSchema: {
            id: z.string()
        }
    },
    async (args) => { /* ... */ }
);

// Good: Comprehensive tool definition
const customerSchema = {
    customer_id: z.string().describe(
        'Customer ID in format CUST-##### (e.g., "CUST-12345")'
    )
};

mcp.registerTool(
    'get_customer_by_id',
    {
        title: 'Get Customer By ID',
        description: `Retrieve customer account information by customer ID.
        
        Use this when:
        - You have a customer ID and need their details
        - User mentions "my account" (look up by context)
        
        Do NOT use for:
        - Searching by name/email (use search_customers instead)
        - Getting order history (use get_customer_orders instead)
        
        Returns: Customer object with name, email, phone, address, account_status
        
        Example:
          Input: customer_id="CUST-12345"
          Output: { name: "Alice Johnson", email: "alice@example.com", account_status: "active" }`,
        inputSchema: customerSchema
    },
    async (args) => {
        const customer = await customerDb.findById(args.customer_id);
        return { content: [{ type: "text", text: JSON.stringify(customer) }] };
    }
);

// Anti-pattern: Too many parameters (10) - agent will struggle
const complexOrderSchema = {
    customer_id: z.string(),
    product_ids: z.array(z.string()),
    quantities: z.array(z.number()),
    shipping_address: z.object({}),
    billing_address: z.object({}),
    payment_method: z.string(),
    promotional_code: z.string(),
    gift_wrap: z.boolean(),
    gift_message: z.string(),
    shipping_speed: z.string()
};

mcp.registerTool(
    'create_order',
    {
        title: 'Create Order',
        description: '10 parameters - agent will struggle.',
        inputSchema: complexOrderSchema
    },
    async (args) => { /* ... */ }
);

// Better: Break into 3 simple tools (2-3 parameters each)

// Tool 1: Create cart (2 parameters)
mcp.registerTool(
    'create_order_cart',
    {
        title: 'Create Order Cart',
        description: 'Create shopping cart. Returns cart_id. Use this as first step when customer wants to place an order.',
        inputSchema: {
            customer_id: z.string(),
            items: z.array(z.object({ product_id: z.string(), quantity: z.number() }))
        }
    },
    async (args) => {
        const cartId = await createCart(args.customer_id, args.items);
        return { content: [{ type: "text", text: cartId }] };
    }
);

// Tool 2: Set shipping (3 parameters)
mcp.registerTool(
    'set_cart_shipping',
    {
        title: 'Set Cart Shipping',
        description: 'Set shipping details for cart. Call after create_order_cart, before finalize_order.',
        inputSchema: {
            cart_id: z.string(),
            address: z.object({}),
            speed: z.enum(['standard', 'express', 'overnight'])
        }
    },
    async (args) => {
        await setShipping(args.cart_id, args.address, args.speed);
        return { content: [{ type: "text", text: "Shipping set" }] };
    }
);

// Tool 3: Finalize order (2 parameters)
mcp.registerTool(
    'finalize_order',
    {
        title: 'Finalize Order',
        description: 'Complete order and charge payment. Returns order_id. Final step after cart is configured.',
        inputSchema: {
            cart_id: z.string(),
            payment_method: z.string()
        }
    },
    async (args) => {
        const orderId = await finalizeOrder(args.cart_id, args.payment_method);
        return { content: [{ type: "text", text: orderId }] };
    }
);

// Standard response format for all MCP tools
interface ToolResponse {
    success: boolean;
    data?: any;
    error?: string;
    message: string;
}

mcp.registerTool(
    'example_tool',
    {
        title: 'Example Tool',
        description: 'Tool with consistent response format.',
        inputSchema: { param: z.string() }
    },
    async (args): Promise<ToolResponse> => {
        try {
            const result = await process(args.param);
            return {
                success: true,
                data: result,
                error: undefined,
                message: "Operation completed successfully"
            };
        } catch (e: any) {
            return {
                success: false,
                data: undefined,
                error: e.constructor.name,
                message: `Failed: ${e.message}`
            };
        }
    }
);