# Zypin MCP

A generic MCP (Model Context Protocol) server for testing automation and tool integration. This server provides essential automation capabilities with a focus on simplicity and reliability.

## Features

- **Simple Setup**: Minimal configuration and dependencies
- **Essential Tools**: Core automation functionality
- **Fast**: Lightweight implementation with minimal overhead
- **Reliable**: Focused on the most commonly used features

## Project Structure

```
zypin-mcp/
├── package.json              # Project configuration and dependencies
├── index.js                  # Main CLI entry point and MCP server
├── browser.js                # Simple browser wrapper using Playwright
├── tools.js                  # MCP tools implementation (16 tools)
├── test.js                   # Basic functionality tests
├── .gitignore                # Git ignore rules
├── README.md                 # This documentation
└── node_modules/             # Dependencies (3 packages)
```

### File Descriptions

- **`index.js`**: Main entry point that sets up the MCP server, handles CLI arguments, and manages the browser lifecycle
- **`browser.js`**: Simple wrapper around Playwright that provides essential automation methods
- **`tools.js`**: Defines all 16 MCP tools with their schemas and handlers
- **`test.js`**: Basic test suite to verify core functionality
- **`.gitignore`**: Minimal git ignore rules for essential exclusions

## Architecture

The project follows a simple, modular architecture:

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   MCP Client    │    │   index.js      │    │   browser.js    │
│   (VS Code,     │◄──►│   (MCP Server)  │◄──►│   (Playwright)  │
│   Cursor, etc.) │    │                 │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌─────────────────┐
                       │   tools.js      │
                       │   (16 MCP Tools)│
                       └─────────────────┘
```

### Component Interactions

1. **MCP Client** sends requests to the server via STDIO transport
2. **index.js** receives MCP protocol messages and routes them to appropriate handlers
3. **tools.js** defines the available tools and their schemas
4. **browser.js** executes the actual automation commands

### Key Design Principles

- **Single Responsibility**: Each file has a clear, focused purpose
- **Minimal Dependencies**: Only 3 essential packages
- **Command Line Only**: Simple CLI options, no config files
- **Essential Tools Only**: 16 tools covering 80% of use cases
- **Error Handling**: Clear error messages and graceful failures

## Quick Start

### Installation

#### Option 1: Standalone Installation
```bash
npm install https://github.com/zypin-testing/zypin-mcp
```

#### Option 2: Integrated with Zypin Core (Recommended)
```bash
npm install -g https://github.com/zypin-testing/zypin-core
```

### Basic Usage

#### Standalone Usage
Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "zypin-browser": {
      "command": "npx",
      "args": ["https://github.com/zypin-testing/zypin-mcp"]
    }
  }
}
```

#### Integrated Usage (Zypin Core)
```bash
# Start MCP server through Zypin CLI
zypin mcp

# With options
zypin mcp --browser firefox --headed
```

**Benefits of Zypin Core Integration:**
- ✅ Unified CLI interface
- ✅ Automatic updates with `zypin update`
- ✅ Integrated with testing workflow
- ✅ Consistent command structure

### Command Line Options

#### Standalone Usage
```bash
# Basic usage
npx zypin-mcp

# With options
npx zypin-mcp --browser firefox --headed --width 1920 --height 1080
```

#### Integrated Usage (Zypin Core)
```bash
# Basic usage
zypin mcp

# With options
zypin mcp --browser firefox --headed --width 1920 --height 1080
```

**Available Options:**
- `--browser <browser>`: Browser to use (chromium, firefox, webkit) - default: chromium
- `--headless`: Run in headless mode (default)
- `--headed`: Run in headed mode (overrides headless)
- `--width <width>`: Viewport width - default: 1280
- `--height <height>`: Viewport height - default: 720
- `--timeout <timeout>`: Default timeout in milliseconds - default: 30000

**Default Settings:**
- Browser: chromium
- Mode: headless
- Viewport: 1280x720
- Timeout: 30000ms

## Available Tools

### Navigation
- `navigate(url)` - Go to a URL
- `go_back()` - Go back to previous page
- `go_forward()` - Go forward to next page
- `reload()` - Reload current page

### Interaction
- `click(selector)` - Click an element
- `type(selector, text)` - Type text into input field
- `select(selector, value)` - Select option from dropdown
- `fill_form(fields)` - Fill multiple form fields

### Information
- `snapshot()` - Get page snapshot with interactive elements
- `screenshot(filename?)` - Take screenshot
- `get_text(selector)` - Get text from element
- `get_url()` - Get current URL
- `get_title()` - Get page title

### Utilities
- `wait_for(selector, timeout?)` - Wait for element to appear
- `evaluate(script)` - Run JavaScript on page
- `close()` - Close browser

