plm-upload-mcp 1.0.0 → 1.1.0

package/README.md

@@ -1,9 +1,11 @@
 # plm-upload-mcp
 
-An MCP server that bulk-uploads local files (SolidWorks STEP/PDF exports) into the
-**LionsBot PLM**, matched to a component by SKU. It runs on **your own machine**, so
-it reads your exported files straight off disk, and it signs in as **you** with your
-PLM/hub login — every uploaded file is tagged with who uploaded it.
+An MCP server for the **LionsBot PLM**. It **reads** the PLM — SKU folders, full
+component metadata, extracted drawing/BOM metadata, and product & staging BOMs — and
+**bulk-uploads** local files (SolidWorks STEP/PDF exports) into it, matched to a
+component by SKU. It runs on **your own machine**, so it reads your exported files
+straight off disk, and it signs in as **you** with your PLM/hub login — every read is
+row-level-security scoped to you, and every uploaded file is tagged with who uploaded it.
 
 Pair it with your SolidWorks MCP: that MCP knows each part's SKU and exports the files;
 this MCP takes `{path, sku}` pairs and pushes them into the PLM.
@@ -57,6 +59,35 @@ Lists the files currently in a component's Drive folder.
 - `sku`: component SKU
 - `bucket`: `main` (default) or `staging`
 
+## Read-only tools
+
+All read tools query the PLM as **you** (RLS-scoped) — you only ever see what you're
+allowed to see. `bucket` / `classification` values are `main` (confirmed), `staging`
+(unconfirmed), or `all` (default).
+
+### `list_sku_folders`
+Every component SKU with its Google Drive folder — the SKU→folder map (SKU, name,
+category, type, revision, status, staging flag, folder id/URL). Filters: `bucket`,
+`category`, `with_folder_only`, `limit`, `offset`.
+
+### `get_component_metadata`
+Full component metadata (every column, incl. cost/supply, drawing-extracted fields,
+CAD provenance, compliance, and the `extract_meta` block). Pass a single `sku` for one
+part, or omit it to page through all. Filters: `search`, `bucket`, `category`,
+`status`, `limit`, `offset`.
+
+### `list_bom_extract_metadata`
+The metadata machine-extracted from each part's drawing/BOM PDF (`extract_meta`): the
+Lionsbot-custom flag, SKU/drawing match check, per-field extracted values, and source
+file + who/when. Only extracted parts are returned. Filters: `sku`, `bucket`, `limit`,
+`offset`.
+
+### `list_boms`
+BOMs across all products, each product carrying its BOM(s) + line items and a derived
+`staging` flag (a product is *staging* while its working BOM still contains any staging
+component). Working BOMs only by default. Filters: `product_sku`, `classification`,
+`include_snapshots`, `include_rows`, `max_rows_per_bom`.
+
 ## Config overrides (rarely needed)
 
 Baked to production defaults; override via env only if the PLM backend moves:

