Add MCP CLI for batch request management

MCP_IMPLEMENTATION.md

@@ -0,0 +1,120 @@
+# MCP CLI Implementation Summary
+
+## Overview
+Successfully implemented an MCP (Model Context Protocol) command-line interface for the batchata library that provides batch request management functionality.
+
+## Features Implemented
+
+### 1. Core Commands
+- **create**: Create new batch requests with model and parameters
+- **list**: Display all batch requests with status information  
+- **results**: Retrieve results for completed batches
+- **cancel**: Cancel running batch requests
+
+### 2. Parameter Support
+- Model specification (required)
+- Message arrays in JSON format
+- File path + prompt combinations
+- Model parameters: temperature, max-tokens, max-output-tokens
+- Custom state directory configuration
+
+### 3. Output Formats
+- Table format (default for list)
+- JSON format (default for results, optional for list)
+- Human-readable status information
+
+### 4. State Management
+- Local directory-based persistence (default: `./.batchata`)
+- Metadata tracking for all batch requests
+- Integration with existing batchata state management
+
+## Technical Implementation
+
+### Architecture
+- Minimal changes to existing codebase
+- New CLI module in `batchata/cli/`
+- Leverages existing Batch, BatchRun infrastructure
+- Clean separation between CLI and core functionality
+
+### Files Added
+```
+batchata/cli/
+├── __init__.py          # CLI module exports
+├── mcp.py              # Main MCP CLI implementation  
+└── demo.py             # Demo script
+
+tests/
+├── test_mcp_cli.py     # Unit tests
+└── test_mcp_integration.py  # Integration tests
+```
+
+### Entry Point
+Added `batchata-mcp` command to pyproject.toml scripts section.
+
+## Usage Examples
+
+```bash
+# Create batch with messages
+batchata-mcp create --model claude-sonnet-4-20250514 \
+  --messages '[{"role": "user", "content": "Hello"}]' \
+  --temperature 0.7
+
+# Create batch with file
+batchata-mcp create --model gpt-4o-2024-08-06 \
+  --file document.pdf --prompt "Summarize this document"
+
+# List all batches (table format)
+batchata-mcp list
+
+# List all batches (JSON format)  
+batchata-mcp list --format json
+
+# Get results for specific batch
+batchata-mcp results <batch_id>
+
+# Cancel running batch
+batchata-mcp cancel <batch_id>
+```
+
+## Validation & Error Handling
+
+- Model validation against supported providers
+- Required parameter validation (messages XOR file+prompt)
+- JSON parsing validation for messages
+- Graceful handling of missing batches
+- Comprehensive error messages
+
+## Testing
+
+### Unit Tests (7 tests)
+- State directory creation
+- Empty list handling
+- Create command with messages
+- Create command with file+prompt
+- Parameter validation
+- Missing batch error handling
+
+### Integration Tests (5 scenarios)
+- End-to-end CLI workflow testing
+- Command-line argument parsing
+- Error condition validation
+- Cross-command interaction testing
+
+## Benefits
+
+1. **Minimal Impact**: No changes to core batchata functionality
+2. **Complete Feature Set**: All required MCP commands implemented
+3. **Robust Error Handling**: Comprehensive validation and error messages
+4. **Extensible Design**: Easy to add new commands or parameters
+5. **Documentation**: Full help system with examples
+6. **Testing**: Comprehensive test coverage
+
+## Future Enhancements
+
+1. Support for batch job templates
+2. Progress monitoring for long-running batches
+3. Bulk operations (create multiple batches)
+4. Export/import of batch configurations
+5. Integration with external MCP servers
+
+The implementation successfully meets all requirements from the issue while maintaining code quality and following the project's architecture patterns.

README.md

