npm package: @orbiterdev/mcp-server
Description: MCP server for Orbiter Dev - Mobile approval for Claude Code
Author: Orbiter Dev
Latest version: 0.1.6

# Orbiter Dev MCP Server

> MCP server for Claude Code integration with Orbiter Dev

## Overview

This MCP (Model Context Protocol) server allows Claude Code to request
approvals from your mobile device via the Orbiter Dev app.

## Installation (Recommended: Zero-Install)

The recommended way to use the Orbiter Dev MCP server is via `npx` (Node Package Execute). This requires zero global installation and ensures you always run the latest version.

**Prerequisites:** 
- Node.js 18+ installed on your machine.

## Configuration

Add the following to your AI IDE's MCP settings (e.g., Cursor, Claude Code, or Antigravity):

```json
{
  "mcpServers": {
    "orbiter-dev": {
      "command": "npx",
      "args": ["-y", "@orbiterdev/mcp-server@latest"],
      "env": {
        "ORBITER_SERVER_URL": "https://api.orbiterdev.ai",
        "ORBITER_TOKEN": "<your-auth-token-from-app>"
      }
    }
  }
}
```

## Available Tools

### `request_approval`

Request approval from the user's mobile device before executing a
potentially risky operation.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action` | string | Yes | The action requiring approval |
| `description` | string | Yes | Human-readable description |
| `files` | string[] | No | List of affected files |
| `diffSummary` | string | No | Summary of code changes |
| `riskLevel` | enum | No | `low`, `medium`, `high`, `critical` |
| `workspaceName` | string | No | Current workspace name |

**Example:**

```typescript
// Claude Code will call this automatically when needed
request_approval({
  action: "deploy",
  description: "Deploy authentication changes to production",
  files: ["src/auth.ts", "src/middleware.ts"],
  riskLevel: "high"
})
```

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run in development
npm run dev

# Run tests
npm test
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `ORBITER_SERVER_URL` | API server URL (default: http://localhost:3000) |
| `ORBITER_TOKEN` | User Auth Token (required for `notify` command) |

## Policy Engine (Auto-Approval)

Create `orbiter.config.json` in your project root to auto-approve safe patterns:

```json
{
  "auto_approval": [
    { "pattern": "^test/", "description": "Auto-approve test files" },
    { "pattern": "console\\.log", "description": "Allow logging" }
  ]
}
```

## Async Hooks (Notifications)

You can use `orbiter notify` to send non-blocking notifications to your mobile device, useful for background tasks.

**Usage:**
```bash
export ORBITER_TOKEN="your-token"
npx @orbiterdev/mcp-server notify --event "Build Finished" --message "Success"
```

**Claude Code Hook Example** (`.claudecode.json`):
```json
{
  "hooks": {
    "PostToolUse": {
      "command": "npx @orbiterdev/mcp-server notify --event 'Tool Done' --message '{{tool_name}} completed'",
      "async": true
    }
  }
}
```

---

*Part of Orbiter Dev - Sprint 1*