PyGithub MCP Server

# PyGithub MCP Server Project Rules This file contains project-specific preferences, troubleshooting tips, and practical guidelines that complement the formal documentation in the `docs/` directory. > Note: For comprehensive information on system architecture and implementation patterns, refer to `docs/system_patterns.md`. For details on the technology stack and development setup, see `docs/tech_context.md`. ## Development Environment Tips ### Build and Environment - Use uv for dependency management and virtual environments - Activate virtual environment before running tools: ```bash source .venv/bin/activate # On Windows: .venv\Scripts\activate ``` - No need to source the venv repeatedly if you're already in it - only source it once per session ### MCP Configuration - Use direct venv Python interpreter in MCP settings: ```json { "command": "/path/to/project/.venv/bin/python", "args": ["-m", "pygithub_mcp_server"] } ``` - Avoid using uvx/uv run in MCP settings to prevent dependency resolution issues - Always include necessary environment variables (e.g., GITHUB_PERSONAL_ACCESS_TOKEN) ## MCP Tool Testing - Human-driven user acceptance testing can be done using MCP Inspector: ```bash source .venv/bin/activate # Must activate venv first npx @modelcontextprotocol/inspector -e GITHUB_PERSONAL_ACCESS_TOKEN=your-token-here uv run pygithub_mcp_server ``` - Use MCP Inspector's Web UI to experiment with available tools - Test both success and error cases with real GitHub repositories ## Pytest Usage Tips - Run tests efficiently without verbose output by default: ```bash pytest tests/test_file.py -q --tb=no --cov=path/to/coverage ``` - Only use verbose mode (-v) for debugging specific failing tests: ```bash pytest tests/test_file.py::test_specific_function -v ``` - Keep test output clean and manageable - Use coverage reporting to identify gaps ## Logging Configuration - The project-wide logging level is controlled in `src/pygithub_mcp_server/server.py` - This file configures the root logger, which affects all loggers in the system - Default log level is set to INFO to prevent excessive debug logging during tests - To increase verbosity for debugging, change both logger.setLevel() and logging.basicConfig() to DEBUG - To decrease logging during tests beyond what --log-level=INFO can do, ensure the server.py log level is appropriately set ## Testing Guidelines and Patterns ### Error Object Creation - Always use the correct GitHubError constructor pattern: ```python # CORRECT - status should be part of the response dict error = GitHubError("Not found", response={"status": 404}) # INCORRECT - status is not a parameter of GitHubError error = GitHubError("Not found", status=404) # This will fail! ``` - When creating error objects in tests, follow the same patterns used in production code - Check the appropriate constructor signatures in the exceptions module ## Common Troubleshooting ### MCP Server Issues - If MCP server fails to start, verify venv Python path in settings - For dependency errors, ensure all requirements are installed in venv - For GitHub API errors, check token permissions and validity - For build errors, ensure virtual environment is activated - When using MCP Inspector, ensure GITHUB_PERSONAL_ACCESS_TOKEN is set in environment ### Debugging Techniques - Check pygithub_mcp_server.log for detailed error logs - Log file contains all API interactions and error traces - Both file and console logging enabled - Log file is created in the project root directory - Log format includes timestamps and module names for tracing ### Git MCP Server Cautions - NEVER use `"."` as a file parameter in git_add operations: ```javascript // DANGEROUS - can track .git directory and cause repository corruption { "repo_path": "/path/to/repo", "files": ["."] } ``` - Always specify individual files or directories explicitly: ```javascript // SAFE - explicitly lists only the files/directories you want to track { "repo_path": "/path/to/repo", "files": [ "src/", "tests/", "docs/", "pyproject.toml", "README.md" ] } ``` - If repository tracking becomes corrupted (showing .git files as modified): 1. Create a backup of important files 2. Reset the repository: `git fetch origin && git reset --hard origin/main` 3. Restore VS Code Git integration: `git config branch.main.vscode-merge-base origin/main` 4. Selectively add back your changes with specific paths - Periodically verify ignored paths with `git check-ignore -v <path>` ## Command Reference ### Common Tasks - Update documentation: `python -m scripts.update_docs` - Run specific test group: `pytest tests/integration/ -v --run-integration` - Check linting: `python -m pylint src tests` - Format code: `python -m black src tests` - Generate coverage report: `pytest --cov=src/pygithub_mcp_server`