ls

Instructions

Implementation Reference

• src/index.ts:387-401 (handler)

  The async handler function that executes the 'ls' tool. It runs `npm ls --json` with optional parameters (package, depth, all, global, production) and returns the JSON output. It catches non-zero exit codes (expected when missing/extraneous packages exist) and returns stdout/stderr.

  async ({ path, package: pkg, depth, all, global: isGlobal, production }) => {
    const args = ["ls", "--json"];
    if (pkg) args.push(pkg);
    if (depth !== undefined) args.push("--depth", String(depth));
    if (all) args.push("--all");
    if (isGlobal) args.push("-g");
    if (production) args.push("--omit=dev");
    try {
      const { stdout } = await run(args, path);
      return { content: [{ type: "text", text: stdout }] };
    } catch (e: any) {
      // npm ls exits non-zero when there are missing/extraneous packages
      return { content: [{ type: "text", text: e.stdout || e.stderr || e.message }] };
    }
  },

• src/index.ts:379-386 (schema)

  Input schema for the 'ls' tool, defining Zod validations for path, package, depth, all, global, and production parameters.

  {
    path: z.string().describe("Absolute path to the package directory"),
    package: z.string().optional().describe("Specific package to look for"),
    depth: z.number().optional().describe("Dependency tree depth (default: 0)"),
    all: z.boolean().optional().describe("Show all packages, not just top-level"),
    global: z.boolean().optional().describe("List global packages"),
    production: z.boolean().optional().describe("Only show production dependencies"),
  },

• src/index.ts:376-402 (registration)

  Registration of the 'ls' tool on the main `server` object using `server.tool("ls", ...)`. This is the primary registration where the tool is added to the MCP server with its schema and handler.

  server.tool(
    "ls",
    "List installed packages in a project",
    {
      path: z.string().describe("Absolute path to the package directory"),
      package: z.string().optional().describe("Specific package to look for"),
      depth: z.number().optional().describe("Dependency tree depth (default: 0)"),
      all: z.boolean().optional().describe("Show all packages, not just top-level"),
      global: z.boolean().optional().describe("List global packages"),
      production: z.boolean().optional().describe("Only show production dependencies"),
    },
    async ({ path, package: pkg, depth, all, global: isGlobal, production }) => {
      const args = ["ls", "--json"];
      if (pkg) args.push(pkg);
      if (depth !== undefined) args.push("--depth", String(depth));
      if (all) args.push("--all");
      if (isGlobal) args.push("-g");
      if (production) args.push("--omit=dev");
      try {
        const { stdout } = await run(args, path);
        return { content: [{ type: "text", text: stdout }] };
      } catch (e: any) {
        // npm ls exits non-zero when there are missing/extraneous packages
        return { content: [{ type: "text", text: e.stdout || e.stderr || e.message }] };
      }
    },
  );

• src/index.ts:1277-1284 (registration)

  Sandbox registration of the 'ls' tool via `sandbox.tool("ls", ...)`. This is a secondary registration in the `createSandboxServer()` function, but uses a noop handler so it does not execute real logic.

  sandbox.tool("ls", "List installed packages in a project", {
    path: z.string().describe("Absolute path to the package directory"),
    package: z.string().optional().describe("Specific package to look for"),
    depth: z.number().optional().describe("Dependency tree depth"),
    all: z.boolean().optional().describe("Show all packages"),
    global: z.boolean().optional().describe("List global packages"),
    production: z.boolean().optional().describe("Only show production dependencies"),
  }, noop);

• src/index.ts:26-38 (helper)

  The `run()` helper function used by the 'ls' handler. It executes the npm CLI via `execFile`, adding npmrc args for authentication and setting a 10MB buffer and 120s timeout.

  async function run(
    args: string[],
    cwd?: string,
  ): Promise<{ stdout: string; stderr: string }> {
    const fullArgs = [...args, ...npmrcArgs];
    const opts: { cwd?: string; timeout: number; env: NodeJS.ProcessEnv; maxBuffer: number } = {
      timeout: 120_000,
      maxBuffer: 10 * 1024 * 1024, // 10MB buffer for large outputs
      env: { ...process.env, NO_COLOR: "1" },
    };
    if (cwd) opts.cwd = cwd;
    return exec(NPM, fullArgs, opts);
  }