AskMeMCP

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview AskMeMCP is a Human-in-the-Loop MCP (Model Context Protocol) Server implemented as an Nx monorepo. It bridges automation systems with human decision-making through a web interface, allowing MCP clients to request human input via the `ask-one-question` and `ask-multiple-choice` tools. ### Key Components: - **askme-ui**: Angular 20+ frontend with reactive UI for displaying and responding to MCP requests - **askme-server**: stdio MCP server with embedded HTTP bridge for browser UI communication - **askme-shared**: Shared TypeScript types for MCP communication between frontend and backend ## Claude Code Configuration To use Ask-Me MCP with Claude Code, add this to your Claude configuration: ```json { "mcpServers": { "ask-me": { "command": "/full/path/to/AskMeMCP/run-stdio-server.sh" } } } ``` Or if you prefer to use node directly: ```json { "mcpServers": { "ask-me": { "command": "node", "args": ["/full/path/to/AskMeMCP/dist/askme-server/main.js"] } } } ``` Or with a custom port for the browser bridge: ```json { "mcpServers": { "ask-me": { "command": "node", "args": ["/full/path/to/AskMeMCP/dist/askme-server/main.js", "--port", "4711"] } } } ``` **Prerequisites:** 1. Build the server: `npx nx build askme-server` 2. Start the web UI: `npx nx serve askme-ui` 3. Use the full absolute path in the configuration ## Server CLI Options The MCP server supports the following command line options: ```bash # Use default port 3000 node dist/askme-server/main.js # Use custom port node dist/askme-server/main.js --port 4711 node dist/askme-server/main.js -p 8080 # Show help node dist/askme-server/main.js --help node dist/askme-server/main.js -h ``` **Port Configuration:** - **Default**: 3000 (browser bridge HTTP server) - **Range**: 1-65535 - **Purpose**: Avoids port conflicts during testing or when running multiple instances - **MCP Transport**: Always uses stdio (port only affects browser bridge) ## Essential Commands All commands use Nx and follow the pattern `npx nx <target> <project>` ### Development ```bash # Serve applications (with hot reload) npx nx serve askme-ui # Frontend on http://localhost:4200 npx nx serve askme-server # stdio MCP server (for Claude Code) # Build for production npx nx build askme-ui npx nx build askme-server # Local installation testing (creates dist/install with bundled package) npm run install:local cd dist/install && npx ask-me-mcp ``` ### Testing ```bash # Unit tests npx nx test askme-ui npx nx test askme-server npx nx test askme-shared # Run all tests npx nx run-many --target=test --all # E2E tests npx nx e2e askme-ui-e2e # Playwright UI tests (development) npx nx run askme-ui-e2e:e2e-headless # Playwright UI tests (CI-friendly) npx nx run askme-ui-e2e:e2e-ci # Playwright UI tests (full CI simulation) npx nx e2e askme-server-e2e # Jest MCP server integration tests # Run a single test file npx nx test askme-ui --testFile=app.spec.ts npx nx test askme-server --testFile=app.spec.ts # Run specific E2E test patterns npx nx e2e askme-ui-e2e --grep "Single Question Flow" npx nx e2e askme-ui-e2e --grep "Multiple Choice" ``` ### Code Quality ```bash # Lint npx nx lint askme-ui npx nx lint askme-server # Format code npx nx format ``` ### Nx-specific ```bash # View project dependency graph npx nx graph # Run commands only on affected projects npx nx affected:test npx nx affected:lint ``` ## Architecture ### Frontend (askme-ui) - **Framework**: Angular 20 with standalone components - **Entry**: `askme-ui/src/main.ts` - **Routing**: Configured in `askme-ui/src/app/app.routes.ts` - **Styling**: SCSS preprocessor - **Key files**: - `app.config.ts` - Application configuration (providers, routing) - `app.routes.ts` - Route definitions - `app.ts` - Root component - **Modern Angular Features**: - Use modern Angular 20+ features such as standalone and signals ### Backend (askme-server) - **Transport**: stdio (stdin/stdout) for MCP communication - **Entry**: `askme-server/src/main.ts` - **Modular Structure** (Restructured following MCP server patterns): - `main.ts` - Minimal entry point - `core/` - Core server functionality (server setup, browser bridge, request management) - `tools/` - Individual tool implementations (ask-one-question, ask-multiple-choice) - **Browser bridge port**: 3000 (for UI communication) - **Architecture Benefits**: Easy to maintain, test, and extend with new tools ### Shared Configuration - **TypeScript**: Base config in `tsconfig.base.json` - **Testing**: Jest configured via `jest.preset.js` - **Linting**: ESLint via `eslint.config.mjs` - **Formatting**: Prettier with single quotes (`.prettierrc`) ### Nx Workspace Features - **Caching**: Build outputs are cached automatically - **Task Pipeline**: Dependencies between projects are managed by Nx - **Affected Commands**: Only rebuild/retest what changed - **Plugin Architecture**: Angular and Node plugins provide executors and generators ## Development Guidelines - Always when you code keep the test <file>.spec.ts up to date, run the tests to check you implementation efforts ## Documentation Standards - Always document well in TSDoc - Add examples to the TSDoc - If necessary, add Mermaid diagrams to provide visual explanations of complex code structures or workflows ## Publishing to npm ### Package Configuration - **Published Package**: `ask-me-mcp` (single package, no separate types package) - **Package Structure**: Self-contained server with bundled Angular UI and TypeScript types - **Binary Command**: `ask-me-mcp` (global command after installation) ### Publishing Process ```bash # Build everything npm run build # Prepare package (copies UI bundle and package.json config) npm run prepublish:public # Publish to npm (remember to bump version first) npm run publish:public ``` ### Version Management - Edit `publish-configs/server-package.json` to bump version before publishing - Current published version structure: `1.0.x` ### Local Testing ```bash # Test exact npm package locally npm run install:local cd dist/install && npx ask-me-mcp ``` ## Known Issues and Solutions ### MCP stdio Protocol Issues - **Problem**: Console.error messages during startup interfere with stdio MCP protocol - **Solution**: All logging is now wrapped with `if (process.env.ASK_ME_MCP_DEBUG)` checks - **Debug Mode**: Set `ASK_ME_MCP_DEBUG=1` to enable verbose logging for troubleshooting ### Claude Code Connection Issues - **Symptoms**: "Connection closed" errors, MCP error -32000 - **Cause**: Server logging to stderr during startup confuses MCP stdio protocol - **Fix**: Implemented in v1.0.1 - logging only shows in debug mode - **CLI Command**: `claude mcp add ask-me npx --yes ask-me-mcp` ### TypeScript Import Resolution - When importing from `@ask-me-mcp/askme-shared` in the server, the build may fail with "Cannot find module" error - This is because the shared module needs to be built first and the import resolution can fail - Solution: Ensure shared module is built first, or use type assertions if needed ## MCP Protocol Implementation Details ### Server Architecture - Uses `@modelcontextprotocol/sdk` for MCP protocol implementation - Implements `StdioServerTransport` for direct stdin/stdout communication - Single 'demo' session for all stdio connections - FIFO queue processing for human requests - Embedded HTTP server for browser UI communication ### Key Server Components (Restructured) - **Main Server** (`askme-server/src/main.ts`): Minimal entry point that orchestrates core modules - **Core Modules** (`askme-server/src/core/`): - `server.ts`: MCP server setup and tool registration - `browser-bridge.ts`: HTTP/SSE communication with browser UI, automatic browser opening - `request-manager.ts`: Request lifecycle and storage management - **Tools** (`askme-server/src/tools/`): Individual tool implementations with clean separation - **Browser Bridge**: Minimal HTTP server on port 3000 for UI communication ### Automatic Browser Opening - **Cross-Platform Support**: Detects when UI is not connected and automatically opens browser - **Platform Commands**: macOS (`open`), Windows (`start`), Linux (`xdg-open`) - **Fallback Instructions**: Provides manual setup instructions if automatic opening fails - **UI Connection Detection**: Uses SSE connection count (`sseConnections.size`) to detect active UI - **Integration**: All tools (ask-one-question, ask-multiple-choice, challenge-hypothesis, choose-next) check UI availability before processing ### Frontend Architecture - Uses Angular signals for reactive state management - Real-time communication with backend via EventSource API - Browser notifications for new requests - **Blueprint Paper Background**: Authentic oldschool technical drawing aesthetic with millimeter grid - Component structure: - **RequestHandlerComponent**: Main container with direct request/response handling - **RequestDisplayComponent**: Shows human request details - **ResponseInputComponent**: Form for human responses with quick actions - **MultipleChoiceResponseComponent**: Enhanced with priority arrows and "why" fields - **HypothesisResponseComponent**: Agreement-based evaluation with emoji scale ### UI Enhancement Features - **Icon Button Design**: Small circular completion status buttons (✅ Done, 🔍 Drill Deeper) positioned between "Clear" and "Submit" - **Completion Status**: Three-state completion system (submit, done, drill-deeper) across all tool types - **Tool-Specific Drilling**: Drill deeper stays within the same tool type (ask-multiple-choice → ask-multiple-choice, etc.) - **Responsive Design**: CSS `.btn-icon` class with hover effects and proper spacing ### Testing Approach - Test-driven development with comprehensive test coverage - Mock EventSource and Notification APIs in tests - Angular component tests use TestBed with mocked services