GitHub MCP Server

mcp-github
memory-bank
# Technical Context

## Technologies

### Core Stack
- **Python 3.9+**
  - Modern Python features
  - Type hinting support
  - Async capabilities

### Dependencies
1. **MCP SDK**
   - `@modelcontextprotocol/sdk`
   - Server implementation
   - Protocol handling

2. **GitHub API**
   - PyGithub package
   - REST API interaction
   - Rate limit handling

3. **Development Tools**
   - uv (dependency management)
   - Black (code formatting)
   - MyPy (static type checking)
   - Pytest (testing framework)

## Development Setup

### Environment Requirements
```bash
# Python version
Python 3.9+

# Required system packages
git
python3-venv
python3-pip

# Virtual environment
python -m venv .venv
source .venv/bin/activate
```

### Project Structure
```
mcp-github/
├── pyproject.toml        # Project metadata and dependencies
├── poetry.lock          # Locked dependencies
├── src/
│   └── mcp_github/     # Main package
│       ├── __init__.py
│       ├── server.py    # MCP server implementation
│       ├── github.py    # GitHub API client
│       ├── commands/    # Command implementations
│       └── tools/       # MCP tool definitions
├── tests/              # Test suite
└── docs/              # Documentation
```

## Technical Constraints

### 1. Authentication
- GitHub Personal Access Token required
- Secure token storage
- Token scope limitations

### 2. Rate Limiting
- GitHub API rate limits
- Cache implementation
- Rate limit handling

### 3. Dependencies
- Minimum dependency footprint
- Maintained packages only
- Security considerations

### 4. Performance
- Async operations where beneficial
- Response caching
- Efficient API usage

## Configuration

### Environment Variables
```bash
GITHUB_TOKEN=            # GitHub Personal Access Token
GITHUB_API_URL=         # GitHub API URL (optional)
LOG_LEVEL=             # Logging level (optional)
CACHE_TTL=            # Cache time-to-live (optional)
```

### Development Configuration
```toml
[project]
name = "mcp-github"
version = "0.1.0"
description = "GitHub MCP server for Cline"
requires-python = ">=3.10"
dependencies = [
    "PyGithub>=2.6.0",
    "mcp>=1.2.1"
]

[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "black>=23.7.0",
    "mypy>=1.5.1"
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
```

## Testing Strategy
- Unit tests for each component
- Integration tests with GitHub API
- Mock MCP client
- GitHub API response mocking
- Comprehensive error testing

## Error Handling
- Custom exception hierarchy
- Detailed error messages
- Error translation to MCP format
- Logging for debugging

## Security Considerations
- Token validation
- Secure credential storage
- Input validation
- Rate limit protection
- Error message sanitization