Agent skill

chatgpt-app:validate

Run validation suite on your ChatGPT App to check schemas, annotations, widgets, and UX compliance.

View SKILL.md on GitHub Repository
Stars 20
Forks 5

Install this agent skill to your Project

npx add-skill https://github.com/hollaugo/tutorials/tree/main/chatgpt-apps-plugin/skills/validate

SKILL.md

Validate ChatGPT App

You are helping the user validate their ChatGPT App before testing and deployment.

Validation Checks

1. Required Files Check (RUN FIRST)

Check that ALL mandatory files exist:

bash
ls package.json tsconfig.server.json setup.sh START.sh .env.example server/index.ts

Expected file structure:

{app-name}/
├── package.json
├── tsconfig.server.json
├── setup.sh
├── START.sh
├── .env.example
├── .gitignore
└── server/
    └── index.ts

If ANY of the above are missing, report as CRITICAL ERROR.

2. Server Implementation Check

Verify server/index.ts uses correct patterns:

MUST have:

typescript
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

MUST NOT have:

typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";  // WRONG

Session management MUST exist:

typescript
const transports = new Map<string, StreamableHTTPServerTransport>();

3. Widget Configuration Check

Verify widgets array structure:

typescript
const widgets: WidgetConfig[] = [
  {
    id: "widget-id",                           // kebab-case
    name: "Widget Name",
    description: "What it displays",
    templateUri: "ui://widget/widget-id.html", // MUST match this format
    invoking: "Loading...",
    invoked: "Ready",
    mockData: { /* sample data */ },
  },
];

4. Tool Response Check

Widget tools MUST return:

typescript
return {
  content: [{ type: "text", text: JSON.stringify(result) }],
  structuredContent: result,  // CRITICAL - becomes window.openai.toolOutput
  _meta: {
    "openai/outputTemplate": widget.templateUri,
    "openai/toolInvocation/invoked": widget.invoked,
  },
};

5. Resource Handler Check

Verify ReadResource returns correct format:

typescript
return {
  contents: [{
    uri,
    mimeType: "text/html+skybridge",  // MUST be this exact value
    text: generateWidgetHtml(widget.id),
  }],
  _meta: {
    "openai/serialization": "markdown-encoded-html",
    "openai/csp": { ... },
  },
};

6. Widget HTML Check

Verify generateWidgetHtml includes:

  • window.PREVIEW_DATA support for local preview
  • window.openai.toolOutput data access
  • openai:set_globals event listener
  • Polling fallback with setInterval
  • rendered flag to prevent re-renders

7. Endpoint Check

Verify these endpoints exist:

  • GET /health - Health check
  • GET /preview - Widget preview index
  • GET /preview/:widgetId - Individual widget preview
  • ALL /mcp - MCP protocol handler
  • DELETE /mcp - Session cleanup

8. Package.json Scripts Check

json
{
  "scripts": {
    "build": "npm run build:server",
    "build:server": "tsc -p tsconfig.server.json",
    "start": "HTTP_MODE=true node dist/server/index.js",
    "dev": "HTTP_MODE=true NODE_ENV=development tsx watch --clear-screen=false server/index.ts"
  }
}

MUST NOT have: dev:web, build:web, concurrently

9. Annotation Validation

  • Query tools have readOnlyHint: true
  • Delete tools have destructiveHint: true
  • External API tools have openWorldHint: true

10. Database Validation (if enabled)

  • All migrations are valid SQL
  • Tables have user_subject column
  • Indexes exist for user queries

Workflow

  1. Run file existence checks
  2. Read and analyze server/index.ts
  3. Verify patterns match requirements
  4. Collect errors and warnings
  5. Display results

Results Format

## Validation Results

### File Structure ✓
All required files present.

### Server Implementation ✓
Using correct Server class with session management.

### Widget Configuration ✓
2 widgets properly configured.

### Tool Responses ✓
All widget tools return structuredContent.

---
**Overall: PASS**

Common Errors

Error Fix
Uses McpServer Change to Server from @modelcontextprotocol/sdk/server/index.js
Missing session management Add Map<string, StreamableHTTPServerTransport>
Wrong widget URI Use ui://widget/{id}.html format
Wrong MIME type Use text/html+skybridge
Missing structuredContent Add to tool response for widget data
Has web/ folder Remove - widgets are inline in server/index.ts

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

hollaugo/tutorials

chatgpt-app:new

Create a new ChatGPT App from concept to working code. Guides through conceptualization, design, implementation, testing, and deployment.

20 5
Explore
hollaugo/tutorials

chatgpt-app:add-auth

Configure authentication for your ChatGPT App using Auth0 or Supabase Auth for multi-user support.

20 5
Explore
hollaugo/tutorials

chatgpt-app:add-tool

Add a new MCP tool to your ChatGPT App. Guides through tool design, schema creation, and code generation.

20 5
Explore
hollaugo/tutorials

chatgpt-app:deploy

Deploy your ChatGPT App to Render with PostgreSQL database and automatic health checks.

20 5
Explore
hollaugo/tutorials

chatgpt-app:golden-prompts

Generate test prompts to validate that ChatGPT will correctly invoke your app's tools.

20 5
Explore
hollaugo/tutorials

chatgpt-app:add-widget

Add a new inline widget to your ChatGPT App with Tailwind CSS and Apps SDK integration.

20 5
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results