Apple Health MCP Template

Apple Health MCP服务器模板


用于生成Apple Health MCP（模型上下文协议）服务器的Jinja2模板存储库。此模板创建了一个完整的Gradio应用程序，作为MCP服务器，用于查询存储在HuggingFace数据集中的Apple Health数据。

概述

此模板存储库提供：

• Jinja2模板：用于生成MCP服务器代码的可配置模板
• CLI工具：用于呈现和验证模板的脚本
• 测试套件：模板功能的全面测试
• CI/CD：GitHub自动化测试操作
• 集成就绪：设计用于与主着陆区应用程序配合使用

存储库结构

apple-health-mcp-template/
├── template/                 # Jinja2 template files
│   ├── app.py.j2            # Main Gradio application
│   ├── requirements.txt.j2   # Python dependencies
│   ├── README.md.j2         # Generated space documentation
│   └── .gitignore.j2        # Git ignore patterns
├── test_configs/            # Test configuration files
│   ├── default.yaml         # Minimal test configuration
│   └── example.yaml         # Complete example configuration
├── scripts/                 # CLI tools
│   ├── render.py           # Template rendering script
│   └── validate.py         # Validation utilities
├── tests/                  # Test suite
│   ├── test_render.py      # Renderer tests
│   └── test_templates.py   # Template-specific tests
└── .github/workflows/      # GitHub Actions CI/CD
    └── test.yml           # Test workflow

快速开始

1.克隆存储库

git clone https://github.com/grll/apple-health-mcp-template.git
cd apple-health-mcp-template

2.安装依赖项

pip install -r requirements-dev.txt

3.渲染模板

python scripts/render.py --config test_configs/default.yaml --output output/

4.验证输出

python scripts/validate.py --output output/ --verbose

配置

模板是使用YAML文件配置的。以下是一个完整的配置示例：

# Required variables
dataset_repo_id: "username/health-data"
space_repo_id: "username/health-mcp-server"
username: "username"
project_name: "my-health"

# Optional variables with defaults
enable_sql_tab: true
enable_mcp_endpoint: true
enable_debug: false
custom_title: "My Health MCP Server"

# Version information
app_version: "1.0.0"
gradio_version: ">=5.34.0"
hf_hub_version: ">=0.20.0"
pandas_version: ">=2.0.0"

# Additional requirements (list)
additional_requirements:
  - "plotly>=5.0.0"
  - "numpy>=1.24.0"

# Metadata
creation_date: "2024-01-01T00:00:00Z"

必需变量

• dataset_repo_id：HuggingFace数据集存储库ID（例如，“用户/健康数据”）
• space_repo_id：HuggingFace空间存储库ID（例如，“用户/健康mcp”）
• username：HuggingFace用户名
• project_name：用户定义的项目名称

可选变量

• enable_sql_tab：显示/隐藏SQL查询接口（默认值：true）
• enable_mcp_endpoint：显示/隐藏MCP配置选项卡（默认值：true）
• enable_debug：启用调试日志记录（默认值：false）
• custom_title：空间的自定义标题（默认：“Apple Health MCP服务器”）
• additional_requirements：附加Python包列表

CLI工具

渲染脚本

这 render.py 脚本使用配置处理模板：

# Basic usage
python scripts/render.py --config config.yaml --output output_dir/

# With variable overrides
python scripts/render.py --config config.yaml --output output_dir/ \
  --var username=myuser --var enable_debug=true

# Dry run (show what would be rendered)
python scripts/render.py --config config.yaml --output output_dir/ --dry-run

# Validate configuration only
python scripts/render.py --config config.yaml --output output_dir/ --validate

选项

• --config, -c：YAML配置文件的路径（必需）
• --output, -o：渲染文件的输出目录（必需）
• --validate：在不呈现的情况下验证配置
• --force：覆盖现有输出目录
• --verbose：启用详细日志记录
• --dry-run：显示在不写入文件的情况下呈现的内容
• --var KEY=VALUE：覆盖配置变量

验证脚本

这 validate.py 脚本验证模板、配置和输出：

# Validate configuration file
python scripts/validate.py --config config.yaml

