Merge pull request #256 from SheetMetalConnect/claude/debug-mcp-server-demo-018CzTp8C4coR3tUhLiziKM5

Debug MCP server and prepare demo

Author: SheetMetalConnect

mcp-server/README.md

@@ -2,9 +2,12 @@
 
 Model Context Protocol (MCP) server for Eryxon Flow Manufacturing Execution System.
 
-## Version 2.1.0 - OpenAI Chat Integration
+## Version 2.3.0 - Agent Batch & ERP Integration
 
-This version adds AI-powered chat capabilities using OpenAI for natural language queries and manufacturing data analysis.
+This version adds:
+- **Agent-optimized batch operations** for AI assistants to efficiently manage jobs, parts, and shipments
+- **ERP synchronization tools** for bidirectional data sync with external systems
+- **Caching layer** for improved performance
 
 ## Architecture
 
@@ -21,17 +24,20 @@ src/
 │   ├── issues.ts         # Issues/NCR domain (4 tools)
 │   ├── substeps.ts       # Substeps domain (5 tools)
 │   ├── dashboard.ts      # Dashboard/Analytics (3 tools)
-│   └── chat.ts           # AI Chat/OpenAI (5 tools) - NEW
+│   ├── chat.ts           # AI Chat/OpenAI (5 tools)
+│   ├── erp-sync.ts       # ERP Integration (6 tools) - NEW in v2.2.0
+│   └── agent-batch.ts    # Agent Batch Operations (16 tools) - NEW in v2.3.0
 ├── types/
 │   └── index.ts          # Shared TypeScript types
 └── utils/
     ├── index.ts          # Utility exports
     ├── supabase.ts       # Supabase client configuration
     ├── response.ts       # Response helper functions
-    └── openai.ts         # OpenAI client configuration - NEW
+    ├── openai.ts         # OpenAI client configuration
+    └── cache.ts          # Cache abstraction layer (Redis/in-memory)
 ```
 
-## Available Tools (33 total)
+## Available Tools (55 total)
 
 ### Jobs Management (7 tools)
 - **fetch_jobs** - Retrieve jobs with optional status filtering
@@ -75,13 +81,42 @@ src/
 - **get_qrm_data** - Get Quick Response Manufacturing capacity data
 - **get_production_metrics** - Get production metrics for a time period
 
-### AI Chat (5 tools) - NEW in v2.1.0
+### AI Chat (5 tools)
 - **chat_query** - Ask natural language questions about manufacturing data
 - **chat_summarize_jobs** - Get AI-generated summary of job status and metrics
 - **chat_analyze_quality** - Get AI analysis of quality issues and NCR patterns
 - **chat_explain_data** - Get AI explanation of specific entities (job, part, operation, issue)
 - **chat_suggest_actions** - Get AI-suggested actions based on production state
 
+### ERP Synchronization (6 tools) - NEW in v2.2.0
+- **erp_sync_diff** - Compare external ERP data with local database and report differences
+- **erp_sync_execute** - Execute bidirectional sync for jobs, parts, and operations
+- **erp_lookup_external_id** - Find local entity by external ERP ID
+- **erp_sync_status** - Get synchronization status and history for an entity
+- **erp_batch_lookup** - Batch lookup multiple external IDs at once
+- **erp_resolve_ids** - Resolve external IDs to local IDs for efficient processing
+
+### Agent Batch Operations (16 tools) - NEW in v2.3.0
+
+Optimized tools for AI assistants to perform complex multi-step operations efficiently:
+
+- **batch_update_parts** - Update multiple parts in a single call
+- **batch_reschedule_operations** - Reschedule multiple operations efficiently
+- **prioritize_job** - Set job priority and bullet card status for rush orders
+- **fetch_parts_by_customer** - Find all parts for a customer across jobs
+- **batch_complete_operations** - Complete multiple operations in one call
+- **get_job_overview** - Get comprehensive job summary with parts and operations
+- **check_resource_availability** - Check availability of machines, personnel, and tooling
+- **assign_resource_to_operations** - Assign resources to multiple operations
+- **get_shipping_status** - Get shipping status with job details
+- **manage_shipment** - Create, update, or add jobs to shipments
+- **get_jobs_ready_for_shipping** - Find jobs ready for shipping
+- **get_cell_capacity** - Get manufacturing cell capacity and utilization
+- **plan_shipping** - Plan optimal shipping dates based on job completion estimates
+- **find_shipping_consolidation** - Find opportunities to consolidate shipments
+- **get_parts_due_soon** - Get parts due within a specified timeframe
+- **suggest_reschedule** - Get AI-suggested reschedule based on delays and constraints
+
 ## Setup
 
 1. Install dependencies:
@@ -97,6 +132,9 @@ export SUPABASE_SERVICE_KEY="your-service-key-here"
 
 # Optional: For AI chat features
 export OPENAI_API_KEY="your-openai-api-key"
+
+# Optional: For Redis caching (defaults to in-memory)
+export REDIS_URL="redis://localhost:6379"
 ```
 
 3. Build the server:
