# AskMeMCP - Human-in-the-Loop MCP Server

AskMeMCP is a Model Context Protocol (MCP) server that enables AI assistants to request human input through a web interface. It implements multiple interactive tools (`ask-one-question`, `ask-multiple-choice`, `challenge-hypothesis`, `choose-next`), allowing MCP clients like Claude Code to pause execution and wait for human responses.

## Features

- **stdio Transport**: Direct integration with Claude Code and other MCP clients
- **Self-Contained Server**: Serves Angular UI statically - no separate UI server needed
- **Dynamic Port Allocation**: Automatically finds available port if default is in use
- **Automatic Browser Opening**: Opens UI automatically when requests arrive
- **Real-time Updates**: Server-Sent Events for live communication
- **Multiple Tool Types**: Single questions, multiple choice, hypothesis challenges, and decision workflows

## Installation

### Option 1: Using npx (No Installation Required)

You can run Ask-Me MCP directly using npx without installing it globally:

```bash
npx ask-me-mcp
```

Note: The first time you run this, npx will ask for confirmation to install the package temporarily. To skip this confirmation, use:

```bash
npx --yes ask-me-mcp
```

### Option 2: Global Installation

```bash
npm install -g ask-me-mcp
ask-me-mcp
```

## Configuration for Different Clients

### Claude Desktop App

Add to your Claude configuration file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "ask-me": {
      "command": "npx",
      "args": ["--yes", "ask-me-mcp"]
    }
  }
}
```

### Claude Code

Using the CLI:
```bash
claude mcp add askme -- npx -y ask-me-mcp
```

Or manually add to your Claude Code configuration:
- **macOS**: `~/Library/Application Support/Claude/claude_code_config.json`
- **Windows**: `%APPDATA%\Claude\claude_code_config.json`
- **Linux**: `~/.config/Claude/claude_code_config.json`

```json
{
  "mcpServers": {
    "ask-me": {
      "command": "npx",
      "args": ["--yes", "ask-me-mcp"]
    }
  }
}
```

### Cursor

Add to your Cursor settings (in `.cursor/mcp_settings.json` in your project root):

```json
{
  "mcpServers": {
    "ask-me": {
      "command": "npx",
      "args": ["--yes", "ask-me-mcp"]
    }
  }
}
```

### VS Code with Continue or Similar Extensions

For VS Code extensions that support MCP, add to your extension's configuration:

```json
{
  "mcpServers": {
    "ask-me": {
      "command": "npx",
      "args": ["--yes", "ask-me-mcp"]
    }
  }
}
```

### Port Configuration

The server has two port behaviors:

1. **Auto-discovery (default)**: Finds available port starting from 3000
   ```bash
   npx --yes ask-me-mcp
   ```

2. **Fixed port**: Uses exact port specified with `--port` (fails if port is in use)
   ```bash
   npx --yes ask-me-mcp --port 8080
   ```

For Claude Code configuration with fixed port:

```json
{
  "mcpServers": {
    "ask-me": {
      "command": "npx",
      "args": ["--yes", "ask-me-mcp", "--port", "8080"]
    }
  }
}
```

### Option 3: Build from Source

```bash
# Clone the repository
git clone https://github.com/yourusername/AskMeMCP.git
cd AskMeMCP

# Install dependencies
npm install

# Build all projects
npm run build

# Configure Claude Code with full path
```

Add to your Claude Code configuration:

```json
{
  "mcpServers": {
    "ask-me": {
      "command": "node",
      "args": ["/full/path/to/AskMeMCP/dist/askme-server/main.js"]
    }
  }
}
```

## Usage

Once configured, you can use the available tools in Claude Code:

### ask-one-question Tool
```
Please use the ask-one-question tool to ask me what my favorite color is
```

### ask-multiple-choice Tool
```
Please use the ask-multiple-choice tool with these questions:
{
  "questions": [
    {
      "text": "Which deployment environments should we target?",
      "options": ["Development", "Staging", "Production"]
    },
    {
      "text": "Which features should be included in this release?",
      "options": ["User Authentication", "Dashboard Updates", "API Improvements", "Mobile Support"]
    }
  ]
}
```

All requests will appear in the web UI where you can provide responses. For multiple choice questions, you can select multiple options and add comments to each choice.

## Architecture

- **askme-server**: stdio MCP server with embedded HTTP bridge for browser communication
- **askme-ui**: Angular 20+ frontend with reactive UI using signals
- **askme-shared**: Shared TypeScript types for frontend-backend communication

## Development

```bash
# Run the UI in development mode
npx nx serve askme-ui

# Run the server in development mode
npx nx serve askme-server

# Run tests
npx nx test askme-ui
npx nx test askme-server

# Lint code
npx nx lint askme-ui
npx nx lint askme-server
```

## Troubleshooting

### Connection Issues with Claude Code

If you see "Connection failed" errors:

1. **Enable Debug Mode**: Run with debug logging to see what's happening:
   ```bash
   ASK_ME_MCP_DEBUG=1 claude --debug
   ```

2. **Check the Server**: Test if the server runs correctly:
   ```bash
   npx --yes ask-me-mcp --help
   ```

3. **Port Conflicts**: If port 3000 is in use, specify a different port:
   ```bash
   claude mcp add ask-me npx --yes ask-me-mcp --port 8080
   ```

4. **Manual Test**: Run the server directly to see any errors:
   ```bash
   npx --yes ask-me-mcp
   ```

### Common Issues

- **First Time Confirmation**: The first run of `npx ask-me-mcp` may ask for confirmation. Use `npx --yes` to skip this.
- **Port Already in Use**: The server automatically finds an available port, but you can specify one with `--port`
- **Browser Not Opening**: If the browser doesn't open automatically, manually navigate to the port shown in debug logs

## License

MIT