aio-tests-mcp 0.1.0__tar.gz

aio_tests_mcp-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Secrets
+.env
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+dist/
+*.egg-info/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.idea/
+.vscode/

aio_tests_mcp-0.1.0/.kiro/settings/mcp.json

@@ -0,0 +1,15 @@
+{
+  "mcpServers": {
+    "aio-tests": {
+      "command": "/Users/rsharma/Downloads/Projects/MCP Servers/.venv/bin/python",
+      "args": ["-m", "aio_tests_mcp.server"],
+      "env": {
+        "AIO_API_TOKEN": "${AIO_API_TOKEN}",
+        "AIO_PROJECT_KEY": "BSTDV001"
+      },
+      "cwd": "/Users/rsharma/Downloads/Projects/MCP Servers",
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}

aio_tests_mcp-0.1.0/.kiro/specs/aio-tests-mcp-server/.config.kiro

@@ -0,0 +1 @@
+{"specId": "8219d27b-870f-4463-9ed9-45cd09685596", "workflowType": "requirements-first", "specType": "feature"}

aio_tests_mcp-0.1.0/.kiro/specs/aio-tests-mcp-server/design.md

@@ -0,0 +1,496 @@
+# Design Document: AIO Tests MCP Server
+
+## Overview
+
+This document describes the technical design for an MCP server that wraps the AIO Tests for Jira Cloud REST API. The server exposes test management operations (test cases, cycles, executions, folders, attachments, traceability, versioning) as MCP tools consumable by AI-powered IDEs.
+
+The server is built in Python using the FastMCP framework and deployed as a shared service using SSE (Server-Sent Events) transport. A single deployment serves the entire organization, authenticated via a service account API token.
+
+### Key Design Decisions
+
+1. **FastMCP over raw MCP SDK**: FastMCP provides decorator-based tool registration, automatic schema generation from type hints, and built-in SSE transport — reducing boilerplate significantly.
+2. **Single shared deployment**: One server instance with a service account token serves all users. Project scoping is per-request, not per-connection.
+3. **Async HTTP client (httpx)**: All AIO API calls use `httpx.AsyncClient` for non-blocking I/O, connection pooling, and timeout management.
+4. **Retry with tenacity**: Exponential backoff for 429/5xx responses using the `tenacity` library rather than hand-rolled retry logic.
+5. **Pydantic models for validation**: All tool inputs are validated via Pydantic models before any API call is made, providing clear error messages.
+6. **No bulk deletes by design**: Destructive operations are limited to single-item scope as a safety guardrail against accidental mass data loss from AI agents.
+
+## Architecture
+
+```mermaid
+graph TB
+    subgraph "AI IDEs"
+        K[Kiro]
+        C[Cursor]
+        O[Other MCP Clients]
+    end
+
+    subgraph "MCP Server (Shared Deployment)"
+        F[FastMCP Framework<br/>SSE Transport]
+        T[Tool Layer<br/>Input Validation]
+        S[Service Layer<br/>Business Logic]
+        AC[API Client<br/>httpx + Retry]
+        L[Structured Logger<br/>JSON + Correlation IDs]
+    end
+
+    subgraph "External Services"
+        AIO[AIO Tests Cloud API<br/>tcms.aiojiraapps.com]
+        FS[Local Filesystem<br/>Attachment Upload/Download]
+    end
+
+    K -->|SSE/MCP| F
+    C -->|SSE/MCP| F
+    O -->|SSE/MCP| F
+    F --> T
+    T --> S
+    S --> AC
+    AC -->|HTTPS + AioAuth| AIO
+    S --> FS
+    T --> L
+    S --> L
+    AC --> L
+```
+
+### Request Flow
+
+```mermaid
+sequenceDiagram
+    participant Client as MCP Client (IDE)
+    participant MCP as FastMCP Server
+    participant Tool as Tool Function
+    participant Service as Service Layer
+    participant API as AIO Tests API
+
+    Client->>MCP: Invoke tool (SSE)
+    MCP->>Tool: Dispatch to tool function
+    Tool->>Tool: Validate input (Pydantic)
+    alt Validation fails
+        Tool-->>Client: Return validation error
+    end
+    Tool->>Service: Call service method
+    Service->>Service: Resolve project key
+    Service->>API: HTTPS request (AioAuth header)
+    alt 429 or 5xx
+        API-->>Service: Error response
+        Service->>Service: Retry with backoff (up to 3x)
+        Service->>API: Retry request
+    end
+    API-->>Service: Success response
+    Service-->>Tool: Parsed response
+    Tool-->>Client: Formatted result
+```
+
+## Components and Interfaces
+
+### Package Structure
+
+```
+aio_tests_mcp/
+├── __init__.py
+├── server.py              # FastMCP server initialization, entry point
+├── config.py              # Configuration from environment variables
+├── models/
+│   ├── __init__.py
+│   ├── test_case.py       # Test case Pydantic models
+│   ├── test_cycle.py      # Test cycle Pydantic models
+│   ├── execution.py       # Execution Pydantic models
+│   ├── folder.py          # Folder Pydantic models
+│   ├── attachment.py      # Attachment Pydantic models
+│   ├── traceability.py    # Traceability link models
+│   ├── versioning.py      # Version history models
+│   └── common.py          # Shared models (pagination, errors)
+├── tools/
+│   ├── __init__.py
+│   ├── test_cases.py      # Test case CRUD tools
+│   ├── test_cycles.py     # Test cycle management tools
+│   ├── executions.py      # Execution management tools
+│   ├── folders.py         # Folder management tools
+│   ├── attachments.py     # Attachment tools
+│   ├── traceability.py    # Traceability link tools
+│   └── versioning.py      # Version history tools
+├── services/
+│   ├── __init__.py
+│   ├── aio_client.py      # HTTP client with retry logic
+│   └── project_resolver.py # Project key resolution logic
+├── templates/
+│   ├── __init__.py
+│   └── folder_templates.py # Predefined folder structures
+└── logging.py             # Structured JSON logging setup
+```
+
+### Component Responsibilities
+
+| Component | Responsibility |
+|-----------|---------------|
+| `server.py` | FastMCP initialization, tool registration, SSE transport startup |
+| `config.py` | Read and validate environment variables, expose typed config |
+| `tools/*` | MCP tool functions with `@mcp.tool` decorators, input validation |
+| `services/aio_client.py` | HTTP client wrapper with auth, retry, error mapping |
+| `services/project_resolver.py` | Resolve project key from parameter or default |
+| `models/*` | Pydantic models for request/response validation |
+| `templates/folder_templates.py` | Predefined folder hierarchy definitions |
+| `logging.py` | Structured JSON logger with correlation ID injection |
+
+### Key Interfaces
+
+#### AIOClient (services/aio_client.py)
+
+```python
+class AIOClient:
+    """Async HTTP client for AIO Tests Cloud API with retry and auth."""
+
+    def __init__(self, api_token: str, base_url: str = "https://tcms.aiojiraapps.com/aio-tcms/api/v1/") -> None: ...
+
+    async def get(self, path: str, params: dict | None = None) -> dict: ...
+    async def post(self, path: str, json: dict | None = None) -> dict: ...
+    async def put(self, path: str, json: dict | None = None) -> dict: ...
+    async def delete(self, path: str) -> dict: ...
+    async def upload(self, path: str, file_path: Path) -> dict: ...
+    async def download(self, path: str, dest_path: Path) -> Path: ...
+    async def close(self) -> None: ...
+```
+
+#### ProjectResolver (services/project_resolver.py)
+
+```python
+class ProjectResolver:
+    """Resolves project key from explicit parameter or default config."""
+
+    def __init__(self, default_project_key: str | None) -> None: ...
+
+    def resolve(self, project_key: str | None) -> str:
+        """Return project_key if provided, else default, else raise error."""
+        ...
+```
+
+#### Tool Function Signature Pattern
+
+```python
+@mcp.tool
+async def create_test_case(
+    title: str,
+    description: str = "",
+    folder_id: str | None = None,
+    priority: str | None = None,
+    case_type: str | None = None,
+    project_key: str | None = None,
+) -> dict:
+    """Create a new test case in AIO Tests.
+
+    Args:
+        title: Test case title (required)
+        description: Test case description
+        folder_id: Target folder ID for organization
+        priority: Priority level (Critical, High, Medium, Low)
+        case_type: Type of test (Functional, Integration, Unit, etc.)
+        project_key: Jira project key (uses default if not provided)
+
+    Returns:
+        Created test case with key and metadata
+    """
+    ...
+```
+
+## Data Models
+
+### Configuration
+
+```python
+class ServerConfig(BaseModel):
+    """Server configuration from environment variables."""
+    aio_api_token: str  # Required: AIO_API_TOKEN
+    aio_project_key: str | None = None  # Optional: AIO_PROJECT_KEY
+    aio_base_url: str = "https://tcms.aiojiraapps.com/aio-tcms/api/v1/"
+    server_host: str = "0.0.0.0"
+    server_port: int = 8000
+    log_level: str = "INFO"
+    max_retries: int = 3
+    retry_base_delay: float = 1.0  # seconds
+    request_timeout: float = 30.0  # seconds
+```
+
+### Test Case Models
+
+```python
+class CreateTestCaseInput(BaseModel):
+    """Input for creating a test case."""
+    title: str = Field(..., min_length=1, max_length=500)
+    description: str = ""
+    folder_id: str | None = None
+    priority: str | None = None
+    case_type: str | None = None
+    status: str | None = None
+    automation_status: str | None = None
+    project_key: str | None = None
+
+class TestCaseResponse(BaseModel):
+    """Response from AIO Tests for a test case."""
+    key: str
+    title: str
+    description: str | None = None
+    folder_id: str | None = None
+    priority: str | None = None
+    case_type: str | None = None
+    status: str | None = None
+    created_by: str | None = None
+    created_on: str | None = None
+```
+
+### Pagination Models
+
+```python
+class PaginationParams(BaseModel):
+    """Pagination parameters for list operations."""
+    page: int = Field(default=1, ge=1)
+    page_size: int = Field(default=25, ge=1, le=100)
+
+class PaginatedResponse(BaseModel):
+    """Paginated response wrapper."""
+    items: list[dict]
+    total_count: int
+    current_page: int
+    total_pages: int
+    page_size: int
+```
+
+### Folder Template Models
+
+```python
+class FolderNode(BaseModel):
+    """A node in a folder hierarchy template."""
+    name: str
+    children: list["FolderNode"] = []
+
+class FolderTemplate(BaseModel):
+    """A predefined folder structure template."""
+    template_id: str
+    name: str
+    description: str
+    root_nodes: list[FolderNode]
+```
+
+### Versioning Models
+
+```python
+class VersionEntry(BaseModel):
+    """A single version in a test case's history."""
+    version_number: int
+    author: str | None = None
+    timestamp: str | None = None
+    change_summary: str | None = None
+
+class VersionDiff(BaseModel):
+    """Differences between two versions of a test case."""
+    test_case_key: str
+    from_version: int
+    to_version: int
+    differences: list[FieldDiff]
+
+class FieldDiff(BaseModel):
+    """A single field difference between versions."""
+    field_name: str
+    old_value: str | None = None
+    new_value: str | None = None
+```
+
+### Error Models
+
+```python
+class AIOError(BaseModel):
+    """Structured error response."""
+    error_code: str
+    message: str
+    correlation_id: str
+    details: dict | None = None
+```
+
+## Correctness Properties
+
+*A property is a characteristic or behavior that should hold true across all valid executions of a system — essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.*
+
+### Property 1: Correlation ID Universality
+
+*For any* tool invocation (successful or failed), the server SHALL include a unique correlation ID in all log entries produced during that invocation AND in any error response returned to the client.
+
+**Validates: Requirements 1.6, 8.6**
+
+### Property 2: Create Operations Return Identifiers
+
+*For any* valid input to a create tool (create_test_case, create_test_cycle, create_test_execution, create_test_folder, create_test_case_version), the response SHALL contain a non-empty identifier (key or ID) for the created resource.
+
+**Validates: Requirements 2.1, 3.1, 4.1, 5.1, 13.3**
+
+### Property 3: Update Operations Send Only Specified Fields
+
+*For any* update tool invocation (update_test_case, update_test_cycle, update_test_execution) with a subset of updatable fields, the API request body SHALL contain only the fields explicitly provided by the caller — no unspecified fields shall be included in the request payload.
+
+**Validates: Requirements 2.3, 3.3, 4.2**
+
+### Property 4: Pagination Metadata Consistency
+
+*For any* list tool response with pagination, the following invariants SHALL hold: `total_pages == ceil(total_count / page_size)`, `current_page == requested_page`, `len(items) <= page_size`, and if `current_page < total_pages` then `len(items) == page_size`.
+
+**Validates: Requirements 2.5, 3.4, 11.1, 11.2, 13.7**
+
+### Property 5: Bulk Operations Return One Result Per Input
+
+*For any* bulk operation (bulk_update_executions, bulk_organize_cases) with N input items, the response SHALL contain exactly N result entries, one for each input item.
+
+**Validates: Requirements 4.3, 5.6**
+
+### Property 6: Partial Failure Isolation
+
+*For any* bulk operation containing a mix of valid and invalid items, all valid items SHALL be processed successfully regardless of which other items fail, and each failed item SHALL have an individual error report.
+
+**Validates: Requirements 4.5**
+
+### Property 7: Template Expansion Correctness
+
+*For any* folder template, invoking `create_folder_structure` SHALL result in exactly as many folder creation API calls as there are nodes in the template's hierarchy, and the parent-child relationships in the API calls SHALL match the template's structure.
+
+**Validates: Requirements 5.4**
+
+### Property 8: Folder Suggestion Validity
+
+*For any* non-empty set of test case keys, the `suggest_folder_structure` tool SHALL return a valid tree structure where every node has a name, no node is orphaned (all non-root nodes have a parent in the tree), and nesting depth does not exceed 4 levels.
+
+**Validates: Requirements 5.5, 5.7**
+
+### Property 9: Retry with Exponential Backoff
+
+*For any* API request that receives a retryable error (HTTP 429 or 5xx), the server SHALL retry up to 3 times with delays that increase exponentially (delay_n >= delay_base * 2^(n-1)), and SHALL return a service unavailable error only after all retries are exhausted.
+
+**Validates: Requirements 8.3, 8.4**
+
+### Property 10: Input Validation Before API Call
+
+*For any* tool invocation with invalid input (missing required fields, values outside allowed ranges, malformed identifiers), the server SHALL return a descriptive validation error WITHOUT making any HTTP request to the AIO Tests API.
+
+**Validates: Requirements 8.5**
+
+### Property 11: Project Key Resolution
+
+*For any* tool invocation that includes an explicit `project_key` parameter, the API request SHALL use that project key in the request path, regardless of whether a default project key is configured.
+
+**Validates: Requirements 9.1, 9.2**
+
+### Property 12: Version History Ordering
+
+*For any* response from `get_version_history`, the version entries SHALL be ordered by version_number in ascending order (oldest first), and each version_number SHALL be unique within the list.
+
+**Validates: Requirements 13.1**
+
+### Property 13: Version Diff Accuracy
+
+*For any* two distinct versions of a test case, the `compare_versions` response SHALL list only fields where the values actually differ between the two versions, and for each listed difference, `old_value` SHALL match the field's value in the earlier version and `new_value` SHALL match the later version.
+
+**Validates: Requirements 13.4**
+
+## Error Handling
+
+### Error Classification and Response Strategy
+
+| HTTP Status | Error Code | User Message | Action |
+|-------------|-----------|--------------|--------|
+| 400 | `VALIDATION_ERROR` | Descriptive field-level errors | Return immediately, no retry |
+| 401 | `AUTH_INVALID` | "API token is invalid or expired" | Return immediately, no retry |
+| 403 | `PERMISSION_DENIED` | "Insufficient permissions for this operation" | Return immediately, no retry |
+| 404 | `NOT_FOUND` | "Resource not found: {resource_type} {identifier}" | Return immediately, no retry |
+| 429 | `RATE_LIMITED` | "Rate limited, retrying..." → "Rate limit exceeded after retries" | Retry with exponential backoff |
+| 5xx | `SERVICE_ERROR` | "AIO Tests service error, retrying..." → "Service unavailable" | Retry with exponential backoff |
+| Network error | `CONNECTION_ERROR` | "Unable to reach AIO Tests API" | Retry with exponential backoff |
+
+### Retry Strategy
+
+```python
+# Retry configuration
+MAX_RETRIES = 3
+BASE_DELAY = 1.0  # seconds
+MAX_DELAY = 30.0  # seconds
+RETRYABLE_STATUSES = {429, 500, 502, 503, 504}
+
+# Delay calculation: min(base * 2^attempt, max_delay) + jitter
+```
+
+### Input Validation Rules
+
+All validation happens at the tool layer before any API call:
+
+- **Required string fields**: Must be non-empty after stripping whitespace
+- **Identifiers (keys)**: Must match expected format (e.g., project key pattern `^[A-Z][A-Z0-9_]+$`)
+- **Pagination**: `page >= 1`, `1 <= page_size <= 100`
+- **File paths**: Must exist on filesystem before upload attempt
+- **Lists for bulk operations**: Must be non-empty, max 50 items per call
+
+### Security Considerations
+
+- **Token never logged**: The `AIO_API_TOKEN` value is never included in log output, error messages, or MCP responses. Only the presence/absence of the token is logged.
+- **HTTPS only**: All communication with `tcms.aiojiraapps.com` uses HTTPS. The client rejects non-TLS connections.
+- **Input sanitization**: All user-provided strings are validated for length and character content before being passed to the API.
+- **No credential echo**: Error responses for 401 never include the token value, only that it's invalid.
+- **Correlation IDs are opaque**: UUIDs used for correlation, no user data embedded.
+
+## Testing Strategy
+
+### Testing Approach
+
+This project uses a dual testing approach:
+
+1. **Property-based tests** (using `hypothesis`): Verify the 13 correctness properties above hold across randomly generated inputs. Each property test runs a minimum of 100 iterations.
+2. **Unit tests** (using `pytest`): Cover specific examples, edge cases, error mappings, and integration points.
+3. **Integration tests**: Verify the server starts, registers tools, and handles real HTTP flows against a mock API.
+
+### Property-Based Testing Configuration
+
+- **Library**: `hypothesis` (Python)
+- **Minimum iterations**: 100 per property
+- **Tag format**: `# Feature: aio-tests-mcp-server, Property {N}: {title}`
+
+Each correctness property maps to one property-based test:
+
+| Property | Test File | What's Generated |
+|----------|-----------|-----------------|
+| 1: Correlation ID | `tests/test_logging_properties.py` | Random tool names and inputs |
+| 2: Create returns ID | `tests/test_crud_properties.py` | Random valid creation inputs |
+| 3: Update sends only specified | `tests/test_crud_properties.py` | Random field subsets |
+| 4: Pagination consistency | `tests/test_pagination_properties.py` | Random page/page_size/total_count |
+| 5: Bulk result count | `tests/test_bulk_properties.py` | Random-length input lists |
+| 6: Partial failure isolation | `tests/test_bulk_properties.py` | Random valid/invalid ID mixes |
+| 7: Template expansion | `tests/test_folder_properties.py` | Random template structures |
+| 8: Suggestion validity | `tests/test_folder_properties.py` | Random test case metadata sets |
+| 9: Retry backoff | `tests/test_retry_properties.py` | Random retryable status sequences |
+| 10: Validation before API | `tests/test_validation_properties.py` | Random invalid inputs |
+| 11: Project key resolution | `tests/test_project_properties.py` | Random project keys |
+| 12: Version ordering | `tests/test_versioning_properties.py` | Random version lists |
+| 13: Diff accuracy | `tests/test_versioning_properties.py` | Random version state pairs |
+
+### Unit Test Coverage
+
+- All tool functions: happy path with mocked API responses
+- Error mapping: each HTTP error status → correct error code
+- Edge cases: empty inputs, missing project key, non-existent files
+- Configuration: startup with/without env vars
+- Destructive operation safety: verify no bulk delete tools exist
+
+### Test Infrastructure
+
+- **Mocking**: `httpx` responses mocked via `respx` or `pytest-httpx`
+- **Fixtures**: Shared fixtures for `AIOClient`, `ServerConfig`, mock API responses
+- **Markers**: `@pytest.mark.property` for PBT, `@pytest.mark.integration` for integration tests
+
+### Running Tests
+
+```bash
+# All tests
+pytest tests/ -v
+
+# Property tests only
+pytest tests/ -v -m property
+
+# With coverage
+pytest tests/ --cov=aio_tests_mcp --cov-report=term-missing
+
+# Property tests with more examples
+pytest tests/ -v -m property --hypothesis-seed=0
+```
+