mcp-proxy-oauth-dcr 0.1.0__tar.gz

mcp_proxy_oauth_dcr-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,267 @@
+# MCP Proxy Architecture
+
+## Overview
+
+This document describes the architecture and structure of the MCP Proxy with OAuth DCR support.
+
+## Project Structure
+
+```
+mcp-proxy/
+├── src/
+│   └── mcp_proxy/
+│       ├── __init__.py              # Main package exports
+│       ├── models.py                # Core data models (Pydantic)
+│       ├── protocols.py             # Protocol interfaces (typing.Protocol)
+│       ├── exceptions.py            # Custom exception hierarchy
+│       ├── logging_config.py        # Structured logging setup
+│       ├── auth/                    # Authentication module
+│       │   ├── __init__.py
+│       │   └── manager.py           # OAuth DCR implementation (TBD)
+│       ├── config/                  # Configuration module
+│       │   ├── __init__.py
+│       │   └── manager.py           # Config loading/validation (TBD)
+│       ├── http/                    # HTTP client module
+│       │   ├── __init__.py
+│       │   └── client.py            # HTTP MCP client (TBD)
+│       ├── stdio/                   # Stdio interface module
+│       │   ├── __init__.py
+│       │   └── interface.py         # Stdio communication (TBD)
+│       └── translator/              # Protocol translator module
+│           ├── __init__.py
+│           └── translator.py        # Protocol conversion (TBD)
+├── tests/
+│   ├── __init__.py
+│   ├── conftest.py                  # Pytest fixtures
+│   └── test_models.py               # Model tests
+├── .kiro/
+│   └── specs/
+│       └── mcp-proxy-oauth-dcr/     # Feature specifications
+├── pyproject.toml                   # Project configuration
+├── README.md                        # User documentation
+├── ARCHITECTURE.md                  # This file
+└── .gitignore                       # Git ignore rules
+```
+
+## Core Components
+
+### 1. Data Models (`models.py`)
+
+Defines all data structures using Pydantic for validation:
+
+- **JsonRpcMessage**: JSON-RPC 2.0 message structure
+- **HttpMcpRequest/Response**: HTTP MCP protocol structures
+- **ClientCredentials**: OAuth client credentials
+- **OAuthTokenResponse**: OAuth token response
+- **AuthenticationState**: Current authentication state
+- **SessionState**: MCP session state
+- **MessageCorrelation**: Request/response correlation tracking
+- **ProxyConfig**: Proxy configuration
+
+### 2. Protocol Interfaces (`protocols.py`)
+
+Defines abstract interfaces using `typing.Protocol`:
+
+- **StdioInterface**: Stdio communication interface
+- **ProtocolTranslator**: Protocol translation interface
+- **AuthenticationManager**: OAuth DCR and token management interface
+- **HttpClient**: HTTP communication interface
+- **ConfigurationManager**: Configuration management interface
+
+### 3. Exception Hierarchy (`exceptions.py`)
+
+Custom exceptions for error handling:
+
+- **McpProxyError**: Base exception
+  - **ProtocolError**: Protocol translation errors
+  - **AuthenticationError**: Authentication errors
+  - **NetworkError**: Network and connection errors
+  - **ConfigurationError**: Configuration errors
+
+### 4. Logging (`logging_config.py`)
+
+Structured logging using `structlog`:
+
+- Configurable log levels
+- JSON output for production
+- Console output for development
+- Context variable support
+
+## Module Organization
+
+### Authentication Module (`auth/`)
+
+Handles OAuth Dynamic Client Registration and token management:
+
+- DCR protocol implementation (RFC 7591)
+- Token acquisition and refresh
+- Credential storage and lifecycle
+- Authentication state management
+
+### Configuration Module (`config/`)
+
+Manages proxy configuration:
+
+- Environment variable loading
+- Configuration file parsing
+- Parameter validation
+- Default value management
+
+### HTTP Module (`http/`)
+
+HTTP communication with backend MCP servers:
+
+- aiohttp-based async HTTP client
+- Server-Sent Events (SSE) support
+- Connection pooling and retry logic
+- Session management
+
+### Stdio Module (`stdio/`)
+
+Stdio interface for Kiro communication:
+
+- Async stdin/stdout handling
+- JSON-RPC message parsing
+- Newline-delimited message protocol
+- Subprocess lifecycle management
+
+### Translator Module (`translator/`)
+
+Protocol translation between stdio and HTTP:
+
+- Stdio to HTTP conversion
+- HTTP to stdio conversion
+- Message correlation tracking
+- Error translation
+
+## Design Principles
+
+### 1. Separation of Concerns
+
+Each module has a single, well-defined responsibility:
+
+- Models: Data structures only
+- Protocols: Interface definitions only
+- Implementations: Concrete behavior in separate modules
+
+### 2. Dependency Injection
+
+Components depend on protocol interfaces, not concrete implementations:
+
+```python
+class ProxyOrchestrator:
+    def __init__(
+        self,
+        auth_manager: AuthenticationManager,
+        http_client: HttpClient,
+        translator: ProtocolTranslator,
+    ):
+        ...
+```
+
+### 3. Async/Await
+
+All I/O operations use async/await for concurrency:
+
+- Stdio communication
+- HTTP requests
+- Token refresh
+- Message processing
+
+### 4. Type Safety
+
+Strong typing throughout:
+
+- Pydantic models for runtime validation
+- Type hints for static analysis
+- Protocol interfaces for structural typing
+
+### 5. Error Handling
+
+Comprehensive error handling:
+
+- Custom exception hierarchy
+- Error translation between protocols
+- Graceful degradation
+- Detailed error messages
+
+## Testing Strategy
+
+### Unit Tests
+
+Test individual components in isolation:
+
+- Model validation
+- Protocol translation
+- Authentication flows
+- Configuration parsing
+
+### Property-Based Tests
+
+Test universal properties using Hypothesis:
+
+- Protocol compliance
+- Message correlation
+- Token lifecycle
+- Configuration validation
+
+### Integration Tests
+
+Test component interactions:
+
+- End-to-end message flow
+- Authentication integration
+- Error handling
+- Connection resilience
+
+## Development Workflow
+
+### 1. Setup
+
+```bash
+python3 -m venv venv
+source venv/bin/activate  # or venv\Scripts\activate on Windows
+pip install -e ".[dev]"
+```
+
+### 2. Testing
+
+```bash
+# Run all tests
+pytest
+
+# Run specific test file
+pytest tests/test_models.py
+
+# Run with coverage
+pytest --cov=mcp_proxy --cov-report=html
+```
+
+### 3. Code Quality
+
+```bash
+# Format code
+black src tests
+isort src tests
+
+# Type checking
+mypy src
+
+# Linting
+flake8 src tests
+```
+
+## Next Steps
+
+The following components need implementation:
+
+1. **Configuration Manager** (Task 2)
+2. **JSON-RPC Message Handling** (Task 3)
+3. **Stdio Interface** (Task 4)
+4. **OAuth DCR Authentication** (Task 6)
+5. **HTTP Client** (Task 7)
+6. **Protocol Translator** (Task 8)
+7. **Main Proxy Orchestration** (Task 11)
+8. **CLI Interface** (Task 12)
+
+Each task builds on the foundation established in Task 1.

