feat: MCP ChatGPT App (#241)

* feat: add ChatGPT Apps SDK integration with widget UI for MCP server

Add `ui://widget/cran.html` resource serving interactive search widget for ChatGPT Apps. Update all search tools (`search_packages`, `search_authors`, `search_universal`) to return `structuredContent` responses consumed by widget via `window.openai.toolOutput`. Add OpenAI-specific metadata annotations including `outputTemplate`, `toolInvocation` labels, `readOnlyHint`, and `openWorldHint`. Introduce `makeToolResponse()` helper

* refactor: improve search service type safety and structure

Add explicit TypeScript types for search hits (`PackageCombinedHit`, `AuthorCombinedHit`, `CombinedSearchHit`) with discriminated union on `type` field. Update `SearchService.searchUniversal()` to return structured response with `searchType` and `query` fields alongside typed `combined` results. Refactor search result mapping to construct typed objects with URLs upfront before sorting, eliminating redundant transformations. Add `Package

* feat: enhance ChatGPT widget with package metadata and improved UI

Add `title` and `last_released_at` fields to package search results throughout the stack. Update `PackageService` to fetch these fields from database queries and include them in search hits. Propagate fields through `SearchService` to MCP server responses for consumption by ChatGPT widget.

Redesign widget UI with Radix Colors dark mode palette, replacing previous light theme. Implement card-based layout with Iris/Jade color variants for

* refactor: remove ChatGPT Apps SDK widget integration from MCP server

Remove `ui://widget/cran.html` resource and all `openai/outputTemplate` metadata from MCP server tools. Delete widget HTML file serving logic and associated file system dependencies. Update documentation to reflect MCP-only functionality without ChatGPT Apps SDK integration. Rename server from "Crane App" to "CRAN/E" and adjust tool invocation labels accordingly. Simplify CSP requirements by removing widget-specific directives.

* refactor: update package resource description in MCP server

Change resource description from "CRAN/E package" to "CRAN R-package" to clarify that resources represent R packages from CRAN rather than the CRAN/E platform itself.

* ```
feat: add MCP navigation link and homepage promotion

Add "MCP" item to main navigation menu. Add promotional text on homepage linking to MCP page with icon, encouraging use of remote MCP-server for agents. Apply fade-in animation to new homepage element.
```

* feat: centralize MCP version management and display on MCP page

Extract MCP server version into shared `config.server.ts` constant. Update MCP server initialization and MCP page to use centralized version. Add loader to MCP page to fetch and display version dynamically. Add `mcpVersion` field to `package.json` for version tracking. Fix accessibility issues by converting copy button from div to button element and correcting apostrophe escaping.

Author: flaming-codes

docs/mcp.md

@@ -1,39 +1,40 @@
 # MCP Server (Crane App)
 
-Minimal notes to integrate the deployed MCP server.
-
 ## Endpoint
 - Path: `/api/mcp`
-- Transport: Streamable HTTP (supports SSE for streaming). Works with standard MCP clients.
-- Hosted inside React Router (`loader` + `action`) so it ships with every deployment.
+- Transport: Streamable HTTP (supports SSE for streaming); see `web/app/routes/api.mcp.ts`.
+- Hosted inside Remix route (`loader` + `action`) so it ships with every deployment.
 
 ## Server Info
 - Name: `Crane App MCP Server`
 - Version: `1.0.0`
 
-## Tools
+## Tools (all read-only, open-world)
 - `search_packages`
   - Input: `{ query: string; limit?: number }`
   - Action: Searches CRAN packages via `PackageService.searchPackages`.
-  - Response: includes `url` pointing to the package page (`/package/<name>`).
+  - Response (structuredContent): `{ searchType: "packages", query, combined, packages: { hits }, authors: { hits: [] } }`
+  - Metadata: toolInvocation labels, `openai/toolDefinition.readOnlyHint = true`, `openWorldHint = true`.
 - `search_authors`
   - Input: `{ query: string; limit?: number }`
   - Action: Searches authors via `AuthorService.searchAuthors`.
-  - Response: includes `url` pointing to the author page (`/author/<name>`).
+  - Response (structuredContent): `{ searchType: "authors", query, combined, packages: { hits: { combined: [] } }, authors: { hits } }`
+  - Metadata: same annotations as above.
 - `search_universal`
   - Input: `{ query: string }`
   - Action: Combined packages + authors via `SearchService.searchUniversal`.
-  - Response: each item has `url` to the package/author page.
+  - Response (structuredContent): `{ searchType: "universal", query, combined, packages: { hits }, authors: { hits } }`
+  - Metadata: same annotations as above.
+
+All tool responses also include `content` with a JSON string for debugging.
 
 ## Resources
 - `cran://package/{name}`
   - Description: Full details for a CRAN package.
-  - Data: Includes metadata, authors, maintainer, dependency relations, and download statistics (last month/year).
+  - Data: Includes metadata, authors, maintainer, dependency relations, download stats (month/year), and links back to site.
 - `cran://author/{name}`
   - Description: Full details for a package author.
-  - Data: Includes author metadata and a list of all authored packages with roles.
-
-Responses are returned as MCP tool results with `content: [{ type: "text", text: JSON.stringify(result, null, 2) }]`.
+  - Data: Includes author metadata and list of authored packages with roles and links.
 
 ## Client Connect (example)
 ```ts
@@ -43,9 +44,22 @@ import { WebSocket } from "ws"; // or fetch-based transport depending on client
 const client = new Client({ serverUrl: "https://<host>/api/mcp" });
 await client.connect();
 ```
-
 For raw HTTP/SSE clients, POST MCP JSON-RPC messages to `/api/mcp` and GET the same path to open the stream.
 
+## Deployment & CSP (for ChatGPT app submission)
+- MCP must be publicly reachable (no localhost/test endpoints).
+- Define CSP to allow fetches to Supabase/CRAN. Example:
+  - `connect-src`: your MCP host, Supabase API domains, CRAN logs.
+- Ensure CORS is permissive for `/api/mcp` (Streamable HTTP).
+
+## Submission checklist (OpenAI Apps Directory)
+- Verified organization; submit via https://platform.openai.com/apps-manage (Owner role).
+- Metadata: toolInvocation labels, `openai/toolDefinition.readOnlyHint = true`, `openWorldHint = true`.
+- Privacy policy URL + support contact.
+- Accurate app name/description/screenshots.
+- Tools labeled with readOnlyHint/openWorldHint; no destructive actions.
+- Global data residency (EU projects currently not accepted for submission).
+
 ## Dependencies
 - `@modelcontextprotocol/sdk`
 - `zod`

web/app/data/package.service.ts

@@ -1,6 +1,6 @@
 import { packageIdSchema, packageNameSchema } from "./package.shape";
 import { SitemapItem } from "./types";
-import { Tables } from "./supabase.types.generated";
+import { Database, Tables } from "./supabase.types.generated";
 import { supabase } from "./supabase.server";
 import { slog } from "../modules/observability.server";
 import { authorIdSchema } from "./author.shape";
@@ -27,11 +27,29 @@ type CacheKey = "sitemap-items" | "count-packages";
 
 type CacheValue = SitemapItem[] | number;
 
+type PackageSearchHit =
+  | {
+      name: string;
+      synopsis: string | null;
+      title?: string | null;
+      last_released_at?: string | null;
+    }
+  | {
+      name: string;
+      synopsis: string | null;
+      title?: string | null;
+      last_released_at?: string | null;
+      sources: Array<
+        [
+          /* source name */ string,
+          /* source data */
+          Database["public"]["Functions"]["match_package_embeddings"]["Returns"],
+        ]
+      >;
+    };
+
 type SearchResult = {
-  combined: Array<{
-    name: string;
-    synopsis: string;
-  } | null>;
+  combined: Array<PackageSearchHit | null>;
   isSemanticPreferred: boolean;
 };
 
@@ -380,7 +398,7 @@ export class PackageService {
         // ! ilike is expensive, but we want to make sure we get the exact match w/o case sensitivity.
         supabase
           .from("cran_packages")
-          .select("id,name,synopsis")
+          .select("id,name,synopsis,title,last_released_at")
           .ilike("name", query)
           .maybeSingle(),
         isSimilaritySearchEnabled
@@ -455,6 +473,10 @@ export class PackageService {
       .map((item) => ({
         name: item.name,
         synopsis: item.synopsis,
+        // @ts-expect-error - RPC might return title/last_released_at if updated, otherwise undefined
+        title: item.title,
+        // @ts-expect-error - RPC might return title/last_released_at if updated, otherwise undefined
+        last_released_at: item.last_released_at,
       }));
 
     // Group sources by package id and source name, so that multiple hits per source & package
@@ -474,7 +496,7 @@ export class PackageService {
       groupedSourcesByPackageIds.map(async (item) => {
         const { data, error } = await supabase
           .from("cran_packages")
-          .select("name,synopsis")
+          .select("name,synopsis,title,last_released_at")
           .eq("id", item.packageId)
           .maybeSingle();
 
@@ -486,6 +508,8 @@ export class PackageService {
         return {
           name: data.name,
           synopsis: data.synopsis,
+          title: data.title,
+          last_released_at: data.last_released_at,
           sources: Object.entries(item.sources),
         };
       }),

web/app/data/search.service.ts

@@ -2,6 +2,30 @@ import { AuthorService } from "./author.service";
 import { PackageService } from "./package.service";
 import { BASE_URL } from "../modules/app";
 import { slog } from "../modules/observability.server";
+import type { Database } from "./supabase.types.generated";
+
+export type PackageCombinedHit = {
+  type: "package";
+  name: string;
+  synopsis: string | null;
+  url: string;
+  sources?: Array<
+    [
+      string,
+      Database["public"]["Functions"]["match_package_embeddings"]["Returns"],
+    ]
+  >;
+};
+
+export type AuthorCombinedHit = {
+  type: "author";
+  name: string;
+  id?: number;
+  levenshtein_distance?: number;
+  url: string;
+};
+
+export type CombinedSearchHit = PackageCombinedHit | AuthorCombinedHit;
 
 export class SearchService {
   static async searchUniversal(query: string) {
@@ -30,56 +54,83 @@ export class SearchService {
 
     // Re-sort the hits by 'includes' of name and synopsis
     const resortQuery = normalizedQuery.toLowerCase();
-    const combined = [...packageHits.combined, ...authorHits].sort((a, b) => {
-      const aIncludes =
-        a &&
-        (a.name.toLowerCase().includes(resortQuery) ||
-          ("synopsis" in a && a.synopsis?.toLowerCase().includes(resortQuery)));
-      const bIncludes =
-        b &&
-        (b.name.toLowerCase().includes(resortQuery) ||
-          ("synopsis" in b && b.synopsis?.toLowerCase().includes(resortQuery)));
-
-      if (aIncludes && !bIncludes) return -1;
-      if (!aIncludes && bIncludes) return 1;
-      return 0;
-    });
-
     const withPackageUrl = (name: string) =>
       `${BASE_URL}/package/${encodeURIComponent(name)}`;
     const withAuthorUrl = (name: string) =>
       `${BASE_URL}/author/${encodeURIComponent(name)}`;
 
     const nonNull = <T>(item: T): item is NonNullable<T> => item != null;
 
-    return {
-      combined: combined.filter(nonNull).map((item) => {
-        if ("synopsis" in item) {
-          return {
-            ...item,
-            url: withPackageUrl(item.name),
-          };
+    const packageCombined: PackageCombinedHit[] = packageHits.combined
+      .filter(nonNull)
+      .map((item) => ({
+        type: "package" as const,
+        name: item.name,
+        synopsis: item.synopsis ?? null,
+        title: item.title,
+        last_released_at: item.last_released_at,
+        url: withPackageUrl(item.name),
+        sources: "sources" in item ? item.sources : undefined,
+      }));
+
+    const authorCombined: AuthorCombinedHit[] = authorHits.map((item) => ({
+      type: "author" as const,
+      name: item.name,
+      id: item.id,
+      levenshtein_distance: item.levenshtein_distance,
+      url: withAuthorUrl(item.name),
+    }));
+
+    const getRelevanceRank = (hit: CombinedSearchHit) => {
+      const nameLower = hit.name.toLowerCase();
+      const synopsisLower =
+        "synopsis" in hit && typeof hit.synopsis === "string"
+          ? hit.synopsis.toLowerCase()
+          : "";
+
+      const exactMatch = nameLower === resortQuery;
+      const startsWith = nameLower.startsWith(resortQuery);
+      const includes =
+        nameLower.includes(resortQuery) ||
+        (synopsisLower ? synopsisLower.includes(resortQuery) : false);
+
+      const levenshtein =
+        "levenshtein_distance" in hit &&
+        typeof hit.levenshtein_distance === "number"
+          ? hit.levenshtein_distance
+          : Number.POSITIVE_INFINITY;
+
+      return [
+        exactMatch ? 0 : 1,
+        startsWith ? 0 : 1,
+        includes ? 0 : 1,
+        levenshtein,
+      ] as const;
+    };
+
+    const combinedWithType: CombinedSearchHit[] = [
+      ...packageCombined,
+      ...authorCombined,
+    ]
+      .map((hit, idx) => ({
+        hit,
+        idx,
+        rank: getRelevanceRank(hit),
+      }))
+      .sort((a, b) => {
+        for (let i = 0; i < a.rank.length; i++) {
+          if (a.rank[i] !== b.rank[i]) {
+            return a.rank[i] - b.rank[i];
+          }
         }
-        return {
-          ...item,
-          url: withAuthorUrl(item.name),
-        };
-      }),
-      packages: {
-        hits: {
-          ...packageHits,
-          combined: packageHits.combined.filter(nonNull).map((item) => ({
-            ...item,
-            url: withPackageUrl(item.name),
-          })),
-        },
-      },
-      authors: {
-        hits: authorHits.filter(nonNull).map((item) => ({
-          ...item,
-          url: withAuthorUrl(item.name),
-        })),
-      },
+        return a.idx - b.idx;
+      })
+      .map(({ hit }) => hit);
+
+    return {
+      searchType: "universal" as const,
+      query: normalizedQuery,
+      combined: combinedWithType,
     };
   }
 }