AI Agent Documentation

AI Agent Documentation

This directory contains documentation specifically designed for AI agents and developers building AI-powered shopping assistants.

Contents

• MCP_TOOLS.md - Complete reference for all 29 MCP tools available
• GRAPH_SCHEMA.md - Neo4j graph schema and relationships
• DEMO_USERS.md - Pre-configured demo user profiles for testing
• EXAMPLE_QUERIES.md - Common use cases and tool combinations

Quick Reference

Core Capabilities

The Consumer Graph MCP provides 29 tools across these categories:

1. Product Discovery (8 tools)

   • Search products, discover new items, find alternatives
   • Product details, similarities, and brand discovery

2. Offer Management (4 tools)

   • Active offers, retailer offers, offer search
   • Product-to-offer matching and optimization

3. User Context (9 tools)

   • Purchase history, patterns, and timeline
   • Brand/category/retailer preferences
   • Location and household context

4. Recommendations (4 tools)

   • Collaborative filtering
   • Similar products
   • Community insights
   • New product discovery

5. Analytics (4 tools)

   • Spending patterns
   • Category expansion prediction
   • Repurchase prediction
   • Local trending

Getting Started

1. Test MCP Endpoint

curl http://localhost:8081/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

Expected output: List of 29 available tools

2. Test with Demo User

curl http://localhost:8081/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_user_purchase_history",
      "arguments": {"user_id": "DEMO_USER_HEALTH", "limit": 5}
    },
    "id": 2
  }'

3. Integrate with Your Agent

The MCP tools are designed to be called via OpenAI’s native MCP support:

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{
        "role": "user",
        "content": "What products does DEMO_USER_HEALTH usually buy?"
    }],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_user_purchase_history",
            "description": "Get user's purchase history",
            "parameters": {
                "type": "object",
                "properties": {
                    "user_id": {"type": "string"},
                    "limit": {"type": "number"}
                },
                "required": ["user_id"]
            }
        }
    }]
)

Key Concepts

Graph-Based Shopping Intelligence

The system uses a Neo4j knowledge graph to model:

• Users and their shopping behaviors
• Products with attributes, categories, and similarities
• Offers with eligibility rules and point values
• Retailers and venue types
• Communities of similar shoppers
• Categories for product organization
• Households for shared shopping context

Relationship Types

• PURCHASED - User bought product
• HAS_OFFER - Offer applies to product/brand/category
• ELIGIBLE_FOR - User can redeem offer
• SIMILAR_TO - Products with similarity scores
• MEMBER_OF - User in household or community
• SHOPS_AT - User prefers retailer
• IN_CATEGORY - Product belongs to category

Optimization Patterns

The graph uses intermediary nodes (Community, Category) to reduce edge complexity:

• Before: 2,182 edges (direct user-to-product)
• After: 662 edges (user-to-community-to-product)
• Result: 70% reduction, faster queries, better scalability

Common Patterns

Pattern 1: Personalized Recommendations

1. get_user_purchase_history (understand past behavior)
2. get_community_insights (what similar users like)
3. discover_new_products (filtered by preferences)

Pattern 2: Offer-Driven Shopping

1. get_active_offers (eligible offers for user)
2. match_products_to_offers (find products with offers)
3. optimize_offer_activation (maximize points)

Pattern 3: Context-Aware Search

1. get_user_location_context (understand location)
2. search_products (find relevant items)
3. get_local_trending (see what's popular nearby)

Demo Users

Six pre-configured users with distinct profiles:

• DEMO_USER_HEALTH - Health-conscious, organic preferences
• DEMO_USER_FAMILY - Budget-conscious family, bulk buyer
• DEMO_USER_SINGLE - Convenience-oriented, small portions
• DEMO_USER_FOODIE - Specialty items, adventurous
• DEMO_USER_TRADITIONAL - Mainstream brands, weekly routine
• DEMO_USER_ECO - Sustainable, ethical brands

See DEMO_USERS.md for detailed profiles.

Data Volumes

The demo dataset includes:

• Users: 6 demo users + 120+ similar users
• Products: 135+ products across 10 categories
• Offers: 120+ offers with various point values
• Retailers: 8 retailers (grocery, drugstore, warehouse, specialty)
• Communities: 45 shopping communities
• Categories: 47 product categories

Best Practices

For AI Agents

1. Always use user_id - Most tools require user context for personalization
2. Leverage similarities - Use find_similar_products for explainable recommendations
3. Check community - Use get_community_insights for social proof
4. Combine tools - Multi-tool workflows provide richer context
5. Handle empty results - Not all users have data in all categories

For Developers

1. Start with demo users - Use DEMO_USER_* for testing before production
2. Test edge cases - Try users with no purchase history, no offers, etc.
3. Monitor performance - Tools include query performance metadata
4. Validate inputs - Required parameters will return errors if missing
5. Use limits wisely - Default limits balance completeness and performance

Troubleshooting

No tools available

Check that:

1. Neo4j is running (port 7687)
2. Data is loaded (run ./scripts/setup-neo4j.sh)
3. MCP HTTP server is running (port 8081)

Empty results

Check that:

1. User ID exists in database
2. User has purchase history
3. Offers have correct date ranges (active offers)

Slow queries

Check that:

1. Community/Category nodes are created (optimization)
2. Indexes exist on frequently queried properties
3. Limit parameters are set appropriately

Support

For issues or questions:

• Check existing documentation in this directory
• Review example queries in EXAMPLE_QUERIES.md
• Inspect graph directly via Neo4j Browser (http://localhost:7474)