##### 1) Install dependencies (if not already)
```
npm install # or: pnpm install / yarn install
```
##### 2) Build server (production)
```
npx nx build askme-server
```
##### 3) Build UI (production)
```
npx nx build askme-ui
```
MCP config
Your example config is correct for using the built server in stdio mode:
```jsonc
"ask-me-mcp": {
"command": "node",
"args": [
"C:/Temp/_Work/ask-me-mcp/dist/askme-server/main.js"
],
"disabled": false,
"disabledTools": [
"choose-next",
"challenge-hypothesis",
"ask-multiple-choice"
]
}
```
# 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
