Quack MCP Server

Quack MCP 服务

Quack 是一个作为 MCP 服务构建的持续集成服务，可自动分析和测试 Python 代码。它提供用于 Python 代码检查和静态类型分析的工具。

功能

• 代码检查：使用 pylint 分析 Python 代码的风格、格式和代码质量问题。
• 静态分析：使用 mypy 执行静态类型检查，以识别类型错误。
• 异步处理：任务以异步方式处理，可并发分析多份代码提交。
• 任务管理：跟踪并获取已提交任务的结果。

安装

1. 克隆仓库：

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

2. 安装依赖项：

pip install -r requirements.txt

Quack 服务需要以下依赖项：

mcp[cli]
pylint
mypy
pytest
pytest-asyncio

使用方法

启动服务

使用 stdio 传输（默认）启动 Quack 服务：

python3 quack.py

启用调试日志：

python3 quack.py --debug

使用 SSE（Server-Sent Events）传输通过 HTTP 通信来启动服务：

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

或者，你也可以使用提供的 shell 脚本：

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

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

Docker 容器

Quack 服务可以在 Docker 容器中运行，并会自动使用 SSE 传输：

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

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

在 Docker 容器中运行时，服务会自动以 SSE 模式在端口 8000 上启动。

使用 MCP 工具

Quack 提供以下 MCP 工具：

1. submit_code：提交代码以进行代码检查和静态分析。
2. submit_code_for_linting：提交代码，仅进行代码检查。
3. submit_code_for_static_analysis：提交代码，仅进行静态分析。
4. get_job_results：获取已提交任务的结果。
5. list_jobs：列出所有任务及其状态。

测试架构

Quack 有两种不同的测试概念：

1. 针对 Quack 的测试：tests/ 目录中的测试用于验证 Quack 服务、任务管理器和处理器是否正常工作。添加新处理器时，应在此处添加测试，以验证处理器能否正常工作。

2. 由 Quack 执行的测试：这些是 Quack 对已提交代码执行的分析。代码检查处理器和静态分析处理器会分析 Python 代码并查找问题。你的新处理器也会对单独提交的代码执行同类分析。

目录结构

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

实现新处理器时（例如，测试覆盖率处理器）：

1. 在 quack/processors/ 中创建处理器
2. 在 tests/processors/ 中为处理器添加测试
3. 使用 tests/examples/ 中的代码测试处理器要分析的内容

运行测试

仓库在 tests 目录中包含完整的测试套件。所有测试都使用 pytest 管理。

1. 运行所有测试：

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

2. 运行指定的测试文件：

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

3. 运行指定处理器的测试：

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

4. 运行测试并显示详细输出和测试进度：

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

5. 运行测试，并在首次失败时停止：

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

自动管理服务

许多测试会根据需要自动启动和停止 Quack 服务，因此测试期间无需手动管理服务进程。这由 conftest.py 文件中的 pytest fixtures 处理。

tests/server/test_server_auto.py 中的服务测试展示了如何在测试期间自动启动和停止服务。这些测试会验证：

1. 服务能否正常启动
2. 服务能否处理任务
3. 服务能否正常关闭

使用 Cline 设置 Quack

Quack 可以与 Cline 集成，让你直接通过 Cline 界面使用代码分析功能。

配置步骤

1. 配置 Cline MCP 设置

   可以在 Cline 的 MCP 设置文件中配置 Quack 服务，文件路径为：

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

   本地 Stdio 模式（默认）

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

   Docker 容器搭配 SSE

   在 Docker 容器中运行服务时，请将 Cline 配置为通过 HTTP/SSE 连接：

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

   注意：如果你将 Docker 容器映射到其他端口，请将 localhost:8000 替换为相应的主机和端口。

使用 Cline 搭配 Quack

配置完成后，你可以使用 Cline 通过 Quack 服务分析 Python 代码。以下是一些提示词示例：

• 分析代码中的 lint 问题：

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

• 检查代码中的类型错误：

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

• 获取全面的反馈：

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

测试用示例代码

你可以使用以下包含故意设置的问题的示例代码来测试 Quack 服务：

# 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

工作原理

1. 当你让 Cline 分析 Python 代码时，Cline 会使用 Quack MCP 服务
2. Quack 服务会通过其 lint 和静态分析工具处理代码
3. 分析结果会返回给 Cline，由 Cline 以易读的格式呈现给你

故障排查

如果 Cline 似乎没有使用 Quack 服务：

1. 确保已在 MCP 设置文件中正确配置 Quack 服务
2. 检查 quack.py 文件的路径是否正确（适用于 stdio 模式）
3. 确认 URL 正确且服务正在运行（适用于 SSE 模式）
4. 确保已安装所有依赖项
5. 重启 VSCode 以重新加载 MCP 设置

Docker 特定问题

在 Docker 中运行时：

1. 端口映射：确保容器的 8000 端口已正确映射到主机端口：

   docker run -p 8000:8000 quack-mcp-server
   

2. 网络访问：如果在复杂的网络环境中运行 Docker，请确保主机可以访问容器的端口。

3. 容器日志：检查容器日志中是否存在启动问题：

   docker logs <container_id>
   

4. 测试连接：你可以测试 SSE 端点是否可访问：

   curl http://localhost:8000
   

   这应该会返回 404 响应（因为没有根端点），但可以确认服务正在运行。

架构

Quack 基于 Model Context Protocol（MCP）构建，由以下组件组成：

• 服务端：处理客户端连接和工具调用的主 MCP 服务。
• 作业管理器：管理作业的生命周期，包括提交、处理和结果获取。
• 处理器：执行实际代码分析的专用组件：
  • Lint 处理器：使用 pylint 分析代码风格和质量。
  • 静态分析处理器：使用 mypy 执行静态类型检查。

开发

添加新处理器

添加新处理器的步骤：

1. 在 quack/processors 目录中创建新的处理器类。
2. 实现 process 方法以执行分析。
3. 在服务端注册该处理器。
4. 在 tests/processors/ 中为处理器添加测试。

示例：添加测试覆盖率处理器

1. 使用处理器实现创建 quack/processors/coverage.py
2. 在 quack/server.py 的服务端中添加该处理器
3. 在 tests/processors/test_coverage_processor.py 中创建测试
4. 使用 tests/examples/ 中的示例代码测试处理器

调试

使用 --debug 标志运行服务，以启用详细日志记录：

python3 quack.py --debug

日志会同时写入控制台和 logs/quack.log。