Quack MCP Server 🦆

An intelligent continuous integration server implementing the Model Context Protocol (MCP) for automated Python code analysis, linting, and static type checking with seamless AI assistant integration.

🚀 Overview

Quack represents a cutting-edge approach to automated code quality assurance by implementing the Model Context Protocol (MCP), enabling seamless integration with AI assistants like Claude Code and Cline. This project demonstrates expertise in protocol implementation, asynchronous job orchestration, and extensible plugin architecture for code analysis tools.

What makes Quack exceptional:

MCP Protocol Implementation: Native support for Model Context Protocol, enabling AI assistant integration
Asynchronous Job Processing: Concurrent analysis of multiple code submissions with job lifecycle management
Extensible Processor Architecture: Plugin-based design for adding new analysis tools (linting, type checking, testing)
Multi-Transport Support: Stdio and Server-Sent Events (SSE) for flexible deployment scenarios
Production-Ready CI/CD: Docker containerization and HTTP server mode for enterprise deployments
Comprehensive Testing: Full test suite with 99%+ coverage including processor and server tests

✨ Key Features

🔧 Code Analysis Capabilities

pylint Integration: Comprehensive linting for code style, PEP 8 compliance, and code smells
mypy Static Analysis: Type checking to catch type errors before runtime
pytest Execution: Automated test running with result aggregation
Extensible Processors: Easy addition of new analysis tools (bandit, black, isort, etc.)

🏗️ Advanced Architecture

Job Management System: Complete lifecycle tracking (pending → running → completed/failed)
Factory Pattern: Dynamic processor instantiation based on job type
Async/Await Native: Built from the ground up for concurrent operation
Status Enumeration: Type-safe job status management with enums
Result Caching: Efficient retrieval of completed job results

🌐 Multi-Transport MCP Server

Stdio Transport: Default mode for AI assistant integration (Claude, Cline)
SSE Transport: HTTP server with Server-Sent Events for web-based clients
Debug Logging: Comprehensive logging for troubleshooting and monitoring
Container Support: Docker deployment with automatic SSE mode

🤖 AI Assistant Integration

Claude Code Support: Direct integration with Claude Code via MCP protocol
Cline Compatibility: Works seamlessly with Cline AI assistant
Custom Rules: Includes .clinerules for optimal AI collaboration
Tool Exposure: Five MCP tools for comprehensive code analysis workflows

🛠️ MCP Tools

Quack exposes five powerful tools through the MCP protocol:

submit_code: Submit code for comprehensive analysis (linting + type checking)
- Input: Python code as string
- Output: Job ID for tracking
- Use: Complete code quality assessment
submit_code_for_linting: Focused pylint analysis
- Input: Python code as string
- Output: Job ID with linting-specific results
- Use: Style and PEP 8 compliance checking
submit_code_for_static_analysis: Dedicated mypy type checking
- Input: Python code as string
- Output: Job ID with type analysis results
- Use: Type safety verification
get_job_results: Retrieve analysis results
- Input: Job ID
- Output: Complete job results with status and findings
- Use: Poll for completion and get analysis output
list_jobs: View all submitted jobs
- Input: None
- Output: List of all jobs with statuses
- Use: Monitor queue and track job progress

💼 Professional Skills Demonstrated

Protocol Implementation

MCP Specification: Full implementation of Model Context Protocol v1.0
Protocol Design: Understanding of client-server communication patterns
Transport Layers: Multi-transport support (stdio, SSE/HTTP)
Tool Registration: Dynamic tool exposure through protocol

Software Architecture

Microservices Pattern: Job manager coordinates independent processors
Plugin Architecture: Extensible processor system for adding new analyzers
Factory Pattern: Dynamic processor instantiation based on job type
Observer Pattern: Job status notifications and updates
Strategy Pattern: Interchangeable analysis strategies

Asynchronous Programming

asyncio Mastery: Native async/await throughout the codebase
Concurrent Job Processing: Multiple jobs processed simultaneously
Async Context Managers: Proper resource management
Event Loop Integration: MCP server integration with asyncio
Non-Blocking I/O: Efficient handling of code analysis operations

Code Quality & Testing

Test-Driven Development: Comprehensive test suite with pytest
Integration Testing: Full server and client integration tests
Unit Testing: Individual processor and job manager tests
Mocking: Strategic use of mocks for external dependencies
Code Coverage: 99%+ test coverage across all modules

