registryx-server 0.1.0

package/src/adapters/npm.ts

@@ -0,0 +1,244 @@
+import type { Config } from '../config.js';
+import type { Cache } from '../cache.js';
+import type {
+  RegistryAdapter,
+  PackageSearchResult,
+  PackageMetadata,
+  VersionInfo,
+  VersionDetail,
+  Dependency,
+  DownloadStats,
+  MaintainerInfo,
+  PackageHealth,
+  SecurityAdvisory,
+} from '../types.js';
+import { registryFetch } from '../utils/fetch.js';
+
+export class NpmAdapter implements RegistryAdapter {
+  readonly name = 'npm' as const;
+  constructor(
+    private config: Config,
+    private cache: Cache
+  ) {}
+
+  async search(query: string, limit: number): Promise<PackageSearchResult[]> {
+    const key = `npm:search:${query}:${limit}`;
+    const cached = this.cache.get<PackageSearchResult[]>(key);
+    if (cached) return cached;
+
+    const url = `https://registry.npmjs.org/-/v1/search?text=${encodeURIComponent(query)}&size=${limit}`;
+    const res = await registryFetch(url, this.config);
+    const data = (await res.json()) as any;
+
+    const results: PackageSearchResult[] = (data.objects ?? []).map(
+      (obj: {
+        package: { name: string; version: string; description?: string };
+        downloads?: { monthly?: number };
+      }) => ({
+        name: obj.package.name,
+        version: obj.package.version,
+        description: obj.package.description ?? '',
+        downloads: '',
+        registry: 'npm' as const,
+      })
+    );
+    this.cache.set(key, results);
+    return results;
+  }
+
+  async getPackage(name: string): Promise<PackageMetadata> {
+    const key = `npm:pkg:${name}`;
+    const cached = this.cache.get<PackageMetadata>(key);
+    if (cached) return cached;
+
+    const url = `https://registry.npmjs.org/${encodeURIComponent(name)}`;
+    const res = await registryFetch(url, this.config);
+    const data = (await res.json()) as any;
+    const latest = data['dist-tags']?.latest ?? '';
+
+    const result: PackageMetadata = {
+      name: data.name,
+      version: latest,
+      description: data.description ?? '',
+      license: typeof data.license === 'string' ? data.license : (data.license?.type ?? 'Unknown'),
+      homepage: data.homepage ?? '',
+      repository:
+        typeof data.repository === 'string' ? data.repository : (data.repository?.url ?? ''),
+      keywords: data.keywords ?? [],
+      registry: 'npm',
+    };
+    this.cache.set(key, result);
+    return result;
+  }
+
+  async getReadme(name: string): Promise<string> {
+    const url = `https://registry.npmjs.org/${encodeURIComponent(name)}`;
+    const res = await registryFetch(url, this.config);
+    const data = (await res.json()) as any;
+    return data.readme ?? 'No README available.';
+  }
+
+  async getMaintainers(name: string): Promise<MaintainerInfo[]> {
+    const url = `https://registry.npmjs.org/${encodeURIComponent(name)}`;
+    const res = await registryFetch(url, this.config);
+    const data = (await res.json()) as any;
+    return (data.maintainers ?? []).map((m: { name: string; email?: string }) => ({
+      name: m.name,
+      email: m.email,
+    }));
+  }
+
+  async listVersions(name: string, limit: number, stableOnly: boolean): Promise<VersionInfo[]> {
+    const url = `https://registry.npmjs.org/${encodeURIComponent(name)}`;
+    const res = await registryFetch(url, this.config);
+    const data = (await res.json()) as any;
+    const versions = Object.keys(data.versions ?? {}).reverse();
+    const timeMap = data.time ?? {};
+
+    let results: VersionInfo[] = versions.map((v) => ({
+      version: v,
+      date: timeMap[v] ?? '',
+      prerelease: /[-+]/.test(v.replace(/^\d+\.\d+\.\d+/, '')),
+    }));
+
+    if (stableOnly) results = results.filter((v) => !v.prerelease);
+    return results.slice(0, limit);
+  }
+
+  async getVersion(name: string, version: string): Promise<VersionDetail> {
+    const url = `https://registry.npmjs.org/${encodeURIComponent(name)}/${version}`;
+    const res = await registryFetch(url, this.config);
+    const data = (await res.json()) as any;
+
+    const deps: Dependency[] = Object.entries(data.dependencies ?? {}).map(([n, v]) => ({
+      name: n,
+      version: v as string,
+      type: 'runtime' as const,
+    }));
+
+    return {
+      name: data.name,
+      version: data.version,
+      date: '',
+      license: typeof data.license === 'string' ? data.license : 'Unknown',
+      size: data.dist?.unpackedSize ? `${Math.round(data.dist.unpackedSize / 1024)}KB` : 'Unknown',
+      dependencies: deps,
+      registry: 'npm',
+    };
+  }
+
+  async getDependencies(
+    name: string,
+    version: string,
+    type: 'runtime' | 'dev' | 'all'
+  ): Promise<Dependency[]> {
+    const url = `https://registry.npmjs.org/${encodeURIComponent(name)}/${version}`;
+    const res = await registryFetch(url, this.config);
+    const data = (await res.json()) as any;
+
+    const deps: Dependency[] = [];
+    if (type === 'runtime' || type === 'all') {
+      for (const [n, v] of Object.entries(data.dependencies ?? {})) {
+        deps.push({ name: n, version: v as string, type: 'runtime' });
+      }
+    }
+    if (type === 'dev' || type === 'all') {
+      for (const [n, v] of Object.entries(data.devDependencies ?? {})) {
+        deps.push({ name: n, version: v as string, type: 'dev' });
+      }
+    }
+    return deps;
+  }
+
+  async getReverseDependencies(name: string, limit: number): Promise<PackageSearchResult[]> {
+    const url = `https://registry.npmjs.org/-/v1/search?text=dependencies:${encodeURIComponent(name)}&size=${limit}`;
+    const res = await registryFetch(url, this.config);
+    const data = (await res.json()) as any;
+
+    return (data.objects ?? []).map(
+      (obj: { package: { name: string; version: string; description?: string } }) => ({
+        name: obj.package.name,
+        version: obj.package.version,
+        description: obj.package.description ?? '',
+        downloads: '',
+        registry: 'npm' as const,
+      })
+    );
+  }
+
+  async getDownloadStats(name: string, period: string): Promise<DownloadStats> {
+    const npmPeriod = period === 'last-year' ? 'last-year' : period;
+    const url = `https://api.npmjs.org/downloads/point/${npmPeriod}/${encodeURIComponent(name)}`;
+    const res = await registryFetch(url, this.config);
+    const data = (await res.json()) as any;
+
+    return {
+      name,
+      registry: 'npm',
+      period,
+      total: data.downloads ?? 0,
+      breakdown: [],
+    };
+  }
+
+  async getPackageHealth(name: string): Promise<PackageHealth> {
+    const url = `https://registry.npmjs.org/${encodeURIComponent(name)}`;
+    const res = await registryFetch(url, this.config);
+    const data = (await res.json()) as any;
+
+    const latest = data['dist-tags']?.latest ?? '';
+    const latestInfo = data.versions?.[latest] ?? {};
+    const timeMap = data.time ?? {};
+    const lastPublish = timeMap[latest] ?? '';
+    const depCount = Object.keys(latestInfo.dependencies ?? {}).length;
+    const hasTypings = !!latestInfo.types || !!latestInfo.typings;
+
+    const signals: string[] = [];
+    if (hasTypings) signals.push('Has TypeScript typings');
+    if (latestInfo.scripts?.test) signals.push('Has test script');
+    if (data.readme && data.readme.length > 500) signals.push('Detailed README');
+
+    return {
+      name,
+      registry: 'npm',
+      score: Math.min(10, signals.length * 3 + 4),
+      lastPublish,
+      dependencyCount: depCount,
+      hasTests: !!latestInfo.scripts?.test,
+      hasTypings,
+      signals,
+    };
+  }
+
+  async getSecurityAdvisories(name: string, _version?: string): Promise<SecurityAdvisory[]> {
+    try {
+      const url = 'https://osv.dev/v1/query';
+      const body = { package: { name, ecosystem: 'npm' } };
+      const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(this.config.timeoutMs),
+      });
+      if (!res.ok) return [];
+      const data = (await res.json()) as any;
+      return (data.vulns ?? []).map(
+        (v: {
+          id: string;
+          summary?: string;
+          severity?: { type: string; score: string }[];
+          references?: { url: string }[];
+          affected?: { ranges?: { events?: { introduced?: string; fixed?: string }[] }[] }[];
+        }) => ({
+          id: v.id,
+          title: v.summary ?? v.id,
+          severity: v.severity?.[0]?.score ?? 'Unknown',
+          url: v.references?.[0]?.url ?? `https://osv.dev/vulnerability/${v.id}`,
+          affectedVersions: 'See advisory',
+        })
+      );
+    } catch {
+      return [];
+    }
+  }
+}

