README.md•5.65 kB
# 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