Webby MCP Server

# Contributing to Webby Thank you for your interest in contributing to Webby! This document provides guidelines and instructions for contributing. ## Code of Conduct - Be respectful and inclusive - Focus on constructive feedback - Help others learn and grow ## How to Contribute ### Reporting Bugs When reporting bugs, please include: - Webby version - Node.js version - Operating system - Steps to reproduce - Expected vs actual behavior - Error messages/stack traces ### Suggesting Features Feature requests should include: - Clear description of the feature - Use case / problem it solves - Example usage (if applicable) - Why this should be in Webby vs a separate tool ### Pull Requests 1. **Fork the repository** 2. **Create a feature branch**: `git checkout -b feature/your-feature-name` 3. **Make your changes** 4. **Run tests**: `npm test` (if available) 5. **Build**: `npm run build` 6. **Commit**: Use clear, descriptive commit messages 7. **Push**: `git push origin feature/your-feature-name` 8. **Open a PR**: Describe your changes clearly ### Commit Message Guidelines ``` type(scope): short description Longer description if needed. Fixes #123 ``` **Types:** - `feat`: New feature - `fix`: Bug fix - `docs`: Documentation changes - `refactor`: Code refactoring - `test`: Adding/updating tests - `chore`: Maintenance tasks **Examples:** - `feat(performance): add WebPageTest browser automation` - `fix(security): handle SSL Labs timeout correctly` - `docs(readme): update API quota information` ## Development Setup ### Prerequisites - Node.js 18+ - npm 9+ - Git ### Setup Steps ```bash # Clone your fork git clone https://github.com/YOUR_USERNAME/webby.git cd webby # Install dependencies npm install # Build npm run build # Run locally node dist/index.js ``` ### Project Structure ``` webby/ ├── src/ │ ├── performance/ # Performance testing tools │ ├── accessibility/ # Accessibility testing tools │ ├── security/ # Security testing tools │ ├── shared/ # Shared utilities (browser, etc.) │ └── orchestrator/ # Category runners ├── __tests__/ # Test files ├── index.ts # Main MCP server entry └── package.json ``` ## Adding a New Tool ### 1. Create Tool Module ```typescript // src/category/tool-name.ts export interface ToolOptions { // Tool-specific options } export interface ToolResult { tool: 'tool_name'; success: boolean; // Tool-specific results error?: string; } export async function analyzeTool( url: string, options: ToolOptions = {} ): Promise<ToolResult> { try { // Implementation return { tool: 'tool_name', success: true, // ... results }; } catch (error) { return { tool: 'tool_name', success: false, error: error instanceof Error ? error.message : String(error), }; } } ``` ### 2. Add to Orchestrator Update `src/orchestrator/run-all.ts`: - Import your tool - Add to appropriate `run*()` function - Update result interface ### 3. Add MCP Tool Definition Update `index.ts`: - Import your function - Add Zod schema for validation - Add tool to `tools` array - Add case to `CallToolRequestSchema` handler ### 4. Update Documentation - Update `README.md` with tool description - Add usage examples - Update tool count - Document API keys/quotas if needed ## Testing ### Manual Testing ```bash # Build npm run build # Test with MCP Inspector (if available) # OR test via Claude Code with the tool enabled ``` ### Adding Tests ```typescript // __tests__/tool-name.test.ts describe('analyzeTool', () => { it('should return success for valid URL', async () => { const result = await analyzeTool('https://example.com'); expect(result.success).toBe(true); }); it('should handle errors gracefully', async () => { const result = await analyzeTool('invalid-url'); expect(result.success).toBe(false); expect(result.error).toBeDefined(); }); }); ``` ## Code Style - **TypeScript**: Strict mode enabled - **Formatting**: Use existing code style - **Naming**: Clear, descriptive names - **Comments**: Explain "why", not "what" - **Error handling**: Always catch and return errors gracefully ## Browser Automation Guidelines When adding browser-based tools: 1. **Use shared browser manager**: Import from `src/shared/browser-utils.ts` 2. **Set appropriate timeouts**: Default to reasonable values 3. **Clean up resources**: Always close pages in `finally` blocks 4. **Handle selectors defensively**: Use multiple fallbacks 5. **Add timeout options**: Let users configure wait times ## API Integration Guidelines When adding API-based tools: 1. **Document rate limits**: In code comments and README 2. **Handle errors**: Network, API errors, rate limits 3. **Return consistent format**: Follow existing tool patterns 4. **API keys**: Use options parameter, never hardcode 5. **Timeouts**: Set reasonable defaults ## Release Process Maintainers will: 1. Review and merge PRs 2. Update CHANGELOG.md 3. Bump version in package.json 4. Create GitHub release 5. Publish to npm (if/when applicable) ## Questions? - Open an issue for questions - Check existing issues/PRs first - Be patient and respectful ## License By contributing, you agree that your contributions will be licensed under the MIT License.