MSSE Capstone Project

MSSE Capstone项目——Garmin数据的MCP服务器

此存储库为MSSE顶点项目提供了一个模型上下文协议（MCP）服务器。它与Garmin Connect集成，通过MCP工具提供活动和健康数据，使AI代理能够访问锻炼信息、用户偏好和设备可用性。

High Level Architecture

目的

此MCP服务器提供：

• Garmin数据集成：活动统计、身体电池、睡眠、心率变异性、压力、训练准备和活动历史
• 用户偏好管理：本地存储的锻炼偏好和可用设备
• MCP兼容接口：AI代理可以用来查询和存储用户数据的工具
• 身份验证处理：Garmin Connect身份验证的强大MFA支持

可用的MCP工具

Garmin数据工具

• daily_stats(mfa_code: str = None) -今天的活动统计数据（步数、距离、卡路里、楼层）
• last_activity(mfa_code: str = None) -最新锻炼/活动详情
• body_battery(start_date: str, end_date: str = None, mfa_code: str = None) -日期范围的车身蓄电池数据
• all_day_stress(start_date: str, end_date: str = None, mfa_code: str = None) -压力水平数据
• sleep_data(start_date: str, end_date: str = None, mfa_code: str = None) -睡眠分析数据
• hrv_data(start_date: str, end_date: str = None, mfa_code: str = None) -心率变异性指标
• training_readiness(mfa_code: str = None) -当前训练准备得分
• training_status(mfa_code: str = None) -培训状态和负载信息
• activities(start_date: str, end_date: str = None, activity_type: str = None, sort_order: str = None, mfa_code: str = None) -带有过滤功能的活动历史记录

用户首选项工具

• workout_preferences(preferences_data: dict = None) -获取或设置锻炼偏好（目标、频率、强度、限制）
• available_equipment(equipment_data: dict = None) -获取或设置可用的锻炼设备

实用工具

• steps_to_miles(steps: int) -将步数转换为英里（步数÷2000）

认证流程

所有Garmin工具都支持MFA身份验证：

1. 第一个电话：使用从中保存的令牌 ~/.garminconnect 如果可用，否则使用来自的凭据登录 garmin_config.json
2. 如果需要MFA：工具返回 mfa_required 指令错误
3. 提供MFA代码：再次调用工具 mfa_code="123456" 参数
4. 后续通话：自动使用已保存的令牌

需求

• Python 3.13+
• 紫外线 （推荐）或pip用于依赖关系管理
• Garmin Connect帐户 有证书

配置

Garmin设置

1. 复制模板： cp garmin_config.json.template garmin_config.json
2. 编辑 garmin_config.json 使用您的Garmin凭据：

   {
     "email": "your.email@example.com",
     "password": "your_password",
     "token_dir": "~/.garminconnect"
   }

1. 令牌会自动保存到 ~/.garminconnect 首次成功身份验证后

Claude桌面集成

添加到您的Claude Desktop配置文件(~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "MSSE-Capstone-Project": {
      "command": "/Users/[username]/.local/bin/uv",
      "args": [
        "--directory",
        "/Users/[username]/MSSE-Capstone-Project",
        "run",
        "server.py"
      ]
    }
  }
}

注： 在任何代码更改后重新启动Claude Desktop以重新加载服务器。

入门指南

安装

1. 克隆存储库

   git clone https://github.com/kafargo/MSSE-Capstone-Project.git
   cd MSSE-Capstone-Project

1. 设置虚拟环境

使用紫外线（推荐）：

   uv venv
   source .venv/bin/activate

或者使用标准Python：

   python3.13 -m venv .venv
   source .venv/bin/activate

1. 安装依赖项

使用紫外线：

   uv sync

或者使用pip：

   pip install -e .
   # For development dependencies:
   pip install -e ".[dev]"

1. 配置Garmin凭据

   cp garmin_config.json.template garmin_config.json
   # Edit garmin_config.json with your credentials

运行服务器

开发/测试：

uv run server.py

使用克劳德桌面： 当Claude启动时，服务器会自动启动（无需手动启动）

验证安装

# Run tests
make test

# Check server processes (when running manually)
pgrep -af server.py

测试

该项目使用具有全面测试覆盖率的pytest。

快速命令

# Run all tests
make test

# Run only unit tests
make test-unit

# Run with coverage report
make test-coverage

# Run MCP-specific tests
make test-mcp

# Run Garmin client tests
make test-garmin

测试结构

tests/
├── conftest.py                  # Shared fixtures and configuration
├── test_garmin_client.py        # Unit tests for Garmin client
├── test_preferences_client.py   # Unit tests for preferences client
├── test_mcp_tools.py            # Integration tests for MCP tools
└── test_utils.py                # Test utilities and helpers

测试类别（标记）

• @pytest.mark.unit -具有模拟依赖关系的快速测试
• @pytest.mark.integration -使用真实组件交互进行测试
• @pytest.mark.mcp -MCP服务器和工具功能
• @pytest.mark.garmin -Garmin客户端功能
• @pytest.mark.slow -进行真正API调用的测试（谨慎使用）

运行特定测试

# Run a specific test file
pytest tests/test_garmin_client.py

# Run a specific test class or function
pytest tests/test_garmin_client.py::TestConfigManagement::test_load_config_existing_file

# Run tests matching a pattern
pytest tests/ -k "mfa"

# Run tests with specific markers
pytest tests/ -m unit

项目结构

MSSE-Capstone-Project/
├── server.py                    # MCP server with tool definitions
├── msse_capstone/
│   ├── __init__.py
│   └── clients/
│       ├── garmin_client.py     # Garmin Connect integration
│       └── preferences_client.py # User preferences management
├── tests/                       # Test suite
├── garmin_config.json.template  # Template for Garmin credentials
├── workout_preferences.json     # Stored workout preferences
├── available_equipment.json     # Stored equipment data
├── pyproject.toml              # Project dependencies and metadata
├── pytest.ini                  # Test configuration
└── Makefile                    # Common development tasks

贡献

欢迎捐款。请打开bug和功能想法的问题，并提交PR main 带有测试和简短的更改日志条目。

许可证

此项目根据MIT许可证条款发布。看 LICENSE 了解详情。