Shortcut MCP

# Contributing to Shortcut MCP Thank you for your interest in contributing to Shortcut MCP! This document provides guidelines and information for contributors. ## 🤝 How to Contribute ### Reporting Issues 1. **Search existing issues** to avoid duplicates 2. **Use issue templates** when available 3. **Provide detailed information** including: - macOS version - Node.js version - Steps to reproduce - Expected vs actual behavior - Error messages and logs ### Suggesting Features 1. **Check the roadmap** to see if it's already planned 2. **Open a feature request** with: - Clear use case description - Proposed implementation approach - Potential breaking changes - Alternative solutions considered ### Code Contributions 1. **Fork the repository** 2. **Create a feature branch** from `main` 3. **Make your changes** following our coding standards 4. **Add tests** for new functionality 5. **Update documentation** as needed 6. **Submit a pull request** ## 🛠️ Development Setup ### Prerequisites - macOS 12.0+ (for Shortcuts integration) - Node.js 18.0+ - Git ### Local Development ```bash # Clone your fork git clone https://github.com/YOUR_USERNAME/shortcut-mcp.git cd shortcut-mcp # Install dependencies npm install # Create a feature branch git checkout -b feature/your-feature-name # Start development with hot reload npm run dev # Run tests npm test # Run linting npm run lint # Fix linting issues npm run lint:fix ``` ### Testing ```bash # Run unit tests npm test # Run tests with coverage npm run test:coverage # Run integration tests npm run test:integration # Run all tests npm run test:all ``` ## 📝 Coding Standards ### TypeScript Guidelines - Use **strict TypeScript** configuration - Prefer **interfaces over types** for object shapes - Use **explicit return types** for public methods - Avoid **any** type - use proper typing - Use **meaningful variable names** ### Code Style - Follow the **ESLint configuration** - Use **Prettier** for formatting - Use **JSDoc comments** for public APIs - Follow **conventional commit** messages ### File Organization ``` src/ ├── types/ # Type definitions ├── utils/ # Utility functions ├── shortcuts/ # Shortcut management ├── security/ # Security layer ├── tools/ # MCP tools └── tests/ # Test files ``` ### Naming Conventions - **Files**: kebab-case (`shortcut-manager.ts`) - **Classes**: PascalCase (`ShortcutManager`) - **Functions/Variables**: camelCase (`executeShortcut`) - **Constants**: UPPER_SNAKE_CASE (`MAX_TIMEOUT`) - **Interfaces**: PascalCase with descriptive names (`ShortcutExecutionResult`) ## 🧪 Testing Guidelines ### Unit Tests - Test **individual functions** in isolation - Mock **external dependencies** - Use **descriptive test names** - Follow **AAA pattern** (Arrange, Act, Assert) ```typescript describe('ShortcutManager', () => { describe('executeShortcut', () => { it('should execute shortcut successfully with valid input', async () => { // Arrange const manager = new ShortcutManager(mockConfig, mockLogger); const request = { name: 'Test Shortcut', input: 'test' }; // Act const result = await manager.executeShortcut(request); // Assert expect(result.success).toBe(true); expect(result.output).toBeDefined(); }); }); }); ``` ### Integration Tests - Test **component interactions** - Use **real configurations** when possible - Test **error scenarios** - Verify **security policies** ### Test Coverage - Aim for **>90% code coverage** - Cover **error paths** - Test **edge cases** - Include **performance tests** for critical paths ## 📖 Documentation Standards ### Code Documentation - Use **JSDoc** for all public APIs - Include **parameter descriptions** - Provide **usage examples** - Document **error conditions** ```typescript /** * Executes a macOS shortcut with the provided parameters. * * @param request - The shortcut execution request * @param request.name - Name of the shortcut to execute * @param request.input - Optional input data for the shortcut * @param request.timeout - Execution timeout in milliseconds * @returns Promise resolving to execution result * * @throws {ShortcutNotFoundError} When the specified shortcut doesn't exist * @throws {SecurityError} When security policies prevent execution * @throws {TimeoutError} When execution exceeds the timeout limit * * @example * ```typescript * const result = await manager.executeShortcut({ * name: 'Weather Report', * input: 'San Francisco', * timeout: 10000 * }); * ``` */ async executeShortcut(request: ExecutionRequest): Promise<ExecutionResult> ``` ### README Updates - Keep **installation instructions** current - Update **feature lists** for new capabilities - Add **usage examples** for new tools - Update **configuration options** ### API Documentation - Document **all MCP tools** - Include **JSON schema** definitions - Provide **request/response examples** - Document **error codes** ## 🔒 Security Considerations ### Security Review Process All contributions are reviewed for security implications: - **Input validation** requirements - **Permission model** compliance - **Audit logging** coverage - **Error information** disclosure ### Security Guidelines - **Validate all inputs** before processing - **Sanitize outputs** to prevent information leakage - **Use allowlists** instead of blocklists when possible - **Log security events** for monitoring - **Follow principle of least privilege** ### Sensitive Information - **Never log** sensitive data (passwords, tokens, etc.) - **Redact** sensitive information in error messages - **Use secure defaults** in configuration - **Document security implications** of new features ## 🚀 Release Process ### Version Numbering We follow [Semantic Versioning](https://semver.org/): - **MAJOR**: Breaking changes - **MINOR**: New features (backward compatible) - **PATCH**: Bug fixes (backward compatible) ### Release Checklist 1. **Update version** in package.json 2. **Update CHANGELOG.md** 3. **Run full test suite** 4. **Update documentation** 5. **Create release notes** 6. **Tag the release** ### Changelog Format ```markdown ## [1.2.0] - 2024-01-15 ### Added - New shortcut filtering by category - Enhanced error reporting with suggestions ### Changed - Improved caching performance - Updated security policy validation ### Fixed - Fixed timeout handling for long-running shortcuts - Resolved race condition in concurrent executions ### Security - Enhanced input sanitization - Added rate limiting for API calls ``` ## 🤔 Questions and Support ### Getting Help - **GitHub Issues**: For bugs and feature requests - **Discussions**: For questions and general discussions - **Documentation**: Check existing docs first - **Code Review**: Ask questions in pull request comments ### Communication Guidelines - Be **respectful** and **constructive** - Provide **context** for your questions - Use **clear, descriptive titles** - Follow up on **your issues** and PRs ## 📋 Pull Request Template ```markdown ## Description Brief description of the changes ## Type of Change - [ ] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that causes existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring ## Testing - [ ] Unit tests pass - [ ] Integration tests pass - [ ] Manual testing completed - [ ] New tests added for changes ## Documentation - [ ] Code comments updated - [ ] API documentation updated - [ ] README updated (if needed) - [ ] CHANGELOG updated ## Security - [ ] No sensitive information exposed - [ ] Input validation implemented - [ ] Security policies respected - [ ] Audit logging included (if applicable) ## Checklist - [ ] Code follows project style guidelines - [ ] Self-review completed - [ ] Breaking changes documented - [ ] All tests pass ``` ## 🏆 Recognition Contributors will be recognized in: - **Contributors section** of README - **Release notes** for significant contributions - **GitHub contributors** graph - **Special mentions** for major features Thank you for contributing to Shortcut MCP! Your efforts help make macOS automation more accessible to everyone. --- **Author**: aezi zhu **GitHub**: [@aezizhu](https://github.com/aezizhu) **Project**: [shortcut-mcp](https://github.com/aezizhu/shortcut-mcp)