websketch-mcp

MCP server exposing WebSketch IR tools for LLM agents.

Features

• 🎨 websketch_render: Render WebSketch IR captures to ASCII wireframes
• 🔍 websketch_diff: Compute diffs between UI captures
• 🔑 websketch_fingerprint: Generate deterministic fingerprints for captures

Installation

npm

npm install -g websketch-mcp

From Source

git clone https://github.com/mcp-tool-shop-org/websketch-mcp.git
cd websketch-mcp
npm ci
npm run build
npm link

Usage

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "websketch": {
      "command": "websketch-mcp"
    }
  }
}

Programmatic

# Run as stdio server
websketch-mcp

Or programmatically in Node.js:

import { spawn } from 'child_process';

const server = spawn('websketch-mcp', [], {
  stdio: ['pipe', 'pipe', 'inherit'],
});

// Send MCP protocol messages via stdin/stdout

Tools

websketch_render

Render a WebSketch IR capture to ASCII wireframe.

Input:

{
  "capture": {
    "root": {
      "type": "Frame",
      "id": "root",
      "children": [...]
    }
  }
}

Output:

┌─────────────────────┐
│ Frame (root)        │
│ ├── Button (#btn1)  │
│ └── Text (#text1)   │
└─────────────────────┘

websketch_diff

Compute a diff between two WebSketch IR captures.

Input:

{
  "before": { "root": {...} },
  "after": { "root": {...} }
}

Output:

{
  "added": [...],
  "removed": [...],
  "modified": [...]
}

websketch_fingerprint

Generate a deterministic fingerprint for a capture.

Input:

{
  "capture": { "root": {...} }
}

Output:

abc123def456...

Development

Prerequisites

• Node.js 18+
• npm

Setup

# Clone the repository
git clone https://github.com/mcp-tool-shop-org/websketch-mcp.git
cd websketch-mcp

# Install dependencies
npm ci

# Build
npm run build

# Run tests
npm test

# Type check
npm run typecheck

# Lint
npm run lint

Scripts

npm run build         # Compile TypeScript to dist/
npm run dev           # Watch mode compilation
npm run start         # Run the compiled server
npm run typecheck     # Type checking without emit
npm run lint          # Run ESLint
npm run lint:fix      # Fix ESLint issues
npm test              # Run tests in watch mode
npm run test:run      # Run tests once
npm run test:coverage # Generate coverage report
npm run clean         # Remove dist/ folder

Project Structure

websketch-mcp/
├── src/
│   └── index.ts          # Main server implementation
├── tests/
│   └── smoke.test.ts     # Test files
├── scripts/
│   └── add-shebang.js    # Post-build script
├── .github/
│   ├── workflows/
│   │   ├── ci.yml        # CI pipeline
│   │   └── security.yml  # Security scanning
│   └── dependabot.yml    # Dependency updates
├── dist/                 # Compiled output (gitignored)
├── package.json          # Package configuration
├── tsconfig.json         # TypeScript configuration
├── vitest.config.ts      # Test configuration
└── .eslintrc.cjs         # ESLint configuration

Testing

# Run all tests
npm test

# Run tests once (for CI)
npm run test:run

# Generate coverage report
npm run test:coverage

Tests are written using Vitest. See tests/ directory for examples.

Publishing

The package is configured with pre-publish safety checks:

# This will automatically:
# 1. Run type checking
# 2. Run linting
# 3. Run tests
# 4. Build the package
npm publish

Manual publish steps:

# Bump version
npm version patch|minor|major

# Publish to npm
npm publish

# Push tags
git push --follow-tags

Troubleshooting

CLI Not Found After Install

# Ensure global bin directory is in PATH
npm config get prefix

# Or use npx
npx websketch-mcp

Build Failures

# Clean and rebuild
npm run clean
npm ci
npm run build

Permission Errors on Unix

The post-build script automatically makes dist/index.js executable. If you encounter issues:

chmod +x dist/index.js

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT - see LICENSE file for details.

Links

• WebSketch IR: github.com/mcp-tool-shop-org/websketch-ir
• Model Context Protocol: modelcontextprotocol.io
• Issues: github.com/mcp-tool-shop-org/websketch-mcp/issues

Support

For questions or issues, please open an issue on GitHub.