Ping Principal MCP

An MCP server that allows AI agents to ask questions to humans via native macOS dialogs. Stop AI hallucination by giving your AI an escape route when it needs human input!

Why This Exists

Ever had an AI confidently give you the wrong API endpoint? Or make assumptions that break your code? This tool gives AI agents a way to ask questions directly through macOS native dialogs instead of hallucinating answers.

Before: AI guesses and gets it wrong
After: AI asks via a nice dialog: "Which database should I use for this project?"

Features

• Native macOS Dialogs - No files, no fuss, just clean system dialogs
• Multiple Dialog Types - Text input, multiple choice, yes/no, info, notifications
• Zero Configuration - Works out of the box with npx
• MCP Standard - Compatible with Claude Desktop, Cursor, and other MCP clients
• Timeout Handling - Dialogs don't hang forever
• macOS Only - Uses native AppleScript for authentic system integration

Installation & Usage

Quick Start

npx ping-principal-mcp

That's it! The server starts and waits for MCP connections.

MCP Client Configuration

Claude Desktop

Add to ~/.claude_desktop_config.json:

{
  "mcpServers": {
    "ping-principal": {
      "command": "npx",
      "args": ["ping-principal-mcp"]
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "ping-principal": {
      "command": "npx", 
      "args": ["ping-principal-mcp"]
    }
  }
}

Dialog Types

Text Input

Ask open-ended questions with text responses:

await ask_human({
  type: "text",
  question: "What's the database connection string?",
  context: "Setting up production environment",
  defaultValue: "postgresql://localhost:5432/mydb"
});

Multiple Choice

Present options for the human to choose from:

await ask_human({
  type: "choice", 
  question: "Which authentication method should I implement?",
  choices: ["OAuth2", "JWT", "Session-based", "API Keys"],
  context: "Building user authentication system"
});

Yes/No Confirmation

Get confirmation before taking actions:

await ask_human({
  type: "confirm",
  question: "Should I delete the old migration files?",
  context: "Database cleanup process",
  defaultAnswer: false
});

Information Display

Show information that needs acknowledgment:

await ask_human({
  type: "info",
  question: "Migration completed successfully! 47 records updated.",
  context: "Database migration finished"
});

Notifications

Send system notifications:

await notify_human({
  message: "Build completed successfully",
  title: "Development Server",
  subtitle: "Ready for testing",
  sound: true
});

CLI Options

npx ping-principal-mcp [OPTIONS]

OPTIONS:
  -h, --help           Show help message
  -v, --version        Show version number  
  -t, --timeout SEC    Set dialog timeout in seconds (default: 300)
  -p, --port PORT      Run in HTTP mode (not yet implemented)
  -H, --host HOST      Host for HTTP mode (not yet implemented)

Examples

Development Workflow

# Start the MCP server
npx ping-principal-mcp

# Now your AI can ask questions like:
# "Should I use TypeScript strict mode for this project?"
# "What's the API endpoint for user authentication?"  
# "Should I add error handling for this edge case?"

With Custom Timeout

npx ping-principal-mcp --timeout 600  # 10 minute timeout

How It Works

1. AI gets stuck → calls ask_human() tool
2. Native dialog appears → clean macOS system dialog
3. Human responds → types answer or makes selection
4. AI continues → uses the human response to proceed

No files to manage, no polling, no complexity. Just direct human-AI communication through the OS.

Requirements

• macOS only (uses AppleScript for native dialogs)
• Node.js 18+
• MCP client (Claude Desktop, Cursor, etc.)

Dialog Timeout

Dialogs automatically timeout after 5 minutes (300 seconds) by default. You can customize this:

• Per dialog: Set timeout parameter in tool calls
• Globally: Use --timeout CLI option
• Result: Timed out dialogs return a cancellation response

Error Handling

• User cancels: Returns cancellation status instead of error
• Timeout: Graceful timeout with clear messaging
• AppleScript errors: Proper error reporting to AI
• Invalid input: Validation and sanitization

Development

From Source

git clone https://github.com/willwillems/ping-principal-mcp.git
cd ping-principal-mcp
npm install
npm run build
npm start

Project Structure

ping-principal-mcp/
├── src/
│   ├── index.ts          # CLI and main entry
│   ├── server.ts         # MCP server implementation  
│   ├── dialogs.ts        # Dialog manager & AppleScript
│   └── types.ts          # TypeScript interfaces
├── dist/                 # Compiled JavaScript
└── package.json

Building

npm run build    # Compile TypeScript
npm run dev      # Watch mode

Troubleshooting

"Permission denied" or dialogs not showing

• Check macOS privacy settings
• Grant terminal access to display dialogs
• Try running from Terminal.app vs integrated terminals

"Module not found" errors

• Make sure you're on macOS
• Check Node.js version (needs 18+)
• Try npm install in the project directory

MCP client not connecting

• Verify the configuration file syntax
• Check that the file path is correct
• Restart your MCP client after configuration changes

Contributing

Contributions welcome! Please feel free to submit issues and pull requests.

License

MIT - see LICENSE file for details.

Stop AI hallucination. Start AI collaboration.