feact: mcp (#240)

* feat: add mcp server

* chore: exclude docs directory from TypeScript compilation

* feat: add URL fields to MCP server search responses

Add `url` field to all search results in MCP server tools (search_packages, search_authors, search_universal) pointing to the respective package/author pages. Update SearchService to include URLs in universal search results.

* feat: add package and author resources to MCP server

Add `cran://package/{name}` and `cran://author/{name}` resources to MCP server. Package resource includes full metadata, authors, maintainer, dependency relations, and download statistics (last month/year). Author resource includes author metadata and list of authored packages with roles. Update documentation and VS Code spell check settings.

* refactor: consolidate package data fetching logic into shared enrichment method

Extract common package data fetching and processing logic from MCP server and package page loader into `PackageService.getEnrichedPackageByName()` method. This eliminates code duplication by centralizing the logic for fetching package metadata, relations, authors, maintainer, downloads, and trending status. Both the MCP resource handler and package route loader now use this shared method, following DRY principle.

* feat: add MCP section to about page with server URL copy functionality

Add dedicated MCP (Model Context Protocol) section to about page explaining CRAN/E's MCP server capabilities. Include description of three main resources (Package Resource, Author Resource, Search Tools) and their use cases. Add copy-to-clipboard functionality for MCP server URL with visual feedback. Update footer link label to "About & MCP" and add "MCP" to page anchors navigation.

* chore: format licenses.json with prettier formatting

Author: flaming-codes

.vscode/settings.json

@@ -20,5 +20,7 @@
     ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"],
     ["cx\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"],
     ["tw`([^`]*)`", "tw`([^`]*)`"]
-  ]
+  ],
+  "spellright.language": ["en"],
+  "spellright.documentTypes": ["markdown", "latex", "plaintext"]
 }

.vscode/spellright.dict

@@ -0,0 +1 @@
+cran

docs/mcp.md

