TickTick MCP Server

# Contributing to TickTick MCP Server Thanks for your interest in contributing! This guide will help you get started. ## Development Setup ### 1. Fork and Clone ```bash git fork https://github.com/yourusername/ticktick-mcp-server cd ticktick-mcp-server ``` ### 2. Install Dependencies ```bash pip install -r requirements.txt pip install -r requirements-dev.txt # If you create this for testing tools ``` ### 3. Set Up Environment Create a `.env` file with your TickTick credentials: ```bash TICKTICK_CLIENT_ID=your_client_id TICKTICK_CLIENT_SECRET=your_client_secret TICKTICK_REDIRECT_URI=http://127.0.0.1:8080 ``` ### 4. Authenticate ```bash python ticktick_rest_api.py --auth ``` ## Testing Your Changes ### Test the MCP Server Locally ```bash # Using MCP inspector mcp dev ticktick_mcp_server.py # Or test with Claude Desktop mcp install ticktick_mcp_server.py ``` ### Test the REST API Client ```bash # Test authentication python ticktick_rest_api.py --auth # Create a test task python ticktick_rest_api.py --test # Test full setup (creates projects and tasks) python ticktick_rest_api.py --setup ``` ### Test the CLI Tool ```bash python add_task.py "Test task" --priority 5 --due today ``` ## Code Style ### Python Style Guide - Follow PEP 8 - Use meaningful variable names - Add docstrings to all functions - Keep functions focused and single-purpose ### Example Function Structure ```python def create_task(title: str, priority: int = 0) -> dict: """ Create a new TickTick task Args: title: Task title priority: Task priority (0, 1, 3, or 5) Returns: Dict containing task data Raises: ValueError: If priority is invalid """ # Implementation here pass ``` ## What to Contribute ### Ideas for Contributions **High Priority:** - [ ] Add rate limiting to prevent API throttling - [ ] Support for task tags and labels - [ ] Task editing functionality - [ ] Task deletion through MCP - [ ] Error handling improvements - [ ] Add unit tests **Medium Priority:** - [ ] Support for subtasks/checklists - [ ] Recurring task creation via MCP - [ ] Custom reminders - [ ] Bulk operations (create multiple tasks at once) - [ ] Filter tasks by date range - [ ] Task search with advanced filters **Nice to Have:** - [ ] GitHub Actions for automated testing - [ ] Docker container support - [ ] Integration with other task managers (Todoist, etc.) - [ ] Web dashboard for task visualization - [ ] Webhook support for real-time updates ### Before Starting 1. **Check existing issues** - Someone might already be working on it 2. **Open an issue** - Describe what you want to add/fix 3. **Get feedback** - Wait for maintainer response before starting large changes ## Submitting Changes ### 1. Create a Branch ```bash git checkout -b feature/your-feature-name # or git checkout -b fix/bug-description ``` ### 2. Make Your Changes - Keep commits focused and atomic - Write clear commit messages - Test your changes thoroughly ### 3. Commit Convention Use conventional commits format: ```bash feat: add support for task tags fix: resolve authentication timeout issue docs: update MCP setup instructions refactor: simplify task creation logic test: add tests for project creation ``` ### 4. Push and Create PR ```bash git push origin feature/your-feature-name ``` Then create a Pull Request on GitHub with: - **Clear title** - Summarize what the PR does - **Description** - Explain why the change is needed - **Testing** - Describe how you tested the changes - **Screenshots** - If applicable (for docs or UI changes) ### PR Template ```markdown ## What does this PR do? Brief description of the changes ## Why is this needed? Explain the problem this solves ## How was this tested? - [ ] Tested with MCP inspector - [ ] Tested with Claude Desktop - [ ] Tested REST API client - [ ] Added unit tests (if applicable) ## Screenshots (if applicable) Add screenshots or GIFs ## Checklist - [ ] Code follows project style - [ ] Documentation updated - [ ] Tests pass - [ ] No breaking changes (or documented if necessary) ``` ## Testing Guidelines ### Manual Testing Checklist Before submitting a PR, test: **MCP Server:** - [ ] Server starts without errors - [ ] All tools work correctly - [ ] Resources load properly - [ ] Error messages are helpful **REST API Client:** - [ ] Authentication works - [ ] Tasks can be created - [ ] Tasks can be listed - [ ] Tasks can be completed - [ ] Projects can be created **CLI Tools:** - [ ] `add_task.py` works with all parameters - [ ] Error handling works correctly - [ ] Help text is accurate ### Future: Automated Tests We'd love to have automated tests! If you want to help: ```python # tests/test_mcp_server.py def test_add_task(): """Test task creation via MCP""" result = mcp.call_tool("add_task", { "title": "Test task", "priority": 5 }) assert "✓ Created task" in result # tests/test_rest_api.py def test_create_task(): """Test REST API task creation""" client = TickTickClient(...) task = client.create_task("Test") assert task['title'] == "Test" ``` ## Documentation ### When to Update Docs Update documentation when you: - Add new features - Change existing behavior - Fix bugs that affect usage - Add new configuration options ### Which Files to Update - **README.md** - Main project overview - **MCP_README.md** - MCP server setup and usage - **EXAMPLES.md** - Add usage examples - **CLAUDE.md** - Technical architecture (if needed) - **Docstrings** - Keep inline documentation up to date ## Community Guidelines ### Be Respectful - Be kind and respectful in all interactions - Provide constructive feedback - Help others learn - Celebrate contributions ### Communication - Use GitHub issues for bugs and feature requests - Use GitHub Discussions for questions and ideas - Be patient - maintainers are volunteers ## Questions? - **Bug reports:** Open an issue with detailed reproduction steps - **Feature requests:** Open an issue describing the use case - **Questions:** Use GitHub Discussions or open an issue - **Security issues:** Email directly (don't open public issues) ## License By contributing, you agree that your contributions will be licensed under the MIT License. ## Thank You! Every contribution helps make this project better. Whether it's: - Reporting a bug - Fixing a typo - Adding a feature - Improving documentation - Helping other users **Your contribution matters. Thank you!**