nrf_list

Instructions

Implementation Reference

• src/index.ts:144-166 (handler)

  Handler function for nrf_list tool - fetches directory contents from GitHub API, sorts directories first then files, and returns formatted listing

  if (name === "nrf_list") {
    const path = (args as { path: string }).path.replace(/^\/+|\/+$/g, "");
    const url = `${BASE_URL}/repos/${REPO}/contents/${encodePath(path)}?ref=${REF}`;
    const data = await githubGet(url);
  
    if (!Array.isArray(data)) {
      return {
        content: [{ type: "text", text: `'${path}' is a file, not a directory. Use nrf_read to read it.` }],
      };
    }
  
    const items = (data as Array<{ name: string; path: string; type: string }>)
      .sort((a, b) => {
        if (a.type === b.type) return a.name.localeCompare(b.name);
        return a.type === "dir" ? -1 : 1;
      })
      .map((item) => `${item.type === "dir" ? "[dir] " : "[file]"} ${item.path}`)
      .join("\n");
  
    return {
      content: [{ type: "text", text: items || "Empty directory" }],
    };
  }

• src/index.ts:54-83 (registration)

  Tool registration including name 'nrf_list', description with useful starting paths, and inputSchema defining 'path' parameter

  const TOOLS: Tool[] = [
    {
      name: "nrf_list",
      description: `List the contents of a directory in the nRF Connect SDK repo (nrfconnect/sdk-nrf @ ${REF}).
  
  Useful starting paths:
  - "doc/nrf"                    → Documentation root (RST files)
  - "doc/nrf/protocols"          → Bluetooth, LTE, Thread, Zigbee docs
  - "doc/nrf/libraries"          → Library reference docs
  - "doc/nrf/applications"       → Application-level docs
  - "samples"                    → All sample projects
  - "samples/bluetooth"          → Bluetooth LE samples
  - "samples/cellular"           → LTE/cellular modem samples
  - "samples/matter"             → Matter protocol samples
  - "samples/nfc"                → NFC samples
  - "samples/tfm"                → Trusted Firmware-M samples
  - "samples/crypto"             → Cryptography samples
  
  Returns dirs first, then files, with full paths you can pass to nrf_read.`,
      inputSchema: {
        type: "object",
        properties: {
          path: {
            type: "string",
            description: "Directory path within the repo (e.g. 'samples/bluetooth')",
          },
        },
        required: ["path"],
      },
    },

• src/index.ts:73-82 (schema)

  Input schema for nrf_list defining 'path' as required string parameter for directory path within repo

  inputSchema: {
    type: "object",
    properties: {
      path: {
        type: "string",
        description: "Directory path within the repo (e.g. 'samples/bluetooth')",
      },
    },
    required: ["path"],
  },

• src/index.ts:33-47 (helper)

  githubGet helper function that makes authenticated requests to GitHub API with rate limit handling

  async function githubGet(url: string): Promise<unknown> {
    const response = await fetch(url, { headers: githubHeaders() });
    if (!response.ok) {
      const body = await response.text();
      // Surface rate limit info if that's the issue
      const remaining = response.headers.get("x-ratelimit-remaining");
      const reset = response.headers.get("x-ratelimit-reset");
      if (response.status === 403 && remaining === "0" && reset) {
        const resetTime = new Date(parseInt(reset) * 1000).toISOString();
        throw new Error(`GitHub rate limit exceeded. Resets at ${resetTime}. Set GITHUB_TOKEN for higher limits.`);
      }
      throw new Error(`GitHub API ${response.status}: ${body}`);
    }
    return response.json();
  }

• src/index.ts:49-52 (helper)

  encodePath helper function that encodes each path segment individually while preserving slashes

  function encodePath(path: string): string {
    // Encode each path segment individually, preserving slashes
    return path.split("/").map(encodeURIComponent).join("/");
  }