From 2de7ad2db1c93a6a8e57e7e0a9abcb4a0d478a22 Mon Sep 17 00:00:00 2001 From: B Harper Date: Sat, 25 Oct 2025 11:52:58 +1100 Subject: [PATCH] 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 --- README.md | 110 ++++++++++++++- ReadMeDev.md | 330 +++++++++++++++++++++++++++++++++++++++++++++ ToDo.md | 3 +- response-debug.txt | 1 + 4 files changed, 442 insertions(+), 2 deletions(-) create mode 100644 ReadMeDev.md diff --git a/README.md b/README.md index 3643d74..5b6d66e 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/ReadMeDev.md b/ReadMeDev.md new file mode 100644 index 0000000..481197f --- /dev/null +++ b/ReadMeDev.md @@ -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. \ No newline at end of file diff --git a/ToDo.md b/ToDo.md index 2a5179c..b0d84ff 100644 --- a/ToDo.md +++ b/ToDo.md @@ -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. (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! diff --git a/response-debug.txt b/response-debug.txt index 131fc02..6f3ff9a 100644 --- a/response-debug.txt +++ b/response-debug.txt @@ -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