Safari MCP Server

# Safari MCP Server - Project Overview ## 🎯 Project Summary You now have a complete Safari MCP Server project at: ``` /Users/<USERNAME>/source/repos/safari-mcp-server/ ``` This server provides AI assistants with comprehensive Safari browser automation and developer tools access through the Model Context Protocol (MCP). ## 📁 Project Structure ``` safari-mcp-server/ ├── src/ # TypeScript source code │ ├── index.ts # Main entry point │ ├── safari-mcp-server.ts # MCP server implementation │ ├── safari-driver.ts # Safari WebDriver manager │ └── types.ts # TypeScript definitions ├── build/ # Compiled JavaScript (after build) ├── tests/ # Test files │ └── basic-tests.ts # Basic validation tests ├── examples/ # Usage examples │ └── example-usage.ts # Programmatic usage example ├── package.json # Project configuration ├── tsconfig.json # TypeScript configuration ├── setup.sh # macOS setup script ├── setup.bat # Windows info script ├── claude_desktop_config.json # Claude Desktop config example ├── .gitignore # Git ignore rules └── README.md # Comprehensive documentation ``` ## 🚀 Quick Start ### 1. Install Dependencies ```bash cd "/Users/<USERNAME>/source/repos/safari-mcp-server" npm install ``` ### 2. Build the Project ```bash npm run build ``` ### 3. Test the Setup ```bash npm test ``` ### 4. Run the Server ```bash npm start ``` ## 🛠️ Available NPM Scripts | Script | Description | |--------|-------------| | `npm run build` | Compile TypeScript to JavaScript | | `npm start` | Start the MCP server | | `npm run dev` | Build and start in development mode | | `npm run watch` | Watch TypeScript files for changes | | `npm run clean` | Clean build directory | | `npm test` | Run basic validation tests | | `npm run setup` | Run setup script (macOS only) | | `npm run example` | Run usage example | | `npm run inspect` | Start with MCP inspector for debugging | ## 🔧 Safari MCP Tools Available ### Session Management - **safari_start_session** - Start automation session with dev tools - **safari_close_session** - Close automation session - **safari_list_sessions** - List active sessions ### Navigation & Page Info - **safari_navigate** - Navigate to URLs - **safari_get_page_info** - Get current page URL and title ### Developer Tools Access - **safari_get_console_logs** - Browser console logs with filtering - **safari_get_network_logs** - Network activity monitoring - **safari_get_performance_metrics** - Page performance data ### Browser Interaction - **safari_execute_script** - Execute JavaScript in browser - **safari_take_screenshot** - Capture page screenshots - **safari_inspect_element** - DOM element inspection ## 📱 Integration with Claude Desktop ### Configuration File Location - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` ### Add This Configuration: ```json { "mcpServers": { "safari-devtools": { "command": "node", "args": [ "/Users/<USERNAME>/source/repos/safari-mcp-server/build/index.js" ] } } } ``` ## ⚠️ Important Notes ### Platform Requirements - **This server only works on macOS** - Safari and SafariDriver are macOS exclusive - **Node.js 18+** required - **Safari 10+** with WebDriver support ### Safari Configuration Required Before using, you must: 1. Enable Safari Developer menu: Safari → Preferences → Advanced → "Show Develop menu in menu bar" 2. Enable automation: Develop → Allow Remote Automation 3. Authorize SafariDriver: `sudo safaridriver --enable` ### Limitations - **Single session limit** - Safari only allows one WebDriver session at a time - **Limited network logging** - Safari's debugging API is more limited than Chrome DevTools Protocol - **macOS dependency** - Cannot run on Windows or Linux ## 🧪 Testing Your Setup ### 1. Basic Tests ```bash npm test ``` ### 2. Interactive Testing with MCP Inspector ```bash npm run inspect ``` ### 3. Example Usage ```bash npm run example ``` ## 🔍 Development & Debugging ### Watch Mode for Development ```bash npm run watch ``` ### Using MCP Inspector The MCP Inspector provides a web interface to test your server: ```bash npm run inspect ``` Then open the provided URL in your browser to interactively test tools. ### Logging The server logs to stderr to avoid interfering with MCP protocol communication on stdout. ## 🚨 Troubleshooting ### Common Issues 1. **"Platform not supported"** - This server only works on macOS - For Windows/Linux, consider Chrome CDP-based solutions 2. **"SafariDriver not enabled"** - Run: `sudo safaridriver --enable` - Check Safari → Develop → Allow Remote Automation is enabled 3. **"Session not found"** - Start a session first with `safari_start_session` - Only one Safari session can be active at a time 4. **"Permission denied"** - Make sure Terminal has necessary permissions - Check macOS Security & Privacy settings ### Getting Help - Check the README.md for detailed documentation - Run tests to validate setup: `npm test` - Use MCP Inspector for interactive debugging: `npm run inspect` ## 🎉 You're Ready! Your Safari MCP Server is now fully set up and ready to provide AI assistants with powerful Safari automation and developer tools access. The server implements the complete MCP specification and provides comprehensive browser control capabilities. Remember: This server must run on macOS to function properly, as it depends on Safari and SafariDriver which are exclusive to Apple platforms.