# User Steps MCP Server

An MCP (Model Context Protocol) server that provides a `user_steps` tool for Claude. This tool allows the agent to present step-by-step checklists to users and automatically opens an interactive terminal UI for completion.

## Installation

### 1. Build the packages

```bash
cd user-steps-mcp
npm install
npm run build

cd cli
npm install
npm run build
```

### 2. Configure Claude Code

Add the MCP server to your Claude Code configuration. Choose one of these methods:

**Option A: Project-level config** (`.mcp.json` in your project root):

```json
{
  "mcpServers": {
    "user-steps": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/user-steps-mcp/dist/index.js"]
    }
  }
}
```

**Option B: Global config** (`~/.claude.json`):

```json
{
  "mcpServers": {
    "user-steps": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/user-steps-mcp/dist/index.js"]
    }
  }
}
```

**Option C: Via Claude CLI:**

```bash
claude mcp add user-steps node /path/to/user-steps-mcp/dist/index.js
```

### 3. Verify installation

```bash
claude mcp list
```

## Usage

When Claude needs the user to perform manual steps, it will call the `user_steps` tool, which **automatically opens a new terminal window** with an interactive checklist UI.

The tool blocks and waits until the user completes the steps or cancels the session.

### Companion CLI Controls

| Key | Action |
|-----|--------|
| ↑/↓ | Navigate steps |
| Space/Enter | Toggle step completion |
| s | Toggle skip step |
| f | Add feedback/notes to step |
| c | Cancel session |

## Tool Schema

### Input

```typescript
{
  title: string;           // Title for the step list (max 50 chars)
  description?: string;    // Context explaining why these steps are needed
  steps: [{
    id: string;            // Unique step identifier
    title: string;         // Step title (max 100 chars)
    description?: string;  // Detailed instructions
    type?: 'action' | 'verification' | 'acknowledgment' | 'confirmation';
    required?: boolean;    // Default: true
    dependsOn?: string[];  // Step IDs that must complete first
  }];
  allowPartialCompletion?: boolean;  // Default: false
  timeoutMs?: number;      // Timeout in milliseconds
}
```

### Output

```typescript
{
  sessionId: string;
  status: 'completed' | 'cancelled' | 'timeout' | 'partial';
  steps: [{
    id: string;
    status: 'pending' | 'completed' | 'skipped';
    completedAt?: string;
    notes?: string;
  }];
  completedCount: number;
  totalCount: number;
  startedAt: string;
  completedAt?: string;
}
```

## Example Tool Call

```json
{
  "title": "Deploy to Production",
  "description": "Complete these steps to deploy the new release",
  "steps": [
    {
      "id": "backup",
      "title": "Create database backup",
      "description": "Run: pg_dump -h localhost production > backup.sql",
      "type": "action"
    },
    {
      "id": "verify",
      "title": "Verify backup exists",
      "type": "verification",
      "dependsOn": ["backup"]
    },
    {
      "id": "deploy",
      "title": "Run deployment script",
      "description": "Execute: ./deploy.sh production",
      "type": "action",
      "dependsOn": ["verify"]
    }
  ]
}
```

## License

MIT