Bodyspec MCP

BodySpec MCP服务器

一个模型上下文协议（MCP）服务器，提供用于与BodySpec API交互的工具，允许访问DEXA扫描数据和健康信息。

特性

• API全面覆盖：所有BodySpec API端点都可用作MCP工具
• 认证：通过进行承载令牌身份验证 .env 文件配置
• 错误处理：全面的错误处理和记录
• 类型安全：完整的Pydantic模型验证
• 异步支持：内置async/await以获得最佳性能
• MCP协议：MCP通信的正确stdio传输实施

可用工具

API状态

• bodyspec_api_info -获取API信息和版本
• bodyspec_health_check -检查API运行状况

用户管理

• bodyspec_get_user_info -获取当前用户配置文件
• bodyspec_update_user_info -更新用户配置文件信息

预约

• bodyspec_list_appointments -使用筛选功能列出用户约会
• bodyspec_get_appointment -获取详细的预约信息

结果

• bodyspec_list_results -列出用户测试结果
• bodyspec_get_result_detail -获取详细的结果信息

DEXA分析

• bodyspec_dexa_scan_info -获取DEXA扫描元数据
• bodyspec_dexa_composition -按地区获取身体成分数据
• bodyspec_dexa_bone_density -获取骨矿物质密度测量值
• bodyspec_dexa_percentiles -获得年龄/性别匹配的百分位数排名
• bodyspec_dexa_visceral_fat -进行内脏脂肪组织分析

安装

1. 克隆或下载此存储库

1. 安装依赖项:

   pip install -r requirements.txt

1. 设置身份验证:

第一步：获取您的Bearer代币

1. 访问BodySpec API文档，网址：https://app.bodyspec.com/docs 1. 登录您的BodySpec帐户（如果尚未登录） 1. 导航到 认证 或 API密钥 文档中的章节 1. 查找有关生成或检索OAuth2访问令牌（承载令牌）的说明 1. 复制令牌-它应该是一个长字符串（JWT格式）

注： 如果您需要帮助查找令牌，请查看MCP设置指南，网址为https://app.bodyspec.com/#mcp-设置

步骤2：配置令牌

创建一个 .env 在项目根目录中创建文件并添加您的令牌：

   # Copy the example file
   cp env_example.txt .env

   # Edit .env and add your token
   BODYSPEC_ACCESS_TOKEN=your_token_here

您还可以在中配置其他设置 .env 文件（请参阅下面的配置部分）。

步骤3：为Cursor配置mcp.json

将最小配置添加到您的 mcp.json 文件（Cursor需要）：

   {
     "mcpServers": {
       "BodySpec": {
         "command": "python",
         "args": ["/path/to/bodyspec-mcp/server.py"],
         "env": {
           "PYTHONUNBUFFERED": "1"
         }
       }
     }
   }

注： 令牌和其他配置值只能在 .env 文件，不在 mcp.jsonThe mcp.json 该文件只需要Cursor知道如何运行服务器。

认证

服务器使用承载令牌身份验证。您需要从BodySpec的API文档中获取一个JWT访问令牌，并按上面所示进行配置。

用法

运行服务器

python server.py

服务器将启动并准备接受MCP工具调用。

工具调用示例

获取API信息

{
  "name": "bodyspec_api_info",
  "arguments": {}
}

列出最近的约会

{
  "name": "bodyspec_list_appointments",
  "arguments": {
    "limit": 10,
    "sort_order": "newest_first"
  }
}

获取身体成分数据

{
  "name": "bodyspec_dexa_composition",
  "arguments": {
    "result_id": "your_result_id_here"
  }
}

获取百分位数排名

{
  "name": "bodyspec_dexa_percentiles",
  "arguments": {
    "result_id": "your_result_id_here",
    "min_age": 30,
    "max_age": 40
  }
}

配置

使用中的环境变量配置服务器 .env 文件。配置源按以下优先级顺序加载（从高到低）：

1. .env 文件 （最高优先级）-应在此处设置所有配置值
2. 系统环境变量 -在shell/系统中设置的变量
3. mcp.json env部分 -仅用于光标特定的设置，如 PYTHONUNBUFFERED

注： 这 .env 文件是您应该配置令牌和所有其他设置的地方。这 mcp.json 这个文件只需要Cursor知道如何运行服务器，并且应该包含最少的配置。

数据模型

服务器使用符合BodySpec API规范的Pydantic模型：

• 用户响应：用户配置文件信息
• 预约：包含位置和服务信息的预约详情
• 结果摘要/结果细节响应：测试结果信息
• Dexa组合响应：按地区分列的身体成分数据
• 地塞米松密度反应：骨密度测量
• Dexapercent反应：年龄/性别匹配的百分位数排名
• Dexa内脏脂肪反应：内脏脂肪组织分析

错误处理

服务器提供全面的错误处理：

• 身份验证错误：令牌无效或过期
• API错误：来自BodySpec API的HTTP错误
• 验证错误：输入参数无效
• 网络错误：超时和连接问题

所有错误都会被记录下来，并作为用户友好的消息返回。

发展

项目结构

bodyspec-mcp-server/
├── server.py              # Main MCP server
├── config.py              # Configuration management
├── auth.py                # Authentication handling
├── api_client.py          # BodySpec API client
├── models.py              # Pydantic data models
├── tools/                 # MCP tools directory
│   ├── __init__.py
│   ├── status_tools.py    # API status tools
│   ├── user_tools.py      # User management tools
│   ├── appointment_tools.py # Appointment tools
│   ├── result_tools.py    # Results tools
│   └── dexa_tools.py      # DEXA-specific tools
├── requirements.txt       # Python dependencies
├── README.md             # This file
└── example_usage.py      # Usage examples

添加新工具

1. 在中创建新的工具模块 tools/ 目录
2. 实施 register_*_tools() 函数
3. 在中导入和注册工具 server.py

测试

测试单个组件：

# Test authentication
from auth import create_auth
auth = create_auth()
print(f"Authenticated: {auth.is_authenticated()}")

# Test API client
from api_client import create_client
import asyncio
client = create_client()
info = await client.get_api_info()
print(f"API Version: {info.version}")

支持

有关BodySpec API的问题，请联系：dev-support@bodyspec.com

对于MCP服务器问题，请检查日志（写入stderr），并确保您已配置 BODYSPEC_ACCESS_TOKEN 在你的 .env 文件。

许可证

本项目是作为i提供的，用于与BodySpec API集成。有关API使用指南，请参阅BodySpec的服务条款。