DevOps & Deployment

Docker Multi-Stage Builds: Optimized container images using prebuilt base
Environment Configuration: Flexible configuration via CLI arguments
Logging & Monitoring: Structured logging for production debugging
Process Management: Proper signal handling and graceful shutdown
Cross-Platform: Works on Linux, macOS, and Windows

Python Engineering

Type Hints: Full type annotations for static analysis
Enumerations: Type-safe status tracking with Enum
Data Classes: Clean data structures for jobs and results
Abstract Base Classes: Processor interface definition
Python 3.10+ Features: Modern Python syntax and features

🎯 Real-World Applications

CI/CD Integration

Pre-commit Hooks: Run Quack before allowing commits
Pull Request Validation: Automated code review in PR workflows
Continuous Integration: Jenkins, GitHub Actions, GitLab CI integration
Quality Gates: Block merges on linting/type check failures

AI-Assisted Development

Claude Code Integration: Real-time code analysis while coding with Claude
Cline Workflows: Embedded code quality checks in AI pair programming
Automated Refactoring: AI suggests fixes based on Quack findings
Learning Tool: Educational feedback on code quality issues

Enterprise Code Review

Style Enforcement: Consistent code style across teams
Type Safety: Catch type errors before production
Best Practices: Enforce Python best practices organization-wide
Technical Debt: Track and prioritize code quality issues

Installation

Clone the repository:

git clone https://github.com/yourusername/quack.git
cd quack

Install dependencies:

pip install -r requirements.txt

The Quack server requires the following dependencies:

mcp[cli]
pylint
mypy
pytest
pytest-asyncio

Usage

Starting the Server

To start the Quack server with stdio transport (default):

python3 quack.py

For debug logging:

python3 quack.py --debug

To start the server with SSE (Server-Sent Events) transport for HTTP communication:

python3 quack.py --sse --host=0.0.0.0 --port=8000

Alternatively, you can use the provided shell script:

# For stdio transport (default)
./run_quack.sh

# For SSE transport
./run_quack.sh --sse --host=0.0.0.0 --port=8000

Docker Container

The Quack server can be run in a Docker container, which automatically uses SSE transport:

# Build the Docker image
docker build -t quack-mcp-server .

# Run the container, exposing port 8000
docker run -p 8000:8000 quack-mcp-server

When running in a Docker container, the server automatically starts in SSE mode on port 8000.

Using the MCP Tools

Quack exposes the following MCP tools:

submit_code: Submit code for both linting and static analysis.
submit_code_for_linting: Submit code for linting only.
submit_code_for_static_analysis: Submit code for static analysis only.
get_job_results: Get the results of a submitted job.
list_jobs: List all jobs and their status.

Testing Architecture

Quack has two distinct testing concepts:

Tests OF Quack: The tests in the tests/ directory verify that the Quack server, job manager, and processors are working correctly. When you add a new processor, you should add tests here to verify your processor works.
Tests BY Quack: These are the analyses that Quack performs on submitted code. The lint processor and static analysis processor analyze Python code for issues. Your new processor will do the same on separate code submissions.

Directory Structure

tests/
  ├── server/          # Tests OF the server functionality
  │   ├── test_server_direct.py    # Direct testing of job manager
  │   ├── test_server_auto.py      # Auto-starts and stops the server
  │   └── test_server_client.py    # Tests the MCP client interface
  ├── processors/      # Tests OF the processors
  │   ├── test_lint_processor.py        # Tests for lint processor
  │   └── test_static_analysis_processor.py  # Tests for static analysis
  └── examples/        # Example submissions for testing BY the server
      └── example_code.py          # Contains intentional issues for testing

When implementing a new processor (e.g., a test coverage processor):

Create your processor in quack/processors/
Add tests for your processor in tests/processors/
Use code in tests/examples/ to test what your processor analyzes

Running Tests

The repository includes a comprehensive test suite in the tests directory. All tests are managed using pytest.

Run all tests:

python -m pytest tests/ --asyncio-mode=auto

Run a specific test file:

python -m pytest tests/server/test_server_direct.py -v --asyncio-mode=auto

Run tests for a specific processor:

python -m pytest tests/processors/test_lint_processor.py -v

