Merge branch 'main' into feature/sentry-integration

Author: TkDodo

docs/mcp/overview.md

@@ -53,6 +53,15 @@ The MCP server exposes tools for documentation and showcase management:
 | `delete_showcase`   | Delete your showcase submission            | Yes           |
 | `list_my_showcases` | List your own showcase submissions         | Yes           |
 
+### NPM Stats Tools
+
+| Tool                        | Description                                             | Auth Required |
+| --------------------------- | ------------------------------------------------------- | ------------- |
+| `get_npm_stats`             | Get aggregated download stats for TanStack or a library | No            |
+| `list_npm_comparisons`      | List preset package comparisons (Data Fetching, etc.)   | No            |
+| `compare_npm_packages`      | Compare download stats for multiple packages over time  | No            |
+| `get_npm_package_downloads` | Get detailed historical downloads for a single package  | No            |
+
 See [Available Tools](./tools) for detailed parameter documentation.
 
 ## How It Works

docs/mcp/tools.md

@@ -338,6 +338,154 @@ List your own showcase submissions. **Requires authentication.** Returns all you
 
 ## Rate Limits
 
-- **Read operations** (documentation, search): 60 requests per minute
+- **Read operations** (documentation, search, stats): 60 requests per minute
 - **Write operations** (submit, update, delete): 10 requests per hour
 - **Pending submission limit**: Maximum 5 pending submissions per user
+
+---
+
+## NPM Stats Tools
+
+These tools provide access to NPM download statistics for package analysis and comparison.
+
+### get_npm_stats
+
+Get aggregated NPM download statistics for the TanStack org or a specific library.
+
+#### Parameters
+
+| Parameter | Type   | Required | Description                                                                   |
+| --------- | ------ | -------- | ----------------------------------------------------------------------------- |
+| `library` | string | No       | Filter to specific library (e.g., `query`, `router`). Omit for org-wide stats |
+
+#### Response
+
+For org-wide stats:
+
+- `org` - Organization name ("tanstack")
+- `totalDownloads` - Total downloads across all packages
+- `ratePerDay` - Current download rate per day
+- `updatedAt` - When stats were last updated
+- `libraries` - Breakdown by library with `id`, `totalDownloads`, `packageCount`
+
+For library-specific stats:
+
+- `library` - Library ID
+- `totalDownloads` - Total downloads for this library
+- `ratePerDay` - Current download rate per day
+- `packageCount` - Number of packages in this library
+- `packages` - Array of packages with `name`, `downloads`, `ratePerDay`
+
+#### Example
+
+```json
+{
+  "name": "get_npm_stats",
+  "arguments": {
+    "library": "query"
+  }
+}
+```
+
+---
+
+### list_npm_comparisons
+
+List available preset package comparisons for common categories like Data Fetching, State Management, Routing, etc.
+
+#### Parameters
+
+| Parameter  | Type   | Required | Description                                              |
+| ---------- | ------ | -------- | -------------------------------------------------------- |
+| `category` | string | No       | Filter by category name (case-insensitive partial match) |
+
+#### Response
+
+- `comparisons` - Array of comparisons with `id`, `name`, `packages`
+- `total` - Number of comparisons returned
+
+#### Available Categories
+
+Data Fetching, State Management, Routing (React), Data Grids, Virtualization, Frameworks, Styling, Build Tools, Testing, Forms, UI Components, Animation, Date & Time, Validation, Documentation, All TanStack Packages
+
+#### Example
+
+```json
+{
+  "name": "list_npm_comparisons",
+  "arguments": {
+    "category": "state"
+  }
+}
+```
+
+---
+
+### compare_npm_packages
+
+Compare NPM download statistics for multiple packages over a time range. Returns binned download data for analysis.
+
+#### Parameters
+
+| Parameter  | Type     | Required | Description                                                                                                    |
+| ---------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------- |
+| `packages` | string[] | Yes      | Package names to compare (max 10)                                                                              |
+| `range`    | string   | No       | Time range: `7-days`, `30-days`, `90-days`, `180-days`, `365-days`, `730-days`, `all-time`. Default: `30-days` |
+| `binType`  | string   | No       | Aggregation: `daily`, `weekly`, `monthly`. Default: `weekly`                                                   |
+
+#### Response
+
+- `packages` - Array of package data with:
+  - `name` - Package name
+  - `totalDownloads` - Total downloads in range
+  - `averagePerDay` - Average downloads per day
+  - `data` - Array of `{ date, downloads }` binned by `binType`
+- `range` - Object with `start` and `end` dates
+- `binType` - The aggregation level used
+
+#### Example
+
+```json
+{
+  "name": "compare_npm_packages",
+  "arguments": {
+    "packages": ["@tanstack/react-query", "swr", "@apollo/client"],
+    "range": "90-days",
+    "binType": "weekly"
+  }
+}
+```
+
+---
+
+### get_npm_package_downloads
+
+Get detailed historical download data for a single NPM package.
+
+#### Parameters
+
+| Parameter | Type   | Required | Description                                             |
+| --------- | ------ | -------- | ------------------------------------------------------- |
+| `package` | string | Yes      | Package name (e.g., `@tanstack/react-query`)            |
+| `year`    | string | No       | Year in YYYY format or `current`. Default: current year |
+
+#### Response
+
+- `package` - Package name
+- `year` - The year requested
+- `totalDownloads` - Total downloads for the year
+- `dayCount` - Number of days with data
+- `averagePerDay` - Average downloads per day
+- `data` - Array of daily downloads with `{ day, downloads }`
+
+#### Example
+
+```json
+{
+  "name": "get_npm_package_downloads",
+  "arguments": {
+    "package": "@tanstack/react-query",
+    "year": "2024"
+  }
+}
+```