mcp_proxy_oauth_dcr-0.1.0/DEVELOPMENT.md

@@ -0,0 +1,360 @@
+# Development Guide
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.8 or higher
+- pip and venv
+- Git
+
+### Initial Setup
+
+1. Clone the repository:
+```bash
+git clone <repository-url>
+cd mcp-proxy
+```
+
+2. Create and activate virtual environment:
+```bash
+python3 -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+```
+
+3. Install development dependencies:
+```bash
+pip install -e ".[dev]"
+```
+
+## Project Structure
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for detailed architecture documentation.
+
+## Development Tasks
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run specific test file
+pytest tests/test_models.py
+
+# Run with verbose output
+pytest -v
+
+# Run with coverage
+pytest --cov=mcp_proxy --cov-report=html
+
+# Run only unit tests
+pytest -m unit
+
+# Run only property-based tests
+pytest -m property
+```
+
+### Code Formatting
+
+```bash
+# Format Python code
+black src tests
+
+# Sort imports
+isort src tests
+
+# Format everything
+black src tests && isort src tests
+```
+
+### Type Checking
+
+```bash
+# Run mypy type checker
+mypy src
+
+# Check specific file
+mypy src/mcp_proxy/models.py
+```
+
+### Linting
+
+```bash
+# Run flake8 linter
+flake8 src tests
+
+# Check specific file
+flake8 src/mcp_proxy/models.py
+```
+
+### Running All Quality Checks
+
+```bash
+# Format, type check, and lint
+black src tests && \
+isort src tests && \
+mypy src && \
+flake8 src tests && \
+pytest
+```
+
+## Code Style Guidelines
+
+### Python Style
+
+- Follow PEP 8 style guide
+- Use Black for automatic formatting (line length: 88)
+- Use isort for import sorting
+- Use type hints for all function signatures
+- Write docstrings for all public functions and classes
+
+### Docstring Format
+
+```python
+def function_name(param1: str, param2: int) -> bool:
+    """Brief description of function.
+    
+    Longer description if needed, explaining the purpose,
+    behavior, and any important details.
+    
+    Args:
+        param1: Description of param1
+        param2: Description of param2
+        
+    Returns:
+        Description of return value
+        
+    Raises:
+        ExceptionType: When this exception is raised
+    """
+    pass
+```
+
+### Type Hints
+
+Always use type hints:
+
+```python
+from typing import Optional, List, Dict
+
+def process_data(
+    data: List[str],
+    config: Optional[Dict[str, Any]] = None
+) -> bool:
+    ...
+```
+
+### Error Handling
+
+Use custom exceptions from `exceptions.py`:
+
+```python
+from mcp_proxy.exceptions import AuthenticationError, DcrError
+
+def authenticate() -> None:
+    try:
+        # Authentication logic
+        pass
+    except Exception as e:
+        raise AuthenticationError("Authentication failed", details=str(e))
+```
+
+## Testing Guidelines
+
+### Unit Tests
+
+- Test individual functions and classes
+- Use fixtures from `conftest.py`
+- Mock external dependencies
+- Test both success and failure cases
+
+Example:
+```python
+def test_valid_config(sample_config):
+    """Test that valid configuration is accepted."""
+    assert sample_config.log_level == "info"
+    assert sample_config.retry_attempts == 3
+```
+
+### Property-Based Tests
+
+- Use Hypothesis for property-based testing
+- Test universal properties that should hold for all inputs
+- Generate diverse test data
+
+Example:
+```python
+from hypothesis import given, strategies as st
+
+@given(st.text(), st.integers())
+def test_message_correlation(request_id, http_id):
+    """Test that message correlation works for any IDs."""
+    # Test logic
+    pass
+```
+
+### Test Organization
+
+- Place tests in `tests/` directory
+- Name test files `test_*.py`
+- Name test functions `test_*`
+- Group related tests in classes
+- Use descriptive test names
+
+## Logging
+
+Use structured logging:
+
+```python
+from mcp_proxy.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+logger.info("processing_request", request_id=123, method="tools/list")
+logger.error("authentication_failed", error=str(e))
+```
+
+## Debugging
+
+### Enable Debug Logging
+
+```python
+from mcp_proxy.logging_config import configure_logging
+
+configure_logging(log_level="debug")
+```
+
+### Using Python Debugger
+
+```python
+import pdb; pdb.set_trace()  # Set breakpoint
+```
+
+### VS Code Debug Configuration
+
+Create `.vscode/launch.json`:
+
+```json
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python: Current File",
+            "type": "python",
+            "request": "launch",
+            "program": "${file}",
+            "console": "integratedTerminal",
+            "justMyCode": false
+        },
+        {
+            "name": "Python: Pytest",
+            "type": "python",
+            "request": "launch",
+            "module": "pytest",
+            "args": ["-v"],
+            "console": "integratedTerminal",
+            "justMyCode": false
+        }
+    ]
+}
+```
+
+## Common Development Tasks
+
+### Adding a New Model
+
+1. Define model in `src/mcp_proxy/models.py`
+2. Add validation using Pydantic validators
+3. Export from `src/mcp_proxy/__init__.py`
+4. Write tests in `tests/test_models.py`
+5. Update documentation
+
+### Adding a New Exception
+
+1. Define exception in `src/mcp_proxy/exceptions.py`
+2. Inherit from appropriate base exception
+3. Export from `src/mcp_proxy/__init__.py`
+4. Update error code mapping if needed
+5. Document when it's raised
+
+### Adding a New Component
+
+1. Create module directory under `src/mcp_proxy/`
+2. Define protocol interface in `protocols.py`
+3. Implement concrete class in module
+4. Write unit tests
+5. Write integration tests
+6. Update documentation
+
+## Git Workflow
+
+### Commit Messages
+
+Use conventional commit format:
+
+```
+type(scope): brief description
+
+Longer description if needed
+
+- Bullet points for details
+- Reference issues: #123
+```
+
+Types:
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation
+- `test`: Tests
+- `refactor`: Code refactoring
+- `style`: Code style changes
+- `chore`: Maintenance tasks
+
+### Branch Naming
+
+- `feature/description`: New features
+- `fix/description`: Bug fixes
+- `docs/description`: Documentation
+- `test/description`: Tests
+
+## Troubleshooting
+
+### Import Errors
+
+If you get import errors, ensure the package is installed in editable mode:
+
+```bash
+pip install -e .
+```
+
+### Test Failures
+
+1. Check test output for specific failure
+2. Run single test: `pytest tests/test_file.py::test_name -v`
+3. Enable debug logging in test
+4. Use debugger to step through code
+
+### Type Checking Errors
+
+1. Ensure all functions have type hints
+2. Check for missing imports
+3. Use `# type: ignore` for known issues (sparingly)
+4. Update type stubs if needed
+
+## Resources
+
+- [Pydantic Documentation](https://docs.pydantic.dev/)
+- [Pytest Documentation](https://docs.pytest.org/)
+- [Hypothesis Documentation](https://hypothesis.readthedocs.io/)
+- [Structlog Documentation](https://www.structlog.org/)
+- [aiohttp Documentation](https://docs.aiohttp.org/)
+- [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification)
+- [OAuth 2.0 DCR (RFC 7591)](https://tools.ietf.org/html/rfc7591)
+
+## Getting Help
+
+- Check existing documentation
+- Review test examples
+- Ask in team chat
+- Create an issue for bugs or feature requests

mcp_proxy_oauth_dcr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 MCP Proxy Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_proxy_oauth_dcr-0.1.0/MANIFEST.in

@@ -0,0 +1,42 @@
+# MANIFEST.in - Include additional files in the distribution package
+# This ensures that non-Python files are included when building the package
+
+# Include documentation files
+include README.md
+include LICENSE
+include ARCHITECTURE.md
+include DEVELOPMENT.md
+include PROXY_USAGE.md
+
+# Include example configuration files
+include examples/.env.example
+include examples/config.json.example
+include examples/CLI_USAGE.md
+
+# Include example scripts
+include examples/run_proxy.py
+include examples/authenticated_client_example.py
+
+# Include type stubs if any
+recursive-include src/mcp_proxy *.pyi
+
+# Exclude unnecessary files from the distribution
+global-exclude __pycache__
+global-exclude *.py[co]
+global-exclude .DS_Store
+global-exclude *.so
+global-exclude *.dylib
+
+# Exclude test files
+prune tests
+prune .pytest_cache
+prune htmlcov
+
+# Exclude development files
+exclude .coverage
+exclude coverage.xml
+exclude .gitignore
+exclude verify_stdio_interface.py
+prune .kiro
+prune venv
+prune .mypy_cache