specs/003-chatgpt-app-integration/research.md

Phase 0: Research & Technical Decisions

1. FastMCP Metadata Injection

Decision: Return CallToolResult with _meta for UI tools.

Strategy:

• We will stop returning pure Pydantic models from tools that need to trigger widgets (read_note, search_notes).
• Instead, these tools will instantiate the Pydantic model, dump it to a dictionary, and wrap it in a CallToolResult object.
• The _meta field will contain openai: { outputTemplate: "..." }.
• Non-UI tools (e.g., list_notes, delete_note) will continue to return Pydantic models or simple text to keep them lightweight.

Rationale: This aligns with the OpenAI Apps SDK pattern and allows us to trigger widgets without breaking the existing schema validation (since structuredContent will still match the Pydantic schema).

2. React Widget Strategy

Decision: Use a separate Vite entry point (widget.html + widget.tsx).

Strategy:

• Create frontend/widget.html as a lightweight entry point.
• Create frontend/src/widget.tsx to render the widget application.
• Refactor NoteViewer.tsx into a "pure" component (if it isn't already) that can be imported by both App.tsx and widget.tsx.
• Use vite-plugin-html or manual rollup config to output multiple HTML files.

Rationale:

• Isolation: Prevents the main app's router, sidebar, and heavy layout styles from leaking into the iframe.
• Performance: The widget bundle will be smaller.
• Simplicity: Easier to reason about "widget state" when it's a fresh React mount rather than a route transition in a complex SPA.

3. Authentication

Decision: Use a configurable "Service Token" strategy.

Strategy:

• Refactor AuthService to support a TokenValidator interface or strategy.
• Implement JWTValidator (existing) and StaticTokenValidator (new).
• Add CHATGPT_SERVICE_TOKEN to AppConfig.
• If CHATGPT_SERVICE_TOKEN is set, the backend will accept it as a valid Bearer token for any user context (or a specific "chatgpt-bot" user).

Rationale:

• Hugging Face OAuth is not compatible with the Apps SDK OIDC flow.
• Implementing a full OIDC provider is out of scope for the hackathon.
• A static service token is secure enough for a demo/hackathon submission and easy to configure in the OpenAI Developer Platform.

4. Infrastructure & Hosting

Decision: Serve widget.html via FastAPI static mount with Skybridge MIME type.

Strategy:

• Update backend/src/api/main.py to serve frontend/dist/widget.html on a specific route (e.g., /widget).
• Ensure the Content-Type header is text/html+skybridge (or whatever the specific requirement is, usually just serving it is enough, but we will double-check if OpenAI needs specific headers). Correction: The expert mentioned text/html+skybridge media type for FileResponse.
• Update CORS to allow https://chatgpt.com (and https://*.chatgpt.com).

Rationale: Required for the widget to load inside the ChatGPT iframe.