@jlcpcb/mcp 0.1.0

package/src/browser/sexpr-parser.ts

@@ -0,0 +1,321 @@
+/**
+ * S-Expression Parser for KiCad format
+ * Parses KiCad symbol and footprint S-expressions for browser-side rendering
+ */
+
+export type SExpr = string | SExpr[]
+
+/**
+ * Tokenize S-expression input into tokens
+ * Handles parentheses, quoted strings, and atoms
+ */
+function tokenize(input: string): string[] {
+  const tokens: string[] = []
+  let i = 0
+
+  while (i < input.length) {
+    const char = input[i]
+
+    // Skip whitespace
+    if (/\s/.test(char)) {
+      i++
+      continue
+    }
+
+    // Opening/closing parens
+    if (char === '(' || char === ')') {
+      tokens.push(char)
+      i++
+      continue
+    }
+
+    // Quoted string
+    if (char === '"') {
+      let str = ''
+      i++ // skip opening quote
+      while (i < input.length) {
+        if (input[i] === '\\' && i + 1 < input.length) {
+          // Escape sequence
+          str += input[i + 1]
+          i += 2
+        } else if (input[i] === '"') {
+          i++ // skip closing quote
+          break
+        } else {
+          str += input[i]
+          i++
+        }
+      }
+      tokens.push(`"${str}"`)
+      continue
+    }
+
+    // Atom (unquoted token)
+    let atom = ''
+    while (i < input.length && !/[\s()]/.test(input[i])) {
+      atom += input[i]
+      i++
+    }
+    if (atom) {
+      tokens.push(atom)
+    }
+  }
+
+  return tokens
+}
+
+/**
+ * Parse tokens into nested S-expression structure
+ */
+function parseTokens(tokens: string[]): { expr: SExpr; remaining: string[] } {
+  if (tokens.length === 0) {
+    return { expr: [], remaining: [] }
+  }
+
+  const token = tokens[0]
+
+  if (token === '(') {
+    // Start of list
+    const list: SExpr[] = []
+    let rest = tokens.slice(1)
+
+    while (rest.length > 0 && rest[0] !== ')') {
+      const { expr, remaining } = parseTokens(rest)
+      list.push(expr)
+      rest = remaining
+    }
+
+    // Skip closing paren
+    if (rest[0] === ')') {
+      rest = rest.slice(1)
+    }
+
+    return { expr: list, remaining: rest }
+  }
+
+  if (token === ')') {
+    // Unexpected closing paren - return empty and let caller handle
+    return { expr: [], remaining: tokens.slice(1) }
+  }
+
+  // Atom or quoted string
+  let value = token
+  // Strip quotes from quoted strings for easier access
+  if (value.startsWith('"') && value.endsWith('"')) {
+    value = value.slice(1, -1)
+  }
+
+  return { expr: value, remaining: tokens.slice(1) }
+}
+
+/**
+ * Parse S-expression string into nested structure
+ */
+export function parseSExpr(input: string): SExpr {
+  const tokens = tokenize(input)
+  const { expr } = parseTokens(tokens)
+  return expr
+}
+
+/**
+ * Check if expression is a list
+ */
+export function isList(expr: SExpr): expr is SExpr[] {
+  return Array.isArray(expr)
+}
+
+/**
+ * Check if expression is an atom (string)
+ */
+export function isAtom(expr: SExpr): expr is string {
+  return typeof expr === 'string'
+}
+
+/**
+ * Get the first element of a list (the tag/type)
+ */
+export function getTag(expr: SExpr): string | undefined {
+  if (isList(expr) && expr.length > 0 && isAtom(expr[0])) {
+    return expr[0]
+  }
+  return undefined
+}
+
+/**
+ * Find a child element by its tag name
+ * Returns first match or undefined
+ */
+export function findChild(expr: SExpr, tag: string): SExpr[] | undefined {
+  if (!isList(expr)) return undefined
+
+  for (const child of expr) {
+    if (isList(child) && getTag(child) === tag) {
+      return child
+    }
+  }
+  return undefined
+}
+
+/**
+ * Find all child elements with a given tag
+ */
+export function findChildren(expr: SExpr, tag: string): SExpr[][] {
+  if (!isList(expr)) return []
+
+  const results: SExpr[][] = []
+  for (const child of expr) {
+    if (isList(child) && getTag(child) === tag) {
+      results.push(child)
+    }
+  }
+  return results
+}
+
+/**
+ * Get a simple attribute value: (tag value) -> value
+ */
+export function getAttr(expr: SExpr, tag: string): string | undefined {
+  const child = findChild(expr, tag)
+  if (child && child.length >= 2 && isAtom(child[1])) {
+    return child[1]
+  }
+  return undefined
+}
+
+/**
+ * Get a numeric attribute value
+ */
+export function getNumericAttr(expr: SExpr, tag: string): number | undefined {
+  const value = getAttr(expr, tag)
+  if (value !== undefined) {
+    const num = parseFloat(value)
+    if (!isNaN(num)) return num
+  }
+  return undefined
+}
+
+/**
+ * Get a point from (tag x y) format
+ */
+export function getPoint(
+  expr: SExpr,
+  tag: string
+): { x: number; y: number } | undefined {
+  const child = findChild(expr, tag)
+  if (child && child.length >= 3) {
+    const x = parseFloat(isAtom(child[1]) ? child[1] : '')
+    const y = parseFloat(isAtom(child[2]) ? child[2] : '')
+    if (!isNaN(x) && !isNaN(y)) {
+      return { x, y }
+    }
+  }
+  return undefined
+}
+
+/**
+ * Get point with optional rotation: (tag x y [rotation])
+ */
+export function getPointWithRotation(
+  expr: SExpr,
+  tag: string
+): { x: number; y: number; rotation?: number } | undefined {
+  const child = findChild(expr, tag)
+  if (child && child.length >= 3) {
+    const x = parseFloat(isAtom(child[1]) ? child[1] : '')
+    const y = parseFloat(isAtom(child[2]) ? child[2] : '')
+    if (!isNaN(x) && !isNaN(y)) {
+      const result: { x: number; y: number; rotation?: number } = { x, y }
+      if (child.length >= 4 && isAtom(child[3])) {
+        const rotation = parseFloat(child[3])
+        if (!isNaN(rotation)) {
+          result.rotation = rotation
+        }
+      }
+      return result
+    }
+  }
+  return undefined
+}
+
+/**
+ * Get size from (size w h) format
+ */
+export function getSize(
+  expr: SExpr
+): { width: number; height: number } | undefined {
+  const child = findChild(expr, 'size')
+  if (child && child.length >= 3) {
+    const width = parseFloat(isAtom(child[1]) ? child[1] : '')
+    const height = parseFloat(isAtom(child[2]) ? child[2] : '')
+    if (!isNaN(width) && !isNaN(height)) {
+      return { width, height }
+    }
+  }
+  return undefined
+}
+
+/**
+ * Get stroke properties from (stroke ...) element
+ */
+export function getStroke(
+  expr: SExpr
+): { width: number; type: string } | undefined {
+  const stroke = findChild(expr, 'stroke')
+  if (!stroke) return undefined
+
+  const width = getNumericAttr(stroke, 'width') ?? 0.254
+  const type = getAttr(stroke, 'type') ?? 'default'
+
+  return { width, type }
+}
+
+/**
+ * Get fill type from (fill (type ...)) element
+ */
+export function getFillType(expr: SExpr): string | undefined {
+  const fill = findChild(expr, 'fill')
+  if (!fill) return undefined
+  return getAttr(fill, 'type')
+}
+
+/**
+ * Get all XY points from (pts (xy x y) (xy x y) ...) structure
+ */
+export function getPoints(expr: SExpr): Array<{ x: number; y: number }> {
+  const pts = findChild(expr, 'pts')
+  if (!pts) return []
+
+  const points: Array<{ x: number; y: number }> = []
+  for (const child of pts) {
+    if (isList(child) && getTag(child) === 'xy' && child.length >= 3) {
+      const x = parseFloat(isAtom(child[1]) ? child[1] : '')
+      const y = parseFloat(isAtom(child[2]) ? child[2] : '')
+      if (!isNaN(x) && !isNaN(y)) {
+        points.push({ x, y })
+      }
+    }
+  }
+
+  return points
+}
+
+/**
+ * Get layers from (layers "Layer1" "Layer2" ...) or (layer "Layer")
+ */
+export function getLayers(expr: SExpr): string[] {
+  // Check for single layer
+  const layer = getAttr(expr, 'layer')
+  if (layer) return [layer]
+
+  // Check for multiple layers
+  const layers = findChild(expr, 'layers')
+  if (!layers) return []
+
+  const result: string[] = []
+  for (let i = 1; i < layers.length; i++) {
+    if (isAtom(layers[i])) {
+      result.push(layers[i])
+    }
+  }
+  return result
+}

