@niroai/mcp-server

Niro MCP Server — connects AI coding assistants to Niro code intelligence via the Model Context Protocol.

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:

npx @niroai/mcp-server --setup

This will:

1. Prompt for your Niro API key (from console.niroai.dev > Settings)
2. Configure your chosen client—including ~/.cursor/mcp.json + MCP allowlists (~/.cursor/permissions.json) when you choose Cursor

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_API_URL | No | API base URL (default: https://api.niroai.dev) |

Default project selection: The bridge walks up from the current working directory looking for a .niro-project file. The first non-comment line of that file is used as the project_id. Commit one in each repository so the correct Niro project is selected when the MCP process runs from that tree — one API key, many repos.

When no .niro-project file is found, the server runs in multi-project mode. The assistant must call list_projects and pass project_id on every tool call; the npm bridge injects project_id automatically when a default is resolved from .niro-project (see injectProjectId in index.js).

Claude Code

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

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

Cursor

Composer and the built-in MCP client load ~/.cursor/mcp.json (Linux/macOS) or %USERPROFILE%\.cursor\mcp.json on Windows. This is not the legacy Cline extension file under globalStorage/saoudrizwan.claude-dev/.

Interactive setup configures Cursor end-to-end (including MCP auto-run allowlists where safe):

npx @niroai/mcp-server --setup --client cursor

For Docker / local ai-assistant, pick the Docker Compose URL during setup or export NIRO_API_URL=http://localhost:8098 first.

Manual ~/.cursor/mcp.json

Merge this under a top-level mcpServers object:

{
  "mcpServers": {
    "niro": {
      "command": "npx",
      "args": ["-y", "@niroai/mcp-server"],
      "transport": "stdio",
      "env": {
        "NIRO_API_KEY": "your-api-key",
        "NIRO_API_URL": "https://api.niroai.dev"
      }
    }
  }
}

Self-hosted deployments should set "NIRO_API_URL" (for example "http://localhost:8098").

Skipping per-tool MCP approval

Cursor honours ~/.cursor/permissions.json: entries in mcpAllowlist use server:tool syntax; the server name must match your mcp.json key ("niro"). The setup wizard tries to append "niro:*" automatically. Fully automatic runs also require Composer / Agent auto-run to be enabled (not “Ask every time”). Official reference: Cursor permissions.json.

If you edit by hand:

{
  "mcpAllowlist": ["niro:*"]
}

When you introduce mcpAllowlist manually, Cursor replaces the in-app MCP allowlist with that array—combine entries for all MCP servers you use (for example "niro:*", "github:*").

Cursor Settings › MCP / Tools edits the same ~/.cursor/mcp.json; the wizard writes that file directly so installs work even when extensions differ.

Windsurf

Add to ~/.codeium/windsurf/mcp_config.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:

{
  "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:

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

Multi-Project Mode

When no .niro-project file is found, the AI assistant discovers projects via list_projects and must pass project_id on every tool call.

Recommended on a machine with several repositories: drop a .niro-project file at each repo root — a single line with the project_id from console.niroai.dev:

# ~/projects/github/my-repo/.niro-project
<project_id-from-console>

Lines starting with # are treated as comments. The bridge walks upward from the MCP working directory (usually the IDE workspace) until it finds the file, then injects that project_id into every tools/call.

If one repo belongs to multiple Niro projects, either omit the file (multi-project mode, LLM passes project_id per call) or place .niro-project files in sub-paths that map cleanly to a single project.

Available Tools

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

| Tool | Description | |------|-------------| | list_projects | List available projects | | get_index_status | Indexing/analysis state and graph stats for a project | | code_grep | Regex / literal search inside source file contents | | explain_code | AI-generated documentation for a class, method, or file | | resolve_fqn | Disambiguate a short name to a fully-qualified name | | get_class_structure | Class members (fields, methods, inheritance, annotations) | | get_source_code | Retrieve source code by FQN (supports batching) | | get_impact_analysis | What breaks if X changes — upstream callers (most impact questions) | | get_blast_radius | Full ripple effect — upstream callers and downstream callees | | get_reverse_call_chain | Who calls X (callers of a method, class, or HTTP path) | | get_call_chain | What does X call (callees) | | trace_execution_path | Complete ordered execution path from A to B in one call | | find_api_endpoints | Declared / exposed HTTP endpoints for a service | | find_outbound_http_calls | Outgoing HTTP calls a service makes to other services | | find_handler | Find the handler for a given HTTP call or event | | list_events | Catalogue of EVENT nodes with producer / handler counts | | get_event_producers_and_handlers | Methods that trigger vs consume a given event | | find_orphaned_events | Events with no handler, or handlers with no producer | | list_data_resources | Catalogue of external data stores (DB tables, collections, topics) | | get_data_resource_usage | Methods that read / write / delete a given data resource | | get_config_symbols | Environment variables and config properties | | find_known_issues | Pre-detected bugs, concerns, and issues across the project |

License

MIT

Publishing Updates to npm

This package is published to npm as @niroai/mcp-server.

Prerequisites

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

   npm login

2. Verify you are logged in and have access:

   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:

   # 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:

   git add -A
   git commit -m "Release vX.Y.Z"
   git push origin main

4. Publish to npm:

   npm publish --access public

   The --access public flag is required for scoped packages (@niroai/*).

5. Verify the published version:

   npm view @niroai/mcp-server version

Quick One-Liner (after code changes are ready)

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