Quack MCP Server

Quack MCP服务器

Quack是一个作为MCP服务器构建的持续集成服务器，可以自动对Python代码进行代码分析和测试。它为Python代码的linting和静态类型分析提供了工具。

特性

• 代码检查：使用pylint分析Python代码的样式、格式和代码质量问题。
• 静态分析：使用mypy执行静态类型检查以识别类型错误。
• 异步处理：作业是异步处理的，允许对多个代码提交进行并发分析。
• 作业管理：跟踪和检索提交作业的结果。

安装

1. 克隆存储库：

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

1. 安装依赖项：

pip install -r requirements.txt

Quack服务器需要以下依赖关系：

mcp[cli]
pylint
mypy
pytest
pytest-asyncio

用法

启动服务器

要使用stdio传输（默认）启动Quack服务器，请执行以下操作：

python3 quack.py

对于调试日志记录：

python3 quack.py --debug

要使用SSE（服务器发送事件）传输启动服务器进行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容器中运行，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容器中运行时，服务器会在端口8000上以SSE模式自动启动。

使用MCP工具

Quack公开了以下MCP工具：

1. submit_code：提交用于linting和静态分析的代码。
2. submit_code_for_linting：仅提交linting代码。
3. submit_code_for_static_analysis：提交代码仅用于静态分析。
4. get_job_results：获取提交作业的结果。
5. list_jobs：列出所有作业及其状态。

测试架构

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

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

1. Quack测试：这些是Quack对提交的代码进行的分析。lint处理器和静态分析处理器分析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

1. 运行特定的测试文件：

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

1. 对特定处理器运行测试：

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

1. 运行带有详细输出的测试并显示测试进度：

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

1. 运行测试并在第一次失败时停止：

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

自动服务器管理

许多测试会根据需要自动启动和停止Quack服务器，因此您不需要在测试期间手动管理服务器进程。这由pytest夹具在 conftest.py 文件。

服务器在中进行测试 tests/server/test_server_auto.py 演示如何自动启动和停止服务器进行测试。这些测试验证了：

1. 服务器正确启动
2. 服务器可以处理作业
3. 服务器正常关闭

与Cline建立Quack

Quack可以与Cline集成，直接通过Cline界面提供代码分析功能。

配置步骤

1. 配置临床MCP设置

Quack服务器可以在Cline的MCP设置文件中配置，网址为：

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

#### 用于本地标准模式（默认）

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

#### 适用于带有SSE的Docker容器

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

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

注：更换 localhost:8000 如果您已将Docker容器映射到其他端口，请使用适当的主机和端口。

将Quack与Cline结合使用

配置后，您可以使用Cline使用Quack服务器分析Python代码。以下是一些示例提示：

• 分析代码中的linting问题:

  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服务器将通过其linting和静态分析工具处理代码
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

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

1. 容器日志：检查容器日志是否有任何启动问题：

   docker logs 

1. 测试连接：您可以测试SSE端点是否可访问：

   curl http://localhost:8000

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

建筑

Quack使用模型上下文协议（MCP）构建，由以下组件组成：

• 服务器：处理客户端连接和工具调用的主MCP服务器。
• 作业管理器：管理作业的生命周期，包括提交、处理和结果检索。
• 处理器：执行实际代码分析的专用组件：

- 棉绒处理器：使用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.