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

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

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

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

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

Option C: Via Claude CLI:

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

3. Verify installation

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

{
  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

{
  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

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