npm package: @niroai/mcp-server
Description: Niro MCP Server — code intelligence for AI coding assistants
Author: Niro AI
Latest version: 1.3.0

# @niroai/mcp-server

Niro MCP Server — connects AI coding assistants to [Niro](https://niroai.dev) code intelligence via the [Model Context Protocol](https://modelcontextprotocol.io/).

Works with Claude Code, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.

## Quick Setup

The interactive setup wizard configures everything for your preferred client:

```bash
npx @niroai/mcp-server --setup
```

This will:
1. Prompt for your Niro API key (from [console.niroai.dev](https://console.niroai.dev) > Settings)
2. Configure the MCP server for your chosen client
3. Install the **niro-explorer** subagent (Claude Code only — enables cost-optimized processing)

## Manual Setup

If you prefer to configure manually, or the setup wizard doesn't cover your client:

### Environment Variables

| Variable              | Required | Description                                        |
|-----------------------|----------|----------------------------------------------------|
| `NIRO_API_KEY`        | Yes      | Your Niro API key (from console.niroai.dev)        |
| `NIRO_PROJECT_ID`     | No       | Default project ID (overrides repo-local files)    |
| `NIRO_PROJECT_ROOT`   | No       | Where to look for `.niro/project.json` / `.niro-project` (default: current working directory) |
| `NIRO_API_URL`        | No       | API base URL (default: `https://api.niroai.dev`)   |
| `NIRO_CLIENT_MODEL`   | No       | Hint logged by ai-assistant (e.g. `claude-haiku-4-5`); not used for auth |

**Default project without a global env:** If `NIRO_PROJECT_ID` is unset, the bridge walks up from `NIRO_PROJECT_ROOT` or `cwd` and uses the first of `.niro/project.json` (`"project_id": "…"`) or `.niro-project` (first non-comment line). Commit one of these in each repository so the correct Niro project is selected when Claude’s MCP process runs from that tree—**one API key, many repos**.

When no default is found, the server runs in **multi-project mode**. The assistant should use `list_projects` and pass `project_id` on tools; the npm bridge can inject `project_id` when a default is resolved (see `injectProjectId` in `index.js`).

### Claude Code

```bash
claude mcp add --scope user niro \
  -e NIRO_API_KEY=your-api-key \
  -- npx -y @niroai/mcp-server
```

### Claude Desktop

Add to your Claude Desktop config:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "niro": {
      "command": "npx",
      "args": ["-y", "@niroai/mcp-server"],
      "env": {
        "NIRO_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Cursor

Add to Cursor MCP settings (Settings > MCP Servers > Add):

```json
{
  "mcpServers": {
    "niro": {
      "command": "npx",
      "args": ["-y", "@niroai/mcp-server"],
      "env": {
        "NIRO_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "niro": {
      "command": "npx",
      "args": ["-y", "@niroai/mcp-server"],
      "env": {
        "NIRO_API_KEY": "your-api-key"
      }
    }
  }
}
```

### VS Code (Copilot MCP)

Add to `.vscode/mcp.json` or user settings:

```json
{
  "servers": {
    "niro": {
      "command": "npx",
      "args": ["-y", "@niroai/mcp-server"],
      "env": {
        "NIRO_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Other MCP Clients

The server uses stdio transport. Configure your client to run:

```bash
NIRO_API_KEY=your-api-key npx -y @niroai/mcp-server
```

## Multi-Project Mode

When no default `project_id` is resolved (no env, no `.niro` files), the AI assistant discovers projects via `list_projects`. That works but relies on the model passing `project_id` on every tool call.

**Recommended on a machine with several repositories:** add a small file to each repo root (or set `NIRO_PROJECT_ID` only in that repo’s MCP `env` if your client supports per-workspace config):

- `.niro/project.json`: `{ "project_id": "<uuid-from-console>" }`
- or `.niro-project`: a single line with the project UUID

The bridge walks upward from the MCP working directory (usually the IDE workspace) until it finds one of these files, then injects that `project_id` into `tools/call` the same way as `NIRO_PROJECT_ID`.

You can still override with `NIRO_PROJECT_ID` in the environment (highest priority) or point search with `NIRO_PROJECT_ROOT` if the client’s cwd is not the repo root.

## Subagent (Claude Code Only)

The setup wizard installs a **niro-explorer** subagent at `~/.claude/agents/niro-explorer.md`. This routes Niro tool processing through Claude Haiku for cost-optimized performance while keeping the main conversation on your selected model.

To install manually:

```bash
mkdir -p ~/.claude/agents
curl -o ~/.claude/agents/niro-explorer.md \
  https://raw.githubusercontent.com/niroai/mcp-server/main/agents/niro-explorer.md
```

## Available Tools

Once connected, your AI assistant has access to these Niro tools:

| Tool | Description |
|------|-------------|
| `list_projects` | Discover available projects |
| `smart_search` | Semantic + structural code search |
| `get_source_code` | Retrieve source code by FQN |
| `get_class_structure` | Fields, methods, inheritance, annotations |
| `get_call_chain` | Trace callers/callees through the graph |
| `get_bigger_picture` | Architectural context for an entity |
| `get_entity_doc` | LLM-generated documentation |
| `search_docs` | Search across documentation |
| `code_grep` | Regex search across indexed files |
| `find_http_endpoints` | Find REST endpoints by path/method |
| `get_declared_endpoints` | List endpoints for a class/module |
| `get_event_producers_and_handlers` | Event/message flow tracing |
| `get_config_symbols` | Configuration keys and usage |
| `get_system_entities` | Top-level entities (services, modules) |
| `resolve_fqn` | Resolve short names to FQNs |
| `get_entity_issues` | Known issues/warnings |
| `get_index_status` | Check project indexing status |
| `get_project_metadata` | Project stats and metadata |

## License

MIT

---

## Publishing Updates to npm

This package is published to npm as [`@niroai/mcp-server`](https://www.npmjs.com/package/@niroai/mcp-server).

### Prerequisites

1. You must be logged in to npm with an account that has publish access to the `@niroai` scope:
   ```bash
   npm login
   ```

2. Verify you are logged in and have access:
   ```bash
   npm whoami
   npm access list packages @niroai
   ```

### Steps to Publish an Update

1. **Make your code changes** and test them locally.

2. **Bump the version** in `package.json` using semantic versioning:
   ```bash
   # Patch release (bug fixes): 1.0.1 -> 1.0.2
   npm version patch

   # Minor release (new features, backward compatible): 1.0.1 -> 1.1.0
   npm version minor

   # Major release (breaking changes): 1.0.1 -> 2.0.0
   npm version major
   ```

3. **Commit and push** your changes:
   ```bash
   git add -A
   git commit -m "Release vX.Y.Z"
   git push origin main
   ```

4. **Publish to npm**:
   ```bash
   npm publish --access public
   ```
   The `--access public` flag is required for scoped packages (`@niroai/*`).

5. **Verify** the published version:
   ```bash
   npm view @niroai/mcp-server version
   ```

### Quick One-Liner (after code changes are ready)

```bash
npm version patch && git push origin main && npm publish --access public
```