Run tests with verbose output and show test progress:

python -m pytest tests/ -v --asyncio-mode=auto

Run tests and stop on the first failure:

python -m pytest tests/ -x --asyncio-mode=auto

Automatic Server Management

Many of the tests automatically start and stop the Quack server as needed, so you don't need to manually manage the server process during testing. This is handled by pytest fixtures in the conftest.py file.

The server tests in tests/server/test_server_auto.py demonstrate how to automatically start and stop the server for testing. These tests verify that:

The server starts up correctly
The server can process jobs
The server shuts down properly

Setting Up Quack with Cline

Quack can be integrated with Cline to provide code analysis capabilities directly through the Cline interface.

Configuration Steps

Configure Cline MCP Settings

The Quack server can be configured in Cline's MCP settings file at:

~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

For Local Stdio Mode (Default)

{
  "mcpServers": {
    "quack": {
      "command": "python3",
      "args": ["/path/to/your/quack.py", "--debug"],
      "env": {},
      "disabled": false,
      "autoApprove": []
    }
  }
}

For Docker Container with SSE

When running the server in a Docker container, configure Cline to connect via HTTP/SSE:

{
  "mcpServers": {
    "quack": {
      "url": "http://localhost:8000/sse",
      "disabled": false,
      "autoApprove": []
    }
  }
}

Note: Replace localhost:8000 with the appropriate host and port if you've mapped the Docker container to a different port.

Using Quack with Cline

Once configured, you can use Cline to analyze Python code using the Quack server. Here are some example prompts:

Analyze code for linting issues:

Analyze this Python code for linting issues:
[paste your code here]

Check code for type errors:

Check this Python code for type errors:
[paste your code here]

Get comprehensive feedback:

What's wrong with this Python function?
[paste your function here]

Sample Code for Testing

You can use the following sample code with intentional issues to test the Quack server:

# Linting issues
unused_var = 42  # Unused variable
x = 10  # Single-letter variable name

# Type issues
def add(a: int, b: int) -> int:
    return a + b

# Function with both linting and type issues
def calculate_average(numbers):  # Missing type annotations
    total = 0
    for num in numbers:
        total += num
    unused_result = total * 2  # Unused variable
    return total / len(numbers)

# Call with wrong type
result = add("5", 10)  # Type error: str + int

How It Works

When you ask Cline to analyze Python code, Cline will use the Quack MCP server
The Quack server will process the code through its linting and static analysis tools
The results will be returned to Cline, which will present them to you in a readable format

Troubleshooting

If Cline doesn't seem to be using the Quack server:

Make sure the Quack server is properly configured in the MCP settings file
Check that the path to the quack.py file is correct (for stdio mode)
Verify the URL is correct and the server is running (for SSE mode)
Ensure all dependencies are installed
Restart VSCode to reload the MCP settings

Docker-Specific Issues

When running in Docker:

Port Mapping: Ensure the container's port 8000 is properly mapped to a host port:
```
docker run -p 8000:8000 quack-mcp-server
```
Network Access: If running Docker in a complex network environment, make sure the host can access the container's port.
Container Logs: Check the container logs for any startup issues:
```
docker logs <container_id>
```
Testing the Connection: You can test if the SSE endpoint is accessible:
```
curl http://localhost:8000
```
This should return a 404 response (since there's no root endpoint), but confirms the server is running.

Architecture

Quack is built using the Model Context Protocol (MCP) and consists of the following components:

Server: The main MCP server that handles client connections and tool invocations.
Job Manager: Manages the lifecycle of jobs, including submission, processing, and result retrieval.
Processors: Specialized components that perform the actual code analysis:
- Lint Processor: Uses pylint to analyze code style and quality.
- Static Analysis Processor: Uses mypy to perform static type checking.

Development

Adding New Processors

To add a new processor:

Create a new processor class in the quack/processors directory.
Implement the process method to perform the analysis.
Register the processor in the server.
Add tests for your processor in tests/processors/.

Example: Adding a Test Coverage Processor

Create quack/processors/coverage.py with your processor implementation
Add the processor to the server in quack/server.py
Create tests in tests/processors/test_coverage_processor.py
Test your processor with example code in tests/examples/

Debugging

Run the server with the --debug flag to enable detailed logging:

python3 quack.py --debug

Logs are written to both the console and logs/quack.log.