package/src/adapters/pypi.ts

@@ -0,0 +1,215 @@
+import type { Config } from '../config.js';
+import type { Cache } from '../cache.js';
+import type {
+  RegistryAdapter,
+  PackageSearchResult,
+  PackageMetadata,
+  VersionInfo,
+  VersionDetail,
+  Dependency,
+  DownloadStats,
+  MaintainerInfo,
+  PackageHealth,
+  SecurityAdvisory,
+} from '../types.js';
+import { registryFetch } from '../utils/fetch.js';
+
+export class PypiAdapter implements RegistryAdapter {
+  readonly name = 'pypi' as const;
+  constructor(
+    private config: Config,
+    private cache: Cache
+  ) {}
+
+  async search(query: string, limit: number): Promise<PackageSearchResult[]> {
+    const key = `pypi:search:${query}:${limit}`;
+    const cached = this.cache.get<PackageSearchResult[]>(key);
+    if (cached) return cached;
+
+    const results: PackageSearchResult[] = [];
+    try {
+      const pkgUrl = `https://pypi.org/pypi/${encodeURIComponent(query)}/json`;
+      const res = await registryFetch(pkgUrl, this.config);
+      const data = (await res.json()) as any;
+      results.push({
+        name: data.info.name,
+        version: data.info.version,
+        description: data.info.summary ?? '',
+        downloads: '',
+        registry: 'pypi',
+      });
+    } catch {
+      // Package not found directly — that's OK
+    }
+    this.cache.set(key, results.slice(0, limit));
+    return results.slice(0, limit);
+  }
+
+  async getPackage(name: string): Promise<PackageMetadata> {
+    const key = `pypi:pkg:${name}`;
+    const cached = this.cache.get<PackageMetadata>(key);
+    if (cached) return cached;
+
+    const url = `https://pypi.org/pypi/${encodeURIComponent(name)}/json`;
+    const res = await registryFetch(url, this.config);
+    const data = (await res.json()) as any;
+    const info = data.info;
+
+    const result: PackageMetadata = {
+      name: info.name,
+      version: info.version,
+      description: info.summary ?? '',
+      license: info.license ?? 'Unknown',
+      homepage: info.home_page ?? info.project_url ?? '',
+      repository: info.project_urls?.Source ?? info.project_urls?.Repository ?? '',
+      keywords: info.keywords ? info.keywords.split(',').map((k: string) => k.trim()) : [],
+      registry: 'pypi',
+    };
+    this.cache.set(key, result);
+    return result;
+  }
+
+  async getReadme(name: string): Promise<string> {
+    const url = `https://pypi.org/pypi/${encodeURIComponent(name)}/json`;
+    const res = await registryFetch(url, this.config);
+    const data = (await res.json()) as any;
+    return data.info.description ?? 'No README available.';
+  }
+
+  async getMaintainers(name: string): Promise<MaintainerInfo[]> {
+    const url = `https://pypi.org/pypi/${encodeURIComponent(name)}/json`;
+    const res = await registryFetch(url, this.config);
+    const data = (await res.json()) as any;
+    const info = data.info;
+    const maintainers: MaintainerInfo[] = [];
+    if (info.author) maintainers.push({ name: info.author, email: info.author_email });
+    if (info.maintainer) maintainers.push({ name: info.maintainer, email: info.maintainer_email });
+    return maintainers;
+  }
+
+  async listVersions(name: string, limit: number, stableOnly: boolean): Promise<VersionInfo[]> {
+    const url = `https://pypi.org/pypi/${encodeURIComponent(name)}/json`;
+    const res = await registryFetch(url, this.config);
+    const data = (await res.json()) as any;
+
+    const releases = Object.keys(data.releases ?? {}).reverse();
+    let results: VersionInfo[] = releases.map((v) => {
+      const files = data.releases[v] ?? [];
+      const date = files[0]?.upload_time_iso_8601 ?? '';
+      return {
+        version: v,
+        date,
+        prerelease: /(?:a|b|rc|dev|alpha|beta)\d*/i.test(v),
+      };
+    });
+
+    if (stableOnly) results = results.filter((v) => !v.prerelease);
+    return results.slice(0, limit);
+  }
+
+  async getVersion(name: string, version: string): Promise<VersionDetail> {
+    const url = `https://pypi.org/pypi/${encodeURIComponent(name)}/${version}/json`;
+    const res = await registryFetch(url, this.config);
+    const data = (await res.json()) as any;
+    const info = data.info;
+
+    const deps: Dependency[] = (info.requires_dist ?? []).map((d: string) => {
+      const match = d.match(/^([^\s;]+)/);
+      return {
+        name: match?.[1] ?? d,
+        version: '',
+        type: 'runtime' as const,
+      };
+    });
+
+    return {
+      name: info.name,
+      version: info.version,
+      date: data.urls?.[0]?.upload_time_iso_8601 ?? '',
+      license: info.license ?? 'Unknown',
+      size: data.urls?.[0]?.size ? `${Math.round(data.urls[0].size / 1024)}KB` : 'Unknown',
+      dependencies: deps,
+      registry: 'pypi',
+    };
+  }
+
+  async getDependencies(
+    name: string,
+    version: string,
+    _type: 'runtime' | 'dev' | 'all'
+  ): Promise<Dependency[]> {
+    const vd = await this.getVersion(name, version);
+    return vd.dependencies;
+  }
+
+  async getReverseDependencies(_name: string, _limit: number): Promise<PackageSearchResult[]> {
+    return []; // PyPI doesn't expose reverse dependencies
+  }
+
+  async getDownloadStats(name: string, period: string): Promise<DownloadStats> {
+    return {
+      name,
+      registry: 'pypi',
+      period,
+      total: 0, // PyPI doesn't have a public real-time download API
+      breakdown: [],
+    };
+  }
+
+  async getPackageHealth(name: string): Promise<PackageHealth> {
+    const url = `https://pypi.org/pypi/${encodeURIComponent(name)}/json`;
+    const res = await registryFetch(url, this.config);
+    const data = (await res.json()) as any;
+    const info = data.info;
+
+    const signals: string[] = [];
+    if (info.description && info.description.length > 500) signals.push('Detailed description');
+    if (info.license) signals.push('License specified');
+    if (info.requires_python) signals.push('Python version specified');
+    if (info.project_urls?.Documentation) signals.push('Has documentation URL');
+
+    const depCount = (info.requires_dist ?? []).length;
+
+    return {
+      name,
+      registry: 'pypi',
+      score: Math.min(10, signals.length * 2 + 3),
+      lastPublish: data.urls?.[0]?.upload_time_iso_8601 ?? '',
+      dependencyCount: depCount,
+      hasTests: false,
+      hasTypings: info.classifiers?.some((c: string) => c.includes('Typing')) ?? false,
+      signals,
+    };
+  }
+
+  async getSecurityAdvisories(name: string, _version?: string): Promise<SecurityAdvisory[]> {
+    try {
+      const url = 'https://osv.dev/v1/query';
+      const body = { package: { name, ecosystem: 'PyPI' } };
+      const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(this.config.timeoutMs),
+      });
+      if (!res.ok) return [];
+      const data = (await res.json()) as any;
+      return (data.vulns ?? []).map(
+        (v: {
+          id: string;
+          summary?: string;
+          severity?: { score: string }[];
+          references?: { url: string }[];
+        }) => ({
+          id: v.id,
+          title: v.summary ?? v.id,
+          severity: v.severity?.[0]?.score ?? 'Unknown',
+          url: v.references?.[0]?.url ?? `https://osv.dev/vulnerability/${v.id}`,
+          affectedVersions: 'See advisory',
+        })
+      );
+    } catch {
+      return [];
+    }
+  }
+}

