feat: deduplicate multi-artifact package results

PyPI packages like numpy return one NDJSON line per artifact (sdist,
wheels for each platform). This floods the agent with duplicate results
for the same package.

- Add lib/artifacts.ts with deduplicateArtifacts() that groups results
  by (type, namespace, name, version) and selects one representative
  per group (source dist > universal wheel > first artifact)
- Add optional `platform` parameter to depscore tool for agents that
  can detect the user's OS/arch (e.g. 'darwin-arm64', 'linux-x64')
- Filter out purlError/summary NDJSON lines before processing
- Add 18 unit tests for deduplication and platform matching
- Add 2 integration tests for numpy deduplication with/without platform

Made-with: Cursor

Author: kapravel

artifacts.test.ts

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+import { test } from 'node:test'
+import assert from 'node:assert'
+import { deduplicateArtifacts } from './lib/artifacts.ts'
+import type { ArtifactData } from './lib/artifacts.ts'
+
+function makeArtifact (overrides: Partial<ArtifactData> = {}): ArtifactData {
+  return {
+    type: 'pypi',
+    name: 'numpy',
+    version: '1.26.0',
+    score: { overall: 0.95, supply_chain: 0.9, quality: 0.8, maintenance: 0.85, vulnerability: 1.0, license: 1.0 },
+    ...overrides
+  }
+}
+
+test('deduplicateArtifacts', async (t) => {
+  await t.test('single artifact passes through unchanged', () => {
+    const artifacts = [makeArtifact({ release: 'numpy-1.26.0.tar.gz' })]
+    const result = deduplicateArtifacts(artifacts)
+    assert.strictEqual(result.length, 1)
+    assert.strictEqual(result[0]!.release, 'numpy-1.26.0.tar.gz')
+  })
+
+  await t.test('multiple artifacts for same package are deduplicated to one', () => {
+    const artifacts = [
+      makeArtifact({ release: 'numpy-1.26.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl' }),
+      makeArtifact({ release: 'numpy-1.26.0-cp312-cp312-macosx_14_0_arm64.whl' }),
+      makeArtifact({ release: 'numpy-1.26.0-cp312-cp312-win_amd64.whl' }),
+      makeArtifact({ release: 'numpy-1.26.0.tar.gz' }),
+    ]
+    const result = deduplicateArtifacts(artifacts)
+    assert.strictEqual(result.length, 1)
+  })
+
+  await t.test('source dist is preferred over wheels when no platform specified', () => {
+    const artifacts = [
+      makeArtifact({ release: 'numpy-1.26.0-cp312-cp312-manylinux_2_17_x86_64.whl' }),
+      makeArtifact({ release: 'numpy-1.26.0.tar.gz' }),
+      makeArtifact({ release: 'numpy-1.26.0-cp312-cp312-win_amd64.whl' }),
+    ]
+    const result = deduplicateArtifacts(artifacts)
+    assert.strictEqual(result.length, 1)
+    assert.strictEqual(result[0]!.release, 'numpy-1.26.0.tar.gz')
+  })
+
+  await t.test('universal wheel is preferred when no sdist available', () => {
+    const artifacts = [
+      makeArtifact({ release: 'requests-2.31.0-cp312-cp312-manylinux_2_17_x86_64.whl' }),
+      makeArtifact({ release: 'requests-2.31.0-py3-none-any.whl' }),
+      makeArtifact({ release: 'requests-2.31.0-cp312-cp312-win_amd64.whl' }),
+    ]
+    const result = deduplicateArtifacts(artifacts)
+    assert.strictEqual(result.length, 1)
+    assert.strictEqual(result[0]!.release, 'requests-2.31.0-py3-none-any.whl')
+  })
+
+  await t.test('platform hint selects darwin-arm64 wheel', () => {
+    const artifacts = [
+      makeArtifact({ release: 'numpy-1.26.0-cp312-cp312-manylinux_2_17_x86_64.whl' }),
+      makeArtifact({ release: 'numpy-1.26.0-cp312-cp312-macosx_14_0_arm64.whl' }),
+      makeArtifact({ release: 'numpy-1.26.0.tar.gz' }),
+    ]
+    const result = deduplicateArtifacts(artifacts, 'darwin-arm64')
+    assert.strictEqual(result.length, 1)
+    assert.strictEqual(result[0]!.release, 'numpy-1.26.0-cp312-cp312-macosx_14_0_arm64.whl')
+  })
+
+  await t.test('platform hint selects linux-x64 wheel', () => {
+    const artifacts = [
+      makeArtifact({ release: 'numpy-1.26.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl' }),
+      makeArtifact({ release: 'numpy-1.26.0-cp312-cp312-macosx_14_0_arm64.whl' }),
+      makeArtifact({ release: 'numpy-1.26.0.tar.gz' }),
+    ]
+    const result = deduplicateArtifacts(artifacts, 'linux-x64')
+    assert.strictEqual(result.length, 1)
+    assert.strictEqual(result[0]!.release, 'numpy-1.26.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl')
+  })
+
+  await t.test('platform hint selects win32-x64 wheel', () => {
+    const artifacts = [
+      makeArtifact({ release: 'numpy-1.26.0-cp312-cp312-manylinux_2_17_x86_64.whl' }),
+      makeArtifact({ release: 'numpy-1.26.0-cp312-cp312-win_amd64.whl' }),
+      makeArtifact({ release: 'numpy-1.26.0.tar.gz' }),
+    ]
+    const result = deduplicateArtifacts(artifacts, 'win32-x64')
+    assert.strictEqual(result.length, 1)
+    assert.strictEqual(result[0]!.release, 'numpy-1.26.0-cp312-cp312-win_amd64.whl')
+  })
+
+  await t.test('platform hint with no match falls back to source dist', () => {
+    const artifacts = [
+      makeArtifact({ release: 'numpy-1.26.0-cp312-cp312-manylinux_2_17_x86_64.whl' }),
+      makeArtifact({ release: 'numpy-1.26.0.tar.gz' }),
+    ]
+    const result = deduplicateArtifacts(artifacts, 'win32-x64')
+    assert.strictEqual(result.length, 1)
+    assert.strictEqual(result[0]!.release, 'numpy-1.26.0.tar.gz')
+  })
+
+  await t.test('different packages are not deduplicated', () => {
+    const artifacts = [
+      makeArtifact({ name: 'numpy', release: 'numpy-1.26.0.tar.gz' }),
+      makeArtifact({ name: 'scipy', release: 'scipy-1.11.0.tar.gz' }),
+    ]
+    const result = deduplicateArtifacts(artifacts)
+    assert.strictEqual(result.length, 2)
+  })
+
+  await t.test('different versions of same package are not deduplicated', () => {
+    const artifacts = [
+      makeArtifact({ version: '1.26.0', release: 'numpy-1.26.0.tar.gz' }),
+      makeArtifact({ version: '1.25.0', release: 'numpy-1.25.0.tar.gz' }),
+    ]
+    const result = deduplicateArtifacts(artifacts)
+    assert.strictEqual(result.length, 2)
+  })
+
+  await t.test('artifacts without release field use first-in-group', () => {
+    const a1 = makeArtifact({ score: { overall: 0.9 } })
+    const a2 = makeArtifact({ score: { overall: 0.8 } })
+    const result = deduplicateArtifacts([a1, a2])
+    assert.strictEqual(result.length, 1)
+    assert.deepStrictEqual(result[0]!.score, { overall: 0.9 })
+  })
+
+  await t.test('works across different ecosystems', () => {
+    const artifacts = [
+      makeArtifact({ type: 'npm', name: 'express', version: '4.18.2' }),
+      makeArtifact({ type: 'pypi', name: 'numpy', version: '1.26.0', release: 'numpy-1.26.0-cp312-manylinux_x86_64.whl' }),
+      makeArtifact({ type: 'pypi', name: 'numpy', version: '1.26.0', release: 'numpy-1.26.0.tar.gz' }),
+    ]
+    const result = deduplicateArtifacts(artifacts)
+    assert.strictEqual(result.length, 2)
+    const types = result.map(r => r.type)
+    assert.ok(types.includes('npm'))
+    assert.ok(types.includes('pypi'))
+  })
+
+  await t.test('zip source distributions are recognized', () => {
+    const artifacts = [
+      makeArtifact({ release: 'package-1.0.0-cp312-win_amd64.whl' }),
+      makeArtifact({ release: 'package-1.0.0.zip' }),
+    ]
+    const result = deduplicateArtifacts(artifacts)
+    assert.strictEqual(result.length, 1)
+    assert.strictEqual(result[0]!.release, 'package-1.0.0.zip')
+  })
+
+  await t.test('darwin-x64 platform matching', () => {
+    const artifacts = [
+      makeArtifact({ release: 'pkg-1.0-cp312-cp312-macosx_10_9_x86_64.whl' }),
+      makeArtifact({ release: 'pkg-1.0-cp312-cp312-macosx_14_0_arm64.whl' }),
+      makeArtifact({ release: 'pkg-1.0.tar.gz' }),
+    ]
+    const result = deduplicateArtifacts(artifacts, 'darwin-x64')
+    assert.strictEqual(result.length, 1)
+    assert.strictEqual(result[0]!.release, 'pkg-1.0-cp312-cp312-macosx_10_9_x86_64.whl')
+  })
+
+  await t.test('linux-arm64 platform matching', () => {
+    const artifacts = [
+      makeArtifact({ release: 'pkg-1.0-cp312-cp312-manylinux_2_17_aarch64.whl' }),
+      makeArtifact({ release: 'pkg-1.0-cp312-cp312-manylinux_2_17_x86_64.whl' }),
+      makeArtifact({ release: 'pkg-1.0.tar.gz' }),
+    ]
+    const result = deduplicateArtifacts(artifacts, 'linux-arm64')
+    assert.strictEqual(result.length, 1)
+    assert.strictEqual(result[0]!.release, 'pkg-1.0-cp312-cp312-manylinux_2_17_aarch64.whl')
+  })
+
+  await t.test('empty array returns empty', () => {
+    const result = deduplicateArtifacts([])
+    assert.strictEqual(result.length, 0)
+  })
+
+  await t.test('namespace is included in grouping key', () => {
+    const artifacts = [
+      makeArtifact({ type: 'maven', namespace: 'org.apache', name: 'commons', version: '3.0' }),
+      makeArtifact({ type: 'maven', namespace: 'org.spring', name: 'commons', version: '3.0' }),
+    ]
+    const result = deduplicateArtifacts(artifacts)
+    assert.strictEqual(result.length, 2)
+  })
+})

