@universal-mcp-toolkit/server-npm-registry 0.1.0

package/.well-known/mcp-server.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json.schemastore.org/json",
+  "name": "npm-registry",
+  "title": "NPM Registry MCP Server",
+  "description": "Search and inspect npm registry packages, versions, and dist-tags.",
+  "version": "0.1.0",
+  "packageName": "@universal-mcp-toolkit/server-npm-registry",
+  "homepage": "https://github.com/universal-mcp-toolkit/universal-mcp-toolkit",
+  "transports": [
+    "stdio",
+    "sse"
+  ],
+  "authentication": {
+    "mode": "environment-variables",
+    "required": []
+  },
+  "capabilities": {
+    "tools": true,
+    "resources": true,
+    "prompts": true
+  },
+  "tools": [
+    "search_packages",
+    "get_package_metadata",
+    "list_package_versions"
+  ],
+  "resources": [
+    "package"
+  ],
+  "prompts": [
+    "release-plan"
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 universal-mcp-toolkit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,70 @@
+import * as _universal_mcp_toolkit_core from '@universal-mcp-toolkit/core';
+import { ToolkitServer, ToolkitServerMetadata } from '@universal-mcp-toolkit/core';
+import { z } from 'zod';
+
+declare const metadata: ToolkitServerMetadata;
+declare const serverCard: _universal_mcp_toolkit_core.ToolkitServerCard;
+declare const searchResultSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
+    keywords: z.ZodArray<z.ZodString>;
+    score: z.ZodNumber;
+    homepage: z.ZodNullable<z.ZodString>;
+    npmUrl: z.ZodNullable<z.ZodString>;
+    repositoryUrl: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+declare const maintainerSchema: z.ZodObject<{
+    name: z.ZodString;
+    email: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+declare const versionInfoSchema: z.ZodObject<{
+    version: z.ZodString;
+    publishedAt: z.ZodNullable<z.ZodString>;
+    deprecated: z.ZodBoolean;
+    unpackedSize: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+declare const packageMetadataSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
+    latestVersion: z.ZodNullable<z.ZodString>;
+    homepage: z.ZodNullable<z.ZodString>;
+    repositoryUrl: z.ZodNullable<z.ZodString>;
+    license: z.ZodNullable<z.ZodString>;
+    distTags: z.ZodRecord<z.ZodString, z.ZodString>;
+    maintainers: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        email: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    versions: z.ZodArray<z.ZodObject<{
+        version: z.ZodString;
+        publishedAt: z.ZodNullable<z.ZodString>;
+        deprecated: z.ZodBoolean;
+        unpackedSize: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type NpmSearchResult = z.infer<typeof searchResultSchema>;
+type NpmMaintainer = z.infer<typeof maintainerSchema>;
+type NpmVersionInfo = z.infer<typeof versionInfoSchema>;
+type NpmPackageMetadata = z.infer<typeof packageMetadataSchema>;
+interface NpmRegistryClient {
+    searchPackages(input: {
+        query: string;
+        limit: number;
+        from: number;
+    }): Promise<ReadonlyArray<NpmSearchResult>>;
+    getPackageMetadata(packageName: string): Promise<NpmPackageMetadata>;
+}
+interface CreateNpmRegistryServerOptions {
+    client?: NpmRegistryClient;
+    env?: NodeJS.ProcessEnv;
+    fetch?: typeof fetch;
+}
+declare class NpmRegistryServer extends ToolkitServer {
+    private readonly client;
+    constructor(client: NpmRegistryClient);
+}
+declare function createServer(options?: CreateNpmRegistryServerOptions): Promise<NpmRegistryServer>;
+declare function main(argv?: readonly string[]): Promise<void>;
+
+export { type CreateNpmRegistryServerOptions, type NpmMaintainer, type NpmPackageMetadata, type NpmRegistryClient, NpmRegistryServer, type NpmSearchResult, type NpmVersionInfo, createServer, main, metadata, serverCard };

package/dist/index.js

@@ -0,0 +1,359 @@
+// src/index.ts
+import {
+  createServerCard,
+  defineTool,
+  ExternalServiceError,
+  loadEnv,
+  parseRuntimeOptions,
+  runToolkitServer,
+  ToolkitServer
+} from "@universal-mcp-toolkit/core";
+import { resolve } from "path";
+import { fileURLToPath } from "url";
+import { z } from "zod";
+var toolNames = ["search_packages", "get_package_metadata", "list_package_versions"];
+var resourceNames = ["package"];
+var promptNames = ["release-plan"];
+var metadata = {
+  id: "npm-registry",
+  title: "NPM Registry MCP Server",
+  description: "Search and inspect npm registry packages, versions, and dist-tags.",
+  version: "0.1.0",
+  packageName: "@universal-mcp-toolkit/server-npm-registry",
+  homepage: "https://github.com/universal-mcp-toolkit/universal-mcp-toolkit",
+  repositoryUrl: "https://github.com/universal-mcp-toolkit/universal-mcp-toolkit",
+  documentationUrl: "https://github.com/universal-mcp-toolkit/universal-mcp-toolkit/tree/main/servers/npm-registry",
+  envVarNames: [],
+  transports: ["stdio", "sse"],
+  toolNames,
+  resourceNames,
+  promptNames
+};
+var serverCard = createServerCard(metadata);
+var envShape = {
+  NPM_REGISTRY_BASE_URL: z.string().url().optional(),
+  NPM_SEARCH_BASE_URL: z.string().url().optional()
+};
+var searchResultSchema = z.object({
+  name: z.string(),
+  version: z.string(),
+  description: z.string().nullable(),
+  keywords: z.array(z.string()),
+  score: z.number(),
+  homepage: z.string().nullable(),
+  npmUrl: z.string().nullable(),
+  repositoryUrl: z.string().nullable()
+});
+var maintainerSchema = z.object({
+  name: z.string(),
+  email: z.string().nullable()
+});
+var versionInfoSchema = z.object({
+  version: z.string(),
+  publishedAt: z.string().nullable(),
+  deprecated: z.boolean(),
+  unpackedSize: z.number().nonnegative().nullable()
+});
+var packageMetadataSchema = z.object({
+  name: z.string(),
+  description: z.string().nullable(),
+  latestVersion: z.string().nullable(),
+  homepage: z.string().nullable(),
+  repositoryUrl: z.string().nullable(),
+  license: z.string().nullable(),
+  distTags: z.record(z.string(), z.string()),
+  maintainers: z.array(maintainerSchema),
+  versions: z.array(versionInfoSchema)
+});
+var searchResponseSchema = z.object({
+  objects: z.array(
+    z.object({
+      package: z.object({
+        name: z.string(),
+        version: z.string(),
+        description: z.string().nullable().optional(),
+        keywords: z.array(z.string()).optional(),
+        links: z.object({
+          homepage: z.string().nullable().optional(),
+          npm: z.string().nullable().optional(),
+          repository: z.string().nullable().optional()
+        }).optional()
+      }),
+      score: z.object({
+        final: z.number()
+      }).optional()
+    })
+  )
+});
+var rawVersionSchema = z.object({
+  dist: z.object({
+    unpackedSize: z.number().nonnegative().optional()
+  }).optional(),
+  deprecated: z.string().optional()
+});
+var packageResponseSchema = z.object({
+  name: z.string(),
+  description: z.string().nullable().optional(),
+  homepage: z.string().nullable().optional(),
+  license: z.string().nullable().optional(),
+  repository: z.object({
+    url: z.string().nullable().optional()
+  }).optional(),
+  "dist-tags": z.record(z.string(), z.string()).optional(),
+  maintainers: z.array(
+    z.object({
+      name: z.string(),
+      email: z.string().nullable().optional()
+    })
+  ).optional(),
+  versions: z.record(z.string(), rawVersionSchema).optional(),
+  time: z.record(z.string(), z.string()).optional()
+});
+function resolveEnv(source = process.env) {
+  return loadEnv(envShape, source);
+}
+function toNullableString(value) {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+function encodePackageName(packageName) {
+  return encodeURIComponent(packageName);
+}
+function getTemplateVariable(variables, name) {
+  const value = variables[name];
+  return Array.isArray(value) ? value[0] ?? "" : value ?? "";
+}
+var FetchNpmRegistryClient = class {
+  registryBaseUrl;
+  searchBaseUrl;
+  fetchImpl;
+  constructor(options) {
+    this.registryBaseUrl = (options.registryBaseUrl ?? "https://registry.npmjs.org").replace(/\/+$/, "");
+    this.searchBaseUrl = (options.searchBaseUrl ?? "https://registry.npmjs.org/-/v1").replace(/\/+$/, "");
+    this.fetchImpl = options.fetch;
+  }
+  async searchPackages(input) {
+    const url = new URL(`${this.searchBaseUrl}/search`);
+    url.searchParams.set("text", input.query);
+    url.searchParams.set("size", String(input.limit));
+    url.searchParams.set("from", String(input.from));
+    const payload = await this.requestJson(url, searchResponseSchema);
+    return payload.objects.map((entry) => ({
+      name: entry.package.name,
+      version: entry.package.version,
+      description: toNullableString(entry.package.description),
+      keywords: entry.package.keywords ?? [],
+      score: entry.score?.final ?? 0,
+      homepage: toNullableString(entry.package.links?.homepage),
+      npmUrl: toNullableString(entry.package.links?.npm),
+      repositoryUrl: toNullableString(entry.package.links?.repository)
+    }));
+  }
+  async getPackageMetadata(packageName) {
+    const payload = await this.requestJson(
+      new URL(`${this.registryBaseUrl}/${encodePackageName(packageName)}`),
+      packageResponseSchema
+    );
+    const times = payload.time ?? {};
+    const versions = Object.entries(payload.versions ?? {}).map(([version, detail]) => ({
+      version,
+      publishedAt: toNullableString(times[version]),
+      deprecated: typeof detail.deprecated === "string" && detail.deprecated.length > 0,
+      unpackedSize: detail.dist?.unpackedSize ?? null
+    })).sort((left, right) => {
+      const leftTime = left.publishedAt === null ? 0 : Date.parse(left.publishedAt);
+      const rightTime = right.publishedAt === null ? 0 : Date.parse(right.publishedAt);
+      return rightTime - leftTime;
+    });
+    return {
+      name: payload.name,
+      description: toNullableString(payload.description),
+      latestVersion: toNullableString(payload["dist-tags"]?.latest),
+      homepage: toNullableString(payload.homepage),
+      repositoryUrl: toNullableString(payload.repository?.url),
+      license: toNullableString(payload.license),
+      distTags: payload["dist-tags"] ?? {},
+      maintainers: (payload.maintainers ?? []).map((maintainer) => ({
+        name: maintainer.name,
+        email: toNullableString(maintainer.email)
+      })),
+      versions
+    };
+  }
+  async requestJson(url, schema) {
+    const response = await this.fetchImpl(url, {
+      method: "GET",
+      headers: {
+        accept: "application/json"
+      }
+    });
+    if (!response.ok) {
+      const body = await response.text();
+      throw new ExternalServiceError(`npm registry request failed with status ${response.status}.`, {
+        statusCode: response.status,
+        details: body
+      });
+    }
+    const payload = await response.json();
+    const parsed = schema.safeParse(payload);
+    if (!parsed.success) {
+      throw new ExternalServiceError("npm registry returned an unexpected response shape.", {
+        details: parsed.error.flatten()
+      });
+    }
+    return parsed.data;
+  }
+};
+var NpmRegistryServer = class extends ToolkitServer {
+  client;
+  constructor(client) {
+    super(metadata);
+    this.client = client;
+    this.registerTool(
+      defineTool({
+        name: "search_packages",
+        title: "Search npm packages",
+        description: "Search the npm registry for packages matching a text query.",
+        inputSchema: {
+          query: z.string().trim().min(1),
+          limit: z.number().int().min(1).max(50).default(10),
+          from: z.number().int().min(0).max(500).default(0)
+        },
+        outputSchema: {
+          results: z.array(searchResultSchema),
+          returned: z.number().int()
+        },
+        handler: async ({ query, limit, from }, context) => {
+          await context.log("info", `Searching npm registry for ${query}`);
+          const results = await this.client.searchPackages({ query, limit, from });
+          return {
+            results: [...results],
+            returned: results.length
+          };
+        },
+        renderText: ({ results, returned }) => {
+          if (returned === 0) {
+            return "No npm packages found.";
+          }
+          return results.map((result) => `${result.name}@${result.version}`).join("\n");
+        }
+      })
+    );
+    this.registerTool(
+      defineTool({
+        name: "get_package_metadata",
+        title: "Get package metadata",
+        description: "Fetch npm registry metadata for a specific package.",
+        inputSchema: {
+          packageName: z.string().trim().min(1)
+        },
+        outputSchema: {
+          package: packageMetadataSchema
+        },
+        handler: async ({ packageName }, context) => {
+          await context.log("info", `Fetching npm metadata for ${packageName}`);
+          return {
+            package: await this.client.getPackageMetadata(packageName)
+          };
+        },
+        renderText: ({ package: pkg }) => `${pkg.name} latest=${pkg.latestVersion ?? "unknown"}`
+      })
+    );
+    this.registerTool(
+      defineTool({
+        name: "list_package_versions",
+        title: "List package versions",
+        description: "List recent versions and dist-tags for a package in the npm registry.",
+        inputSchema: {
+          packageName: z.string().trim().min(1),
+          limit: z.number().int().min(1).max(100).default(20)
+        },
+        outputSchema: {
+          packageName: z.string(),
+          distTags: z.record(z.string(), z.string()),
+          versions: z.array(versionInfoSchema)
+        },
+        handler: async ({ packageName, limit }, context) => {
+          await context.log("info", `Listing npm versions for ${packageName}`);
+          const pkg = await this.client.getPackageMetadata(packageName);
+          return {
+            packageName: pkg.name,
+            distTags: pkg.distTags,
+            versions: pkg.versions.slice(0, limit)
+          };
+        },
+        renderText: ({ packageName, versions }) => `${packageName}: ${versions.map((version) => version.version).join(", ")}`
+      })
+    );
+    this.registerTemplateResource(
+      "package",
+      "npm://package/{packageName}",
+      {
+        title: "Package metadata",
+        description: "Metadata resource for an npm package.",
+        mimeType: "application/json"
+      },
+      async (uri, variables) => {
+        const packageName = getTemplateVariable(variables, "packageName");
+        const pkg = await this.client.getPackageMetadata(packageName);
+        return this.createJsonResource(uri.toString(), pkg);
+      }
+    );
+    this.registerPrompt(
+      "release-plan",
+      {
+        title: "Release plan prompt",
+        description: "Draft a release plan for publishing or promoting an npm package.",
+        argsSchema: {
+          packageName: z.string().trim().min(1),
+          targetVersion: z.string().trim().min(1),
+          currentVersion: z.string().trim().min(1).optional(),
+          goal: z.string().trim().min(1)
+        }
+      },
+      async ({ packageName, targetVersion, currentVersion, goal }) => this.createTextPrompt(
+        [
+          `Create a release plan for ${packageName} targeting version ${targetVersion}.`,
+          currentVersion ? `Current published version: ${currentVersion}.` : "Assume the current version needs verification.",
+          `Primary goal: ${goal}.`,
+          "Cover changelog scope, semver impact, dist-tags, validation, rollback, and communication steps."
+        ].join(" ")
+      )
+    );
+  }
+};
+async function createServer(options = {}) {
+  if (options.client) {
+    return new NpmRegistryServer(options.client);
+  }
+  const env = resolveEnv(options.env);
+  const client = new FetchNpmRegistryClient({
+    fetch: options.fetch ?? globalThis.fetch,
+    ...env.NPM_REGISTRY_BASE_URL ? { registryBaseUrl: env.NPM_REGISTRY_BASE_URL } : {},
+    ...env.NPM_SEARCH_BASE_URL ? { searchBaseUrl: env.NPM_SEARCH_BASE_URL } : {}
+  });
+  return new NpmRegistryServer(client);
+}
+function isMainModule(metaUrl) {
+  const entry = process.argv[1];
+  return typeof entry === "string" && fileURLToPath(metaUrl) === resolve(entry);
+}
+async function main(argv = process.argv.slice(2)) {
+  const runtimeOptions = parseRuntimeOptions(argv);
+  await runToolkitServer(
+    {
+      createServer: () => createServer(),
+      serverCard
+    },
+    runtimeOptions
+  );
+}
+if (isMainModule(import.meta.url)) {
+  await main();
+}
+export {
+  NpmRegistryServer,
+  createServer,
+  main,
+  metadata,
+  serverCard
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@universal-mcp-toolkit/server-npm-registry",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Package metadata, search, and version tools for the npm registry.",
+  "license": "MIT",
+  "bin": {
+    "server-npm-registry": "./dist/index.js",
+    "umt-npm-registry": "./dist/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Markgatcha/universal-mcp-toolkit.git"
+  },
+  "homepage": "https://github.com/Markgatcha/universal-mcp-toolkit#readme",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    ".well-known"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "developer-tools",
+    "typescript",
+    "npm",
+    "registry",
+    "packages",
+    "versions"
+  ],
+  "dependencies": {
+    "@universal-mcp-toolkit/core": "0.1.0",
+    "zod": "^4.3.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsx watch src/index.ts",
+    "lint": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "clean": "rimraf dist"
+  }
+}