@vucinatim/agentic-devtools 0.1.0

package/src/tools/npm/client.mjs

@@ -0,0 +1,317 @@
+import { execFile } from "node:child_process";
+import { chmod, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { DEFAULT_NPM_REGISTRY, getNpmAuthStatus, resolveNpmAuthConfig } from "./auth.mjs";
+
+export class NpmRegistryError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = "NpmRegistryError";
+    this.details = details;
+  }
+}
+
+export const encodePackageName = (packageName) =>
+  encodeURIComponent(String(packageName ?? "").trim());
+
+const normalizeRegistry = (registry = DEFAULT_NPM_REGISTRY) =>
+  String(registry || DEFAULT_NPM_REGISTRY).replace(/\/+$/, "");
+
+const isNotFound = (error) =>
+  error instanceof NpmRegistryError && error.details.status === 404;
+
+export const createNpmClient = ({
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+} = {}) => {
+  const auth = resolveNpmAuthConfig(env);
+  const registry = normalizeRegistry(auth.registry);
+
+  if (typeof fetchImpl !== "function") {
+    throw new Error("npm client requires a fetch implementation.");
+  }
+
+  const request = async (pathname, { method = "GET", body, authRequired = false, headers = {} } = {}) => {
+    if (authRequired && !auth.token) {
+      throw new NpmRegistryError(
+        "Missing npm token. Run `agentic-devtools connect npm`, set NPM_TOKEN/NODE_AUTH_TOKEN, or configure ~/.npmrc.",
+      );
+    }
+
+    const response = await fetchImpl(`${registry}${pathname}`, {
+      method,
+      headers: {
+        accept: "application/json",
+        ...(body ? { "content-type": "application/json" } : {}),
+        ...(authRequired ? { Authorization: `Bearer ${auth.token}` } : {}),
+        ...headers,
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+
+    const text = await response.text();
+    let payload = null;
+    if (text) {
+      try {
+        payload = JSON.parse(text);
+      } catch {
+        payload = { error: text };
+      }
+    }
+
+    if (!response.ok) {
+      throw new NpmRegistryError(formatNpmErrorMessage(payload, response.status), {
+        status: response.status,
+        payload,
+      });
+    }
+
+    return payload;
+  };
+
+  const getCurrentUser = async () => request("/-/whoami", { authRequired: true });
+
+  const getPackageInfo = async (packageName) =>
+    request(`/${encodePackageName(packageName)}`, { authRequired: false });
+
+  const checkPackageNameAvailability = async (packageName) => {
+    try {
+      const info = await getPackageInfo(packageName);
+      return {
+        packageName,
+        available: false,
+        version: info["dist-tags"]?.latest ?? null,
+        description: info.description ?? null,
+      };
+    } catch (error) {
+      if (isNotFound(error)) {
+        return {
+          packageName,
+          available: true,
+          version: null,
+          description: null,
+        };
+      }
+      throw error;
+    }
+  };
+
+  const getPackageVersions = async (packageName) => {
+    const info = await getPackageInfo(packageName);
+    return {
+      packageName: info.name,
+      latest: info["dist-tags"]?.latest ?? null,
+      versions: Object.keys(info.versions ?? {}),
+    };
+  };
+
+  const getPackageDistTags = async (packageName) => {
+    const info = await getPackageInfo(packageName);
+    return {
+      packageName: info.name,
+      distTags: info["dist-tags"] ?? {},
+    };
+  };
+
+  const getPackageVisibility = async (packageName) =>
+    request(`/-/package/${encodePackageName(packageName)}/visibility`, {
+      authRequired: true,
+    });
+
+  const setPackageAccess = async ({
+    packageName,
+    access = "public",
+    publishRequiresTfa,
+    automationTokenOverridesTfa,
+  }) =>
+    request(`/-/package/${encodePackageName(packageName)}/access`, {
+      method: "POST",
+      authRequired: true,
+      body: {
+        access,
+        ...(publishRequiresTfa == null
+          ? {}
+          : { publish_requires_tfa: Boolean(publishRequiresTfa) }),
+        ...(automationTokenOverridesTfa == null
+          ? {}
+          : { automation_token_overrides_tfa: Boolean(automationTokenOverridesTfa) }),
+      },
+    });
+
+  const listTokens = async ({ page = 0, perPage = 10 } = {}) =>
+    request(`/-/npm/v1/tokens?page=${page}&perPage=${perPage}`, {
+      authRequired: true,
+    });
+
+  const deleteToken = async ({ token, otp } = {}) =>
+    request(`/-/npm/v1/tokens/token/${encodeURIComponent(token)}`, {
+      method: "DELETE",
+      authRequired: true,
+      headers: otp ? { "npm-otp": otp } : {},
+    });
+
+  const getTrustedPublishers = async ({ packageName, otp } = {}) =>
+    request(`/-/package/${encodePackageName(packageName)}/trust`, {
+      authRequired: true,
+      headers: otp ? { "npm-otp": otp } : {},
+    });
+
+  const addGitHubTrustedPublisher = async ({
+    packageName,
+    repository,
+    workflowFile = "publish.yml",
+    environment,
+    otp,
+  } = {}) =>
+    request(`/-/package/${encodePackageName(packageName)}/trust`, {
+      method: "POST",
+      authRequired: true,
+      headers: otp ? { "npm-otp": otp } : {},
+      body: [
+        {
+          type: "github",
+          claims: {
+            repository,
+            workflow_ref: {
+              file: workflowFile,
+            },
+            ...(environment ? { environment } : {}),
+          },
+        },
+      ],
+    });
+
+  const deleteTrustedPublisher = async ({ packageName, configId, otp } = {}) =>
+    request(
+      `/-/package/${encodePackageName(packageName)}/trust/${encodeURIComponent(configId)}`,
+      {
+        method: "DELETE",
+        authRequired: true,
+        headers: otp ? { "npm-otp": otp } : {},
+      },
+    );
+
+  const exchangeOidcToken = async ({ packageName, oidcToken } = {}) => {
+    if (!oidcToken) {
+      throw new NpmRegistryError("Missing OIDC id_token for npm token exchange.");
+    }
+    return request(`/-/npm/v1/oidc/token/exchange/package/${encodePackageName(packageName)}`, {
+      method: "POST",
+      authRequired: false,
+      headers: { Authorization: `Bearer ${oidcToken}` },
+    });
+  };
+
+  const publishPackageDirectory = async ({
+    cwd = process.cwd(),
+    tag = "latest",
+    access = "public",
+    dryRun = true,
+    confirm = "",
+  } = {}) => {
+    const packageJson = JSON.parse(
+      await readFile(path.join(cwd, "package.json"), "utf8"),
+    );
+    if (!dryRun && confirm !== `publish ${packageJson.name}@${packageJson.version}`) {
+      throw new NpmRegistryError(
+        `Publishing requires confirm="publish ${packageJson.name}@${packageJson.version}".`,
+      );
+    }
+
+    const args = ["publish", "--access", access, "--tag", tag];
+    if (dryRun) {
+      args.push("--dry-run");
+    }
+
+    const tempDir = await mkdtemp(path.join(os.tmpdir(), "agentic-npm-"));
+    const userconfigPath = path.join(tempDir, ".npmrc");
+    if (auth.token) {
+      const registryUrl = new URL(registry);
+      await writeFile(
+        userconfigPath,
+        `registry=${registry}/\n//${registryUrl.host}/:_authToken=${auth.token}\n`,
+      );
+      await chmod(userconfigPath, 0o600).catch(() => {});
+    }
+
+    const envForPublish = {
+      ...process.env,
+      ...env,
+      NPM_CONFIG_REGISTRY: registry,
+      ...(auth.token ? { NPM_CONFIG_USERCONFIG: userconfigPath } : {}),
+    };
+
+    try {
+      const result = await execNpm(args, { cwd, env: envForPublish });
+      return {
+        ok: result.status === 0,
+        dryRun,
+        packageName: packageJson.name,
+        version: packageJson.version,
+        tag,
+        access,
+        tokenSource: auth.source,
+        stdout: result.stdout,
+        stderr: result.stderr,
+      };
+    } finally {
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  };
+
+  return {
+    auth,
+    registry,
+    getAuthStatus: () => getNpmAuthStatus(env),
+    getCurrentUser,
+    getPackageInfo,
+    checkPackageNameAvailability,
+    getPackageVersions,
+    getPackageDistTags,
+    getPackageVisibility,
+    setPackageAccess,
+    listTokens,
+    deleteToken,
+    getTrustedPublishers,
+    addGitHubTrustedPublisher,
+    deleteTrustedPublisher,
+    exchangeOidcToken,
+    publishPackageDirectory,
+  };
+};
+
+const execNpm = (args, { cwd, env }) =>
+  new Promise((resolve, reject) => {
+    execFile("npm", args, { cwd, env }, (error, stdout, stderr) => {
+      const result = {
+        status: error?.code ?? 0,
+        stdout,
+        stderr,
+      };
+      if (error && error.code == null) {
+        reject(error);
+        return;
+      }
+      resolve(result);
+    });
+  });
+
+const formatNpmErrorMessage = (payload, status) => {
+  if (payload && typeof payload === "object") {
+    const message = payload.error || payload.message;
+    if (typeof message === "string" && message.trim()) {
+      const trimmed = message.trim();
+      try {
+        const nested = JSON.parse(trimmed);
+        if (typeof nested?.error === "string" && nested.error.trim()) {
+          return nested.error.trim();
+        }
+      } catch {
+        // Keep the original npm error string when it is not nested JSON.
+      }
+      return trimmed;
+    }
+  }
+  return `npm registry request failed with HTTP ${status}`;
+};

package/src/tools/npm/mcp.mjs

@@ -0,0 +1,343 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import {
+  disconnectNpm,
+  getNpmAuthStatus,
+  NPM_AUTH_CONFIG_PATH,
+  runNpmBrowserAuthFlow,
+} from "./auth.mjs";
+import { createNpmClient } from "./client.mjs";
+
+const HELP_TEXT = `Usage: agentic-devtools mcp npm
+
+npm MCP server
+
+Optional environment variables:
+  NPM_TOKEN
+  NODE_AUTH_TOKEN
+  NPM_CONFIG_REGISTRY
+  AGENTIC_DEVTOOLS_NPM_AUTH_CONFIG_PATH
+
+Prefer GitHub Actions Trusted Publishing for real package publishing. Local publishing is supported but explicit confirmation is required.
+`;
+
+const createToolResult = (value) => ({
+  content: [
+    {
+      type: "text",
+      text: JSON.stringify(value, null, 2),
+    },
+  ],
+  structuredContent: value,
+});
+
+const packageNameSchema = z.string().min(1);
+
+const createServer = () => {
+  const server = new McpServer(
+    {
+      name: "npm",
+      version: "0.1.0",
+    },
+    {
+      instructions:
+        "Use these tools for npm registry inspection, token status checks, trusted publishing verification, and explicitly confirmed publishing. Prefer GitHub Actions Trusted Publishing over local write tokens.",
+    },
+  );
+
+  const withClient = async (callback) => {
+    const client = createNpmClient();
+    return callback(client);
+  };
+
+  server.registerTool(
+    "getNpmAuthStatus",
+    {
+      description:
+        "Show whether npm credentials are configured without exposing token values.",
+    },
+    async () => createToolResult(getNpmAuthStatus()),
+  );
+
+  server.registerTool(
+    "connectNpm",
+    {
+      description:
+        "Open a browser-based guided setup flow for an npm granular token.",
+    },
+    async () =>
+      createToolResult({
+        ...(await runNpmBrowserAuthFlow()),
+        configPath: NPM_AUTH_CONFIG_PATH,
+      }),
+  );
+
+  server.registerTool(
+    "disconnectNpm",
+    {
+      description: "Remove the locally stored npm token from Agentic Devtools.",
+    },
+    async () => createToolResult(await disconnectNpm()),
+  );
+
+  server.registerTool(
+    "testNpmConnection",
+    {
+      description:
+        "Verify that the configured npm token can call the npm registry identity endpoint.",
+    },
+    async () =>
+      createToolResult(
+        await withClient(async (client) => ({
+          ok: true,
+          tokenSource: client.auth.source,
+          registry: client.registry,
+          user: await client.getCurrentUser(),
+        })),
+      ),
+  );
+
+  server.registerTool(
+    "getNpmPackageInfo",
+    {
+      description: "Fetch public package metadata from the npm registry.",
+      inputSchema: {
+        packageName: packageNameSchema,
+      },
+    },
+    async ({ packageName }) =>
+      createToolResult(
+        await withClient((client) => client.getPackageInfo(packageName)),
+      ),
+  );
+
+  server.registerTool(
+    "checkNpmPackageNameAvailability",
+    {
+      description: "Check if a package name is available on npm.",
+      inputSchema: {
+        packageName: packageNameSchema,
+      },
+    },
+    async ({ packageName }) =>
+      createToolResult(
+        await withClient((client) =>
+          client.checkPackageNameAvailability(packageName),
+        ),
+      ),
+  );
+
+  server.registerTool(
+    "getNpmPackageVersions",
+    {
+      description: "List published versions and latest tag for an npm package.",
+      inputSchema: {
+        packageName: packageNameSchema,
+      },
+    },
+    async ({ packageName }) =>
+      createToolResult(
+        await withClient((client) => client.getPackageVersions(packageName)),
+      ),
+  );
+
+  server.registerTool(
+    "getNpmPackageDistTags",
+    {
+      description: "List npm dist-tags for a package.",
+      inputSchema: {
+        packageName: packageNameSchema,
+      },
+    },
+    async ({ packageName }) =>
+      createToolResult(
+        await withClient((client) => client.getPackageDistTags(packageName)),
+      ),
+  );
+
+  server.registerTool(
+    "getNpmPackageVisibility",
+    {
+      description:
+        "Get npm package visibility. Requires an npm token with access to the package.",
+      inputSchema: {
+        packageName: packageNameSchema,
+      },
+    },
+    async ({ packageName }) =>
+      createToolResult(
+        await withClient((client) => client.getPackageVisibility(packageName)),
+      ),
+  );
+
+  server.registerTool(
+    "setNpmPackageAccess",
+    {
+      description:
+        "Set npm package access and optional 2FA publishing policy. Requires explicit inputs and a token with package admin rights.",
+      inputSchema: {
+        packageName: packageNameSchema,
+        access: z.enum(["public", "private"]).default("public"),
+        publishRequiresTfa: z.boolean().optional(),
+        automationTokenOverridesTfa: z.boolean().optional(),
+      },
+    },
+    async (args) =>
+      createToolResult(
+        await withClient((client) => client.setPackageAccess(args)),
+      ),
+  );
+
+  server.registerTool(
+    "listNpmTokens",
+    {
+      description:
+        "List npm access tokens for the configured user. Token values are redacted by npm.",
+      inputSchema: {
+        page: z.number().int().min(0).optional(),
+        perPage: z.number().int().min(1).max(100).optional(),
+      },
+    },
+    async (args) =>
+      createToolResult(
+        await withClient((client) => client.listTokens(args ?? {})),
+      ),
+  );
+
+  server.registerTool(
+    "exchangeNpmOidcToken",
+    {
+      description:
+        "Exchange a supported CI OIDC id_token for a short-lived npm registry token for one package. Usually npm CLI handles this inside GitHub Actions.",
+      inputSchema: {
+        packageName: packageNameSchema,
+        oidcToken: z.string().min(1),
+      },
+    },
+    async (args) =>
+      createToolResult(
+        await withClient((client) => client.exchangeOidcToken(args)),
+      ),
+  );
+
+  server.registerTool(
+    "getNpmTrustedPublishers",
+    {
+      description:
+        "Get npm Trusted Publisher configurations for a package. Requires package write permission and usually npm 2FA OTP.",
+      inputSchema: {
+        packageName: packageNameSchema,
+        otp: z.string().optional(),
+      },
+    },
+    async (args) =>
+      createToolResult(
+        await withClient((client) => client.getTrustedPublishers(args)),
+      ),
+  );
+
+  server.registerTool(
+    "addNpmGitHubTrustedPublisher",
+    {
+      description:
+        "Add a GitHub Actions Trusted Publisher for an npm package. Requires package write permission and usually npm 2FA OTP.",
+      inputSchema: {
+        packageName: packageNameSchema,
+        repository: z.string().min(1),
+        workflowFile: z.string().min(1).default("publish.yml"),
+        environment: z.string().optional(),
+        otp: z.string().optional(),
+      },
+    },
+    async (args) =>
+      createToolResult(
+        await withClient((client) => client.addGitHubTrustedPublisher(args)),
+      ),
+  );
+
+  server.registerTool(
+    "deleteNpmTrustedPublisher",
+    {
+      description:
+        "Delete a Trusted Publisher configuration by UUID. Requires package write permission and usually npm 2FA OTP.",
+      inputSchema: {
+        packageName: packageNameSchema,
+        configId: z.string().min(1),
+        otp: z.string().optional(),
+      },
+    },
+    async (args) =>
+      createToolResult(
+        await withClient((client) => client.deleteTrustedPublisher(args)),
+      ),
+  );
+
+  server.registerTool(
+    "publishNpmPackageDirectory",
+    {
+      description:
+        "Run npm publish for a local package directory. Defaults to dry-run. Real publishing requires confirm='publish <name>@<version>'. Prefer GitHub Actions Trusted Publishing.",
+      inputSchema: {
+        cwd: z.string().min(1).optional(),
+        tag: z.string().min(1).default("latest"),
+        access: z.enum(["public", "restricted"]).default("public"),
+        dryRun: z.boolean().default(true),
+        confirm: z.string().optional(),
+      },
+    },
+    async (args) =>
+      createToolResult(
+        await withClient((client) => client.publishPackageDirectory(args)),
+      ),
+  );
+
+  return server;
+};
+
+const argv = process.argv.slice(2);
+
+if (argv.includes("--help") || argv.includes("-h")) {
+  process.stdout.write(HELP_TEXT);
+  process.exit(0);
+}
+
+if (argv.includes("--auth-status")) {
+  process.stdout.write(`${JSON.stringify(getNpmAuthStatus(), null, 2)}\n`);
+  process.exit(0);
+}
+
+if (argv.includes("--connect")) {
+  process.stdout.write("Opening npm browser setup flow...\n");
+  const result = await runNpmBrowserAuthFlow({
+    onReady: ({ url }) => {
+      process.stdout.write(`npm setup URL: ${url}\n`);
+    },
+  });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  process.exit(0);
+}
+
+if (argv.includes("--test-connection")) {
+  const client = createNpmClient();
+  process.stdout.write(
+    `${JSON.stringify(
+      {
+        ok: true,
+        tokenSource: client.auth.source,
+        registry: client.registry,
+        user: await client.getCurrentUser(),
+      },
+      null,
+      2,
+    )}\n`,
+  );
+  process.exit(0);
+}
+
+const server = createServer();
+const transport = new StdioServerTransport();
+
+await server.connect(transport);