# 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
