mcp-oauth-mcpserver-blueprint: Instructions file for GitHub Copilot

GitHub Copilot Instructions for MCP OAuth Server

Project Overview

This project is a Model Context Protocol (MCP) server with OAuth 2.1 authentication support, built in Python using FastMCP and Authlib. The server provides secure authentication for accessing third-party APIs (specifically GitHub) and is designed to be containerized with Docker.

Code Style and Standards

Python Style

• Python Version: Target Python 3.12
• Formatting: Use Black with 100 character line length
• Linting: Follow Ruff configuration in pyproject.toml
• Type Hints: All functions must have complete type hints
• Docstrings: Use Google-style docstrings for all public functions and classes
• Naming Conventions:
  • Classes: PascalCase (e.g., OAuthHandler)
  • Functions/methods: snake_case (e.g., get_authorization_url)
  • Constants: UPPER_SNAKE_CASE (e.g., DEFAULT_TIMEOUT)
  • Private methods: prefix with underscore (e.g., _internal_method)

Code Organization

• Keep modules focused and single-purpose
• Use dependency injection for testability
• Separate configuration, business logic, and I/O
• Follow the existing project structure

Error Handling

• Use specific exception types
• Provide clear, actionable error messages
• Log errors with appropriate context
• Never suppress exceptions without explicit reason
• ALWAYS use exception chaining: Use raise ... from err or raise ... from None

  # Good: Shows exception chain
  try:
      result = api_call()
  except Exception as e:
      raise ValueError(f"API call failed: {e}") from e
  
  # Bad: Hides the original exception
  try:
      result = api_call()
  except Exception as e:
      raise ValueError(f"API call failed: {e}")
  

Code Quality Rules (Ruff)

The project uses Ruff for linting with the following enabled rules:

• E/W: pycodestyle errors and warnings (PEP 8 compliance)
• F: pyflakes (detect unused imports, undefined names, etc.)
• I: isort (import sorting)
• B: flake8-bugbear (common bugs and design problems)
• C4: flake8-comprehensions (better list/dict/set comprehensions)
• UP: pyupgrade (modern Python syntax)