package/src/http/routes.ts

@@ -0,0 +1,253 @@
+/**
+ * HTTP routes for the EasyEDA Component Browser
+ * Handles serving the HTML page and proxying API requests
+ *
+ * Returns KiCad S-expression strings for symbol/footprint preview rendering
+ */
+
+import { readFileSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import type { IncomingMessage, ServerResponse } from 'http'
+import {
+  createLogger,
+  type EasyEDAComponentData,
+  type EasyEDACommunityComponent,
+  easyedaCommunityClient,
+  symbolConverter,
+  footprintConverter,
+} from '@jlcpcb/core'
+
+const logger = createLogger('http-routes')
+
+// Get the directory of this file to find assets
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+// Cache the HTML content in memory
+let htmlCache: string | null = null
+
+/**
+ * Load the HTML page from the assets directory
+ */
+function getHtmlPage(): string {
+  if (htmlCache) return htmlCache
+
+  try {
+    // When bundled, __dirname points to dist/ since everything is in index.js
+    // When running from source, __dirname is src/http/
+    const possiblePaths = [
+      // Bundled: dist/index.js looking for dist/assets/search.html
+      join(__dirname, 'assets/search.html'),
+      // Bundled alternative path
+      join(__dirname, '../dist/assets/search.html'),
+      // Source: src/http/ looking for src/assets/
+      join(__dirname, '../assets/search.html'),
+      join(__dirname, '../assets/search-built.html'),
+      // From project root
+      join(process.cwd(), 'dist/assets/search.html'),
+      join(process.cwd(), 'packages/jlc-mcp/dist/assets/search.html'),
+    ]
+
+    for (const path of possiblePaths) {
+      try {
+        htmlCache = readFileSync(path, 'utf-8')
+        logger.debug(`Loaded HTML from: ${path}`)
+        return htmlCache
+      } catch {
+        // Try next path
+      }
+    }
+
+    throw new Error('HTML file not found')
+  } catch (error) {
+    logger.error('Failed to load HTML page:', error)
+    return `<!DOCTYPE html>
+<html>
+<head><title>Error</title></head>
+<body>
+<h1>Error: Search page not found</h1>
+<p>The search page has not been built. Run: bun run build</p>
+</body>
+</html>`
+  }
+}
+
+/**
+ * Main request handler
+ */
+export async function handleRequest(
+  req: IncomingMessage,
+  res: ServerResponse
+): Promise<void> {
+  const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`)
+  const pathname = url.pathname
+
+  logger.debug(`${req.method} ${pathname}`)
+
+  // Route requests
+  if (pathname === '/' || pathname === '/index.html') {
+    serveHtml(res)
+  } else if (pathname === '/api/search') {
+    await handleSearch(url, res)
+  } else if (pathname.startsWith('/api/component/')) {
+    const uuid = pathname.replace('/api/component/', '')
+    await handleComponent(uuid, res)
+  } else if (pathname === '/health') {
+    res.writeHead(200, { 'Content-Type': 'application/json' })
+    res.end(JSON.stringify({ status: 'ok' }))
+  } else {
+    res.writeHead(404, { 'Content-Type': 'application/json' })
+    res.end(JSON.stringify({ error: 'Not found' }))
+  }
+}
+
+/**
+ * Serve the HTML page
+ */
+function serveHtml(res: ServerResponse): void {
+  res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
+  res.end(getHtmlPage())
+}
+
+/**
+ * Handle search API requests
+ * GET /api/search?q=query&source=user|lcsc|all&page=1&limit=20
+ */
+async function handleSearch(
+  url: URL,
+  res: ServerResponse
+): Promise<void> {
+  const query = url.searchParams.get('q') || ''
+  const source = url.searchParams.get('source') || 'user'
+  const page = parseInt(url.searchParams.get('page') || '1', 10)
+  const limit = parseInt(url.searchParams.get('limit') || '20', 10)
+
+  if (!query) {
+    res.writeHead(400, { 'Content-Type': 'application/json' })
+    res.end(JSON.stringify({ error: 'Missing query parameter' }))
+    return
+  }
+
+  try {
+    // Fetch more than we need for pagination (EasyEDA doesn't support offset)
+    const allResults = await easyedaCommunityClient.search({
+      query,
+      source: source as 'user' | 'lcsc' | 'easyeda' | 'all',
+      limit: Math.min(limit * page + limit, 100), // Max 100 results
+    })
+
+    // Calculate pagination
+    const startIndex = (page - 1) * limit
+    const endIndex = startIndex + limit
+    const results = allResults.slice(startIndex, endIndex)
+    const totalPages = Math.ceil(allResults.length / limit)
+
+    res.writeHead(200, { 'Content-Type': 'application/json' })
+    res.end(JSON.stringify({
+      results,
+      pagination: {
+        page,
+        limit,
+        total: allResults.length,
+        totalPages,
+        hasNext: page < totalPages,
+        hasPrev: page > 1,
+      },
+    }))
+  } catch (error) {
+    logger.error('Search error:', error)
+    res.writeHead(500, { 'Content-Type': 'application/json' })
+    res.end(JSON.stringify({ error: 'Search failed' }))
+  }
+}
+
+/**
+ * Convert EasyEDACommunityComponent to EasyEDAComponentData format
+ * Required because converters expect the LCSC-style structure
+ */
+function communityToComponentData(
+  community: EasyEDACommunityComponent
+): EasyEDAComponentData {
+  // Extract component info from the head c_para
+  const cPara = community.symbol.head?.c_para as Record<string, string> | undefined ?? {}
+  const fpCPara = community.footprint.head?.c_para as Record<string, string> | undefined ?? {}
+
+  return {
+    info: {
+      name: community.title || cPara.name || 'Unknown',
+      prefix: cPara.pre || cPara.Prefix || 'U',
+      package: fpCPara.package || community.footprint.name,
+      manufacturer: cPara.Manufacturer || cPara.BOM_Manufacturer,
+      description: community.description || cPara.BOM_Manufacturer_Part,
+      category: cPara.package, // Best guess for category
+    },
+    symbol: community.symbol,
+    footprint: community.footprint,
+    model3d: community.model3d,
+    rawData: community.rawData,
+  }
+}
+
+/**
+ * Handle component fetch API requests
+ * GET /api/component/:uuid
+ *
+ * Returns KiCad S-expression strings for browser-side rendering
+ */
+async function handleComponent(
+  uuid: string,
+  res: ServerResponse
+): Promise<void> {
+  if (!uuid) {
+    res.writeHead(400, { 'Content-Type': 'application/json' })
+    res.end(JSON.stringify({ error: 'Missing UUID' }))
+    return
+  }
+
+  try {
+    const component = await easyedaCommunityClient.getComponent(uuid)
+
+    if (!component) {
+      res.writeHead(404, { 'Content-Type': 'application/json' })
+      res.end(JSON.stringify({ error: 'Component not found' }))
+      return
+    }
+
+    // Convert community component to converter-compatible format
+    const componentData = communityToComponentData(component)
+
+    // Generate KiCad S-expression strings using existing converters
+    let symbolSexpr = ''
+    let footprintSexpr = ''
+
+    try {
+      // Get just the symbol entry (not the full library wrapper)
+      symbolSexpr = symbolConverter.convertToSymbolEntry(componentData)
+    } catch (e) {
+      logger.warn('Symbol conversion failed:', e)
+    }
+
+    try {
+      footprintSexpr = footprintConverter.convert(componentData)
+    } catch (e) {
+      logger.warn('Footprint conversion failed:', e)
+    }
+
+    // Return S-expr strings for browser rendering
+    res.writeHead(200, { 'Content-Type': 'application/json' })
+    res.end(JSON.stringify({
+      uuid: component.uuid,
+      title: component.title,
+      description: component.description,
+      owner: component.owner,
+      symbolSexpr,
+      footprintSexpr,
+      model3d: component.model3d,
+    }))
+  } catch (error) {
+    logger.error('Component fetch error:', error)
+    res.writeHead(500, { 'Content-Type': 'application/json' })
+    res.end(JSON.stringify({ error: 'Failed to fetch component' }))
+  }
+}

package/src/http/server.ts

@@ -0,0 +1,74 @@
+/**
+ * HTTP server for the EasyEDA Component Browser
+ * Runs alongside the MCP stdio server to serve the web UI and proxy API requests
+ */
+
+import { createServer, type IncomingMessage, type ServerResponse } from 'http'
+import { createLogger } from '@jlcpcb/core'
+import { handleRequest } from './routes.js'
+
+const logger = createLogger('http-server')
+
+const DEFAULT_PORT = 3847
+
+let serverInstance: ReturnType<typeof createServer> | null = null
+
+/**
+ * Start the HTTP server
+ * @returns The port the server is listening on
+ */
+export function startHttpServer(): number {
+  if (serverInstance) {
+    logger.debug('HTTP server already running')
+    return DEFAULT_PORT
+  }
+
+  const port = parseInt(process.env.JLC_MCP_HTTP_PORT || String(DEFAULT_PORT), 10)
+
+  serverInstance = createServer(async (req: IncomingMessage, res: ServerResponse) => {
+    // Add CORS headers to all responses
+    res.setHeader('Access-Control-Allow-Origin', '*')
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS')
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type')
+
+    // Handle preflight requests
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204)
+      res.end()
+      return
+    }
+
+    try {
+      await handleRequest(req, res)
+    } catch (error) {
+      logger.error('Request error:', error)
+      res.writeHead(500, { 'Content-Type': 'application/json' })
+      res.end(JSON.stringify({ error: 'Internal server error' }))
+    }
+  })
+
+  serverInstance.listen(port, () => {
+    logger.info(`HTTP server listening on http://localhost:${port}`)
+  })
+
+  serverInstance.on('error', (error: NodeJS.ErrnoException) => {
+    if (error.code === 'EADDRINUSE') {
+      logger.warn(`Port ${port} already in use, HTTP server not started`)
+    } else {
+      logger.error('HTTP server error:', error)
+    }
+  })
+
+  return port
+}
+
+/**
+ * Stop the HTTP server
+ */
+export function stopHttpServer(): void {
+  if (serverInstance) {
+    serverInstance.close()
+    serverInstance = null
+    logger.info('HTTP server stopped')
+  }
+}