docs_list_packages

Instructions

Implementation Reference

• src/tools.ts:30-47 (handler)

  The handler function for docs_list_packages. It maps over the cached scan results (PackageDocs[]) and returns a formatted list of package names, versions, sources, and file counts. Returns a text result with a line per package, plus structured JSON data.

  () => {
    const rows = cache.map((p) => ({
      name: p.name,
      version: p.version,
      source: p.source,
      fileCount: p.files.length,
    }));
    if (rows.length === 0) {
      return textResult(
        "No packages with docs found. Scan options: " + JSON.stringify(options),
        rows as unknown as JsonObject[],
      );
    }
    const lines = rows.map(
      (r) => `${r.name}@${r.version} (${r.source}) — ${r.fileCount} file${r.fileCount === 1 ? "" : "s"}`,
    );
    return textResult(lines.join("\n"), rows as unknown as JsonObject[]);
  },

• src/tools.ts:23-48 (registration)

  Registration of the docs_list_packages tool via server.registerTool(). Defines the tool name, description, empty input schema, and binds the handler.

  server.registerTool(
    {
      name: "docs_list_packages",
      description:
        "List every @particle-academy/* (and other scanned) package that has docs available, with name, version, source (node_modules vs workspace), and file count.",
      inputSchema: { type: "object", properties: {} },
    },
    () => {
      const rows = cache.map((p) => ({
        name: p.name,
        version: p.version,
        source: p.source,
        fileCount: p.files.length,
      }));
      if (rows.length === 0) {
        return textResult(
          "No packages with docs found. Scan options: " + JSON.stringify(options),
          rows as unknown as JsonObject[],
        );
      }
      const lines = rows.map(
        (r) => `${r.name}@${r.version} (${r.source}) — ${r.fileCount} file${r.fileCount === 1 ? "" : "s"}`,
      );
      return textResult(lines.join("\n"), rows as unknown as JsonObject[]);
    },
  );

• src/tools.ts:28-28 (schema)

  Input schema for docs_list_packages: an empty object with no properties, since this tool takes no arguments.

  inputSchema: { type: "object", properties: {} },

• src/tools.ts:15-21 (helper)

  The registerDocsTools function which creates the scan cache and registers all docs tools. The cache is created via scan() from src/scanner.ts and is used by the docs_list_packages handler.

  export function registerDocsTools(server: McpServer, options: ScanOptions = {}): void {
    let cache: PackageDocs[] = scan(options);
  
    const refresh = () => {
      cache = scan(options);
      return cache;
    };