index.ts

@@ -7,6 +7,7 @@ import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js'
 import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js'
 import { randomUUID } from 'node:crypto'
 import { buildPurl } from './lib/purl.ts'
+import { deduplicateArtifacts } from './lib/artifacts.ts'
 import { z } from 'zod'
 import pino from 'pino'
 import readline from 'readline'
@@ -395,12 +396,13 @@ function createConfiguredServer (): McpServer {
           depname: z.string().describe('The name of the dependency'),
           version: z.string().describe("The version of the dependency, use 'unknown' if not known").default('unknown'),
         })).describe('Array of packages to check'),
+        platform: z.string().optional().describe("Optional OS-architecture hint (e.g., 'linux-x64', 'darwin-arm64', 'win32-x64'). Used to select the most relevant artifact when a package has platform-specific builds."),
       },
       annotations: {
         readOnlyHint: true,
       },
     },
-    async ({ packages }, extra) => {
+    async ({ packages, platform }, extra) => {
       logger.info(`Received request for ${packages.length} packages`)
       const accessToken = extra.authInfo?.token || SOCKET_API_KEY
       if (!accessToken) {
@@ -476,6 +478,7 @@ function createConfiguredServer (): McpServer {
             const jsonLines = responseText.split('\n')
               .filter(line => line.trim())
               .map(line => JSON.parse(line))
+              .filter((obj: Record<string, unknown>) => !obj['_type'])
 
             if (!jsonLines.length) {
               const errorMsg = 'No valid JSON objects found in NDJSON response'
@@ -485,11 +488,11 @@ function createConfiguredServer (): McpServer {
               }
             }
 
-            // Process each result
-            for (const jsonData of jsonLines) {
+            const deduplicated = deduplicateArtifacts(jsonLines, platform)
+            for (const jsonData of deduplicated) {
               const ns = jsonData.namespace ? `${jsonData.namespace}/` : ''
               const purl: string = `pkg:${jsonData.type || 'unknown'}/${ns}${jsonData.name || 'unknown'}@${jsonData.version || 'unknown'}`
-              if (jsonData.score && jsonData.score.overall !== undefined) {
+              if (jsonData.score && jsonData.score['overall'] !== undefined) {
                 const scoreEntries = Object.entries(jsonData.score)
                   .filter(([key]) => key !== 'overall' && key !== 'uuid')
                   .map(([key, value]) => {

lib/artifacts.ts

@@ -0,0 +1,88 @@
+export interface ArtifactData {
+  type?: string
+  namespace?: string
+  name?: string
+  version?: string
+  release?: string
+  score?: Record<string, unknown>
+  _type?: string
+  [key: string]: unknown
+}
+
+type PlatformPattern = RegExp
+
+const PLATFORM_PATTERNS: Record<string, PlatformPattern[]> = {
+  'darwin-arm64': [/macosx.*arm64/i],
+  'darwin-x64': [/macosx.*x86_64/i],
+  'linux-x64': [/(manylinux|linux).*x86_64/i],
+  'linux-arm64': [/(manylinux|linux).*(aarch64|arm64)/i],
+  'win32-x64': [/win.*(amd64|x86_64)/i],
+  'win32-ia32': [/win.*win32/i],
+}
+
+function artifactGroupKey (artifact: ArtifactData): string {
+  const ns = artifact.namespace || ''
+  return `${artifact.type || ''}/${ns}/${artifact.name || ''}@${artifact.version || ''}`
+}
+
+function isSourceDist (release: string): boolean {
+  return /\.(tar\.gz|tar\.bz2|zip)$/i.test(release) || /sdist/i.test(release)
+}
+
+function isUniversalWheel (release: string): boolean {
+  return /[-_]none[-_]any\.whl$/i.test(release) || /py3[-_]none[-_]any/i.test(release)
+}
+
+function matchesPlatform (release: string, platform: string): boolean {
+  const patterns = PLATFORM_PATTERNS[platform]
+  if (patterns) {
+    return patterns.some(p => p.test(release))
+  }
+  return release.toLowerCase().includes(platform.toLowerCase())
+}
+
+function selectBestArtifact (artifacts: ArtifactData[], platform?: string): ArtifactData {
+  if (artifacts.length === 1) {
+    return artifacts[0]!
+  }
+
+  if (platform) {
+    const match = artifacts.find(a => a.release && matchesPlatform(a.release, platform))
+    if (match) return match
+  }
+
+  const sdist = artifacts.find(a => a.release && isSourceDist(a.release))
+  if (sdist) return sdist
+
+  const universal = artifacts.find(a => a.release && isUniversalWheel(a.release))
+  if (universal) return universal
+
+  return artifacts[0]!
+}
+
+/**
+ * Deduplicate artifacts that share the same (type, namespace, name, version) identity.
+ * When multiple artifacts exist for the same package (e.g. PyPI wheels for different
+ * platforms), one representative is selected using a priority: platform-matching artifact
+ * (if hint provided) > source distribution > universal wheel > first artifact.
+ */
+export function deduplicateArtifacts (artifacts: ArtifactData[], platform?: string): ArtifactData[] {
+  const groups = new Map<string, ArtifactData[]>()
+
+  for (const artifact of artifacts) {
+    const key = artifactGroupKey(artifact)
+    let group = groups.get(key)
+    if (!group) {
+      group = []
+      groups.set(key, group)
+    }
+    group.push(artifact)
+  }
+
+  const results: ArtifactData[] = []
+  for (const group of groups.values()) {
+    results.push(selectBestArtifact(group, platform))
+  }
+
+  return results
+}

test.ts

@@ -100,6 +100,39 @@ test('Socket MCP Server', async (t) => {
     assert.ok(textContent.text.includes('pkg:pypi/'), 'Result should contain pypi purl format')
   })
 
+  await t.test('pypi multi-artifact package is deduplicated to one result', async () => {
+    const packages = [
+      { depname: 'numpy', ecosystem: 'pypi', version: '1.26.4' }
+    ]
+
+    const result = await client.callTool({
+      name: 'depscore',
+      arguments: { packages }
+    })
+
+    assert.ok(result?.content && Array.isArray(result.content) && result.content.length > 0)
+    const textContent = result.content[0] as { type: string; text: string }
+    const numpyLines = textContent.text.split('\n').filter(line => line.includes('pkg:pypi/numpy'))
+    assert.strictEqual(numpyLines.length, 1, `Expected 1 deduplicated result for numpy, got ${numpyLines.length}:\n${numpyLines.join('\n')}`)
+  })
+
+  await t.test('depscore accepts optional platform parameter', async () => {
+    const packages = [
+      { depname: 'numpy', ecosystem: 'pypi', version: '1.26.4' }
+    ]
+
+    const result = await client.callTool({
+      name: 'depscore',
+      arguments: { packages, platform: 'darwin-arm64' }
+    })
+
+    assert.ok(result?.content && Array.isArray(result.content) && result.content.length > 0)
+    const textContent = result.content[0] as { type: string; text: string }
+    assert.ok(textContent.text.includes('pkg:pypi/numpy'), 'Result should contain numpy')
+    const numpyLines = textContent.text.split('\n').filter(line => line.includes('pkg:pypi/numpy'))
+    assert.strictEqual(numpyLines.length, 1, 'Platform hint should still produce one deduplicated result')
+  })
+
   await t.test('call depscore tool with golang ecosystem', async (t) => {
     const golangPackages = [
       { depname: 'github.com/gin-gonic/gin', ecosystem: 'golang', version: 'v1.9.0' }