# Nexus MCP Server

MCP (Model Context Protocol) server for [Nexus](https://nexus.app) - AI-assisted Project Delivery Platform.

This allows Claude Code and other MCP-compatible AI assistants to interact with your Nexus projects, bugs, milestones, and concepts.

## Installation

```bash
npm install -g @nexus/mcp-server
```

Or use directly with npx:

```bash
npx @nexus/mcp-server
```

## Authentication

### Option 1: Browser Login (Recommended)

```bash
nexus-mcp login
```

This opens your browser to authenticate with Nexus and automatically saves your API key.

### Option 2: Manual API Key

Generate an API key from Nexus Settings, then:

```bash
nexus-mcp auth --key nxk_your_api_key_here
```

### Option 3: Environment Variable

```bash
export NEXUS_API_KEY=nxk_your_api_key_here
```

## Usage with Claude Code

Add the Nexus MCP server to Claude Code:

```bash
claude mcp add nexus -- npx @nexus/mcp-server
```

Or with a local installation:

```bash
claude mcp add nexus -- nexus-mcp serve
```

## Available Tools

### Projects

| Tool | Description |
|------|-------------|
| `nexus_list_projects` | List all projects with optional status filtering |
| `nexus_get_project` | Get detailed project information |
| `nexus_create_project` | Create a new project (with optional screenshot) |
| `nexus_update_project` | Update project details and test credentials |
| `nexus_update_project_status` | Change project status |

### Bugs/Cards

| Tool | Description |
|------|-------------|
| `nexus_list_bugs` | Get all bugs for a project |
| `nexus_create_bug` | Create a new bug with severity, steps, etc. |
| `nexus_update_card` | Update card status, priority, assignee |
| `nexus_add_comment` | Add a comment to a card |

### Templates

| Tool | Description |
|------|-------------|
| `nexus_list_templates` | List available project templates |
| `nexus_create_template` | Create a new template |

### Milestones

| Tool | Description |
|------|-------------|
| `nexus_list_milestones` | List milestones with date filtering |
| `nexus_create_milestone` | Create a milestone with tasks |
| `nexus_update_milestone` | Update milestone details |
| `nexus_update_milestone_task` | Toggle task completion |

### Concepts

| Tool | Description |
|------|-------------|
| `nexus_list_concepts` | List product concepts |
| `nexus_get_concept` | Get concept details with PRD |
| `nexus_create_concept` | Create a new concept |
| `nexus_update_concept` | Update concept or PRD |
| `nexus_promote_concept` | Promote concept to project |

## Examples

### List open bugs

```
User: What bugs are open on the wellness-app project?
Claude: [Uses nexus_list_bugs tool]
```

### Create a critical bug

```
User: Create a critical bug for wellness-app: checkout button doesn't work on mobile
Claude: [Uses nexus_create_bug with severity="CRITICAL"]
```

### Update project status

```
User: Move wellness-app to QA
Claude: [Uses nexus_update_project_status with status="IN_QA"]
```

### Add test credentials

```
User: Update test credentials for wellness-app with username: test@example.com, password: Test123!
Claude: [Uses nexus_update_project with testCredentials]
```

### Create a launch milestone

```
User: Create a launch milestone for wellness-app on January 15th
Claude: [Uses nexus_create_milestone with type="LAUNCH"]
```

## CLI Commands

```bash
# Authentication
nexus-mcp login              # Browser-based login
nexus-mcp auth --key <key>   # Set API key manually
nexus-mcp status             # Check auth status
nexus-mcp logout             # Remove credentials

# Configuration
nexus-mcp config             # Show current config
nexus-mcp config --url <url> # Set custom API URL

# Server
nexus-mcp serve              # Start MCP server (default)
```

## Configuration

Configuration is stored in `~/.nexus-mcp/config.json`:

```json
{
  "apiKey": "nxk_...",
  "baseUrl": "https://nexus.app",
  "orgId": "optional-default-org"
}
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `NEXUS_API_KEY` | API key (overrides config file) |
| `NEXUS_API_URL` | API base URL (overrides config file) |

## Development

```bash
# Clone the repo
git clone https://github.com/your-org/nexus-mcp.git
cd nexus-mcp

# Install dependencies
npm install

# Build
npm run build

# Run in development
npm run dev
```

## License

MIT