MCP 服务器

Quack MCP Server

nowucca

开发者工具

访问服务器

README

Quack MCP 服务器

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

特性

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

安装

克隆存储库：

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

安装依赖项：

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 脚本：

# 对于 stdio 传输（默认）
./run_quack.sh

# 对于 SSE 传输
./run_quack.sh --sse --host=0.0.0.0 --port=8000

Docker 容器

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

# 构建 Docker 镜像
docker build -t quack-mcp-server .

# 运行容器，暴露端口 8000
docker run -p 8000:8000 quack-mcp-server

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

使用 MCP 工具

Quack 公开了以下 MCP 工具：

submit_code: 提交代码以进行 linting 和静态分析。
submit_code_for_linting: 仅提交代码以进行 linting。
submit_code_for_static_analysis: 仅提交代码以进行静态分析。
get_job_results: 获取已提交作业的结果。
list_jobs: 列出所有作业及其状态。

测试架构

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

Quack 的测试: tests/ 目录中的测试验证 Quack 服务器、作业管理器和处理器是否正常工作。当您添加新的处理器时，您应该在此处添加测试以验证您的处理器是否工作。
Quack 的测试: 这些是 Quack 对提交的代码执行的分析。lint 处理器和静态分析处理器分析 Python 代码是否存在问题。您的新处理器将在单独的代码提交上执行相同的操作。

目录结构

tests/
  ├── server/          # 服务器功能的测试
  │   ├── test_server_direct.py    # 作业管理器的直接测试
  │   ├── test_server_auto.py      # 自动启动和停止服务器
  │   └── test_server_client.py    # 测试 MCP 客户端接口
  ├── processors/      # 处理器的测试
  │   ├── test_lint_processor.py        # lint 处理器的测试
  │   └── test_static_analysis_processor.py  # 静态分析的测试
  └── examples/        # 用于服务器测试的示例提交
      └── example_code.py          # 包含用于测试的故意问题

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

在 quack/processors/ 中创建您的处理器
在 tests/processors/ 中为您的处理器添加测试
使用 tests/examples/ 中的代码来测试您的处理器分析的内容

运行测试

该存储库在 tests 目录中包含一个全面的测试套件。所有测试都使用 pytest 进行管理。

运行所有测试：

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

运行特定的测试文件：

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

运行特定处理器的测试：

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

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

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

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

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

自动服务器管理

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

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

服务器正确启动
服务器可以处理作业
服务器正确关闭

使用 Cline 设置 Quack

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

配置步骤

配置 Cline MCP 设置

Quack 服务器可以在 Cline 的 MCP 设置文件中配置，位于：

~/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": []
    }
  }
}

对于带有 SSE 的 Docker 容器

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

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

注意：如果已将 Docker 容器映射到不同的端口，请将 localhost:8000 替换为适当的主机和端口。

将 Quack 与 Cline 结合使用

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

分析代码是否存在 linting 问题:

分析此 Python 代码是否存在 linting 问题：
[在此处粘贴您的代码]

检查代码是否存在类型错误:

检查此 Python 代码是否存在类型错误：
[在此处粘贴您的代码]

获取全面的反馈:

这个 Python 函数有什么问题？
[在此处粘贴您的函数]

用于测试的示例代码

您可以使用以下带有故意问题的示例代码来测试 Quack 服务器：

# Linting 问题
unused_var = 42  # 未使用的变量
x = 10  # 单字母变量名

# 类型问题
def add(a: int, b: int) -> int:
    return a + b

# 具有 linting 和类型问题的函数
def calculate_average(numbers):  # 缺少类型注释
    total = 0
    for num in numbers:
        total += num
    unused_result = total * 2  # 未使用的变量
    return total / len(numbers)

# 使用错误的类型调用
result = add("5", 10)  # 类型错误：str + int

工作原理

当您要求 Cline 分析 Python 代码时，Cline 将使用 Quack MCP 服务器
Quack 服务器将通过其 linting 和静态分析工具处理代码
结果将返回给 Cline，Cline 将以可读的格式将其呈现给您

故障排除

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

确保 Quack 服务器已在 MCP 设置文件中正确配置
检查 quack.py 文件的路径是否正确（对于 stdio 模式）
验证 URL 是否正确并且服务器正在运行（对于 SSE 模式）
确保已安装所有依赖项
重新启动 VSCode 以重新加载 MCP 设置

Docker 特有的问题

在 Docker 中运行时：

端口映射: 确保容器的端口 8000 正确映射到主机端口：
```
docker run -p 8000:8000 quack-mcp-server
```
网络访问: 如果在复杂的网络环境中运行 Docker，请确保主机可以访问容器的端口。
容器日志: 检查容器日志中是否存在任何启动问题：
```
docker logs <container_id>
```
测试连接: 您可以测试 SSE 端点是否可访问：
```
curl http://localhost:8000
```
这应该返回 404 响应（因为没有根端点），但确认服务器正在运行。

架构

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

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

开发

添加新的处理器

要添加新的处理器：

在 quack/processors 目录中创建一个新的处理器类。
实现 process 方法以执行分析。
在服务器中注册处理器。
在 tests/processors/ 中为您的处理器添加测试。

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

使用您的处理器实现在 quack/processors/coverage.py 中创建
在 quack/server.py 中将处理器添加到服务器
在 tests/processors/test_coverage_processor.py 中创建测试
使用 tests/examples/ 中的示例代码测试您的处理器

调试

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

python3 quack.py --debug

日志将写入控制台和 logs/quack.log。