Add comprehensive documentation - README.md and ReadMeDev.md

- README.md: Clean user-facing documentation with truthful feature descriptions - ReadMeDev.md: Technical developer documentation with architecture details - No exaggeration or marketing fluff - just what we actually built - Covers real features: VS Code interface, MCP server, tool overrides, web interface - Includes honest installation, configuration, and troubleshooting sections
2026-09-09 11:14:27 +08:00 · 2025-10-25 11:52:58 +11:00
parent a19312c2df
commit 2de7ad2db1
4 changed files with 442 additions and 2 deletions
@@ -1,6 +1,114 @@
 # HumanAgent MCP - VS Code Extension

-A VS Code extension that implements a Model Context Protocol (MCP) server for real-time human-AI communication. This extension enables AI agents to initiate conversations with human developers directly through VS Code's chat interface.
+# HumanAgent MCP
+
+A VS Code extension that enables AI agents to communicate directly with developers through an integrated chat interface. Built on the Model Context Protocol (MCP) standard.
+
+## What it does
+
+When AI assistants like Claude or Cursor need clarification, approval, or input from you, they can use the HumanAgent_Chat tool to send messages directly to your VS Code interface. You see their questions in real-time and can respond immediately, creating a seamless collaborative workflow.
+
+## Installation
+
+1. Open VS Code
+2. Install the HumanAgent MCP extension from the marketplace
+3. The extension automatically starts an MCP server on port 3737
+4. Configure your AI assistant to use the MCP server at `http://127.0.0.1:3737/mcp`
+
+## Usage
+
+### VS Code Interface
+
+After installation, you'll see:
+- **Chat Sessions** view in the Explorer panel showing active conversations
+- **HumanAgent Chat** panel (dockable) for the main chat interface
+- Audio notifications when new messages arrive (configurable)
+
+### Basic Workflow
+
+1. AI assistant calls the `HumanAgent_Chat` tool when it needs human input
+2. Message appears in your VS Code chat interface with optional sound notification
+3. You respond through the chat interface
+4. AI assistant receives your response and continues working
+
+### Commands
+
+- **Create New Chat Session** - Start a fresh conversation
+- **Configure MCP Server** - Set up workspace or global MCP registration
+- **Show Status** - View server status and active sessions
+
+## Configuration
+
+### MCP Server Registration
+
+The extension can register the MCP server in two ways:
+
+**Workspace Registration** (Recommended)
+- Creates `.vscode/mcp.json` in your current workspace
+- Server only available to this workspace
+- Automatic session management per workspace
+
+**Global Registration**
+- Registers in VS Code's global MCP settings  
+- Available to all workspaces
+- Manual session management
+
+### Settings
+
+Access via VS Code Settings (search for "HumanAgent"):
+
+- `humanagent-mcp.logging.enabled` - Enable debug logging to `.vscode` directory (default: false)
+- `humanagent-mcp.logging.level` - Log level: ERROR, WARN, INFO, DEBUG (default: INFO)
+
+### Tool Customization
+
+Create `.vscode/override-prompt.md` in your workspace to customize how the AI tool behaves:
+
+```markdown
+# Custom HumanAgent_Chat Tool
+
+## Description
+Your custom description here
+
+## Properties
+- message: Custom message field description
+- timeout: Response timeout in seconds (optional)
+```
+
+## Web Interface
+
+Access the web interface at `http://127.0.0.1:3737/` to:
+- View chat sessions from any browser
+- Send messages from outside VS Code  
+- Monitor active conversations
+
+## Requirements
+
+- VS Code 1.105.0 or higher
+- Network access to localhost port 3737
+- AI assistant configured to use MCP (Claude, Cursor, etc.)
+
+## Troubleshooting
+
+**Extension not starting**
+- Check VS Code Developer Console for errors
+- Verify port 3737 is not in use by another application
+
+**AI can't connect**  
+- Ensure MCP server is registered (use Configure MCP Server command)
+- Check the server URL includes your session ID: `http://127.0.0.1:3737/mcp?sessionId=your-session-id`
+
+**No audio notifications**
+- Check VS Code notification settings
+- Test notifications using the Configure panel
+
+**Messages not appearing**
+- Refresh the Chat Sessions view
+- Check server status in the HumanAgent Chat panel
+
+## License
+
+MIT License

 ## Features

