# nrf-mcp

MCP server for Nordic nRF Connect SDK development. Provides Claude with tools to browse documentation and sample code from the [nrfconnect/sdk-nrf](https://github.com/nrfconnect/sdk-nrf) repository.

## Tools

| Tool | Description |
|---|---|
| `nrf_list` | List files and directories at a given path (includes file sizes). Supports recursive tree view with `depth` (max 3) |
| `nrf_read` | Read a file's contents (`.rst` docs, `.c`/`.h` source, `CMakeLists.txt`, `prj.conf`, etc.). Supports `startLine`/`endLine` for partial reads. Large files (>500 KB) are streamed and auto-truncated |
| `nrf_search` | Search across the repo using GitHub code search with qualifier support. Returns context snippets and supports pagination |
| `nrf_diff` | Compare a file between two SDK versions (tags, branches, or SHAs). Returns a unified diff |
| `nrf_kconfig` | Look up a `CONFIG_*` symbol — finds its Kconfig definition, type, defaults, and dependencies |

### Search examples

```
# Find all uses of a symbol
DFU_TARGET_IMAGE_TYPE_ANY

# Search docs only
FOTA path:doc/nrf

# Search samples only
peripheral_hr path:samples

# Filter by file type
CONFIG_BT_PERIPHERAL extension:conf
bt_le_adv_start extension:c
```

### Recursive directory listing

Use `depth` to get a full project overview in one call:

```json
{ "path": "samples/bluetooth/central_bas", "depth": 2 }
```

### Reading specific line ranges

When working with large files, use `startLine` and `endLine` to read just the relevant section:

```json
{ "path": "samples/bluetooth/central_bas/src/main.c", "startLine": 1, "endLine": 50 }
```

### Paginating search results

Search returns up to 20 results per page. Use the `page` parameter to fetch more:

```json
{ "query": "bt_le_adv_start extension:c", "page": 2 }
```

### Comparing SDK versions

See what changed in a file between releases:

```json
{ "path": "samples/bluetooth/central_bas/src/main.c", "fromRef": "v3.0.0", "toRef": "v3.2.4" }
```

### Kconfig symbol lookup

Look up what a `prj.conf` option does:

```json
{ "symbol": "CONFIG_BT_PERIPHERAL" }
```

## Setup

### Prerequisites

- Node.js 18+
- [GitHub CLI (`gh`)](https://cli.github.com/) authenticated — used to supply a GitHub token at runtime

### Install and build

```bash
npm install
npm run build
```

### Register with Claude Code

```bash
claude mcp add -s user nrf-mcp -- /path/to/nrf-mcp/run.sh
```

### Register with Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "nrf-mcp": {
      "command": "/path/to/nrf-mcp/run.sh",
      "args": []
    }
  }
}
```

Then restart Claude Desktop.

The `run.sh` wrapper fetches a fresh token from `gh auth token` each time the server starts, so no token is ever hardcoded.

### Configuration

| Variable | Default | Description |
|---|---|---|
| `NRF_SDK_REF` | `main` (set via `nrfSdkRef` in `package.json`) | SDK version to target — any git ref (tag, branch, commit SHA) |
| `GITHUB_TOKEN` | *(from `gh auth token`)* | GitHub API token; set explicitly to bypass the `gh` CLI |

To target a different SDK version, set the env var in the MCP registration:

```bash
claude mcp remove nrf-mcp
claude mcp add -s user -e NRF_SDK_REF=v3.2.4 nrf-mcp -- /path/to/nrf-mcp/run.sh
```

### Rebuild after changes

```bash
npm run build
```

During development, use `npm run watch` to recompile automatically on save.

## Testing

Run the end-to-end test suite (requires `gh` to be authenticated):

```bash
npm test
```

The tests spawn the server via `run.sh`, exercise all five tools (including recursive listing, line ranges, pagination, snippets, diff, Kconfig lookup, and error handling), and validate input error handling.

## Troubleshooting

**`gh: command not found` or empty token**
The `run.sh` script fetches a token via `gh auth token`. Make sure the GitHub CLI is installed and you are logged in:
```bash
gh auth login
gh auth token   # should print a token
```

**`GitHub API 401` errors**
`nrf_search` requires authentication. If the token is missing or expired, re-authenticate with `gh auth login`. For Claude Desktop, ensure `run.sh` is executable (`chmod +x run.sh`) — it prepends the Homebrew bin path to find `gh`.

**`GitHub rate limit exceeded`**
Unauthenticated requests are limited to 60/hour. With a valid `GITHUB_TOKEN` the limit is 5 000/hour. The server automatically retries on rate-limit errors with backoff (up to 30s). Ensure `gh auth token` returns a token and that `run.sh` is being used (not `node dist/index.js` directly).

**Tools not appearing in Claude**
- *Claude Code:* run `claude mcp list` to confirm `nrf-mcp` is registered, then restart the session.
- *Claude Desktop:* restart the app after editing `claude_desktop_config.json`. Check the Desktop developer console for MCP startup errors.

**Stale results**
Directory listings and file contents are cached in memory for 5 minutes to reduce API calls. Restart the server to clear the cache.

**Wrong SDK version**
Confirm the active ref with `echo $NRF_SDK_REF` in the same shell, or check what's registered:
```bash
claude mcp list   # shows the -e env vars set at registration time
```
To change it, remove and re-add the registration with the new `-e NRF_SDK_REF=` value.