src/mcp/server.ts

@@ -14,6 +14,19 @@ import {
   listMyShowcases,
   listMyShowcasesSchema,
 } from './tools/list-my-showcases'
+import { getNpmStats, getNpmStatsSchema } from './tools/get-npm-stats'
+import {
+  listNpmComparisons,
+  listNpmComparisonsSchema,
+} from './tools/list-npm-comparisons'
+import {
+  compareNpmPackages,
+  compareNpmPackagesSchema,
+} from './tools/compare-npm-packages'
+import {
+  getNpmPackageDownloads,
+  getNpmPackageDownloadsSchema,
+} from './tools/get-npm-package-downloads'
 
 export type McpAuthContext = {
   userId: string
@@ -298,5 +311,133 @@ export function createMcpServer(authContext?: McpAuthContext) {
     },
   )
 
+  // ============================================================================
+  // NPM Stats Tools
+  // ============================================================================
+
+  // Register get_npm_stats tool
+  server.tool(
+    'get_npm_stats',
+    'Get aggregated NPM download statistics for TanStack org or a specific library. Returns total downloads, growth rate, and package breakdown.',
+    getNpmStatsSchema.shape,
+    async (args) => {
+      try {
+        const parsed = getNpmStatsSchema.parse(args)
+        const result = await getNpmStats(parsed)
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        }
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
+            },
+          ],
+          isError: true,
+        }
+      }
+    },
+  )
+
+  // Register list_npm_comparisons tool
+  server.tool(
+    'list_npm_comparisons',
+    'List available preset package comparisons (Data Fetching, State Management, Routing, etc.). Use with compare_npm_packages for quick comparisons.',
+    listNpmComparisonsSchema.shape,
+    async (args) => {
+      try {
+        const parsed = listNpmComparisonsSchema.parse(args)
+        const result = await listNpmComparisons(parsed)
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        }
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
+            },
+          ],
+          isError: true,
+        }
+      }
+    },
+  )
+
+  // Register compare_npm_packages tool
+  server.tool(
+    'compare_npm_packages',
+    'Compare NPM download statistics for multiple packages over a time range. Returns daily/weekly/monthly download data for visualization and analysis.',
+    compareNpmPackagesSchema.shape,
+    async (args) => {
+      try {
+        const parsed = compareNpmPackagesSchema.parse(args)
+        const result = await compareNpmPackages(parsed)
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        }
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
+            },
+          ],
+          isError: true,
+        }
+      }
+    },
+  )
+
+  // Register get_npm_package_downloads tool
+  server.tool(
+    'get_npm_package_downloads',
+    'Get detailed historical download data for a single NPM package. Returns daily download counts for analysis.',
+    getNpmPackageDownloadsSchema.shape,
+    async (args) => {
+      try {
+        const parsed = getNpmPackageDownloadsSchema.parse(args)
+        const result = await getNpmPackageDownloads(parsed)
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        }
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
+            },
+          ],
+          isError: true,
+        }
+      }
+    },
+  )
+
   return server
 }