package/index.mjs

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 /**
- * plm-upload-mcp — bulk-upload local files (SolidWorks STEP/PDF exports) into
- * the LionsBot PLM, matched to a component by SKU.
+ * plm-upload-mcp — read the LionsBot PLM and bulk-upload local files
+ * (SolidWorks STEP/PDF exports) into it, matched to a component by SKU.
  *
  * Runs locally on each engineer's machine (stdio), so it reads their exported
  * files straight off disk. It authenticates as the engineer with their own PLM
  * login (GoTrue password grant) and every uploaded file is tagged with who
- * uploaded it, server-side, by the plm-edge `upload` action.
+ * uploaded it, server-side, by the plm-edge `upload` action. The read-only
+ * tools query PostgREST directly with the engineer's token, so RLS applies
+ * exactly as it does in the PLM web app — they only ever see what they may see.
  *
  * Config (env):
  *   PLM_EMAIL, PLM_PASSWORD   — the engineer's PLM/hub login (required)
@@ -43,6 +45,13 @@ const MIME = {
 }
 const mimeFor = (name) => MIME[extname(name).toLowerCase()] || 'application/octet-stream'
 
+// Supabase Storage rejects object keys with chars outside its safe set (notably
+// '[' ']', which the common "[SKU] Name" convention starts with) -> the store
+// call 400s with "storage upload failed: 400". The key is internal/UUID-prefixed
+// and never shown, so sanitize it to the safe set; the Drive display name (the
+// separate `upload` filename) keeps the original, brackets and all.
+const storageKeyName = (name) => name.replace(/[^\w !\-.*'()&$@=;:+,?/]/g, '_')
+
 // --- Auth: cache one access token, re-grant when it's near expiry. -----------
 let cached = { token: null, exp: 0 }
 async function getToken() {
@@ -73,6 +82,27 @@ async function edgeJson(body) {
   return data
 }
 
+// --- Read path: PostgREST GET with the engineer's token (RLS-enforced). -------
+// Same data path the PLM web app uses (supabase-js -> /rest/v1). The anon key is
+// the gateway apikey; the bearer token is the signed-in engineer, so row-level
+// security decides what comes back — these tools can never read past the user.
+async function restGet(table, params = {}, { count = false } = {}) {
+  const token = await getToken()
+  const qs = new URLSearchParams(params).toString()
+  const headers = { apikey: ANON_KEY, authorization: `Bearer ${token}` }
+  if (count) headers['prefer'] = 'count=exact'
+  const resp = await fetch(`${GATEWAY}/rest/v1/${table}?${qs}`, { headers })
+  const data = await resp.json().catch(() => null)
+  if (!resp.ok) throw new Error(data?.message || data?.error || `read ${table} failed: http ${resp.status}`)
+  // content-range is "start-end/total" (or "*/total") when count=exact.
+  const total = count ? Number((resp.headers.get('content-range') || '').split('/')[1]) || null : null
+  return { rows: Array.isArray(data) ? data : [], total }
+}
+
+// bucket -> components.staging filter. 'main' = confirmed, 'staging' = unconfirmed.
+const stagingFilter = (bucket) =>
+  bucket === 'staging' ? { staging: 'eq.true' } : bucket === 'main' ? { staging: 'eq.false' } : {}
+
 /** store bytes → storagePath, then upload → mirror into the SKU's Drive folder. */
 async function uploadOne({ path, sku, skuName, category, bucket }) {
   const bytes = await readFile(path) // throws ENOENT with the path — surfaced per-file below
@@ -80,7 +110,8 @@ async function uploadOne({ path, sku, skuName, category, bucket }) {
   const mimeType = mimeFor(filename)
   const token = await getToken()
 
-  const params = new URLSearchParams({ action: 'store', sku, filename, mimeType })
+  // Store under a storage-safe key; the Drive file keeps the original filename below.
+  const params = new URLSearchParams({ action: 'store', sku, filename: storageKeyName(filename), mimeType })
   const sResp = await fetch(`${EDGE}/drive-library?${params}`, {
     method: 'POST',
     headers: { 'content-type': mimeType, authorization: `Bearer ${token}` },
@@ -117,7 +148,7 @@ async function uploadOne({ path, sku, skuName, category, bucket }) {
 }
 
 // --- Server ------------------------------------------------------------------
-const server = new McpServer({ name: 'plm-upload', version: '1.0.0' })
+const server = new McpServer({ name: 'plm-upload', version: '1.1.0' })
 
 server.registerTool(
   'upload_files',
@@ -201,5 +232,265 @@ server.registerTool(
   },
 )
 
+// === Read-only tools (RLS-enforced via the engineer's token) =================
+
+server.registerTool(
+  'list_sku_folders',
+  {
+    title: 'List all SKU folders',
+    description:
+      "List every component SKU in the PLM with its Google Drive folder — the SKU→folder map. " +
+      "Returns SKU, name, category, type, revision, status, whether it is a staging (unconfirmed) " +
+      "or main (confirmed) part, and the Drive folder id/URL. Read-only. Use it to discover which " +
+      "SKUs exist and where each part's files live, or to find the folder for a SKU before uploading.",
+    inputSchema: {
+      bucket: z
+        .enum(['main', 'staging', 'all'])
+        .optional()
+        .describe("Filter by drive: 'main' (confirmed), 'staging' (unconfirmed), or 'all' (default)."),
+      category: z.string().optional().describe('Optional exact category code filter, e.g. MNT.'),
+      with_folder_only: z
+        .boolean()
+        .optional()
+        .describe('If true, only SKUs that already have a Drive folder. Default false.'),
+      limit: z.number().int().min(1).max(2000).optional().describe('Max rows (default 1000).'),
+      offset: z.number().int().min(0).optional().describe('Row offset for paging (default 0).'),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  },
+  async ({ bucket = 'all', category, with_folder_only = false, limit = 1000, offset = 0 }) => {
+    const params = {
+      select: 'sku,name,category,sku_type,revision,status,staging,drive_folder_id,drive_folder_url',
+      order: 'sku.asc',
+      limit: String(limit),
+      offset: String(offset),
+      ...stagingFilter(bucket),
+    }
+    if (category) params.category = `eq.${category}`
+    if (with_folder_only) params.drive_folder_id = 'not.is.null'
+    const { rows, total } = await restGet('components', params, { count: true })
+    const withFolder = rows.filter((r) => r.drive_folder_id).length
+    const lines = rows
+      .slice(0, 50)
+      .map((r) => `• ${r.sku} — ${r.name}${r.staging ? ' [staging]' : ''}${r.drive_folder_id ? '' : ' (no folder)'}`)
+    const more = rows.length > 50 ? `\n… ${rows.length - 50} more (of ${total ?? rows.length}).` : ''
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `${rows.length} SKU(s) (${withFolder} with a Drive folder) of ${total ?? '?'} total in ${bucket}.\n${lines.join('\n')}${more}`,
+        },
+      ],
+      structuredContent: { bucket, count: rows.length, total, folders: rows },
+    }
+  },
+)
+
+server.registerTool(
+  'get_component_metadata',
+  {
+    title: 'Get component metadata',
+    description:
+      "Read full component metadata from the PLM component database. Every column — identity " +
+      "(sku, name, category, type, revision, status), cost/supply (unit_cost, moq, lead time, " +
+      "preferred_supplier), drawing-extracted fields (material, colour, manufacturing_method, " +
+      "release_status), CAD provenance, compliance (RoHS/REACH/CE), and Drive folder — plus the " +
+      "extract_meta provenance block. Pass a single `sku` for one part, or omit it to page through " +
+      "all parts. Read-only.",
+    inputSchema: {
+      sku: z.string().optional().describe('Exact SKU for a single component, e.g. MNT-1234-A0.'),
+      search: z.string().optional().describe('Case-insensitive substring match on SKU or name.'),
+      bucket: z.enum(['main', 'staging', 'all']).optional().describe("'main', 'staging', or 'all' (default)."),
+      category: z.string().optional().describe('Optional exact category code filter, e.g. MNT.'),
+      status: z.enum(['active', 'obsolete']).optional().describe('Optional lifecycle status filter.'),
+      limit: z.number().int().min(1).max(500).optional().describe('Max rows when listing (default 100).'),
+      offset: z.number().int().min(0).optional().describe('Row offset for paging (default 0).'),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  },
+  async ({ sku, search, bucket = 'all', category, status, limit = 100, offset = 0 }) => {
+    const params = { select: '*', order: 'sku.asc', ...stagingFilter(bucket) }
+    if (sku) {
+      params.sku = `eq.${sku}`
+      params.limit = '1'
+    } else {
+      params.limit = String(limit)
+      params.offset = String(offset)
+      if (search) params.or = `(sku.ilike.*${search}*,name.ilike.*${search}*)`
+      if (category) params.category = `eq.${category}`
+      if (status) params.status = `eq.${status}`
+    }
+    const { rows, total } = await restGet('components', params, { count: !sku })
+    if (sku) {
+      const c = rows[0]
+      if (!c) return { content: [{ type: 'text', text: `No component with SKU ${sku}.` }], structuredContent: { component: null } }
+      return {
+        content: [{ type: 'text', text: `${c.sku} — ${c.name} (${c.category}, rev ${c.revision ?? '—'}, ${c.status}${c.staging ? ', staging' : ''}).` }],
+        structuredContent: { component: c },
+      }
+    }
+    const lines = rows.slice(0, 50).map((c) => `• ${c.sku} — ${c.name} (${c.status}${c.staging ? ', staging' : ''})`)
+    const more = rows.length > 50 ? `\n… ${rows.length - 50} more shown truncated (of ${total ?? rows.length}).` : ''
+    return {
+      content: [{ type: 'text', text: `${rows.length} component(s) of ${total ?? '?'} total in ${bucket}.\n${lines.join('\n')}${more}` }],
+      structuredContent: { bucket, count: rows.length, total, components: rows },
+    }
+  },
+)
+
+server.registerTool(
+  'list_bom_extract_metadata',
+  {
+    title: 'List extracted BOM/drawing metadata',
+    description:
+      "List the metadata machine-extracted from each part's drawing/BOM PDF (the PLM `extract` step) " +
+      "across all components. For each SKU returns its extract_meta: the Lionsbot-custom-drawing flag, " +
+      "the SKU/drawing match check, the per-field extracted values (release status, material, colour, " +
+      "manufacturing method, CAD revision, drawn/designed by), and the source file + who/when it was " +
+      "extracted. Only parts that have been extracted are returned. Read-only.",
+    inputSchema: {
+      sku: z.string().optional().describe('Restrict to a single SKU, e.g. MNT-1234-A0.'),
+      bucket: z.enum(['main', 'staging', 'all']).optional().describe("'main', 'staging', or 'all' (default)."),
+      limit: z.number().int().min(1).max(2000).optional().describe('Max rows (default 1000).'),
+      offset: z.number().int().min(0).optional().describe('Row offset for paging (default 0).'),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  },
+  async ({ sku, bucket = 'all', limit = 1000, offset = 0 }) => {
+    const params = {
+      select: 'sku,name,category,staging,material,colour,manufacturing_method,release_status,cad_revision,cad_drawn_by,cad_designed_by,extract_meta',
+      order: 'sku.asc',
+      limit: String(limit),
+      offset: String(offset),
+      ...stagingFilter(bucket),
+    }
+    // extract_meta '{}' means never extracted — exclude it.
+    params.extract_meta = 'neq.{}'
+    if (sku) params.sku = `eq.${sku}`
+    const { rows, total } = await restGet('components', params, { count: true })
+    const lines = rows.slice(0, 50).map((r) => {
+      const lb = r.extract_meta?.is_lionsbot === true ? ' [LB]' : ''
+      const m = r.extract_meta?.sku_check?.match === true ? ' ✓match' : r.extract_meta?.sku_check ? ' ✗mismatch' : ''
+      return `• ${r.sku} — ${r.name}${lb}${m}`
+    })
+    const more = rows.length > 50 ? `\n… ${rows.length - 50} more (of ${total ?? rows.length}).` : ''
+    return {
+      content: [{ type: 'text', text: `${rows.length} extracted part(s) of ${total ?? '?'} in ${bucket}.\n${lines.join('\n')}${more}` }],
+      structuredContent: { bucket, count: rows.length, total, extracted: rows },
+    }
+  },
+)
+
+server.registerTool(
+  'list_boms',
+  {
+    title: 'List all BOMs (products + staging)',
+    description:
+      "List the bills of materials across all products. Each product carries its BOM(s) with the line " +
+      "items — component SKU, name, quantity, unit, reference designator — and a derived `staging` flag: " +
+      "a product is 'staging' while its working BOM still contains any staging (unconfirmed) component, " +
+      "otherwise 'main'. By default returns working BOMs only (set include_snapshots to include saved " +
+      "snapshots) with their rows. Filter to one product with product_sku. Read-only.",
+    inputSchema: {
+      product_sku: z.string().optional().describe('Restrict to one product by its SAL SKU, e.g. SAL-0R3-3001.'),
+      classification: z
+        .enum(['main', 'staging', 'all'])
+        .optional()
+        .describe("Only products in this derived class: 'main', 'staging', or 'all' (default)."),
+      include_snapshots: z.boolean().optional().describe('Include saved snapshot BOMs, not just the working BOM. Default false.'),
+      include_rows: z.boolean().optional().describe('Include BOM line items. Default true.'),
+      max_rows_per_bom: z.number().int().min(1).max(5000).optional().describe('Cap rows fetched per BOM (default 2000).'),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  },
+  async ({ product_sku, classification = 'all', include_snapshots = false, include_rows = true, max_rows_per_bom = 2000 }) => {
+    // 1) BOM headers + their product.
+    const bomParams = {
+      select: 'id,name,is_snapshot,snapshot_label,product_id,created_at,product:products(sku,name,status)',
+      order: 'created_at.asc',
+    }
+    if (!include_snapshots) bomParams.is_snapshot = 'eq.false'
+    const { rows: boms } = await restGet('boms', bomParams, {})
+    let scoped = product_sku ? boms.filter((b) => b.product?.sku === product_sku) : boms
+    if (!scoped.length) {
+      return { content: [{ type: 'text', text: product_sku ? `No BOMs for product ${product_sku}.` : 'No BOMs found.' }], structuredContent: { products: [] } }
+    }
+
+    // 2) Rows for those BOMs, embedding each component's SKU + staging flag.
+    const byBom = new Map(scoped.map((b) => [b.id, []]))
+    if (include_rows) {
+      const ids = scoped.map((b) => b.id)
+      // Chunk the in-list so the URL stays a sane length.
+      for (let i = 0; i < ids.length; i += 50) {
+        const chunk = ids.slice(i, i + 50)
+        const { rows } = await restGet('bom_rows', {
+          select:
+            'bom_id,quantity,unit,reference_designator,sort_order,row_type,component:components(sku,name,category,revision,status,staging)',
+          bom_id: `in.(${chunk.join(',')})`,
+          order: 'bom_id.asc,sort_order.asc',
+          limit: String(max_rows_per_bom * chunk.length),
+        })
+        for (const r of rows) if (byBom.has(r.bom_id)) byBom.get(r.bom_id).push(r)
+      }
+    }
+
+    // 3) Group by product; derive staging from the working BOM's rows.
+    const products = new Map()
+    for (const b of scoped) {
+      const key = b.product?.sku ?? b.product_id
+      if (!products.has(key)) {
+        products.set(key, { product: b.product ?? { sku: null, id: b.product_id }, staging: false, boms: [] })
+      }
+      const rows = byBom.get(b.id) ?? []
+      const bomStaging = rows.some((r) => r.component?.staging === true)
+      // A product's class is decided by its working (non-snapshot) BOM.
+      if (!b.is_snapshot && bomStaging) products.get(key).staging = true
+      products.get(key).boms.push({
+        id: b.id,
+        name: b.name,
+        is_snapshot: b.is_snapshot,
+        snapshot_label: b.snapshot_label,
+        row_count: rows.length,
+        rows: include_rows ? rows : undefined,
+      })
+    }
+
+    let list = [...products.values()]
+    if (classification !== 'all') list = list.filter((p) => (classification === 'staging' ? p.staging : !p.staging))
+
+    const stagingCount = list.filter((p) => p.staging).length
+    const lines = list
+      .slice(0, 60)
+      .map((p) => `• ${p.product.sku ?? p.product.id} — ${p.product.name ?? ''} [${p.staging ? 'staging' : 'main'}] · ${p.boms.reduce((n, b) => n + b.row_count, 0)} rows`)
+    const more = list.length > 60 ? `\n… ${list.length - 60} more.` : ''
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `${list.length} product(s): ${stagingCount} staging, ${list.length - stagingCount} main.\n${lines.join('\n')}${more}`,
+        },
+      ],
+      structuredContent: { classification, product_count: list.length, staging_products: stagingCount, products: list },
+    }
+  },
+)
+
+// `node index.mjs --selftest` — verify the storage-key sanitizer without a server.
+if (process.argv.includes('--selftest')) {
+  const assert = (c, m) => { if (!c) { console.error('FAIL:', m); process.exit(1) } }
+  assert(storageKeyName('[MNT-0930-X0] HANDLEBAR MOUNT LEFT_260908.STEP')
+    === '_MNT-0930-X0_ HANDLEBAR MOUNT LEFT_260908.STEP', 'brackets -> _')
+  assert(storageKeyName('BRG-0245-X0 Bushing_260908.pdf')
+    === 'BRG-0245-X0 Bushing_260908.pdf', 'safe name unchanged')
+  const SAFE = /^[\w !\-.*'()&$@=;:+,?/]*$/
+  assert(SAFE.test(storageKeyName('a[b]c#d%e\\f"g<h>i.STEP')), 'all unsafe chars replaced')
+  // stagingFilter mapping
+  assert(JSON.stringify(stagingFilter('main')) === '{"staging":"eq.false"}', 'main -> staging=false')
+  assert(JSON.stringify(stagingFilter('staging')) === '{"staging":"eq.true"}', 'staging -> staging=true')
+  assert(JSON.stringify(stagingFilter('all')) === '{}', 'all -> no filter')
+  console.log('selftest ok')
+  process.exit(0)
+}
+
 const transport = new StdioServerTransport()
 await server.connect(transport)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "plm-upload-mcp",
-  "version": "1.0.0",
-  "description": "MCP server to bulk-upload SolidWorks exports (STEP/PDF) into the LionsBot PLM by SKU.",
+  "version": "1.1.0",
+  "description": "MCP server to read the LionsBot PLM (SKU folders, component metadata, extracted drawing metadata, product & staging BOMs) and bulk-upload SolidWorks exports (STEP/PDF) into it by SKU.",
   "license": "UNLICENSED",
   "keywords": ["mcp", "modelcontextprotocol", "lionsbot", "plm", "solidworks"],
   "type": "module",