@@ -0,0 +1,330 @@
+# HumanAgent MCP - Developer Documentation
+
+Technical documentation for developers working on or extending the HumanAgent MCP extension.
+
+## Architecture
+
+### Core Components
+
+**Extension Entry Point** (`src/extension.ts`)
+- VS Code extension activation and lifecycle
+- MCP server definition provider for VS Code native integration
+- Session management and workspace detection
+- Command registration and event handling
+
+**MCP Server** (`src/mcp/server.ts`)
+- HTTP server on port 3737 serving MCP protocol
+- Tool definitions and execution (HumanAgent_Chat)
+- Session-specific tool overrides
+- SSE connections for real-time updates
+- Web interface generation
+
+**Chat Manager** (`src/mcp/chatManager.ts`)
+- Centralized message and session storage
+- Request/response correlation
+- Session cleanup and memory management
+
+**Webview Provider** (`src/webview/chatWebviewProvider.ts`)
+- VS Code webview integration
+- Chat interface UI and messaging
+- Server configuration and status monitoring
+
+**Configuration Manager** (`src/mcp/mcpConfigManager.ts`)
+- MCP server registration (workspace/global)
+- Configuration file management (.vscode/mcp.json)
+
+### Data Flow
+
+```
+AI Client -> MCP Server (port 3737) -> ChatManager -> Webview Provider -> VS Code UI
+                                   -> SSE Client    -> Web Interface
+```
+
+## Key Features Implementation
+
+### Session Management
+
+Each workspace gets a unique session ID based on workspace path hash. Session data includes:
+- Chat message history (managed by ChatManager)
+- Pending requests awaiting human response
+- Tool overrides loaded from `.vscode/override-prompt.md`
+- Workspace-specific configuration
+
+### Tool Override System
+
+1. Default `HumanAgent_Chat` tool defined in `server.ts`
+2. Per-workspace overrides loaded from `.vscode/override-prompt.md`
+3. Markdown parsed to extract tool description and schema modifications
+4. Session-specific tool maps maintain overrides per workspace
+
+### Real-time Communication
+
+- **MCP Protocol**: Standard JSON-RPC over HTTP for AI client communication
+- **SSE (Server-Sent Events)**: Real-time updates to webview and web interface
+- **VS Code Events**: Native VS Code messaging for webview updates
+
+## Development Setup
+
+### Prerequisites
+
+- Node.js 18+
+- VS Code 1.105.0+
+- TypeScript knowledge
+
+### Build Process
+
+```bash
+# Install dependencies
+npm install
+
+# Development build with watch
+npm run watch
+
+# Production build
+npm run package
+
+# Compile extension only
+npm run compile
+```
+
+### Project Structure
+
+```
+src/
+├── extension.ts              # Extension entry point
+├── mcp/
+│   ├── server.ts            # MCP server implementation  
+│   ├── chatManager.ts       # Session and message management
+│   ├── mcpConfigManager.ts  # Configuration handling
+│   ├── types.ts             # TypeScript interfaces
+│   └── mcpStandalone.ts     # Standalone server entry
+├── webview/
+│   └── chatWebviewProvider.ts # VS Code webview integration
+├── providers/
+│   └── chatTreeProvider.ts   # Explorer tree view
+├── audio/
+│   └── audioNotification.ts  # Sound notifications
+└── serverManager.ts          # Server lifecycle management
+```
+
+### Key Classes
+
+**McpServer**
+- Main server class implementing MCP protocol
+- Tool registration and execution
+- HTTP request handling and routing
+- SSE connection management
+
+**ChatManager** 
+- Message storage and retrieval
+- Pending request tracking
+- Session lifecycle management
+- Memory cleanup and limits
+
+**ChatWebviewProvider**
+- VS Code webview implementation
+- Chat UI rendering and interaction
+- Server status monitoring
+- Configuration management
+
+## Configuration Files
+
+### Extension Manifest (`package.json`)
+
+Key sections:
+- `contributes.commands` - VS Code commands
+- `contributes.views` - Panel and tree view definitions  
+- `contributes.configuration` - User settings schema
+- `contributes.mcpServerDefinitionProviders` - VS Code MCP integration
+
+### Workspace Configuration (`.vscode/mcp.json`)
+
+Generated automatically when registering workspace MCP server:
+
+```json
+{
+  "servers": {
+    "humanagent-mcp": {
+      "type": "http",
+      "url": "http://127.0.0.1:3737/mcp?sessionId=session-xxx",
+      "notifications": {
+        "enableSound": true,
+        "enableFlashing": true
+      }
+    }
+  }
+}
+```
+
+### Tool Override (`.vscode/override-prompt.md`)
+
+Markdown file for customizing tool behavior per workspace. Parsed sections:
+- Description becomes tool description
+- Properties section modifies input schema
+- Additional context included in tool execution
+
+## API Endpoints
+
+The MCP server exposes both MCP protocol and web endpoints:
+
+### MCP Protocol (`/mcp`)
+
+Standard MCP JSON-RPC methods:
+- `initialize` - Client initialization
+- `tools/list` - Available tools query
+- `tools/call` - Tool execution (HumanAgent_Chat)
+
+### Web Endpoints
+
+- `GET /` - Web chat interface
+- `GET /sessions` - Session list API
+- `POST /send-message` - Web message sending
+- `GET /sse/{sessionId}` - Server-sent events connection
+
+## Testing
+
+### Extension Testing
+
+```bash
+# Run in extension development host
+# Press F5 in VS Code to launch debug instance
+```
+
+### MCP Server Testing
+
+```bash
+# Test server independently
+node dist/mcpStandalone.js
+curl http://127.0.0.1:3737/sessions
+```
+
+### Integration Testing
+
+Test AI client integration by configuring Claude/Cursor with:
+```
+http://127.0.0.1:3737/mcp?sessionId=test-session
+```
+
+## Logging and Debugging
+
+### Extension Logs
+
+Enable debug logging via settings:
+- `humanagent-mcp.logging.enabled` = true  
+- `humanagent-mcp.logging.level` = "DEBUG"
+
+Logs written to `.vscode/HumanAgent-server.log` in workspace.
+
+### VS Code Debug Console
+
+View extension debug output:
+1. Help > Toggle Developer Tools
+2. Console tab shows extension logs
+
+### Server Debug Mode
+
+Environment variables for standalone server:
+```bash
+HUMANAGENT_LOGGING_ENABLED=true
+HUMANAGENT_LOGGING_LEVEL=DEBUG
+node dist/mcpStandalone.js
+```
+
+## Extension Points
+
+### Adding New Tools
+
+1. Define tool in `initializeDefaultTools()` method
+2. Add handler in `handleToolCall()` method
+3. Update tool override parsing if needed
+
+### Custom Notification Types
+
+1. Add new SSE message types in `sendMcpNotification()`
+2. Handle in webview JavaScript
+3. Update UI accordingly
+
+### Additional Configuration
+
+1. Add to `package.json` contributes.configuration
+2. Read settings in extension code
+3. Pass to server during initialization
+
+## Common Patterns
+
+### Async Request Handling
+
+```typescript
+// Store request resolver
+this.requestResolvers.set(requestId, {
+  resolve: (response: string) => {
+    // Handle response
+  },
+  reject: (error: Error) => {
+    // Handle error  
+  }
+});
+
+// Set timeout if needed
+if (timeoutMs) {
+  setTimeout(() => {
+    // Timeout logic
+  }, timeoutMs);
+}
+```
+
+### Session-Specific Operations
+
+```typescript
+// Get session tools
+const sessionTools = this.sessionTools.get(sessionId) || this.tools;
+
+// Store session data
+this.sessionData.set(sessionId, data);
+
+// Clean up session
+this.activeSessions.delete(sessionId);
+```
+
+### Webview Communication
+
+```typescript
+// Send to webview
+this._view.webview.postMessage({
+  type: 'messageType',
+  data: payload
+});
+
+// Handle webview messages
+webview.onDidReceiveMessage(message => {
+  switch (message.type) {
+    case 'actionType':
+      // Handle action
+      break;
+  }
+});
+```
+
+## Build and Packaging
+
+### Development Build
+
+```bash
+npm run compile
+```
+
+### Production Package
+
+```bash
+npm run package
+```
+
+This creates `dist/extension.js` and `dist/mcpStandalone.js` for distribution.
+
+### Extension Packaging
+
+```bash
+vsce package
+```
+
+Creates `.vsix` file for manual installation or marketplace publishing.
@@ -1,5 +1,5 @@
 [X] Assess / Set logging path and details correctly for release & dev.
