@achieveai/hitl-mcp-server 1.0.0

package/dist/index.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { DialogManager } from './dialog-manager.js';
+import { v4 as uuidv4 } from 'uuid';
+const TOOL_NAME = 'ask_human';
+const SERVER_NAME = 'hitl-mcp-server';
+const SERVER_VERSION = '1.0.0';
+class HumanInTheLoopServer {
+    server;
+    dialogManager;
+    constructor() {
+        this.server = new Server({
+            name: SERVER_NAME,
+            version: SERVER_VERSION,
+        }, {
+            capabilities: {
+                tools: {},
+            },
+        });
+        this.dialogManager = new DialogManager();
+        this.setupHandlers();
+    }
+    setupHandlers() {
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+            tools: [
+                {
+                    name: TOOL_NAME,
+                    description: `CRITICAL: Use this tool when you need human guidance or decision-making. This tool is ESSENTIAL for:
+• Resolving ambiguities or unclear requirements
+• Making subjective decisions that require human judgment
+• Choosing between multiple valid approaches
+• Confirming critical actions before execution
+• Getting additional context or clarification
+• Handling edge cases not covered by your instructions
+
+This tool opens an interactive dialog box for the human to respond, ensuring you get the guidance needed to proceed correctly. The human can select from provided options or enter a custom response.
+
+IMPORTANT: Prefer using this tool over making assumptions or returning incomplete results. Getting human input ensures accuracy and alignment with user expectations.`,
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            question: {
+                                type: 'string',
+                                description: 'The question or decision you need help with. Be clear and specific.'
+                            },
+                            options: {
+                                type: 'array',
+                                description: 'Array of possible choices for the human to select from',
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        label: {
+                                            type: 'string',
+                                            description: 'Display label for this option'
+                                        },
+                                        value: {
+                                            type: 'string',
+                                            description: 'Value to return if this option is selected'
+                                        },
+                                        description: {
+                                            type: 'string',
+                                            description: 'Optional detailed description of what this option means'
+                                        }
+                                    },
+                                    required: ['label', 'value']
+                                },
+                                minItems: 1
+                            },
+                            allowMultiple: {
+                                type: 'boolean',
+                                description: 'Whether to allow selecting multiple options (checkbox vs radio)',
+                                default: false
+                            },
+                            allowOther: {
+                                type: 'boolean',
+                                description: 'Whether to show an "Other" text field for custom input',
+                                default: true
+                            },
+                            context: {
+                                type: 'string',
+                                description: 'Additional context to help the human understand the situation'
+                            },
+                            timeout: {
+                                type: 'number',
+                                description: 'Timeout in milliseconds (default: no timeout)',
+                                minimum: 1000,
+                                maximum: 3600000
+                            }
+                        },
+                        required: ['question', 'options']
+                    }
+                }
+            ]
+        }));
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            if (request.params.name !== TOOL_NAME) {
+                throw new McpError(ErrorCode.MethodNotFound, `Tool not found: ${request.params.name}`);
+            }
+            const args = request.params.arguments;
+            if (!args.question || !Array.isArray(args.options) || args.options.length === 0) {
+                throw new McpError(ErrorCode.InvalidParams, 'Missing required parameters: question and options array');
+            }
+            try {
+                const dialogOptions = args.options.map((opt) => ({
+                    label: opt.label || opt.value,
+                    value: opt.value,
+                    description: opt.description
+                }));
+                const response = await this.dialogManager.showDialog({
+                    id: uuidv4(),
+                    question: args.question,
+                    options: dialogOptions,
+                    allowMultiple: args.allowMultiple || false,
+                    allowOther: args.allowOther !== false,
+                    context: args.context,
+                    timeout: args.timeout
+                });
+                let result = {
+                    success: true,
+                    timestamp: response.timestamp
+                };
+                if (response.otherText === 'SKIPPED') {
+                    result.skipped = true;
+                    result.response = 'User skipped this question';
+                }
+                else if (response.otherText && response.otherText !== '') {
+                    result.response = response.otherText;
+                    result.responseType = 'custom';
+                }
+                else if (response.selectedValues.length > 0) {
+                    result.response = args.allowMultiple
+                        ? response.selectedValues
+                        : response.selectedValues[0];
+                    result.responseType = 'selection';
+                }
+                else {
+                    result.response = null;
+                    result.responseType = 'none';
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2)
+                        }
+                    ]
+                };
+            }
+            catch (error) {
+                console.error('Dialog error:', error);
+                if (error instanceof Error && error.message === 'Dialog timeout') {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    success: false,
+                                    error: 'timeout',
+                                    message: 'The user did not respond within the timeout period'
+                                }, null, 2)
+                            }
+                        ]
+                    };
+                }
+                throw new McpError(ErrorCode.InternalError, `Failed to show dialog: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            }
+        });
+    }
+    async run() {
+        const transport = new StdioServerTransport();
+        await this.dialogManager.initialize();
+        await this.server.connect(transport);
+        console.error(`${SERVER_NAME} v${SERVER_VERSION} running on stdio`);
+        process.on('SIGINT', async () => {
+            await this.cleanup();
+            process.exit(0);
+        });
+        process.on('SIGTERM', async () => {
+            await this.cleanup();
+            process.exit(0);
+        });
+    }
+    async cleanup() {
+        console.error('Shutting down...');
+        await this.dialogManager.close();
+    }
+}
+const server = new HumanInTheLoopServer();
+server.run().catch((error) => {
+    console.error('Server error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/test-client.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=test-client.d.ts.map

package/dist/test-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-client.d.ts","sourceRoot":"","sources":["../src/test-client.ts"],"names":[],"mappings":""}

package/dist/test-client.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import { DialogManager } from './dialog-manager.js';
+async function testDialogManager() {
+    console.log('Starting Dialog Manager Test...\n');
+    const manager = new DialogManager();
+    await manager.initialize();
+    const testCases = [
+        {
+            name: 'Single Choice Question',
+            request: {
+                id: 'test-1',
+                question: 'Which approach should I use for implementing the authentication system?',
+                options: [
+                    {
+                        label: 'JWT Tokens',
+                        value: 'jwt',
+                        description: 'Stateless authentication using JSON Web Tokens'
+                    },
+                    {
+                        label: 'Session-based',
+                        value: 'session',
+                        description: 'Traditional server-side session management'
+                    },
+                    {
+                        label: 'OAuth 2.0',
+                        value: 'oauth',
+                        description: 'Delegated authentication using OAuth providers'
+                    }
+                ],
+                allowMultiple: false,
+                allowOther: true,
+                context: 'This is for a new web application with expected 10k daily active users'
+            }
+        },
+        {
+            name: 'Multiple Choice Question',
+            request: {
+                id: 'test-2',
+                question: 'Which files should I include in the commit?',
+                options: [
+                    {
+                        label: 'src/auth.ts',
+                        value: 'auth.ts',
+                        description: 'Main authentication module'
+                    },
+                    {
+                        label: 'src/middleware.ts',
+                        value: 'middleware.ts',
+                        description: 'Authentication middleware'
+                    },
+                    {
+                        label: 'tests/auth.test.ts',
+                        value: 'auth.test.ts',
+                        description: 'Unit tests for authentication'
+                    },
+                    {
+                        label: 'README.md',
+                        value: 'readme',
+                        description: 'Updated documentation'
+                    }
+                ],
+                allowMultiple: true,
+                allowOther: false,
+                context: 'Several files have been modified in the working directory'
+            }
+        },
+        {
+            name: 'Timeout Test',
+            request: {
+                id: 'test-3',
+                question: 'This dialog will timeout in 10 seconds. Do you want to proceed?',
+                options: [
+                    {
+                        label: 'Yes',
+                        value: 'yes'
+                    },
+                    {
+                        label: 'No',
+                        value: 'no'
+                    }
+                ],
+                allowMultiple: false,
+                allowOther: false,
+                timeout: 10000
+            }
+        }
+    ];
+    for (const testCase of testCases) {
+        console.log(`\\n=== ${testCase.name} ===`);
+        console.log(`Question: ${testCase.request.question}`);
+        console.log('Waiting for user response...');
+        try {
+            const response = await manager.showDialog(testCase.request);
+            console.log('Response received:', JSON.stringify(response, null, 2));
+        }
+        catch (error) {
+            console.error('Error:', error instanceof Error ? error.message : error);
+        }
+        // Wait a bit between tests
+        await new Promise(resolve => setTimeout(resolve, 2000));
+    }
+    console.log('\\nAll tests completed. Closing dialog manager...');
+    await manager.close();
+    process.exit(0);
+}
+// Run the test
+testDialogManager().catch(error => {
+    console.error('Test failed:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=test-client.js.map

package/dist/test-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-client.js","sourceRoot":"","sources":["../src/test-client.ts"],"names":[],"mappings":"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"}

package/example-usage.md

@@ -0,0 +1,223 @@
+# Example Usage Scenarios
+
+## 1. Ambiguous File Selection
+
+```json
+{
+  "tool": "ask_human",
+  "arguments": {
+    "question": "I found multiple index files. Which one should I modify?",
+    "options": [
+      {
+        "label": "src/index.ts",
+        "value": "src/index.ts",
+        "description": "Main TypeScript entry point"
+      },
+      {
+        "label": "public/index.html",
+        "value": "public/index.html",
+        "description": "HTML template file"
+      },
+      {
+        "label": "dist/index.js",
+        "value": "dist/index.js",
+        "description": "Compiled JavaScript (build output)"
+      }
+    ],
+    "allowMultiple": false,
+    "allowOther": true,
+    "context": "User asked to 'update the index file' but didn't specify which one"
+  }
+}
+```
+
+## 2. Deployment Confirmation
+
+```json
+{
+  "tool": "ask_human",
+  "arguments": {
+    "question": "Ready to deploy to production. Should I proceed?",
+    "options": [
+      {
+        "label": "Yes, deploy now",
+        "value": "deploy",
+        "description": "Deploy immediately to production"
+      },
+      {
+        "label": "Run tests first",
+        "value": "test-first",
+        "description": "Run the test suite before deploying"
+      },
+      {
+        "label": "Deploy to staging",
+        "value": "staging",
+        "description": "Deploy to staging environment instead"
+      },
+      {
+        "label": "Cancel deployment",
+        "value": "cancel",
+        "description": "Do not deploy at this time"
+      }
+    ],
+    "allowMultiple": false,
+    "allowOther": false,
+    "context": "All tests passed, build successful, last deployment was 3 days ago",
+    "timeout": 60000
+  }
+}
+```
+
+## 3. Code Style Preference
+
+```json
+{
+  "tool": "ask_human",
+  "arguments": {
+    "question": "Which naming convention should I use for the new API endpoints?",
+    "options": [
+      {
+        "label": "camelCase",
+        "value": "camelCase",
+        "description": "getUserData, createNewPost"
+      },
+      {
+        "label": "kebab-case",
+        "value": "kebab-case",
+        "description": "get-user-data, create-new-post"
+      },
+      {
+        "label": "snake_case",
+        "value": "snake_case",
+        "description": "get_user_data, create_new_post"
+      }
+    ],
+    "allowMultiple": false,
+    "allowOther": true,
+    "context": "Creating REST API endpoints for the user service"
+  }
+}
+```
+
+## 4. Multiple File Selection
+
+```json
+{
+  "tool": "ask_human",
+  "arguments": {
+    "question": "Which test files should I run?",
+    "options": [
+      {
+        "label": "Unit tests",
+        "value": "unit",
+        "description": "src/__tests__/*.test.ts"
+      },
+      {
+        "label": "Integration tests",
+        "value": "integration",
+        "description": "tests/integration/*.spec.ts"
+      },
+      {
+        "label": "E2E tests",
+        "value": "e2e",
+        "description": "tests/e2e/*.test.ts"
+      },
+      {
+        "label": "Performance tests",
+        "value": "performance",
+        "description": "tests/performance/*.bench.ts"
+      }
+    ],
+    "allowMultiple": true,
+    "allowOther": false,
+    "context": "Preparing for release, multiple test suites available"
+  }
+}
+```
+
+## 5. Error Resolution Strategy
+
+```json
+{
+  "tool": "ask_human",
+  "arguments": {
+    "question": "TypeScript compilation failed with 15 errors. How should I proceed?",
+    "options": [
+      {
+        "label": "Fix all errors now",
+        "value": "fix-all",
+        "description": "Attempt to fix all TypeScript errors"
+      },
+      {
+        "label": "Fix critical errors only",
+        "value": "fix-critical",
+        "description": "Fix only errors that prevent compilation"
+      },
+      {
+        "label": "Add @ts-ignore comments",
+        "value": "ignore",
+        "description": "Suppress errors with ignore comments"
+      },
+      {
+        "label": "Show me the errors",
+        "value": "show",
+        "description": "Display all errors for review"
+      }
+    ],
+    "allowMultiple": false,
+    "allowOther": true,
+    "context": "Errors are mostly related to type mismatches and missing type definitions"
+  }
+}
+```
+
+## Response Examples
+
+### Successful Selection Response
+```json
+{
+  "success": true,
+  "timestamp": 1703001234567,
+  "response": "src/index.ts",
+  "responseType": "selection"
+}
+```
+
+### Multiple Selection Response
+```json
+{
+  "success": true,
+  "timestamp": 1703001234567,
+  "response": ["unit", "integration"],
+  "responseType": "selection"
+}
+```
+
+### Custom Input Response
+```json
+{
+  "success": true,
+  "timestamp": 1703001234567,
+  "response": "Use PascalCase for classes and camelCase for methods",
+  "responseType": "custom"
+}
+```
+
+### Skipped Response
+```json
+{
+  "success": true,
+  "timestamp": 1703001234567,
+  "skipped": true,
+  "response": "User skipped this question"
+}
+```
+
+### Timeout Response
+```json
+{
+  "success": false,
+  "error": "timeout",
+  "message": "The user did not respond within the timeout period"
+}
+```