/mcp-app-verification

name: mcp-app-verification
description: Comprehensive verification checklists for MCP Apps. Tests with basic-host reference, validates handler-before-connect, text fallback, resource URI linking, single-file bundling, host styling, CSP, and legacy pattern detection.
allowed-tools: Read, Bash, Glob, Grep
graph:
  domains: [domain:software-engineering]
  specializations: [specialization:ai-agents-conversational]
  skillAreas: [skill-area:mcp-server-implementation, skill-area:agent-simulation-testing]
  roles: [role:backend-engineer, role:fullstack-engineer]
  workflows: [workflow:feature-development]
  topics: [topic:api-design]

mcp-app-verification

Run comprehensive verification checklists for MCP Apps covering correctness, compatibility, and migration completeness.

Overview

MCP Apps have several critical invariants that must be verified before deployment. This skill provides systematic verification across multiple dimensions:

1. **Runtime verification**: App loads and functions in basic-host reference 2. **Pattern verification**: Critical code patterns are correct (handler-before-connect, text fallback) 3. **Build verification**: Single-file bundle is valid and complete 4. **Styling verification**: Host theming applies correctly 5. **CSP verification**: All origins declared, no silent failures 6. **Migration verification**: No remaining legacy patterns (OpenAI, old MIME types, snake_case)

Capabilities

basic-host Test Execution

• Build the MCP App
• Start the server
• Launch basic-host reference implementation against the server
• Verify app loads without console errors
• Verify handlers fire correctly

Handler-Before-Connect Invariant

• Search source code for `app.connect()` call
• Verify ALL handlers (`ontoolinput`, `ontoolresult`, `onhostcontextchanged`, `onteardown`) are registered BEFORE connect
• Flag violations -- handlers registered after connect will silently not work

Text Fallback Verification

• Search all tool handlers for `content` array in return value
• Verify each tool returns at least one `{ type: 'text', text: '...' }` entry
• Flag tools that only return `structuredContent` without text fallback

Resource URI Link Integrity

• Extract all `resourceUri` values from `registerAppTool` calls
• Extract all URIs from `registerAppResource` calls
• Verify every tool `resourceUri` has a matching registered resource
• Flag orphaned resources (registered but not referenced)

Single-File Bundle Verification

• Build the project
• Verify `dist/mcp-app.html` (or equivalent) exists
• Check the HTML file is self-contained (no external `<script src>`, `<link href>`, `<img src>` to relative paths)
• Verify `vite-plugin-singlefile` is in dev dependencies

Host Styling Verification

• Search CSS for `var(--color-*`, `var(--font-*`, `var(--border-radius-*` patterns
• Verify fallback values are present: `var(--color-background-primary, #ffffff)` not just `var(--color-background-primary)`
• Check `onhostcontextchanged` handler exists and applies styling

CSP Verification

• Build and search output for network origins
• Compare against CSP configuration in `registerAppResource`
• Flag origins present in code but missing from CSP
• Verify conditional origins match between runtime and CSP config

Legacy Pattern Detection (Migration)

• Search for remaining OpenAI patterns: `window.openai.toolInput`, `window.openai.toolOutput`, `window.openai`
• Search for old metadata paths: `openai/`
• Search for old MIME types: `text/html+skybridge`
• Search for hardcoded MIME type: `text/html;profile=mcp-app` (should use `RESOURCE_MIME_TYPE`)
• Search for snake_case CSP: `_domains"` or `_domains:` (should be camelCase)

Usage

Full Verification Workflow

# Step 1: Build the project
npm run build

# Step 2: Verify single-file bundle
ls -la dist/mcp-app.html
# Should be a single file with all assets inlined

# Step 3: Check for external references in bundle
grep -E '<script src="|<link.*href="|<img src="(?!data:)' dist/mcp-app.html
# Should return NOTHING (all assets inlined)

# Step 4: Start server
npm run serve &
SERVER_PID=$!

# Step 5: Test with basic-host
cd /tmp/mcp-ext-apps/examples/basic-host
SERVERS='["http://localhost:3001/mcp"]' npm run start
# Verify: app loads, handlers fire, styling applies

# Step 6: Stop server
kill $SERVER_PID

Pattern Verification Commands

# Handler-before-connect check
# Find app.connect() and verify handlers are above it
grep -n 'app\.connect\|\.ontoolinput\|\.ontoolresult\|\.onhostcontextchanged\|\.onteardown' src/main.ts

# Text fallback check
# Every tool handler should return content array
grep -A5 'return {' src/server.ts | grep -c 'content:'

# Resource URI linking
grep 'resourceUri' src/server.ts
grep "registerAppResource" src/server.ts

# RESOURCE_MIME_TYPE usage (not hardcoded)
grep 'RESOURCE_MIME_TYPE' src/server.ts
grep "text/html;profile" src/server.ts  # Should NOT match

# CSS variable fallbacks
grep -c 'var(--.*,' src/global.css  # Count with fallbacks
grep 'var(--' src/global.css | grep -v ','  # Flag missing fallbacks

Migration Verification (OpenAI -> MCP)

# Server-side legacy patterns
grep -rn 'openai/' src/        # Old metadata paths
grep -rn 'text/html+skybridge' src/  # Old MIME type
grep -rn "text/html;profile=mcp-app" src/  # Hardcoded (use RESOURCE_MIME_TYPE)
grep -rn '_domains"' src/      # Snake_case CSP
grep -rn "_domains:" src/      # Snake_case CSP

# Client-side legacy patterns
grep -rn 'window\.openai\.toolInput' src/
grep -rn 'window\.openai\.toolOutput' src/
grep -rn 'window\.openai' src/

# All should return ZERO matches

Automated Verification Script

#!/bin/bash
# mcp-app-verify.sh - Comprehensive MCP App verification

ERRORS=0

echo "=== MCP App Verification ==="

# 1. Build
echo "[1/8] Building..."
npm run build 2>&1 || { echo "FAIL: Build failed"; ERRORS=$((ERRORS+1)); }

# 2. Single-file bundle
echo "[2/8] Checking singl