关于项目
这个项目是为了创造。NET9/MCP SDK/SK项目MCP服务器 用于Atera API票据管理。
另请参见C:\\工作\\项目\\财务\\ AteraMcpServer\\客户端-项目审查和验收标准.md 和C:\\工作\\项目\\ Fiverr \\ AteraMcpServer \\ Python参考模型分析.md
客户端Python项目参考
客户端出于同样的目的提供了一个Python项目 可以在这里找到并参考： C： \\Work\\Projects\\Fiverr\\Python参考atera-mcp服务器\\
里程碑1:Python参考代码分析
GetAgentList API分析
基于对Python参考代码的分析 C:\Work\Projects\Fiverr\Python-reference-atera-mcp-server\:
端点详细信息
- 基本URL:
https://app.atera.com - 端点：
/api/v3/agents - 方法：GET
- 身份验证：API密钥输入
X-API-KEY头球
请求参数
- 可选查询参数：
- page：分页页码（默认值：1） - itemsInPage：每页项目数（默认值：100）
响应结构
{
"items": [
{
"agentID": "integer",
"customerID": "integer",
"customerName": "string",
"machineID": "string",
"machineName": "string",
"deviceType": "string",
"domain": "string",
"onlineStatus": "boolean",
"lastRebootTime": "datetime",
"lastSeenDateTime": "datetime",
"operatingSystem": "string",
"ipAddress": "string",
"externalIP": "string",
"snmpEnabled": "boolean",
"monitoringThreshold": "integer"
}
],
"itemsCount": "integer",
"totalItems": "integer"
}域模型的关键字段
C#域模型中需要映射的基本字段：
agentID：代理的唯一标识符customerID：关联的客户IDcustomerName：客户企业名称machineName：被监控机器的名称onlineStatus：当前连接状态lastRebootTime：上次系统重启operatingSystem：操作系统详细信息ipAddress：内部IPexternalIP：公共IP
此分析将为我们的C#域模型设计和API集成层实现提供信息。C： \\Work\\Projects\\Fiverr\\Python参考atera-mcp服务器。 但我们不应该盲目地从Python项目中复制任何代码或结构， 因为我们将遵循清洁架构、富域模型、SOLID和TDD/ATDD。
待办
完整项目范围
此报价涵盖了Atera MCP服务器的Pro Tier交付成果，并明确了责任分工：
我的交付成果（专业级别）： 交付完整的C#MCP服务器，包括： •19个针对Atera API的完全测试的C#MCP工具（11个GET，8个突变）。 •为您的数据库查询配置了8种MindsDB技能。 •全面的测试套件（以原始268条路径的复杂性为基准），以确保高可靠性。 •用于部署到两个本地环境的CI/CD管道。
当前里程碑： 里程碑1：核心MCP基础和初始API工具（V0）
步骤：
- 使用干净的体系结构创建C#解决方案（域、API、数据访问层）
- 将Semantic Kernel和Atera API客户端与安全的凭证存储集成在一起
- 实施
GetAgentList带单元测试的MCP工具 - 为本地Docker部署配置CI/CD管道（GitHub操作）
验收标准：\ ✅ C#解决方案成功构建，初始工具的测试通过率为100%\ ✅ GetAgentList 通过MCP客户端返回有效数据（Claude Desktop测试）\ ✅ CI/CD管道会自动部署到您的本地环境 main 分支推送
里程碑1当前状态
已实施：
✅ C#解决方案结构似乎是通过以下方式创建的： 域层（AteraMcp） 数据访问层（AteraApi.DataAccess） 测试项目（\*.UnitTests，\*.IntegrationTests） ✅ GetAgentList工具实现已启动： 核心工具类存在（AgentListTool.cs） 存在单元测试（AgentListToolFacts.cs） 存在集成测试（AteraMcpServerFacts.cs） ✅ API客户端集成： AteraApiGateway类与测试一起存在 可能已实施身份验证（基于测试文件） 尚未实施：
❌ CI/CD管道配置（没有可见的GitHub操作/Docker文件） ❌ 完整的测试覆盖率（需要验证100%的通过率） ❌ 最终部署验证（需要Claude Desktop测试） 解决方案结构和初始工具实施的核心基础已经到位。剩下的工作重点是管道设置和验证。
测试注意事项
- 使用启动服务器
dotnet run --no-build在测试夹具中。 - 使用 我是RPC客户端 发送请求并断言响应。
- 测试按顺序运行以避免端口冲突。
______________________________________________________________________
第三方依赖关系
语义内核（SK）：\
MCP-SDK女士：\
MCP服务器配置示例
注： --no-build 标记是必需的，否则可能会出现连接错误。
"AteraMcp": {
"command": "C:\\Users\\Grand\\.dotnet\\dotnet.exe",
"args": [
"run",
"--project",
"C:\\Work\\Projects\\Fiverr\\AteraMcpServer\\AteraMcp\\AteraMcp.csproj",
"--no-build"
],
"timeout": 60,
"transportType": "stdio",
"env": {
"DOTNET_ENVIRONMENT": "Development",
"Atera__ApiKey": "6a..."
},
"disabled": false
}环境设置
- 创建一个
.env本地测试文件：
DOCKER_USERNAME=your_dockerhub_username
DOCKER_PASSWORD=your_dockerhub_password- 对于GitHub操作，添加存储库机密：
DOCKER_USERNAME：您的Docker Hub用户名DOCKER_PASSWORD：您的Docker Hub密码/访问令牌
设置GitHub机密
要从GitHub Actions构建和推送Docker镜像，您需要为您的Docker Hub凭据设置机密：
- 导航到您的GitHub存储库。
- 点击 设置.
- 在左侧边栏中，单击 秘密和变量 > 行动.
- 点击 新存储库密钥.
- 创建以下机密：
- DOCKER_USERNAME：您的Docker Hub用户名 - DOCKER_PASSWORD：您的Docker Hub密码或访问令牌
GitHub Actions工作流将使用这些秘密向Docker Hub进行身份验证。
分析测试日志
CI/CD测试脚本(test-ci-cd.sh 和 test-ci-cd.ps1)在中生成详细日志 Logs/ 目录。以下是如何使用PowerShell有效地阅读它们。
基本命令：
查看文件内容的标准命令是 Get-Content:
Get-Content .\Logs\test-ci-cd-YYYYMMDD-HHMMSS.log准则和最佳实践：
- 大文件速度慢： 测试脚本可以生成非常大的日志文件。跑步
Get-Content在大文件上可能会很慢，让命令看起来像卡住了。要快速查看最近的活动，请使用-Tail参数以查看最后N行。
# Shows the last 50 lines of the log, which is much faster
Get-Content .\Logs\.log -Tail 50- 实时反馈： PowerShell脚本现在使用
Tee-Object在控制台中实时显示命令输出 *同时* 将其写入日志文件。这对于监控长时间运行的命令（如dotnet test或docker build)并确认它们没有卡住。
.gitignore和工具： 该项目的.gitignore文件包含规则*.log这是一种最佳实践，但它可能会阻止某些IDE工具或自动代理访问日志文件。如果工具报告无法访问日志文件，解决方法是使用直接Get-Content从标准PowerShell终端执行命令，因为这不受相同的限制。
Docker容器化
AteraMcp服务器已对接，便于部署和CI/CD集成。
主要特点
- 多阶段构建，实现最佳图像大小
- 针对控制台应用程序优化的.NET 9运行时
- 适当的层缓存可实现快速重建
- MCP协议的标准通信
塑造形象
docker build -t atera-mcp .运行容器
# Basic run (stdio mode)
docker run -it atera-mcp
# With environment variables
docker run -it -e ATERA_API_KEY=your_key atera-mcp测试容器
# Send JSON-RPC 2.0 command
echo '{"jsonrpc":"2.0","method":"mcp-version","id":1}' | docker run -i atera-mcpCI/CD集成
GitHub操作工作流示例：
steps:
- name: Build Docker image
run: docker build -t atera-mcp .
- name: Run tests
run: |
echo '{"jsonrpc":"2.0","method":"echo","params":{"message":"test"},"id":1}' \
| docker run -i -e ATERA_API_KEY=${{ secrets.ATERA_API_KEY }} atera-mcp实现注意事项
- 通过stdio使用JSON-RPC 2.0
- 配置的环境变量
.dockerignore优化构建上下文
测试
一次性CI/CD验证
使用辅助脚本在本地执行完整的跨环境测试计划。
Linux/WSL
从…开始 Windows终端 使用内置 wsl 命令（无需打开单独的WSL窗口）：
# Windows PowerShell / CMD
wsl bash -c "cd /mnt/c/Work/Projects/Fiverr/AteraMcpServer && chmod +x scripts/test-ci-cd.sh && ./scripts/test-ci-cd.sh"或者，如果你已经 内部 WSL外壳：
cd /mnt/c/Work/Projects/Fiverr/AteraMcpServer
chmod +x scripts/test-ci-cd.sh # first time only
./scripts/test-ci-cd.shWindows PowerShell
# From a Developer PowerShell prompt
# -ApiKey parameter is optional if the variable or .atera_apikey exists
.\scripts\test-ci-cd.ps1 -ApiKey 'your_api_key_here'脚本执行以下操作：
- 通过以下方式调试和发布构建/测试
build.sh/build.ps1. - CI管道仿真
act. - Docker镜像构建和容器内集成测试。
- （PowerShell）本机Windows调试/发布测试运行。
API密钥处理
项目按以下顺序查找Atera API密钥：
- 环境变量
Atera__ApiKey（首选）。 .atera_apikey存储库根目录中的明文文件（仅方便使用，默认情况下忽略git）。
如果两者都不提供，那么到达Atera API的集成测试将被跳过/失败。
自动动作缓存
测试脚本将自动执行以下操作：
- 检查本地缓存
act在……里面.bin/目录 - 全系统使用
act如有 - 安装并缓存
act如果丢失，请在本地
不需要手动安装-脚本会处理所有事情。
建立和运行
先决条件
- .NET 9 SDK（9.0.301或更高版本）
- 启用WSL 2集成的Docker桌面
- 转到设置->资源->WSL集成并为您的发行版启用
- GitHub CLI（可选，用于CI模拟）
- PowerShell 7+（适用于Windows脚本）
- Bash（用于Linux/WSL脚本）
- MCP。NET SDK
编译说明
- 导航到项目目录：
cd C:\Work\Projects\Fiverr\AteraMcpServer- 使用构建解决方案。净值9：
C:\Users\Grand\.dotnet\dotnet.exe build- 运行测试：
C:\Users\Grand\.dotnet\dotnet.exe test.NET 9兼容性
- 项目目标
net9.0并使用现代。NET功能 - MCP SDK与完美配合。NET 9-关于的所有警告。NET 9兼容性可以安全地忽略
- 已验证正在使用。净价9.0.301瑞典克朗
故障排除
如果您遇到构建问题：
- 清除NuGet缓存：
dotnet nuget locals all --clear- 还原包：
dotnet restore- 完全重建：
dotnet clean
dotnet build配置设置
- API密钥配置:
- 对于开发，使用用户机密：
dotnet user-secrets init
dotnet user-secrets set "Atera:ApiKey" "your_api_key_here"- 对于生产，设置环境变量：
Atera__ApiKey=your_api_key_here- 配置文件:
- appsettings.json：模板配置（已签入源代码管理） - appsettings.Development.json：本地覆盖（gitignored）
配置
API密钥应存储在用户机密中（与AteraApi.DataAccess项目共享）：
{
"Atera": {
"ApiKey": "your_api_key_here"
}
}```