@@ -0,0 +1,54 @@
+# 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.
+
+## Server Info
+- Name: `Crane App MCP Server`
+- Version: `1.0.0`
+
+## Tools
+- `search_packages`
+  - Input: `{ query: string; limit?: number }`
+  - Action: Searches CRAN packages via `PackageService.searchPackages`.
+  - Response: includes `url` pointing to the package page (`/package/<name>`).
+- `search_authors`
+  - Input: `{ query: string; limit?: number }`
+  - Action: Searches authors via `AuthorService.searchAuthors`.
+  - Response: includes `url` pointing to the author page (`/author/<name>`).
+- `search_universal`
+  - Input: `{ query: string }`
+  - Action: Combined packages + authors via `SearchService.searchUniversal`.
+  - Response: each item has `url` to the package/author page.
+
+## Resources
+- `cran://package/{name}`
+  - Description: Full details for a CRAN package.
+  - Data: Includes metadata, authors, maintainer, dependency relations, and download statistics (last month/year).
+- `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) }]`.
+
+## Client Connect (example)
+```ts
+import { Client } from "@modelcontextprotocol/sdk/client";
+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.
+
+## Dependencies
+- `@modelcontextprotocol/sdk`
+- `zod`
+
+## Notes
+- Stateless by default; adjust `WebStandardStreamableHTTPServerTransport` options in `app/routes/api.mcp.ts` if you need session IDs or retry tuning.

web/app/data/package.service.ts

@@ -6,9 +6,17 @@ import { slog } from "../modules/observability.server";
 import { authorIdSchema } from "./author.shape";
 import { groupBy, omit, uniqBy } from "es-toolkit";
 import TTLCache from "@isaacs/ttlcache";
-import { format, hoursToMilliseconds, minutesToMilliseconds } from "date-fns";
+import {
+  format,
+  formatRelative,
+  hoursToMilliseconds,
+  minutesToMilliseconds,
+  subDays,
+} from "date-fns";
 import { google } from "@ai-sdk/google";
 import { embed } from "ai";
+import { AuthorService } from "./author.service";
+import { PackageInsightService } from "./package-insight.service.server";
 
 // import { embed } from "ai";
 // import { google } from "@ai-sdk/google";
@@ -27,6 +35,30 @@ type SearchResult = {
   isSemanticPreferred: boolean;
 };
 
+type EnrichedPackage = {
+  pkg: Package;
+  relations: Awaited<
+    ReturnType<typeof PackageService.getPackageRelationsByPackageId>
+  >;
+  groupedRelations: ReturnType<typeof groupBy<any, string>>;
+  authorsData: Awaited<ReturnType<typeof AuthorService.getAuthorsByPackageId>>;
+  authorsList: Array<Tables<"authors"> & { roles: string[] }>;
+  maintainer: (Tables<"authors"> & { roles: string[] }) | undefined;
+  dailyDownloads: Awaited<
+    ReturnType<typeof PackageInsightService.getDailyDownloadsForPackage>
+  >;
+  yearlyDailyDownloads: Awaited<
+    ReturnType<typeof PackageInsightService.getDailyDownloadsForPackage>
+  >;
+  trendingPackages: Awaited<
+    ReturnType<typeof PackageInsightService.getTrendingPackages>
+  >;
+  totalMonthDownloads: number;
+  totalYearDownloads: number;
+  isTrending: boolean;
+  lastRelease: string;
+};
+
 export class PackageService {
   /** Cache for singular domains, e.g. the sitemap. */
   private static cache = new TTLCache<CacheKey, CacheValue>({
@@ -63,6 +95,98 @@ export class PackageService {
     return data;
   }
 
+  /**
+   * Get enriched package data with relations, authors, maintainer, downloads, and trending status.
+   * This method consolidates the data fetching and processing logic used by both
+   * the MCP resource and the package page loader to follow DRY principle.
+   */
+  static async getEnrichedPackageByName(
+    packageName: string,
+  ): Promise<EnrichedPackage | null> {
+    packageNameSchema.parse(packageName);
+
+    const pkg = await this.getPackageByName(packageName);
+    if (!pkg) {
+      return null;
+    }
+
+    const now = new Date();
+
+    const [
+      relations,
+      authorsData,
+      dailyDownloads,
+      yearlyDailyDownloads,
+      trendingPackages,
+    ] = await Promise.all([
+      this.getPackageRelationsByPackageId(pkg.id),
+      AuthorService.getAuthorsByPackageId(pkg.id),
+      PackageInsightService.getDailyDownloadsForPackage(
+        packageName,
+        "last-month",
+      ),
+      PackageInsightService.getDailyDownloadsForPackage(
+        packageName,
+        `${format(subDays(now, 365), "yyyy-MM-dd")}:${format(now, "yyyy-MM-dd")}`,
+      ),
+      PackageInsightService.getTrendingPackages(),
+    ]);
+
+    // Process Relations
+    const groupedRelations = groupBy(
+      relations || [],
+      (item) => item.relationship_type,
+    );
+
+    // Process Authors & Maintainers
+    const authorsList = (authorsData || [])
+      .map(({ author, roles }) => ({
+        ...((Array.isArray(author) ? author[0] : author) as Tables<"authors">),
+        roles: roles || [],
+      }))
+      .filter((a) => !a.roles.includes("mnt"));
+
+    const maintainer = (authorsData || [])
+      .map(({ author, roles }) => ({
+        ...((Array.isArray(author) ? author[0] : author) as Tables<"authors">),
+        roles: roles || [],
+      }))
+      .filter((a) => a.roles.includes("mnt"))
+      .at(0);
+
+    // Process Downloads
+    const totalMonthDownloads =
+      dailyDownloads
+        .at(0)
+        ?.downloads?.reduce((acc, curr) => acc + curr.downloads, 0) || 0;
+
+    const totalYearDownloads =
+      yearlyDailyDownloads
+        .at(0)
+        ?.downloads?.reduce((acc, curr) => acc + curr.downloads, 0) || 0;
+
+    const isTrending =
+      trendingPackages.findIndex((item) => item.package === packageName) !== -1;
+
+    const lastRelease = formatRelative(new Date(pkg.last_released_at), now);
+
+    return {
+      pkg,
+      relations,
+      groupedRelations,
+      authorsData,
+      authorsList,
+      maintainer,
+      dailyDownloads,
+      yearlyDailyDownloads,
+      trendingPackages,
+      totalMonthDownloads,
+      totalYearDownloads,
+      isTrending,
+      lastRelease,
+    };
+  }
+
   static async getPackageIdByName(packageName: string): Promise<number | null> {
     packageNameSchema.parse(packageName);
 

web/app/data/search.service.ts

@@ -0,0 +1,85 @@
+import { AuthorService } from "./author.service";
+import { PackageService } from "./package.service";
+import { BASE_URL } from "../modules/app";
+import { slog } from "../modules/observability.server";
+
+export class SearchService {
+  static async searchUniversal(query: string) {
+    const normalizedQuery = query.trim().slice(0, 512);
+
+    const [packages, authors] = await Promise.allSettled([
+      PackageService.searchPackages(normalizedQuery),
+      AuthorService.searchAuthors(normalizedQuery),
+    ]);
+
+    if (packages.status === "rejected") {
+      slog.error("Failed to search packages", { error: packages.reason });
+    }
+    if (authors.status === "rejected") {
+      slog.error("Failed to search authors", { error: authors.reason });
+    }
+
+    const packageHits =
+      packages.status === "fulfilled"
+        ? packages.value
+        : {
+            combined: [],
+            isSemanticPreferred: false,
+          };
+    const authorHits = authors.status === "fulfilled" ? authors.value : [];
+
+    // 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),
+          };
+        }
+        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),
+        })),
+      },
+    };
+  }
+}