final project se333 NigelMaloney

SE333最终项目——MCP服务器

基于Python 模型上下文协议（MCP）服务器 提供自动化代码质量分析和测试分析工具，使用 fastmcp 通过SSE运输。

存储库：

______________________________________________________________________

目录

1. 概述
2. 安装和设置
3. 配置
4. 运行提示工作流
5. MCP工具参考

- 分析_平均值 - generate_test_report - 检测码味道 - 扫描安全风险 - enforce_style_guide - 检查复杂性

1. 测试
2. 故障排除和常见问题

______________________________________________________________________

概述

此MCP服务器公开了六个代码质量分析工具，这些工具与中描述的工作流相一致 tester.prompt.md 和 codereview.prompt.md所有工具都可以通过HTTP/SSE由任何兼容MCP的客户端（VS Code、Claude Desktop等）调用。

技术栈：

______________________________________________________________________

安装和设置

先决条件

• Python 3.14+
• uv 包管理器

步骤

# 1. Clone the repository
git clone https://github.com/ghaccount409-school/final_project_se333_NigelMaloney.git
cd final_project_se333_NigelMaloney
cd CodeBase

# 2. Install dependencies (creates .venv automatically)
uv sync

# 3. Install dev dependencies (pytest, pytest-cov)
uv add pytest pytest-cov --dev

# 4. Start the server
uv run python main.py

服务器启动于 http://127.0.0.1:8000。您应该看到：

INFO:     Started server process [XXXXX]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

______________________________________________________________________

配置

VS代码(mcp.json)

添加以下内容 %APPDATA%\Code\User\mcp.json （Windows）或 ~/.config/Code/User/mcp.json （macOS/Linux）：

{
  "servers": {
    "se333-MCP-server": {
      "url": "http://127.0.0.1:8000/sse",
      "type": "http"
    }
  }
}

克劳德桌面版

{
  "mcpServers": {
    "se333-server": {
      "command": "uv",
      "args": ["run", "python", "/absolute/path/to/final_project_se333_NigelMaloney/CodeBase/main.py"]
    }
  }
}

服务器默认值

______________________________________________________________________

运行提示工作流

此存储库包括从Copilot Chat使用的提示文件：

• .github/prompts/tester.prompt.md
• .github/prompts/codereview.prompt.md

在Copilot聊天中使用以下命令：

运行测试人员工作流程

#file:.github/prompts/tester.prompt.md  

例子：

#file:.github/prompts/tester.prompt.md https://github.com/spring-projects/spring-petclinic https://github.com/ghaccount409-school/se333-demo

这与测试仪提示指令模式相匹配：

#file:./tester.prompt.md  

运行代码审查工作流

#file:.github/prompts/codereview.prompt.md

当前 codereview.prompt.md 其指令中不需要位置存储库参数。

______________________________________________________________________

MCP工具参考

analyze_coverage

来源： tester.prompt.md --步骤5（解析Jacoco/覆盖率输出并识别差距）

评估代码覆盖率，并返回带有建议的结构化状态。

参数：

退货： dict

状态阈值：

例子：

check_complexity(cyclomatic_complexity=12, lines_of_code=80)
# → {"complexity_level": "high", "density": 0.15, "needs_refactoring": True, ...}

______________________________________________________________________

测试

# from repository root:
# cd final_project_se333_NigelMaloney/CodeBase

# Run all tests
uv run pytest test_main.py -v

# Run with coverage report
uv run pytest test_main.py --cov=main --cov-report=term-missing

# Run a specific test class
uv run pytest test_main.py::TestScanSecurityRisks -v

测试套件摘要（37个测试，100%覆盖率）：

______________________________________________________________________

故障排除和常见问题

安装

Q No module named 'mcp' 或 No module named 'fastmcp'

跑 uv sync 从 CodeBase 安装所有声明的依赖项的目录。如果 uv 不在您的路径上，请将其定位在 ~/.local/bin/uv （macOS/Linux）或 %USERPROFILE%\.local\bin\uv.exe （Windows）。

______________________________________________________________________

Q Python 3.14 not found 或 requires-python >=3.14

检查您的版本 python --version如果低于3.14，请通过安装 python.org 或 pyenv:

pyenv install 3.14.0
pyenv local 3.14.0
cd CodeBase
uv sync

______________________________________________________________________

Q： Windows上的虚拟环境激活失败

# PowerShell (may require execution policy change)
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
.\.venv\Scripts\Activate.ps1

或使用 uv run 直接避免手动激活。

______________________________________________________________________

运行时

Q OSError: [Errno 10048] / Address already in use 在8000端口

另一个进程正在使用端口8000（可能是之前的服务器实例）。

# Windows — find and kill the process
Get-Process -Id (Get-NetTCPConnection -LocalPort 8000).OwningProcess | Stop-Process

______________________________________________________________________

Q： VS Code无法发现MCP工具

1. 确认服务器正在运行：打开浏览器 http://127.0.0.1:8000/sse --您应该看到一个流式响应。
2. 检查你的 mcp.json 用途 "type": "http" 以及确切的URL http://127.0.0.1:8000/sse.
3. 重新加载VS代码： Ctrl+Shift+P → *开发者：重新加载窗口*.
4. 检查MCP日志： Ctrl+Shift+P → *MCP：显示日志*.

______________________________________________________________________

Q： 工具调用返回 422 Unprocessable Entity

所有布尔参数必须是JSON布尔值(true/false)，不是字符串("true").所有整数参数必须是JSON数字，而不是字符串。

// Wrong
{"has_duplicates": "true", "has_long_functions": "false"}

// Correct
{"has_duplicates": true, "has_long_functions": false}

______________________________________________________________________

Q analyze_coverage 回报 "status": "error"

total_lines 被传递为 0。在调用此工具之前，请确保覆盖率工具已针对实际源文件运行。

______________________________________________________________________

测试

Q pytest 未找到

cd CodeBase
uv add pytest pytest-cov --dev

______________________________________________________________________

Q test_main_runs_mcp_server 失败与 OSError

端口8000已占用（活动服务器已在运行）。在运行测试之前停止它，因为此测试会模拟 FastMCP.run 但早期的测试运行可能使事件循环处于不良状态。终止服务器进程并重新运行。

______________________________________________________________________

Q： 添加新工具后覆盖率降至100%以下

为每个引入的新分支编写至少一个测试。运行：

cd CodeBase
uv run pytest test_main.py --cov=main --cov-report=term-missing

这 Missing 列将显示尚未覆盖的确切行。

______________________________________________________________________

安全与生产

Q： 在公共IP上公开此服务器安全吗？

否。服务器没有身份验证、TLS和速率限制。它仅用于本地/环回使用。对于任何网络部署，将其放置在具有HTTPS和API密钥验证的反向代理（例如nginx）之后。

______________________________________________________________________

Q： 如何向MCP服务器添加身份验证？

fastmcp 不提供内置的身份验证中间件。选项：

1. 反向代理 --将nginx或Caddy放在前面，并需要一个承载令牌头。
2. 定制中间件 --包装ASGI应用程序 mcp 与Starlette BaseHTTPMiddleware 这验证了一个秘密。
3. 基于环境的秘密 --检查 os.environ["API_KEY"] 在每个工具内并提高 ValueError 关于不匹配。

______________________________________________________________________

最后更新时间： 2026年3月12日\ 版本： 0.1.0