@@ -179,6 +179,50 @@ from batchata import Batch
 # Your API keys will now be loaded from .env
 ```
 
+## MCP CLI
+
+Batchata includes an MCP (Model Context Protocol) command-line interface for managing batch requests:
+
+```bash
+# Create a batch with messages
+batchata-mcp create --model claude-sonnet-4-20250514 --messages '[{"role": "user", "content": "Hello"}]'
+
+# Create a batch with file and prompt
+batchata-mcp create --model gpt-4o-2024-08-06 --file document.pdf --prompt "Summarize this document"
+
+# Add model parameters
+batchata-mcp create --model claude-sonnet-4-20250514 --messages '[{"role": "user", "content": "Hello"}]' --temperature 0.7 --max-tokens 1000
+
+# List all batches
+batchata-mcp list
+
+# Get results for a specific batch
+batchata-mcp results <batch_id>
+
+# Cancel a running batch
+batchata-mcp cancel <batch_id>
+```
+
+### MCP Commands
+
+- **create**: Create a new batch request with specified model and parameters
+- **list**: List all batch requests with status information
+- **results**: Retrieve results for a completed batch
+- **cancel**: Cancel a running batch request
+
+### MCP Parameters
+
+- `--model`: Required. Model to use (e.g., "claude-sonnet-4-20250514", "gpt-4o-2024-08-06")
+- `--messages`: JSON array of messages for direct text processing
+- `--file` + `--prompt`: File path and prompt for document processing
+- `--temperature`: Model temperature parameter
+- `--max-tokens`: Maximum input tokens
+- `--max-output-tokens`: Maximum output tokens
+- `--state-dir`: Directory to store batch state (default: `./.batchata`)
+
+The MCP CLI stores batch state and results in a local directory, allowing you to track and manage multiple batch requests over time.
+```
+
 ## Limitations
 
 - Field/citation mapping is heuristic, which means it isn't perfect.

batchata/cli/__init__.py

@@ -0,0 +1,5 @@
+"""CLI interface for batchata."""
+
+from .mcp import main as mcp_main
+
+__all__ = ["mcp_main"]

batchata/cli/demo.py

@@ -0,0 +1,64 @@
+"""Demo of MCP CLI functionality."""
+
+import json
+import tempfile
+from pathlib import Path
+
+from batchata.cli.mcp import MCPCommands
+
+
+def demo_mcp_cli():
+    """Demo the MCP CLI functionality."""
+    print("=== Batchata MCP CLI Demo ===\n")
+
+    # Use a temporary directory for demo
+    with tempfile.TemporaryDirectory() as temp_dir:
+        mcp = MCPCommands(state_dir=temp_dir)
+
+        print("1. Listing empty batches:")
+        batches = mcp.list()
+        print(f"   Found {len(batches)} batches\n")
+
+        # Create some demo metadata files to simulate batches
+        demo_batch_id = "demo-batch-12345"
+        metadata = {
+            "batch_id": demo_batch_id,
+            "model": "claude-sonnet-4-20250514",
+            "created_at": "2025-01-26T15:30:00",
+            "state_file": str(mcp.batches_dir / f"{demo_batch_id}_state.json"),
+            "results_dir": str(mcp.batches_dir / demo_batch_id),
+            "kwargs": {"temperature": 0.7, "max_tokens": 1000}
+        }
+
+        metadata_file = mcp.batches_dir / f"{demo_batch_id}_metadata.json"
+        with open(metadata_file, 'w') as f:
+            json.dump(metadata, f, indent=2)
+
+        print("2. Listing batches after creating demo metadata:")
+        batches = mcp.list()
+        print(f"   Found {len(batches)} batches")
+        if batches:
+            batch = batches[0]
+            print(f"   - Batch ID: {batch['batch_id']}")
+            print(f"   - Model: {batch['model']}")
+            print(f"   - Created: {batch['created_at']}")
+            print(f"   - Status: {batch['status']}")
+
+        print("\n3. Testing results for demo batch:")
+        try:
+            results = mcp.results(demo_batch_id)
+            print(f"   Results: {json.dumps(results, indent=2)}")
+        except Exception as e:
+            print(f"   Expected error (no state file): {e}")
+
+        print("\n4. Testing validation:")
+        try:
+            mcp.create(model="test-model")  # Should fail - no messages or file
+        except ValueError as e:
+            print(f"   Expected validation error: {e}")
+
+        print("\n=== Demo Complete ===")
+
+
+if __name__ == "__main__":
+    demo_mcp_cli()