## Integration with Zypin Core

Zypin MCP is now integrated into the Zypin Core framework, providing a unified testing and automation experience.

### Complete Testing Workflow

```bash
# 1. Create a test project
zypin create-project my-tests --template selenium/basic-webdriver
cd my-tests
npm install

# 2. Start testing services
zypin start --packages selenium

# 3. Run traditional tests
zypin run --input test.js

# 4. Start MCP server for testing automation
zypin mcp --browser chromium --headed

# 5. Update everything
zypin update
```

### MCP Client Configuration

When using Zypin Core integration, configure your MCP client to use the integrated command:

```json
{
  "mcpServers": {
    "zypin-browser": {
      "command": "zypin",
      "args": ["mcp", "--browser", "chromium"]
    }
  }
}
```

### Benefits of Integration

- **Unified Interface**: All testing tools accessible through one CLI
- **Automatic Updates**: MCP server updates with `zypin update`
- **Consistent Workflow**: Same command patterns across all tools
- **Integrated Monitoring**: Health checks and process management
- **Template Support**: MCP projects can be created from templates

## Examples

### Basic Navigation
```javascript
// Navigate to a website
await navigate({ url: "https://example.com" });

// Take a screenshot
await screenshot({ filename: "homepage.png" });

// Get page information
const info = await snapshot();
console.log(info.title, info.url);
```

### Form Interaction
```javascript
// Fill a login form
await fill_form({
  "#username": "myuser",
  "#password": "mypass"
});

// Click submit button
await click({ selector: "#login-button" });

// Wait for redirect
await wait_for({ selector: ".dashboard" });
```

### Element Interaction
```javascript
// Click a link
await click({ selector: "a[href='/products']" });

// Type in search box
await type({ 
  selector: "#search-input", 
  text: "laptop" 
});

// Select from dropdown
await select({ 
  selector: "#category", 
  value: "electronics" 
});
```

## Comparison with Full Playwright MCP

| Feature | Zypin MCP | Full Playwright MCP |
|---------|------------------|---------------------|
| Bundle Size | ~10MB | ~50MB |
| Dependencies | 3 | 15+ |
| Configuration | CLI only | 50+ options |
| Tools | 15 essential | 30+ advanced |
| Setup Time | 2 minutes | 10+ minutes |
| Use Cases | 80% of scenarios | 100% of scenarios |

## Requirements

- Node.js 18 or newer
- MCP-compatible client (VS Code, Cursor, Claude Desktop, etc.)

## License

MIT

## Development

### Running Tests

```bash
# Run basic functionality tests
node test.js

# Test MCP server startup
npx https://github.com/zypin-testing/zypin-mcp --help
```

### Adding New Tools

To add a new tool:

1. Add the tool definition to `tools.js`:
```javascript
{
  name: 'new_tool',
  description: 'Description of the new tool',
  inputSchema: {
    type: 'object',
    properties: {
      param: { type: 'string', description: 'Parameter description' }
    },
    required: ['param']
  },
  handler: async ({ param }) => {
    // Tool implementation
    return { success: true, message: 'Tool executed' };
  }
}
```

2. Add corresponding method to `browser.js` if needed
3. Update this README with the new tool documentation

### Project Metrics

- **Lines of Code**: ~500 lines total
- **Files**: 6 core files
- **Dependencies**: 3 packages
- **Bundle Size**: ~10MB
- **Startup Time**: < 2 seconds

## Contributing

This is a simplified version focused on essential functionality. For advanced features, consider using the full Playwright MCP server.

### Guidelines

- Keep it simple - avoid adding complexity unless absolutely necessary
- Focus on the 80% use case - don't add features for edge cases
- Maintain the single-file architecture for each component
- Test any changes with the included test suite

## Troubleshooting

### Common Issues

**Browser not found error:**
```bash
# Install Playwright browsers
npx playwright install chromium
```

**MCP client connection issues:**
- Ensure the server starts without errors: `npx https://github.com/zypin-testing/zypin-mcp --help`
- Check that your MCP client configuration is correct
- Verify the server is running in the correct directory

**Tool execution errors:**
- Check that selectors are valid CSS selectors
- Ensure elements exist on the page before interacting
- Use `wait_for` tool to wait for elements to appear

**Command line issues:**
- Check that browser type is one of: `chromium`, `firefox`, `webkit`
- Ensure viewport dimensions are positive numbers
- Verify command line arguments are valid

### Debug Mode

Run with debug output:
```bash
# See server startup messages
npx https://github.com/zypin-testing/zypin-mcp 2>&1 | tee server.log
```

### Getting Help

- Check the [MCP documentation](https://modelcontextprotocol.io/)
- Review the [Playwright documentation](https://playwright.dev/)
- Test with the included `test.js` file