# VS Code Simple Browser MCP Server

A Model Context Protocol (MCP) server that enables LLMs to interact with VS Code's Simple Browser, providing website interaction capabilities and console log monitoring.

## Features

### Browser Controls
- **Open URLs**: Launch websites in VS Code's Simple Browser
- **Navigation**: Navigate between different URLs
- **Page Refresh**: Reload the current page
- **Browser State**: Get current URL and browser status
- **Close Browser**: Close the Simple Browser window

### Console Log Monitoring
- **Real-time Logging**: Capture console messages from web pages
- **Log Filtering**: Filter logs by level (log, warn, error, info, debug)
- **Historical Logs**: Retrieve logs with timestamps and source information
- **Log Management**: Clear console log history

### JavaScript Execution
- **Code Execution**: Execute JavaScript code in the browser context
- **Result Handling**: Get return values from executed code
- **DOM Manipulation**: Interact with page elements through JavaScript

## Available Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `open_url` | Open a URL in Simple Browser | `url` (required), `title` (optional) |
| `navigate` | Navigate to a different URL | `url` (required) |
| `get_current_url` | Get the currently displayed URL | None |
| `refresh_page` | Refresh the current page | None |
| `execute_javascript` | Execute JavaScript in browser context | `code` (required), `waitForResult` (optional) |
| `get_console_logs` | Retrieve console logs | `level` (optional), `limit` (optional), `since` (optional) |
| `clear_console_logs` | Clear stored console logs | None |
| `get_browser_state` | Get current browser state | None |
| `close_browser` | Close the Simple Browser | None |

## Installation

1. **Clone the repository**:
   ```bash
   git clone https://github.com/YOUR_USERNAME/vscode-simple-browser-mcp.git
   cd vscode-simple-browser-mcp
   ```

2. **Install dependencies**:
   ```bash
   npm install
   ```

3. **Build the project**:
   ```bash
   npm run build
   ```

## Usage

### With Claude Desktop

Add the server to your Claude Desktop configuration file:

**macOS/Linux**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "vscode-simple-browser": {
      "command": "node",
      "args": [
        "/path/to/your/vscode-simple-browser-mcp/build/index.js"
      ]
    }
  }
}
```

### Standalone

Run the server directly:

```bash
npm start
```

## Development

### Project Structure

```
vscode-simple-browser-mcp/
├── src/
│   └── index.ts           # Main MCP server implementation
├── build/                 # Compiled JavaScript output
├── .vscode/
│   ├── mcp.json          # MCP server configuration
│   └── tasks.json        # VS Code tasks
├── .github/
│   └── copilot-instructions.md
├── package.json
├── tsconfig.json
└── README.md
```

### Development Commands

- `npm run build` - Build the TypeScript project
- `npm run dev` - Watch mode for development
- `npm start` - Run the compiled server

### Adding New Tools

1. Define the tool using the MCP SDK:
   ```typescript
   server.tool(
     "tool_name",
     "Tool description",
     {
       parameter: z.string().describe("Parameter description"),
     },
     async ({ parameter }) => {
       // Tool implementation
       return {
         content: [
           {
             type: "text",
             text: "Tool result",
           },
         ],
       };
     }
   );
   ```

2. Update this README with the new tool information

## Example Usage

### Opening a Website
```
Please open https://example.com in the Simple Browser
```

### Executing JavaScript
```
Execute JavaScript to get the page title: document.title
```

### Monitoring Console Logs
```
Get the latest console logs from the browser
```

### Getting Browser State
```
What's the current state of the browser?
```

## Architecture Notes

### Current Implementation
This is a foundational implementation that provides:
- Basic browser control through simulated VS Code commands
- In-memory console log storage
- JavaScript execution simulation

### Future Enhancements
For a production implementation, consider:
- Direct VS Code Extension API integration
- Real-time webview message passing
- Advanced console log capture mechanisms
- Screenshot capabilities
- Network request monitoring
- Element inspection tools

## Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/your-feature-name`
3. Make your changes
4. Add tests if applicable
5. Commit your changes: `git commit -am 'Add some feature'`
6. Push to the branch: `git push origin feature/your-feature-name`
7. Submit a pull request

## Issues and Bug Reports

If you encounter any issues or bugs, please create an issue on GitHub with:
- A clear description of the problem
- Steps to reproduce the issue
- Your environment details (OS, VS Code version, Node.js version)
- Any relevant error messages or logs

## License

ISC License

## Support

For issues and questions:
- Check the [MCP documentation](https://modelcontextprotocol.io/)
- Review VS Code Extension API documentation
- Create an issue in this repository
- Join the MCP community discussions

## Roadmap

Future enhancements planned:
- [ ] Real-time console log streaming
- [ ] Network request monitoring
- [ ] Screenshot capture capabilities
- [ ] Advanced DOM inspection tools
- [ ] Performance monitoring integration
- [ ] Multi-tab browser support