prototype-text-display

Claude Code <--stdio--> MCP Server <--WebSocket--> Vue Frontend
                            |
                        XState Machine
                        (holds state)

States: idle <-> displaying

Context:
- text: string           # Current displayed text
- history: string[]      # Previous text values (for undo)
- lastAction: string     # Last executed action
- lastError: string      # Last error message

function getAvailableActions(state: string, context: Context): AvailableAction[] {
  const actions = [/* always available: set_text, append_text, reset */];

  if (state === 'displaying') {
    actions.push({ name: 'clear_text', ... });

    if (context.history.length > 0) {
      actions.push({
        name: 'undo',
        reason: `Can undo ${context.history.length} change(s)`
      });
    }
  }

  return actions;
}

{
  "name": "Agentic UI Prototype",
  "purpose": "A simple text display controlled by AI",
  "capabilities": ["Display text", "Set text", "Append text", "Clear", "Undo", "Reset"]
}

{
  "currentState": "displaying",
  "text": "Hello World",
  "textLength": 11,
  "historyCount": 1,
  "lastAction": "set_text",
  "availableActions": [
    { "name": "set_text", "description": "Set the displayed text", "inputSchema": {...} },
    { "name": "clear_text", "description": "Clear all text", "inputSchema": {...} },
    { "name": "undo", "description": "Undo last change", "reason": "Can undo 1 change(s)" }
  ]
}

// Request
{ "action": "set_text", "payload": { "text": "Hello World" } }

// Response
{
  "success": true,
  "action": "set_text",
  "newState": "displaying",
  "text": "Hello World",
  "availableActions": [...]
}

packages/agentic-ui-prototype/
├── package.json
├── README.md
├── mcp-server/
│   ├── package.json
│   ├── tsconfig.json
│   └── src/
│       ├── index.ts         # MCP server + tool handlers
│       ├── machine.ts       # XState state machine
│       └── websocket.ts     # WebSocket for frontend sync
└── frontend/
    ├── package.json
    ├── vite.config.ts
    └── src/
        ├── App.vue
        ├── components/
        │   ├── TextDisplay.vue      # Shows the text
        │   ├── StateIndicator.vue   # Shows state + actions
        │   └── ActionLog.vue        # Action history
        └── composables/
            └── useWebSocket.ts      # WebSocket connection

User: "Set the text to 'Hello World'"
Claude: [calls execute_action { action: "set_text", payload: { text: "Hello World" } }]
-> Frontend updates in real-time

User: "Append ' from Claude!' to it"
Claude: [calls execute_action { action: "append_text", payload: { text: " from Claude!" } }]
-> Text now shows "Hello World from Claude!"

User: "Undo that"
Claude: [calls execute_action { action: "undo" }]
-> Text reverts to "Hello World"

export function closeWebSocketServer(): Promise<void> {
  return new Promise((resolve) => {
    if (!wss) { resolve(); return; }

    // Close all client connections
    for (const client of clients) {
      client.close(1000, 'Server shutting down');
    }
    clients.clear();

    // Close the server
    wss.close(() => {
      wss = null;
      resolve();
    });
  });
}

export function isPortInUse(port: number): Promise<boolean> {
  // Check if port is available before binding
}

// Graceful shutdown handler
async function shutdown(signal: string) {
  console.error(`Received ${signal}, shutting down gracefully...`);
  await closeWebSocketServer();
  process.exit(0);
}

// Register signal handlers
process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT', () => shutdown('SIGINT'));
process.on('SIGHUP', () => shutdown('SIGHUP'));

// Check port before starting
const portInUse = await isPortInUse(WS_PORT);
if (portInUse) {
  console.error(`Error: Port ${WS_PORT} is already in use.`);
  process.exit(1);
}

Claude Code starts
       |
       v
MCP Server spawned (stdio)
       |
       v
WebSocket server binds to port 8765
       |
       v
[Normal operation - tools available]
       |
       v
Claude Code exits (sends SIGTERM)
       |
       v
Graceful shutdown handler triggered
       |
       v
WebSocket connections closed
       |
       v
WebSocket server closed (port released)
       |
       v
Process exits cleanly