Dice Rolling MCP Server

# Structured Content Implementation ## Overview This document describes the **Minimal Enhancement** implementation of structured content support for the dice-rolling-mcp server, following the OpenAI Apps SDK specification. ## Implementation Status ✅ **Phase 1: Minimal Enhancement (COMPLETED)** - All tools now return `structuredContent` alongside human-readable `content` - Full TypeScript type definitions for all structured content types - Comprehensive test coverage (102 tests passing) - Updated documentation ## What Was Added ### 1. Type Definitions (`src/types.ts`) Four new structured content interfaces: #### `DiceRollStructuredContent` ```typescript { notation: string; // Original dice notation label?: string; // Optional roll label total: number; // Final result rolls: DieRoll[]; // Individual die results with metadata timestamp: string; // ISO timestamp breakdown: string; // Mathematical breakdown critical?: { // Critical hit/fail detection type: 'success' | 'fail'; naturalRoll: number; }; modifier?: number; // Applied modifiers } ``` #### `DiceValidationStructuredContent` ```typescript { notation: string; valid: boolean; expression?: DiceExpression; // Parsed expression (if valid) error?: string; // Error message (if invalid) breakdown?: { // Structured breakdown dice: Array<{ count: number; size: number; modifiers: string[]; }>; modifier: number; }; } ``` #### `SearchResultStructuredContent` ```typescript { query: string; results: Array<{ id: string; title: string; snippet: string; relevance: number; // 0.0-1.0 relevance score }>; totalResults: number; } ``` #### `FetchContentStructuredContent` ```typescript { id: string; title: string; content: string; metadata?: { category?: string; tags?: string[]; lastUpdated?: string; }; } ``` ### 2. Tool Updates (`src/index.ts`) All four tools now return structured content: - **`dice_roll`**: Returns complete roll metadata including critical detection - **`dice_validate`**: Returns validation status and parsed expression - **`search`**: Returns search results with relevance scoring - **`fetch`**: Returns content with metadata ### 3. Test Coverage (`__tests__/structured-content.test.ts`) New test suite with 6 tests covering: - DiceRollStructuredContent structure and values - Critical success/fail detection - DiceValidationStructuredContent for valid and invalid notation - SearchResultStructuredContent with relevance scoring - FetchContentStructuredContent with metadata ### 4. Documentation Updates - Updated `README.md` with structured content information - Added return value documentation for all tools - Created this implementation document ## Usage Example ### Before (text only): ```json { "content": [{ "type": "text", "text": "You rolled 2d6+3:\n🎲 Total: 13" }] } ``` ### After (text + structured data): ```json { "content": [{ "type": "text", "text": "You rolled 2d6+3:\n🎲 Total: 13" }], "structuredContent": { "notation": "2d6+3", "total": 13, "rolls": [ { "size": 6, "result": 5 }, { "size": 6, "result": 5 } ], "timestamp": "2025-10-06T...", "breakdown": "2d6:[5,5] + 3", "modifier": 3 } } ``` ## Benefits 1. **Backward Compatible**: All existing functionality preserved 2. **Machine-Readable**: AI workflows can programmatically access roll data 3. **Future-Ready**: Foundation for component templates and rich UI 4. **Tested**: Full test coverage ensures reliability 5. **Type-Safe**: TypeScript definitions prevent integration errors ## Next Steps ### Phase 2: Basic Visual Component (Future) - Create HTML component template for dice roll visualization - Register as resource with `text/html+skybridge` mimetype - Link to tools via `_meta["openai/outputTemplate"]` - Add animated dice rendering - Implement roll history display ### Phase 3: Full Featured Implementation (Future) - Multiple component templates (roll display, interactive widget, history) - CSP policies for security - Localization support - Component-initiated tool access - Advanced statistics dashboard ## Testing Run tests: ```bash yarn test # All tests yarn test structured-content # Structured content tests only ``` Build and verify: ```bash yarn build:mcp # Build TypeScript yarn test # Run all tests ``` ## Files Modified ### Local MCP Server (STDIO) - `src/types.ts` - Added 4 new interfaces - `src/index.ts` - Updated 4 tool handlers to return structured content - `__tests__/structured-content.test.ts` - New test file (6 tests) ### Remote MCP Server (HTTP) - `app/[transport]/route.ts` - Updated all 4 tool handlers to return structured content ### Documentation - `README.md` - Updated tool documentation - `STRUCTURED_CONTENT.md` - This file (implementation guide) ## Compatibility - ✅ Maintains full backward compatibility - ✅ Works with existing MCP clients - ✅ OpenAI Apps SDK compliant - ✅ All 102 tests passing - ✅ TypeScript strict mode compliant --- **Implementation Date**: 2025-10-06 **Status**: Production Ready **Breaking Changes**: None