@origindot./zigzag/README-old.md

Comprehensive MCP server providing AI agents with visual, development, and design validation tools

# AI Agent MCP Toolbox

Comprehensive MCP server that provides AI agents with visual, development, and design validation capabilities.

## Features

- 📸 **Screenshot & Screen Recording** - Capture screens, windows, or regions
- 🔍 **UI Inspection** - Extract UI element hierarchies and properties
- ⚡ **Performance Monitoring** - Real-time performance metrics and analysis
- 🎨 **Design Validation** - Validate against design guidelines (coming soon)
- ♿ **Accessibility Auditing** - WCAG compliance checking
- 📁 **File Watching** - Monitor file changes during development (coming soon)

## Installation

```bash
# Clone the repository
git clone https://github.com/yourusername/ai-agent-mcp-toolbox.git
cd ai-agent-mcp-toolbox

# Install dependencies
npm install

# Build the project
npm run build
```

## Configuration

Add to your Claude Code configuration:

```json
{
  "mcpServers": {
    "ai-agent-toolbox": {
      "command": "node",
      "args": ["/path/to/ai-agent-mcp-toolbox/dist/index.js"]
    }
  }
}
```

## Available Tools

### Screenshot Tool

Capture screenshots of the entire screen, specific windows, or regions.

**Parameters:**
- `target` (required): 'screen' | 'window' | 'region'
- `window_title`: Title of window to capture (for window target)
- `region`: Object with x, y, width, height (for region target)
- `format`: 'png' | 'jpg' | 'webp' (default: 'png')
- `quality`: 1-100 (default: 90)

**Example:**
```javascript
// Capture entire screen
await tools.screenshot({
  target: "screen",
  format: "png"
});

// Capture specific region
await tools.screenshot({
  target: "region",
  region: { x: 100, y: 100, width: 800, height: 600 },
  format: "jpg",
  quality: 85
});
```

### UI Inspect Tool

Extract UI element hierarchy and analyze accessibility compliance.

**Parameters:**
- `target` (required): Application name or window title
- `element_path`: Specific element path to focus on
- `include_properties`: Array of properties to extract
- `depth`: Maximum depth of element tree (default: 3)

**Example:**
```javascript
// Inspect application UI
await tools.ui_inspect({
  target: "MyApp",
  depth: 5,
  include_properties: ["text", "position", "size"]
});
```

### Performance Monitor Tool

Monitor application performance metrics and system resources.

**Parameters:**
- `target` (required): Application or process to monitor
- `duration`: Monitoring duration in seconds (default: 30)
- `metrics`: Array of metrics to collect (default: ['cpu', 'memory'])
  - Options: 'cpu', 'memory', 'gpu', 'network', 'disk', 'fps'
- `interval`: Sampling interval in seconds (default: 1)

**Example:**
```javascript
// Monitor application performance
await tools.performance_monitor({
  target: "MyApp",
  duration: 60,
  metrics: ["cpu", "memory", "fps"],
  interval: 2
});
```

## Development

```bash
# Run in development mode
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Generate documentation
npm run docs
```

## Architecture

The toolbox is built with a modular architecture:

```
src/
├── index.ts          # Entry point
├── server.ts         # MCP server implementation
├── types/            # TypeScript definitions
├── tools/            # Individual tool implementations
│   ├── screenshot.ts
│   ├── ui-inspect.ts
│   └── performance-monitor.ts
└── utils/            # Utility functions
```

## Platform Support

- **macOS**: Full support for all features
- **Windows**: Full support with Windows-specific implementations
- **Linux**: Support varies by distribution and desktop environment

## Roadmap

- [ ] Screen recording functionality
- [ ] Design guideline validation (Microsoft Fluent, Apple HIG, Material Design)
- [ ] File watching and hot reload detection
- [ ] Advanced accessibility auditing
- [ ] Integration with design tools (Figma, Sketch)
- [ ] Custom design system support
- [ ] Real-time collaboration features

## Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

## License

MIT License - see LICENSE file for details

## Troubleshooting

### Screenshot tool not working

Make sure you have the necessary permissions:
- **macOS**: Grant screen recording permission in System Preferences
- **Windows**: Run with appropriate permissions
- **Linux**: May require X11 or Wayland permissions

### Performance monitoring shows 0 values

Some metrics require elevated permissions or specific hardware support:
- GPU metrics require compatible graphics drivers
- Some system metrics may require administrator/root access

## Support

For issues and feature requests, please use the GitHub issue tracker.