nrf-mcp

Instructions

Implementation Reference

• src/index.ts:168-204 (handler)

  The handler function for nrf_read tool that fetches file contents from GitHub API. It validates the path, checks if it's a file vs directory, enforces size limits (500KB max), decodes base64 content, and returns the file text.

  if (name === "nrf_read") {
    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) as {
      type?: string;
      size?: number;
      content?: string;
      encoding?: string;
    };
  
    if (Array.isArray(data)) {
      return {
        content: [{ type: "text", text: `'${path}' is a directory. Use nrf_list to browse it.` }],
      };
    }
  
    const size = data.size ?? 0;
    if (size > 500_000) {
      return {
        content: [{
          type: "text",
          text: `File is too large to read directly (${(size / 1024).toFixed(0)} KB). Consider browsing the directory and reading specific source files.`,
        }],
      };
    }
  
    if (!data.content) {
      return {
        content: [{ type: "text", text: `No text content available for '${path}' (may be a binary file).` }],
      };
    }
  
    const content = Buffer.from(data.content, "base64").toString("utf-8");
    return {
      content: [{ type: "text", text: content }],
    };
  }

• src/index.ts:95-104 (schema)

  Input schema definition for nrf_read tool specifying the required 'path' parameter (string) for the file path within the nRF Connect SDK repo.

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

• src/index.ts:84-105 (registration)

  Registration of nrf_read tool in the TOOLS array with name, description (including usage examples and supported file types), and inputSchema.

    {
      name: "nrf_read",
      description: `Read the contents of a file from the nRF Connect SDK repo (nrfconnect/sdk-nrf @ ${REF}).
  
  Works for any text file: .rst documentation, .c/.h source, CMakeLists.txt, Kconfig, prj.conf, .yaml, README.rst, etc.
  
  Use nrf_list to discover paths first. Examples:
  - "samples/bluetooth/central_bas/README.rst"
  - "samples/bluetooth/central_bas/src/main.c"
  - "samples/bluetooth/central_bas/CMakeLists.txt"
  - "samples/bluetooth/central_bas/prj.conf"`,
      inputSchema: {
        type: "object",
        properties: {
          path: {
            type: "string",
            description: "File path within the repo (e.g. 'samples/bluetooth/peripheral_hr/src/main.c')",
          },
        },
        required: ["path"],
      },
    },

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

  Helper function githubGet() that makes authenticated HTTP GET requests to GitHub API with proper headers and error handling for rate limits.

  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)

  Helper function encodePath() that encodes each path segment individually while preserving slashes for GitHub API URLs.

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