This is a Python SDK (not an MCP server). The codebase defines a PurchaseIntentClient class with two methods (score, batch_score) that lack proper MCP tool registration, transport implementation, and protocol structure. Tool descriptions exist but are minimal; parameter descriptions are present in docstrings but not in formalized schemas. No evidence of MCP protocol compliance, error handling patterns, or structured output schemas. The code appears to be a standalone Python library, not an MCP server exposing tools to agents.
Not an MCP server, no MCP protocol implementation detected. The repo contains only a Python SDK/client library with no transport layer, tool registration mechanism, or MCP-compliant endpoint.
Parameter schemas not formally defined. Tool parameters are documented in docstrings (session, historical, context) but lack JSON Schema type definitions, required/optional flags, and structured constraints. No enum definitions for constrained fields (device, referral_source, day_of_week).
Output schema not documented. Both tools return dicts (intent_score, intent_tier, top_signals, recommended_interventions, signal_breakdown) but no formal output schema is provided. LLMs cannot reliably parse or chain results without documented field types and structure.
scorebatch_score
Recommendations
Convert this Python SDK into an actual MCP server. Define an MCP transport (Streamable HTTP recommended) and register tools with proper MCP protocol handshake.
Create formal JSON Schema for tool inputs. Define 'session' as an object with required fields (pages_viewed: integer, time_on_site_sec: integer, product_views: integer, cart_adds: integer, search_queries: integer, is_returning: boolean). Define 'historical' and 'context' as optional objects with typed fields. Use enum for 'device' (mobile|desktop|tablet) and 'referral_source' (google_shopping|google_search|email|direct|social|affiliate|display).
Add input validation and error responses. Example: if 'session' is missing required keys, return 'Error: Missing required session field: cart_adds (integer). Required session fields: pages_viewed, time_on_site_sec, product_views, cart_adds, search_queries, is_returning.' rather than silently defaulting.
Enhance 'score' description from generic to LLM-actionable: 'Score a visitor's purchase intent from behavioral signals (cart adds, product views, search, time on site) and historical data (past purchases, recency). Returns intent_score (0-100), tier (hot/warm/cool/cold), top contributing signals, and recommended interventions. Use this to prioritize high-intent visitors for targeted outreach.'
Minimal error handling. Neither tool validates inputs or returns structured error responses. Invalid session/context data silently defaults to zero contributions rather than raising actionable errors. No guidance for recovery (e.g., 'session dict missing required keys').
Generic batch tool naming. 'batch_score' lacks a clear verb and doesn't follow verb_noun convention. Better: 'score_batch' or 'bulk_score' to clarify it scores multiple visitors in one call.
Parameter format constraints not documented. 'device' accepts mobile/desktop/tablet; 'referral_source' has a predefined set (google_shopping, email, etc.); day_of_week should be enum. These should be declared as enums with validation, not free-form strings.
Tool description for 'batch_score' is single sentence with no detail. Should explain: accepts list of visitor dicts, returns results sorted by intent_score, any limits on batch size (if applicable).
No idempotency guarantees. Both tools perform stateless scoring calculations, which is naturally idempotent, but this is never documented. LLMs need to know repeated calls with same input always produce same output.
scorebatch_score
Rename 'batch_score' to 'score_batch' for clarity. Describe behavior: 'Score multiple visitors in one call. Accepts array of visitor objects (each with visitor_id, session, historical, context). Returns results sorted by intent_score descending, with visitor_id preserved for tracking.'
Add per-parameter descriptions inline. For example, context.referral_source should note: 'Source of visitor traffic (enum: google_shopping, google_search, email, direct, social, affiliate, display). Influences intent weighting.'
Document intervention logic. The tool selects recommendations based on intent_score and tier. Include in description: 'Hot-tier visitors (85+) see proactive interventions (exit popups, live chat). Warm (65+) see decision-aids (comparisons, deadlines). Cool (40+) see trust signals. Cold (<40) see awareness content.'
Add a bounds/limit note to batch_score: 'Maximum 1000 visitors per call. Results capped at 10,000 rows to prevent context overflow.'
Declare tool as READ_ONLY and IDEMPOTENT in annotations (when MCP server is implemented). Both tools only read data and compute scores; they do not modify external state.