package/src/cache.ts

@@ -0,0 +1,39 @@
+interface CacheEntry<T> {
+  value: T;
+  expiresAt: number;
+}
+
+export class Cache {
+  private store = new Map<string, CacheEntry<unknown>>();
+  private readonly ttlMs: number;
+
+  constructor(ttlMs: number) {
+    this.ttlMs = ttlMs;
+  }
+
+  get<T>(key: string): T | undefined {
+    const entry = this.store.get(key);
+    if (!entry) return undefined;
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      return undefined;
+    }
+    return entry.value as T;
+  }
+
+  set<T>(key: string, value: T): void {
+    if (this.ttlMs <= 0) return;
+    this.store.set(key, {
+      value,
+      expiresAt: Date.now() + this.ttlMs,
+    });
+  }
+
+  clear(): void {
+    this.store.clear();
+  }
+
+  get size(): number {
+    return this.store.size;
+  }
+}

package/src/config.ts

@@ -0,0 +1,41 @@
+import type { RegistryName } from './types.js';
+
+export interface Config {
+  registries: RegistryName[];
+  npmToken?: string;
+  timeoutMs: number;
+  cacheTtlMs: number;
+}
+
+const VALID_REGISTRIES = new Set<RegistryName>(['npm', 'pypi', 'maven', 'crates']);
+
+export function loadConfig(): Config {
+  const registriesEnv = process.env.REGISTRYX_MCP_REGISTRIES ?? 'npm,pypi,maven,crates';
+  const registries = registriesEnv
+    .split(',')
+    .map((r) => r.trim().toLowerCase())
+    .filter((r): r is RegistryName => VALID_REGISTRIES.has(r as RegistryName));
+
+  if (registries.length === 0) {
+    throw new Error(
+      'No valid registries configured. Set REGISTRYX_MCP_REGISTRIES to comma-separated values: npm, pypi, maven, crates'
+    );
+  }
+
+  const timeoutMs = parseInt(process.env.REGISTRYX_MCP_TIMEOUT_MS ?? '15000', 10);
+  if (isNaN(timeoutMs) || timeoutMs < 1000 || timeoutMs > 120000) {
+    throw new Error('REGISTRYX_MCP_TIMEOUT_MS must be between 1000 and 120000');
+  }
+
+  const cacheTtlMs = parseInt(process.env.REGISTRYX_MCP_CACHE_TTL_MS ?? '300000', 10);
+  if (isNaN(cacheTtlMs) || cacheTtlMs < 0) {
+    throw new Error('REGISTRYX_MCP_CACHE_TTL_MS must be >= 0');
+  }
+
+  return {
+    registries,
+    npmToken: process.env.REGISTRYX_MCP_NPM_TOKEN || undefined,
+    timeoutMs,
+    cacheTtlMs,
+  };
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { loadConfig } from './config.js';
+import { createServer } from './server.js';
+
+async function main() {
+  const config = loadConfig();
+  const server = createServer(config);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  process.on('SIGINT', async () => {
+    await server.close();
+    process.exit(0);
+  });
+  process.on('SIGTERM', async () => {
+    await server.close();
+    process.exit(0);
+  });
+}
+
+main().catch((err) => {
+  console.error('Fatal:', err);
+  process.exit(1);
+});