AI导哈

代码分析服务器

Quack MCP 服务器是一款实现模型上下文协议（MCP）的智能持续集成服务器，提供自动化Python代码分析、格式检查和静态类型检查功能，并支持与AI助手的无缝集成。

  • by smhajimirzaei
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 smhajimirzaei/QUACK-MCP-SERVER

使用说明

Quack MCP服务器🦆

一个智能持续集成服务器，实现了模型上下文协议（MCP），用于自动化Python代码分析、linting和静态类型检查，并与无缝的AI助手集成。

🚀 概述

Quack通过实施 模型上下文协议（MCP），实现与Claude Code和Cline等人工智能助手的无缝集成。该项目展示了协议实现、异步作业编排和代码分析工具的可扩展插件架构方面的专业知识。

是什么让Quack与众不同：

  • MCP协议实现：原生支持模型上下文协议，实现AI助手集成
  • 异步作业处理：使用作业生命周期管理对多个代码提交进行并发分析
  • 可扩展处理器架构：基于插件的设计，用于添加新的分析工具（linting、类型检查、测试）
  • 多运输支持：用于灵活部署场景的Stdio和服务器发送事件（SSE）
  • 生产就绪CI/CD：用于企业部署的Docker容器化和HTTP服务器模式
  • 综合测试：覆盖率超过99%的完整测试套件，包括处理器和服务器测试

✨ 主要特点

🔧 代码分析能力

  • pylint集成：全面的代码风格、PEP 8合规性和代码气味检测
  • mypy静态分析：在运行前进行类型检查以捕获类型错误
  • pytest执行：自动测试运行，结果聚合
  • 可扩展处理器：易于添加新的分析工具（bandian、black、isort等）

🏗️ 高级体系结构

  • 作业管理系统：完整的生命周期跟踪（待定→ 跑步→ 完成/失败）
  • 工厂模式：基于作业类型的动态处理器实例化
  • 异步/等待本机：从头开始为并发操作而构建
  • 状态枚举：使用枚举进行类型安全的作业状态管理
  • 结果缓存：高效检索已完成的作业结果

🌐 多传输MCP服务器

  • 标准运输：AI助手集成的默认模式（Claude、Cline）
  • 苏格兰和南方能源公司运输：为基于web的客户端提供服务器发送事件的HTTP服务器
  • 调试日志记录：用于故障排除和监控的全面日志记录
  • 容器支持：具有自动SSE模式的Docker部署

🤖 AI助手集成

  • Claude代码支持：通过MCP协议与Claude Code直接集成
  • 临床兼容性：与Cline AI助手无缝协作
  • 自定义规则：包括用于最佳AI协作的.clinules
  • 工具曝光：五个MCP工具，用于全面的代码分析工作流程

🛠️ MCP工具

Quack通过MCP协议展示了五个强大的工具：

  1. submit_code：提交代码进行综合分析（linting+类型检查）

    • 输入：Python代码为字符串
    • 输出：用于跟踪的作业ID
    • 用途：完成代码质量评估

  2. submit_code_for_linting：重点皮林分析

    • 输入：Python代码为字符串
    • 输出：带有linting特定结果的作业ID
    • 用途：样式和PEP 8合规性检查

  3. submit_code_for_static_analysis：专用mypy类型检查

    • 输入：Python代码为字符串
    • 输出：带有类型分析结果的作业ID
    • 用途：类型安全验证

  4. get_job_results：检索分析结果

    • 输入：作业ID
    • 输出：完成工作结果，包括状态和发现
    • 用途：轮询完成情况并获取分析输出

  5. list_jobs：查看所有提交的作业

    • 输入：无
    • 输出：所有具有状态的作业列表
    • 用途：监控队列并跟踪作业进度

💼 展示专业技能

协议实现

  • MCP规范：完全实现模型上下文协议v1.0
  • 协议设计：了解客户端-服务器通信模式
  • 传输层：多传输支持（stdio、SSE/HTTP）
  • 工具注册：通过协议动态暴露工具

软件架构

  • 微服务模式：作业经理协调独立处理者
  • 插件架构：用于添加新分析仪的可扩展处理器系统
  • 工厂模式：基于作业类型的动态处理器实例化
  • 观察者模式：作业状态通知和更新
  • 策略模式：可互换的分析策略

异步编程

  • 异步掌握：整个代码库中的原生async/await
  • 并发作业处理：同时处理多个作业
  • 异步上下文管理器：适当的资源管理
  • 事件循环集成：MCP服务器与asyncio的集成
  • 非阻塞I/O：高效处理代码分析操作

代码质量与测试

  • 测试驱动开发：带pytest的全面测试套件
  • 集成测试：完整的服务器和客户端集成测试
  • 单元测试：个人处理器和作业管理器测试
  • 嘲讽：策略性地使用模拟来处理外部依赖关系
  • 代码覆盖率：所有模块的测试覆盖率超过99%

DevOps与部署

  • Docker多阶段构建：使用预构建的库优化容器映像
  • 环境配置：通过CLI参数灵活配置
  • 记录和监控：用于生产调试的结构化日志记录
  • 流程管理：正确的信号处理和优雅的关机
  • 交叉平台的：适用于Linux、macOS和Windows

Python工程

  • 类型提示：用于静态分析的完整类型注释
  • 枚举：使用Enum进行类型安全状态跟踪
  • 数据类：工作和结果的干净数据结构
  • 抽象基类：处理器接口定义
  • Python 3.10+功能：现代Python语法和功能

🎯 实际应用

CI/CD集成

  • 预提交钩子：在允许提交之前运行Quack
  • 拉取请求验证：PR工作流程中的自动代码审查
  • 持续集成：Jenkins、GitHub Actions、GitLab CI集成
  • 质量门：在linting/类型检查失败时进行块合并

人工智能辅助开发

  • Claude代码集成：使用Claude编码时进行实时代码分析
  • 临床工作流程：AI配对编程中的嵌入式代码质量检查
  • 自动重构：AI根据Quack的发现提出修复建议
  • 学习手段：关于代码质量问题的教育反馈

企业代码审查

  • 风格强制：跨团队的一致代码风格
  • 类型安全：生产前捕获类型错误
  • 最佳实践：在整个组织范围内实施Python最佳实践
  • 技术债：跟踪代码质量问题并确定其优先级

安装

  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服务器、作业管理器和处理器是否正常工作。添加新处理器时，应在此处添加测试以验证处理器是否正常工作。

  2. 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

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

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

    docker logs <container_id>

  4. 测试连接：您可以测试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.

相关 MCP