@@ -161,7 +199,7 @@ Use the create_ncr tool with operation_id, title, and severity
 Use the get_qrm_data tool to see cell capacity utilization
 ```
 
-### AI Chat Examples (NEW)
+### AI Chat Examples
 
 #### Ask a natural language question
 ```
@@ -177,26 +215,61 @@ Use chat_summarize_jobs with:
 - focus: "delays"
 ```
 
-#### Analyze quality patterns
+### ERP Sync Examples (NEW)
+
+#### Check differences before syncing
+```
+Use erp_sync_diff with:
+- entity_type: "jobs"
+- external_data: [...array of ERP job records...]
+```
+
+#### Execute bidirectional sync
+```
+Use erp_sync_execute with:
+- jobs: [...ERP job records...]
+- parts: [...ERP part records...]
+- options: { skip_unchanged: true, continue_on_error: true }
+```
+
+#### Find entity by external ID
 ```
-Use chat_analyze_quality with:
-- time_period: "this_month"
-- include_recommendations: true
+Use erp_lookup_external_id with:
+- entity_type: "jobs"
+- external_id: "ERP-JOB-123"
+- external_source: "SAP"
 ```
 
-#### Explain a specific entity
+### Agent Batch Examples (NEW)
+
+#### Prioritize a rush job
 ```
-Use chat_explain_data with:
-- entity_type: "job"
-- entity_id: "job-uuid-here"
-- detail_level: "detailed"
+Use prioritize_job with:
+- job_number: "JOB-2024-0001"
+- priority: "urgent"
+- set_bullet_card: true
+- notes: "Customer requested expedited delivery"
 ```
 
-#### Get action suggestions
+#### Get parts due soon
 ```
-Use chat_suggest_actions with:
-- focus_area: "bottlenecks"
-- max_suggestions: 5
+Use get_parts_due_soon with:
+- days_ahead: 3
+- include_in_progress: true
+```
+
+#### Check resource availability
+```
+Use check_resource_availability with:
+- resource_type: "machine"
+- include_usage: true
+```
+
+#### Plan shipping
+```
+Use plan_shipping with:
+- job_ids: ["uuid1", "uuid2"]
+- consolidate: true
 ```
 
 ## Adding New Tools
@@ -250,15 +323,17 @@ The module includes specialized system prompts for different contexts:
 - **production** - Production planning and scheduling
 - **general** - General assistance
 
-### Chat Tool Features
+## Caching
+
+Version 2.2.0+ includes a caching layer that supports:
+
+- **In-memory cache** - Default, no configuration needed
+- **Redis** - Set `REDIS_URL` environment variable
 
-| Tool | Database Access | AI Analysis | Output |
-|------|----------------|-------------|--------|
-| chat_query | Optional | Yes | Natural language response |
-| chat_summarize_jobs | Yes | Yes | Summary + statistics |
-| chat_analyze_quality | Yes | Yes | Analysis + recommendations |
-| chat_explain_data | Yes | Yes | Explanation + raw data |
-| chat_suggest_actions | Yes | Yes | Action items + context |
+Cache is used for:
+- Frequent lookups (external IDs, entity mappings)
+- Prefetched data during batch operations
+- Temporary sync state
 
 ## Development
 
@@ -269,12 +344,14 @@ The module includes specialized system prompts for different contexts:
 ## Tech Stack
 
 - TypeScript 5.x
-- @modelcontextprotocol/sdk 1.0.4
-- @supabase/supabase-js 2.80.0
-- openai 4.70.0 - NEW
+- @modelcontextprotocol/sdk 1.24.3
+- @supabase/supabase-js 2.86.2
+- openai 6.10.0
 
 ## Version History
 
+- **2.3.0** - Agent-optimized batch operations (55 tools in 10 modules)
+- **2.2.0** - ERP synchronization and caching (39 tools in 9 modules)
 - **2.1.0** - OpenAI chat integration (33 tools in 8 modules)
 - **2.0.0** - Modular architecture refactor (28 tools in 7 modules)
 - **1.0.0** - Initial monolithic implementation