# Validate template directory
python scripts/validate.py --template template/

# Validate rendered output
python scripts/validate.py --output rendered_output/

# Validate specific files
python scripts/validate.py --python app.py --requirements requirements.txt

# Validate everything
python scripts/validate.py --all --verbose

模板功能

生成的MCP服务器功能

渲染的MCP服务器包括：

• SQL查询接口：对健康数据执行自定义SQL查询
• 数据库架构浏览器：探索表结构和列
• MCP配置：准备好使用Claude Desktop配置
• 健康数据可视化：基础数据探索界面
• 私人数据处理：所有数据都保留在您的HuggingFace空间中

条件内容

模板支持基于配置的条件呈现：

{% if enable_sql_tab %}
# SQL query interface code
{% endif %}

{% if enable_debug %}
logger.setLevel(logging.DEBUG)
{% endif %}

变量替换

所有配置变量都在模板中可用：

DATASET_REPO_ID = "{{ dataset_repo_id }}"
PROJECT_NAME = "{{ project_name }}"
ENABLE_DEBUG = {{ enable_debug | lower }}

测试

运行所有测试

pytest tests/ -v

测试类别

1. 单元测试 (test_render.py)：测试渲染逻辑和配置处理
2. 模板测试 (test_templates.py)：验证模板内容和呈现
3. 集成测试：端到端模板呈现和验证

手动测试

# Render with test configuration
python scripts/render.py --config test_configs/default.yaml --output test_output/

# Test the generated app
cd test_output/
pip install -r requirements.txt
python app.py

与主应用程序集成

此模板旨在与主着陆区应用程序集成。整合包括：

1. 克隆模板存储库：主应用程序克隆此仓库
2. 使用用户配置渲染：应用用户特定的配置
3. 上传到 HuggingFace：使用渲染代码创建私有空间

集成代码示例

def create_space_from_template(template_repo_url, config, space_repo_id, token, api):
    # Clone template repository
    template_dir = clone_repo(template_repo_url)
    
    # Render templates
    renderer = TemplateRenderer(template_dir / "template")
    rendered_files = renderer.render_templates(config, output_dir)
    
    # Upload to HuggingFace Space
    for file_path in rendered_files:
        api.upload_file(file_path, space_repo_id, token=token)

发展

设置开发环境

# Clone repository
git clone https://github.com/grll/apple-health-mcp-template.git
cd apple-health-mcp-template

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
pytest tests/

# Lint code
flake8 scripts/ tests/

# Format code
black scripts/ tests/

添加新模板

1. 创建新的 .j2 文件在 template/ 目录
2. 将模板变量添加到配置架构中
3. 如果需要，更新验证逻辑
4. 为新模板添加测试
5. 更新文档

模板变量指南

• 使用snake_case作为变量名
• 在布尔变量前加上前缀 enable_
• 记录配置示例中的所有变量
• 为可选变量提供合理的默认值
• 验证变量类型和值

安全考虑

• 输入验证：在模板替换之前，所有用户输入都经过验证
• Jinja2汽车逃生：HTML内容自动转义
• 无代码执行：模板不允许执行任意代码
• 路径消毒：在渲染脚本中验证文件路径

贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 进行更改
4. 添加新功能的测试
5. 运行测试套件(pytest tests/)
6. 提交您的更改(git commit -m 'Add amazing feature')
7. 推到分支(git push origin feature/amazing-feature)
8. 打开拉取请求

贡献指南

• 遵循现有的代码风格和约定
• 为新功能添加测试
• 更新API变更文档
• 确保所有测试通过
• 保持提交的重点和原子性

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

支持

• 问题：通过以下方式报告错误和请求功能
• 讨论：提问并分享想法
• 文档：本自述中提供了完整的文档

更新日志

v1.0.0（初始版本）

• 用于MCP服务器生成的完整Jinja2模板系统
• 用于渲染和验证的CLI工具
• 全面的测试套件
• GitHub操作CI/CD管道
• 主应用程序的集成就绪设计

______________________________________________________________________

*此模板存储库允许轻松生成具有可定制配置和强大验证的Apple Health MCP服务器。*