-[ ] Create a new readme
+[X] Create a new readme - COMPLETED: Created truthful README.md for users and ReadMeDev.md for developers
 [X] Consider how updates to the extension will work.

 [X] Override Prompt Script is not generated from exact coded system tool description - seems to be stale - where is the info coming from for the override creation?
@@ -14,4 +14,5 @@
 [ ] Would be great if I could paste in an image or screen shot - Copilot agent allows this in the vscode plugin.
 [X]  put an option in the MCP.json and the global setup to change the default timout to a new value - FIXED: Removed silent 300-second fallback, now waits indefinitely if no timeout specified, or uses explicit timeout from tool params/overrides
 [X] Getting chat friendly name on startup seems to be failing "[Extension Host] Failed to restore session name: TypeError: fetch failed (at console.<anonymous> (file:///Applications/Visual%20Studio%20Code.app/Contents/Resources/app/out/vs/workbench/api/node/extensionHostProcess.js:203:32117))" - FIXED: Moved session name restoration to after server startup with retry logic
+[ ] Package Extension so we can install locally and test the seperation of workspaces - to ensure we do not cross contaminate anything between workspaces. 
 [ ] Publish Extension - WHEN ALL ELSE IS DONE!
@@ -6,3 +6,4 @@
 2025-10-24T09:33:44.808Z - RESPONSE ENDPOINT CALLED - RequestID: 8-1761298414137
 2025-10-24T09:36:01.128Z - RESPONSE ENDPOINT CALLED - RequestID: 10-1761298555386
 2025-10-24T09:36:37.205Z - RESPONSE ENDPOINT CALLED - RequestID: 11-1761298573778
+2025-10-25T00:51:00.473Z - RESPONSE ENDPOINT CALLED - RequestID: 3-1761353445662