@jlcpcb/mcp 0.1.0

package/src/tools/library-update.ts

@@ -0,0 +1,412 @@
+/**
+ * Library Update Tool
+ * Parses existing JLC-MCP-* libraries and regenerates all components
+ * with latest data, normalization, and hybrid footprint logic
+ */
+
+import { z } from 'zod';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { existsSync, readdirSync } from 'fs';
+import { readFile } from 'fs/promises';
+import { homedir, platform } from 'os';
+import {
+  easyedaClient,
+  symbolConverter,
+  footprintConverter,
+  getLibraryCategory,
+  getLibraryFilename,
+  getFootprintDirName,
+  get3DModelsDirName,
+  getAllCategories,
+  type LibraryCategory,
+  ensureDir,
+  writeText,
+} from '@jlcpcb/core';
+import { join } from 'path';
+
+// KiCad versions to check (newest first)
+const KICAD_VERSIONS = ['9.0', '8.0'];
+
+// 3rd party library namespace
+const LIBRARY_NAMESPACE = 'jlc_mcp';
+
+/**
+ * Detect KiCad major version from existing user directories
+ */
+function detectKicadVersion(): string {
+  const home = homedir();
+  const baseDir = join(home, 'Documents', 'KiCad');
+
+  for (const version of KICAD_VERSIONS) {
+    if (existsSync(join(baseDir, version))) {
+      return version;
+    }
+  }
+  return '9.0'; // Default
+}
+
+/**
+ * Get library paths for update operation
+ * Platform-specific paths matching where ${KICAD9_3RD_PARTY} resolves:
+ * - macOS/Windows: ~/Documents/KiCad/{version}/3rdparty/jlc_mcp/
+ * - Linux: ~/.local/share/kicad/{version}/3rdparty/jlc_mcp/
+ */
+function getLibraryPaths(projectPath?: string): {
+  symbolsDir: string;
+  footprintDir: string;
+  models3dDir: string;
+} {
+  if (projectPath) {
+    const librariesDir = join(projectPath, 'libraries');
+    return {
+      symbolsDir: join(librariesDir, 'symbols'),
+      footprintDir: join(librariesDir, 'footprints', getFootprintDirName()),
+      models3dDir: join(librariesDir, '3dmodels', get3DModelsDirName()),
+    };
+  }
+
+  const home = homedir();
+  const version = detectKicadVersion();
+  const plat = platform();
+
+  let base: string;
+  if (plat === 'linux') {
+    base = join(home, '.local', 'share', 'kicad', version, '3rdparty', LIBRARY_NAMESPACE);
+  } else {
+    base = join(home, 'Documents', 'KiCad', version, '3rdparty', LIBRARY_NAMESPACE);
+  }
+
+  return {
+    symbolsDir: join(base, 'symbols'),
+    footprintDir: join(base, 'footprints', getFootprintDirName()),
+    models3dDir: join(base, '3dmodels', get3DModelsDirName()),
+  };
+}
+
+/**
+ * Extract LCSC IDs from a symbol library file
+ */
+function extractLcscIdsFromLibrary(content: string): string[] {
+  const pattern = /\(property\s+"LCSC"\s+"(C\d+)"/g;
+  const ids: string[] = [];
+  let match;
+  while ((match = pattern.exec(content)) !== null) {
+    ids.push(match[1]);
+  }
+  return ids;
+}
+
+/**
+ * Generate standard KiCad symbol library header
+ */
+function generateEmptyLibrary(): string {
+  return `(kicad_symbol_lib
+\t(version 20241209)
+\t(generator "jlc-mcp")
+\t(generator_version "9.0")
+)\n`;
+}
+
+/**
+ * Find all JLC-MCP-*.kicad_sym files in a directory
+ */
+function findJlcLibraries(symbolsDir: string): string[] {
+  if (!existsSync(symbolsDir)) {
+    return [];
+  }
+
+  try {
+    const files = readdirSync(symbolsDir);
+    return files
+      .filter((f) => f.startsWith('JLC-MCP-') && f.endsWith('.kicad_sym'))
+      .map((f) => join(symbolsDir, f));
+  } catch {
+    return [];
+  }
+}
+
+export const updateLibraryTool: Tool = {
+  name: 'library_update',
+  description: `Parse existing JLC-MCP-* libraries and regenerate all components with latest data.
+
+If no JLC-MCP-* libraries exist, initializes empty library files for all categories:
+- JLC-MCP-Resistors, JLC-MCP-Capacitors, JLC-MCP-Inductors, JLC-MCP-Diodes
+- JLC-MCP-Transistors, JLC-MCP-ICs, JLC-MCP-Connectors, JLC-MCP-Misc
+
+Also creates footprint directory (JLC-MCP.pretty) and 3D models directory (JLC-MCP.3dshapes).
+
+When libraries exist, this tool:
+1. Finds all JLC-MCP-*.kicad_sym files in the symbols directory
+2. Extracts LCSC IDs from each symbol's properties
+3. Fetches fresh data from EasyEDA for each component
+4. Regenerates symbols with value normalization
+5. Applies hybrid footprint logic (KiCad standard vs generated)
+6. Rebuilds category-based libraries
+
+Use dry_run=true to preview changes without writing files.`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      project_path: {
+        type: 'string',
+        description: 'Optional: Project path. If omitted, uses global KiCad library.',
+      },
+      dry_run: {
+        type: 'boolean',
+        description: 'Preview changes without writing files (default: false)',
+      },
+    },
+  },
+};
+
+export const UpdateLibraryParamsSchema = z.object({
+  project_path: z.string().min(1).optional(),
+  dry_run: z.boolean().default(false),
+});
+
+interface UpdateResult {
+  lcscId: string;
+  category: LibraryCategory;
+  symbolName: string;
+  footprintType: 'reference' | 'generated';
+  footprintRef: string;
+  status: 'updated' | 'failed';
+  error?: string;
+}
+
+export async function handleUpdateLibrary(args: unknown) {
+  const params = UpdateLibraryParamsSchema.parse(args);
+  const paths = getLibraryPaths(params.project_path);
+
+  // Find all existing JLC libraries
+  const libraryFiles = findJlcLibraries(paths.symbolsDir);
+
+  if (libraryFiles.length === 0) {
+    // No existing libraries - initialize empty libraries for all categories
+    const allCategories = getAllCategories();
+
+    if (params.dry_run) {
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify({
+            success: true,
+            action: 'would_initialize',
+            dry_run: true,
+            summary: {
+              categories_to_create: allCategories.length,
+              directories_to_create: [
+                paths.symbolsDir,
+                paths.footprintDir,
+                paths.models3dDir,
+              ],
+            },
+            libraries_to_create: allCategories.map((cat) => ({
+              category: cat,
+              filename: getLibraryFilename(cat),
+              path: join(paths.symbolsDir, getLibraryFilename(cat)),
+            })),
+          }, null, 2),
+        }],
+      };
+    }
+
+    // Create directories
+    await ensureDir(paths.symbolsDir);
+    await ensureDir(paths.footprintDir);
+    await ensureDir(paths.models3dDir);
+
+    // Create empty library files for all categories
+    const emptyContent = generateEmptyLibrary();
+    const createdLibraries: string[] = [];
+
+    for (const category of allCategories) {
+      const filename = getLibraryFilename(category);
+      const filepath = join(paths.symbolsDir, filename);
+      await writeText(filepath, emptyContent);
+      createdLibraries.push(filepath);
+    }
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify({
+          success: true,
+          action: 'initialized',
+          dry_run: false,
+          summary: {
+            categories_initialized: allCategories.length,
+            directories_created: [
+              paths.symbolsDir,
+              paths.footprintDir,
+              paths.models3dDir,
+            ],
+          },
+          libraries_created: createdLibraries,
+          next_steps: [
+            'Use library_fetch to add components to your libraries',
+            'Run library_update again after adding components to regenerate with latest data',
+          ],
+        }, null, 2),
+      }],
+    };
+  }
+
+  // Extract all LCSC IDs from existing libraries
+  const allLcscIds: Set<string> = new Set();
+  const libraryInfo: { file: string; ids: string[] }[] = [];
+
+  for (const file of libraryFiles) {
+    const content = await readFile(file, 'utf-8');
+    const ids = extractLcscIdsFromLibrary(content);
+    libraryInfo.push({ file, ids });
+    ids.forEach((id) => allLcscIds.add(id));
+  }
+
+  if (allLcscIds.size === 0) {
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify({
+          success: false,
+          error: 'No LCSC IDs found in existing libraries',
+          libraries_scanned: libraryFiles.length,
+        }),
+      }],
+      isError: true,
+    };
+  }
+
+  // Process each component
+  const results: UpdateResult[] = [];
+  const categorySymbols: Map<LibraryCategory, string[]> = new Map();
+
+  for (const lcscId of allLcscIds) {
+    try {
+      // Fetch fresh component data
+      const component = await easyedaClient.getComponentData(lcscId);
+
+      if (!component) {
+        results.push({
+          lcscId,
+          category: 'Misc',
+          symbolName: '',
+          footprintType: 'generated',
+          footprintRef: '',
+          status: 'failed',
+          error: 'Component not found',
+        });
+        continue;
+      }
+
+      // Determine category
+      const category = getLibraryCategory(
+        component.info.prefix,
+        component.info.category,
+        component.info.description
+      );
+
+      // Generate symbol entry (without library wrapper)
+      const symbolEntry = symbolConverter.convertToSymbolEntry(component);
+      const symbolName = symbolConverter.getSymbolName(component);
+
+      // Collect symbols by category
+      if (!categorySymbols.has(category)) {
+        categorySymbols.set(category, []);
+      }
+      categorySymbols.get(category)!.push(symbolEntry);
+
+      // Handle footprint
+      const footprintResult = footprintConverter.getFootprint(component);
+
+      // Generate custom footprint if needed (not in dry run)
+      if (!params.dry_run && footprintResult.type === 'generated') {
+        await ensureDir(paths.footprintDir);
+        const footprintName = footprintResult.name + '_' + lcscId;
+        const footprintPath = join(paths.footprintDir, `${footprintName}.kicad_mod`);
+        await writeText(footprintPath, footprintResult.content!);
+      }
+
+      results.push({
+        lcscId,
+        category,
+        symbolName,
+        footprintType: footprintResult.type,
+        footprintRef: footprintResult.type === 'reference'
+          ? footprintResult.reference!
+          : `JLC:${footprintResult.name}_${lcscId}`,
+        status: 'updated',
+      });
+    } catch (error) {
+      results.push({
+        lcscId,
+        category: 'Misc',
+        symbolName: '',
+        footprintType: 'generated',
+        footprintRef: '',
+        status: 'failed',
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  // Write category-based libraries (not in dry run)
+  if (!params.dry_run) {
+    await ensureDir(paths.symbolsDir);
+
+    for (const [category, entries] of categorySymbols) {
+      const filename = getLibraryFilename(category);
+      const filepath = join(paths.symbolsDir, filename);
+
+      // Create library file with all symbols
+      const header = `(kicad_symbol_lib
+\t(version 20241209)
+\t(generator "jlc-mcp")
+\t(generator_version "9.0")
+`;
+      const content = header + entries.join('') + ')\n';
+      await writeText(filepath, content);
+    }
+  }
+
+  // Summarize results
+  const successful = results.filter((r) => r.status === 'updated');
+  const failed = results.filter((r) => r.status === 'failed');
+  const byCategory = new Map<LibraryCategory, number>();
+
+  for (const r of successful) {
+    byCategory.set(r.category, (byCategory.get(r.category) || 0) + 1);
+  }
+
+  const footprintStats = {
+    kicad_standard: successful.filter((r) => r.footprintType === 'reference').length,
+    custom_generated: successful.filter((r) => r.footprintType === 'generated').length,
+  };
+
+  return {
+    content: [{
+      type: 'text' as const,
+      text: JSON.stringify({
+        success: true,
+        dry_run: params.dry_run,
+        summary: {
+          total_components: allLcscIds.size,
+          updated: successful.length,
+          failed: failed.length,
+          libraries_generated: categorySymbols.size,
+        },
+        by_category: Object.fromEntries(byCategory),
+        footprint_stats: footprintStats,
+        libraries_written: params.dry_run
+          ? []
+          : Array.from(categorySymbols.keys()).map((cat) =>
+            join(paths.symbolsDir, getLibraryFilename(cat))
+          ),
+        failed_components: failed.map((f) => ({
+          lcsc_id: f.lcscId,
+          error: f.error,
+        })),
+      }, null, 2),
+    }],
+  };
+}

package/src/tools/library.ts

@@ -0,0 +1,263 @@
+/**
+ * Library fetching and conversion tools for MCP
+ * Uses jlc-core for all business logic
+ */
+
+import { z } from 'zod';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import {
+  createLibraryService,
+  createComponentService,
+  easyedaClient,
+  symbolConverter,
+  footprintConverter,
+} from '@jlcpcb/core';
+
+const libraryService = createLibraryService();
+const componentService = createComponentService();
+
+export const getSymbolKicadTool: Tool = {
+  name: 'library_get_symbol',
+  description: 'Get a KiCad-compatible symbol definition by LCSC part number. Returns the symbol in .kicad_sym format. LCSC is JLC PCB\'s preferred supplier for assembly.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      lcsc_id: {
+        type: 'string',
+        description: 'LCSC part number (e.g., C2040)',
+      },
+    },
+    required: ['lcsc_id'],
+  },
+};
+
+export const getFootprintKicadTool: Tool = {
+  name: 'library_get_footprint',
+  description: 'Get a KiCad-compatible footprint definition by LCSC part number. Returns the footprint in .kicad_mod format. LCSC is JLC PCB\'s preferred supplier for assembly.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      lcsc_id: {
+        type: 'string',
+        description: 'LCSC part number (e.g., C2040)',
+      },
+    },
+    required: ['lcsc_id'],
+  },
+};
+
+export const fetchLibraryTool: Tool = {
+  name: 'library_fetch',
+  description: `Fetch a component and add it to KiCad libraries.
+
+Accepts:
+- LCSC part numbers (e.g., C2040) → global JLC-MCP libraries
+- EasyEDA UUIDs (e.g., 8007c710c0b9406db963b55df6990340) → project-local EasyEDA library (requires project_path)
+
+LCSC components are routed to category-based global libraries:
+- JLC-MCP-Resistors.kicad_sym, JLC-MCP-Capacitors.kicad_sym, JLC-MCP-ICs.kicad_sym, etc.
+- Stored at ~/Documents/KiCad/{version}/3rdparty/jlc_mcp/
+
+EasyEDA community components are stored project-locally:
+- <project>/libraries/symbols/EasyEDA.kicad_sym
+- <project>/libraries/footprints/EasyEDA.pretty/
+
+Returns symbol_ref and footprint_ref for immediate use with add_schematic_component.`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      id: {
+        type: 'string',
+        description: 'LCSC part number (e.g., C2040) or EasyEDA community UUID',
+      },
+      project_path: {
+        type: 'string',
+        description: 'Project path (required for EasyEDA UUIDs, optional for LCSC IDs)',
+      },
+      include_3d: {
+        type: 'boolean',
+        description: 'Include 3D model if available (default: false for LCSC, true for EasyEDA)',
+      },
+    },
+    required: ['id'],
+  },
+};
+
+export const get3DModelTool: Tool = {
+  name: 'library_get_3d_model',
+  description: 'Download a 3D model for a component. Requires the model UUID from component_get. Returns the model as base64-encoded STEP data.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      uuid: {
+        type: 'string',
+        description: '3D model UUID from component_get result',
+      },
+      format: {
+        type: 'string',
+        enum: ['step', 'obj'],
+        description: 'Model format: "step" or "obj" (default: step)',
+      },
+    },
+    required: ['uuid'],
+  },
+};
+
+export const LibraryParamsSchema = z.object({
+  lcsc_id: z.string().regex(/^C\d+$/, 'Invalid LCSC part number'),
+});
+
+export const FetchLibraryParamsSchema = z.object({
+  id: z.string().min(1),
+  project_path: z.string().min(1).optional(),
+  include_3d: z.boolean().optional(),
+});
+
+export const Model3DParamsSchema = z.object({
+  uuid: z.string().min(1),
+  format: z.enum(['step', 'obj']).default('step'),
+});
+
+export async function handleGetSymbolKicad(args: unknown) {
+  const params = LibraryParamsSchema.parse(args);
+
+  const component = await easyedaClient.getComponentData(params.lcsc_id);
+
+  if (!component) {
+    return {
+      content: [{
+        type: 'text' as const,
+        text: `Component ${params.lcsc_id} not found`,
+      }],
+      isError: true,
+    };
+  }
+
+  const symbol = symbolConverter.convert(component);
+  return {
+    content: [{
+      type: 'text' as const,
+      text: symbol,
+    }],
+  };
+}
+
+export async function handleGetFootprintKicad(args: unknown) {
+  const params = LibraryParamsSchema.parse(args);
+
+  const component = await easyedaClient.getComponentData(params.lcsc_id);
+
+  if (!component) {
+    return {
+      content: [{
+        type: 'text' as const,
+        text: `Component ${params.lcsc_id} not found`,
+      }],
+      isError: true,
+    };
+  }
+
+  const footprint = footprintConverter.convert(component);
+  return {
+    content: [{
+      type: 'text' as const,
+      text: footprint,
+    }],
+  };
+}
+
+/**
+ * Check if ID is an LCSC part number (C followed by digits)
+ */
+function isLcscId(id: string): boolean {
+  return /^C\d+$/.test(id);
+}
+
+export async function handleFetchLibrary(args: unknown) {
+  const params = FetchLibraryParamsSchema.parse(args);
+  const isCommunityComponent = !isLcscId(params.id);
+
+  // Community components require project_path
+  if (isCommunityComponent && !params.project_path) {
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify({
+          success: false,
+          error: 'EasyEDA community components require project_path for local storage',
+          id: params.id,
+          hint: 'Provide project_path to store in <project>/libraries/EasyEDA.*',
+        }),
+      }],
+      isError: true,
+    };
+  }
+
+  try {
+    const result = await libraryService.install(params.id, {
+      projectPath: params.project_path,
+      include3d: params.include_3d,
+    });
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify({
+          success: true,
+          id: params.id,
+          source: result.source,
+          storage_mode: result.storageMode,
+          category: result.category,
+          symbol_name: result.symbolName,
+          symbol_ref: result.symbolRef,
+          footprint_ref: result.footprintRef,
+          footprint_type: result.footprintType,
+          datasheet: result.datasheet,
+          files: {
+            symbol_library: result.files.symbolLibrary,
+            footprint: result.files.footprint,
+            model_3d: result.files.model3d,
+          },
+          symbol_action: result.symbolAction,
+          validation_data: result.validationData,
+        }, null, 2),
+      }],
+    };
+  } catch (error) {
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify({
+          success: false,
+          error: error instanceof Error ? error.message : 'Unknown error',
+          id: params.id,
+          source: isCommunityComponent ? 'easyeda_community' : 'lcsc',
+        }),
+      }],
+      isError: true,
+    };
+  }
+}
+
+export async function handleGet3DModel(args: unknown) {
+  const params = Model3DParamsSchema.parse(args);
+
+  const model = await easyedaClient.get3DModel(params.uuid, params.format);
+
+  if (!model) {
+    return {
+      content: [{
+        type: 'text' as const,
+        text: `3D model ${params.uuid} not found`,
+      }],
+      isError: true,
+    };
+  }
+
+  return {
+    content: [{
+      type: 'text' as const,
+      text: `3D model downloaded (${model.length} bytes, ${params.format.toUpperCase()} format)\n\nBase64 data:\n${model.toString('base64').slice(0, 500)}...`,
+    }],
+  };
+}