@idealyst/mcp-server 1.2.128 → 1.2.129

package/dist/index.js

@@ -7,7 +7,7 @@ import {
   storageGuides,
   toolDefinitions,
   translateGuides
-} from "./chunk-PLKNERFG.js";
+} from "./chunk-RZIMKJRB.js";
 
 // src/index.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";

package/dist/tools/index.cjs

@@ -85,6 +85,8 @@ __export(tools_exports, {
   getPackageDocsDefinition: () => getPackageDocsDefinition,
   getPaymentsGuide: () => getPaymentsGuide,
   getPaymentsGuideDefinition: () => getPaymentsGuideDefinition,
+  getPdfGuide: () => getPdfGuide,
+  getPdfGuideDefinition: () => getPdfGuideDefinition,
   getRecipe: () => getRecipe,
   getRecipeDefinition: () => getRecipeDefinition,
   getRegistryThemeValues: () => getRegistryThemeValues,
@@ -532,6 +534,21 @@ var getNotificationsGuideDefinition = {
     required: ["topic"]
   }
 };
+var getPdfGuideDefinition = {
+  name: "get_pdf_guide",
+  description: "Get documentation for @idealyst/pdf cross-platform PDF viewer package. Covers PDFViewer component, PDFViewerRef imperative methods, and examples.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      topic: {
+        type: "string",
+        description: "Topic to get docs for: 'overview', 'api', 'examples'",
+        enum: ["overview", "api", "examples"]
+      }
+    },
+    required: ["topic"]
+  }
+};
 var listPackagesDefinition = {
   name: "list_packages",
   description: "List all available Idealyst packages with descriptions, categories, and documentation status. Use this to discover what packages are available in the framework.",
@@ -722,6 +739,7 @@ var toolDefinitions = [
   getNotificationsGuideDefinition,
   getLiveActivityGuideDefinition,
   getNetworkGuideDefinition,
+  getPdfGuideDefinition,
   // Package tools
   listPackagesDefinition,
   getPackageDocsDefinition,
@@ -10573,6 +10591,305 @@ async function quickHealthCheck() {
 `
 };
 
+// src/data/pdf-guides.ts
+var pdfGuides = {
+  "idealyst://pdf/overview": `# @idealyst/pdf
+
+Cross-platform PDF viewer for React and React Native.
+
+## Installation
+
+\`\`\`bash
+yarn add @idealyst/pdf
+\`\`\`
+
+### Platform peer dependencies
+
+| Platform | Peer Dependency | Install |
+|----------|----------------|---------|
+| Web | \`pdfjs-dist\` | \`yarn add pdfjs-dist\` |
+| Native | \`react-native-pdf\` | \`yarn add react-native-pdf react-native-blob-util\` |
+
+**Web**: Uses Mozilla PDF.js to render PDF pages to canvas.
+**Native**: Uses react-native-pdf (PDFKit on iOS, PdfRenderer on Android).
+
+## Key Exports
+
+| Export | Type | Description |
+|--------|------|-------------|
+| \`PDFViewer\` | Component | PDF viewer with zoom, page nav, scroll |
+| \`PDFViewerRef\` | Ref type | Imperative: \`goToPage()\`, \`setZoom()\` |
+| \`PDFSource\` | Type | \`string \\| { uri: string } \\| { base64: string }\` |
+| \`PDFDocumentInfo\` | Type | \`{ totalPages: number }\` |
+| \`FitPolicy\` | Type | \`'width' \\| 'height' \\| 'both'\` |
+| \`PDFDirection\` | Type | \`'horizontal' \\| 'vertical'\` |
+
+## Quick Start
+
+\`\`\`tsx
+import { PDFViewer } from '@idealyst/pdf';
+
+function DocumentScreen() {
+  return (
+    <PDFViewer
+      source="https://example.com/document.pdf"
+      onLoad={({ totalPages }) => console.log('Pages:', totalPages)}
+      onPageChange={(page, total) => console.log(page, '/', total)}
+      style={{ flex: 1 }}
+    />
+  );
+}
+\`\`\`
+
+## Common Mistakes
+
+1. **Forgetting peer deps** \u2014 Web needs \`pdfjs-dist\`, native needs \`react-native-pdf\` + \`react-native-blob-util\`
+2. **PDF.js worker not configured** \u2014 On web, the worker URL is auto-configured from CDN. If using a custom bundler setup, set \`pdfjs.GlobalWorkerOptions.workerSrc\` before rendering.
+3. **page is 1-indexed** \u2014 First page is \`1\`, not \`0\`
+4. **fitPolicy is a string** \u2014 Use \`'width'\`, \`'height'\`, or \`'both'\` (NOT numeric values)
+5. **base64 source** \u2014 Use \`{ base64: 'JVBERi...' }\` without the data URI prefix
+`,
+  "idealyst://pdf/api": `# @idealyst/pdf \u2014 API Reference
+
+## PDFViewerProps
+
+\`\`\`typescript
+interface PDFViewerProps {
+  /** PDF source \u2014 URL string, { uri } object, or { base64 } data */
+  source: PDFSource;
+
+  /** Current page (1-indexed). Default: 1 */
+  page?: number;
+
+  /** Called when page changes */
+  onPageChange?: (page: number, totalPages: number) => void;
+
+  /** Called when document loads */
+  onLoad?: (info: PDFDocumentInfo) => void;
+
+  /** Called on error */
+  onError?: (error: Error) => void;
+
+  /** Enable zoom. Default: true */
+  zoomEnabled?: boolean;
+
+  /** Min zoom. Default: 1 */
+  minZoom?: number;
+
+  /** Max zoom. Default: 5 */
+  maxZoom?: number;
+
+  /** Scroll direction. Default: 'vertical' */
+  direction?: PDFDirection;
+
+  /** Show page indicator. Default: true */
+  showPageIndicator?: boolean;
+
+  /** Fit policy. Default: 'width' */
+  fitPolicy?: FitPolicy;
+
+  /** Container style */
+  style?: ViewStyle;
+
+  /** Test ID */
+  testID?: string;
+}
+\`\`\`
+
+## Types
+
+\`\`\`typescript
+type PDFSource = string | { uri: string } | { base64: string };
+
+type FitPolicy = 'width' | 'height' | 'both';
+
+type PDFDirection = 'horizontal' | 'vertical';
+
+interface PDFDocumentInfo {
+  totalPages: number;
+}
+\`\`\`
+
+## PDFViewerRef (Imperative)
+
+\`\`\`typescript
+interface PDFViewerRef {
+  /** Navigate to page (1-indexed) */
+  goToPage: (page: number) => void;
+
+  /** Set zoom level */
+  setZoom: (level: number) => void;
+}
+\`\`\`
+
+Usage:
+\`\`\`tsx
+const pdfRef = useRef<PDFViewerRef>(null);
+
+<PDFViewer ref={pdfRef} source="..." />
+
+pdfRef.current?.goToPage(5);
+pdfRef.current?.setZoom(2);
+\`\`\`
+`,
+  "idealyst://pdf/examples": `# @idealyst/pdf \u2014 Examples
+
+## Basic URL Viewer
+
+\`\`\`tsx
+import { PDFViewer } from '@idealyst/pdf';
+import { View } from '@idealyst/components';
+
+function BasicPDFScreen() {
+  return (
+    <View style={{ flex: 1 }}>
+      <PDFViewer
+        source="https://example.com/document.pdf"
+        style={{ flex: 1 }}
+      />
+    </View>
+  );
+}
+\`\`\`
+
+## With Page Navigation Controls
+
+\`\`\`tsx
+import { useRef, useState } from 'react';
+import { PDFViewer, PDFViewerRef } from '@idealyst/pdf';
+import { View, Text, Button } from '@idealyst/components';
+
+function PDFWithControls() {
+  const pdfRef = useRef<PDFViewerRef>(null);
+  const [currentPage, setCurrentPage] = useState(1);
+  const [totalPages, setTotalPages] = useState(0);
+
+  return (
+    <View style={{ flex: 1 }}>
+      <PDFViewer
+        ref={pdfRef}
+        source="https://example.com/document.pdf"
+        onLoad={({ totalPages: total }) => setTotalPages(total)}
+        onPageChange={(page) => setCurrentPage(page)}
+        showPageIndicator={false}
+        style={{ flex: 1 }}
+      />
+      <View direction="row" justify="center" align="center" gap="md" padding="md">
+        <Button
+          label="Previous"
+          size="sm"
+          onPress={() => pdfRef.current?.goToPage(Math.max(1, currentPage - 1))}
+        />
+        <Text>{currentPage} / {totalPages}</Text>
+        <Button
+          label="Next"
+          size="sm"
+          onPress={() => pdfRef.current?.goToPage(Math.min(totalPages, currentPage + 1))}
+        />
+      </View>
+    </View>
+  );
+}
+\`\`\`
+
+## Base64 Source
+
+\`\`\`tsx
+import { PDFViewer } from '@idealyst/pdf';
+
+function Base64PDF({ base64Data }: { base64Data: string }) {
+  return (
+    <PDFViewer
+      source={{ base64: base64Data }}
+      fitPolicy="both"
+      style={{ flex: 1 }}
+    />
+  );
+}
+\`\`\`
+
+## Horizontal Mode
+
+\`\`\`tsx
+import { PDFViewer } from '@idealyst/pdf';
+
+function HorizontalPDF() {
+  return (
+    <PDFViewer
+      source="https://example.com/slides.pdf"
+      direction="horizontal"
+      fitPolicy="both"
+      style={{ flex: 1 }}
+    />
+  );
+}
+\`\`\`
+
+## With Error Handling
+
+\`\`\`tsx
+import { useState } from 'react';
+import { PDFViewer } from '@idealyst/pdf';
+import { View, Text } from '@idealyst/components';
+
+function SafePDFViewer({ url }: { url: string }) {
+  const [error, setError] = useState<string | null>(null);
+
+  if (error) {
+    return (
+      <View style={{ flex: 1 }} align="center" justify="center">
+        <Text intent="danger">Failed to load PDF: {error}</Text>
+      </View>
+    );
+  }
+
+  return (
+    <PDFViewer
+      source={url}
+      onError={(err) => setError(err.message)}
+      style={{ flex: 1 }}
+    />
+  );
+}
+\`\`\`
+
+## Zoom Controls
+
+\`\`\`tsx
+import { useRef, useState } from 'react';
+import { PDFViewer, PDFViewerRef } from '@idealyst/pdf';
+import { View, Button } from '@idealyst/components';
+
+function ZoomablePDF() {
+  const pdfRef = useRef<PDFViewerRef>(null);
+  const [zoom, setZoom] = useState(1);
+
+  const handleZoom = (level: number) => {
+    setZoom(level);
+    pdfRef.current?.setZoom(level);
+  };
+
+  return (
+    <View style={{ flex: 1 }}>
+      <PDFViewer
+        ref={pdfRef}
+        source="https://example.com/document.pdf"
+        minZoom={0.5}
+        maxZoom={4}
+        style={{ flex: 1 }}
+      />
+      <View direction="row" justify="center" gap="sm" padding="sm">
+        <Button label="50%" size="sm" onPress={() => handleZoom(0.5)} />
+        <Button label="100%" size="sm" onPress={() => handleZoom(1)} />
+        <Button label="200%" size="sm" onPress={() => handleZoom(2)} />
+      </View>
+    </View>
+  );
+}
+\`\`\`
+`
+};
+
 // src/data/packages.ts
 var packages = {
   components: {
@@ -11801,6 +12118,50 @@ function App() {
       "NetworkState { isConnected, isInternetReachable, type, effectiveType, cellularGeneration, downlink, rtt, isDataSaving }"
     ],
     relatedPackages: ["storage", "config"]
+  },
+  pdf: {
+    name: "PDF",
+    npmName: "@idealyst/pdf",
+    description: "Cross-platform PDF viewer for React and React Native. Renders PDFs from URL, local file, or base64 with page navigation, zoom, and scroll.",
+    category: "media",
+    platforms: ["web", "native"],
+    documentationStatus: "full",
+    installation: "yarn add @idealyst/pdf",
+    peerDependencies: [
+      "pdfjs-dist (web)",
+      "react-native-pdf (native)",
+      "react-native-blob-util (native)"
+    ],
+    features: [
+      "Render PDFs from URL, file path, or base64",
+      "Page navigation (controlled or free scroll)",
+      "Pinch-to-zoom with configurable limits",
+      "Horizontal and vertical scroll modes",
+      "Page indicator overlay",
+      "Fit-to-width, fit-to-height, fit-both modes",
+      "PDFViewerRef for imperative control (goToPage, setZoom)"
+    ],
+    quickStart: `import { PDFViewer } from '@idealyst/pdf';
+
+function DocumentScreen() {
+  return (
+    <PDFViewer
+      source="https://example.com/document.pdf"
+      onLoad={({ totalPages }) => console.log('Pages:', totalPages)}
+      onPageChange={(page, total) => console.log(page, '/', total)}
+      style={{ flex: 1 }}
+    />
+  );
+}`,
+    apiHighlights: [
+      "PDFViewer component",
+      "PDFViewerRef \u2014 goToPage(page), setZoom(level)",
+      "PDFSource = string | { uri: string } | { base64: string }",
+      "fitPolicy: 'width' | 'height' | 'both'",
+      "direction: 'horizontal' | 'vertical'",
+      "onLoad, onPageChange, onError callbacks"
+    ],
+    relatedPackages: ["components"]
   }
 };
 function getPackagesByCategory() {
@@ -15985,6 +16346,79 @@ function Test() {
         solution: "Check that you're running on a supported platform (iOS 16.2+ or Android API 24+). On web, Live Activities are not supported and will always return not_supported."
       }
     ]
+  },
+  // =====================================================================
+  // MEDIA PACKAGES — PDF
+  // =====================================================================
+  pdf: {
+    packageName: "PDF",
+    npmName: "@idealyst/pdf",
+    description: "Cross-platform PDF viewer using pdfjs-dist (web) and react-native-pdf (native)",
+    platforms: ["web", "native"],
+    complexity: "moderate",
+    installation: {
+      yarn: "yarn add @idealyst/pdf",
+      npm: "npm install @idealyst/pdf"
+    },
+    peerDependencies: [
+      {
+        name: "pdfjs-dist",
+        required: true,
+        platforms: ["web"],
+        note: "Mozilla PDF.js for web rendering"
+      },
+      {
+        name: "react-native-pdf",
+        required: true,
+        platforms: ["native"],
+        note: "Native PDF renderer (PDFKit on iOS, PdfRenderer on Android)"
+      },
+      {
+        name: "react-native-blob-util",
+        required: true,
+        platforms: ["native"],
+        note: "Required peer dependency of react-native-pdf for file handling"
+      }
+    ],
+    ios: {
+      podInstallRequired: true,
+      additionalSteps: [
+        "cd ios && pod install",
+        "Ensure minimum iOS deployment target is 13.0 or higher"
+      ]
+    },
+    android: {
+      permissions: [],
+      additionalSteps: [
+        "No special permissions required for PDF viewing",
+        "Ensure minSdkVersion is 21 or higher"
+      ]
+    },
+    web: {
+      additionalDependencies: ["pdfjs-dist"],
+      notes: [
+        "The pdfjs-dist worker is auto-configured from CDN by default.",
+        "For custom setups: set pdfjs.GlobalWorkerOptions.workerSrc before rendering PDFViewer.",
+        "For Vite: import pdfjs-dist/build/pdf.worker.min.mjs and set as workerSrc."
+      ]
+    },
+    verification: `import { PDFViewer } from '@idealyst/pdf';
+// Should render without errors:
+<PDFViewer source="https://example.com/sample.pdf" style={{ flex: 1 }} />`,
+    troubleshooting: [
+      {
+        issue: "PDF.js worker not found on web",
+        solution: "Set pdfjs.GlobalWorkerOptions.workerSrc to the correct worker URL before rendering PDFViewer. The package sets a CDN default, but custom bundler setups may need manual configuration."
+      },
+      {
+        issue: "react-native-pdf not linking on iOS",
+        solution: "Run cd ios && pod install and rebuild the project. Ensure minimum deployment target is iOS 13.0+."
+      },
+      {
+        issue: "Blank screen on Android",
+        solution: "Ensure minSdkVersion is 21+ in android/build.gradle. Also check that react-native-blob-util is installed as a peer of react-native-pdf."
+      }
+    ]
   }
 };
 function getInstallGuide(packageName) {
@@ -66975,6 +67409,17 @@ function getNetworkGuide(args) {
   }
   return textResponse(guide);
 }
+function getPdfGuide(args) {
+  const topic = args.topic;
+  const uri = `idealyst://pdf/${topic}`;
+  const guide = pdfGuides[uri];
+  if (!guide) {
+    return textResponse(
+      `Topic "${topic}" not found. Available topics: overview, api, examples`
+    );
+  }
+  return textResponse(guide);
+}
 function listPackages(args = {}) {
   const category = args.category;
   if (category) {
@@ -67226,6 +67671,7 @@ var toolHandlers = {
   get_notifications_guide: getNotificationsGuide,
   get_live_activity_guide: getLiveActivityGuide,
   get_network_guide: getNetworkGuide,
+  get_pdf_guide: getPdfGuide,
   list_packages: listPackages,
   get_package_docs: getPackageDocs,
   search_packages: searchPackages2,
@@ -67299,6 +67745,8 @@ function callTool(name, args = {}) {
   getPackageDocsDefinition,
   getPaymentsGuide,
   getPaymentsGuideDefinition,
+  getPdfGuide,
+  getPdfGuideDefinition,
   getRecipe,
   getRecipeDefinition,
   getRegistryThemeValues,