AI导哈

运动数据库MCP服务

一个生产就绪的Model Context Protocol (MCP)服务器，通过Claude AI应用程序提供对1300多种运动数据库的全面访问。

  • by milosptr
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 milosptr/fittality-exercises-mcp

使用说明

运动数据库MCP服务器

一个生产就绪的模型上下文协议（MCP）服务器，通过Claude AI应用程序提供对1300多个练习数据库的全面访问。

📋 目录

🎯 概述

运动数据库MCP服务器是一个全面的健身数据服务，通过模型上下文协议为Claude AI应用程序提供1300多种运动的访问权限。它使用TypeScript和Express构建，提供高级搜索功能、健康监控和性能跟踪。

什么是MCP？

这 模型上下文协议（MCP） 是连接AI应用程序与外部数据源和工具的标准。该服务器实现了MCP，为Claude提供了对运动数据的无缝访问。

关键能力

  • 🔍 高级搜索 -具有过滤和分页功能的多字段练习搜索
  • 📊 健康监测 -实时数据库运行状况和性能指标
  • 🎯 练习建议 -根据设备和肌肉群寻找替代运动
  • 📋 数据验证 -执行ID验证和数据库完整性检查
  • 🚀 生产就绪 -具有全面的错误处理功能，可扩展

✨ 特性

运动数据库

  • 1324次练习 具有全面的元数据
  • 10种设备类型 （体重、哑铃、杠铃等）
  • 15+运动类别 （胸部、背部、腿部、腹肌等）
  • 50+肌肉群 用于有针对性的锻炼
  • Apple HealthKit集成 有适当的类别

搜索和筛选

  • 文本搜索 跨越练习名称和说明
  • 设备过滤 可用的健身器材
  • 类别筛选 按肌肉群和身体部位
  • 多条件搜索 支持分页
  • 相关性评分 获得最佳搜索结果

健康与监测

  • 实时健康检查 具有详细的状态报告
  • 性能指标 跟踪搜索延迟和内存使用情况
  • 数据库完整性验证 检查重复和缺失的字段
  • 系统信息 报告Node.js和运行时详细信息

MCP集成

  • 11个MCP工具 全面锻炼通道
  • 4 MCP资源 用于直接数据访问
  • SSE 运输 通过HTTP进行实时通信
  • Zod模式验证 用于类型安全

🚀 快速开始

# Clone the repository
git clone <repository-url>
cd fittality-exercises-mcp

# Install dependencies
pnpm install

# Build the project
pnpm build

# Start the server
pnpm dev

服务器将于启动 http://localhost:8080 健康检查在 /health.

📦 安装

先决条件

  • Node.js >= 18.0.0
  • pnpm >=8.0.0（或npm/yarn）
  • TypeScript 5.8+（包含在开发依赖项中）

环境设置

  1. 克隆并安装：

    git clone <repository-url>
cd fittality-exercises-mcp
pnpm install

  2. 配置环境（可选）：

    cp .env.example .env
# Edit .env with your configuration

  3. 构建项目：

    pnpm build

  4. 启动服务器：

    # Development mode (with hot reload)
pnpm dev

# Production mode
node dist/main.js

环境变量

变量 默认值 描述
PORT 8080 服务器端口
NODE_ENV development 环境模式
JWT_SECRET - 用于身份验证的JWT密钥（如果需要）

🎮 用法

Claude桌面集成

将此服务器添加到您的Claude Desktop配置中：

{
  "mcpServers": {
    "exercise-database": {
      "command": "node",
      "args": ["/path/to/fittality-exercises-mcp/dist/main.js"],
      "env": {
        "PORT": "8080"
      }
    }
  }
}

克劳德网络集成（OAuth 2.0）

服务器支持OAuth 2.0用于Claude Web集成。部署后，Claude Web可以使用以下OAuth端点进行连接：

OAuth端点

  • OAuth元数据: /.well-known/oauth-authorization-server
  • 授权: /authorize
  • 代币交换: /token
  • 令牌撤销: /revoke

OAuth配置

为安全操作设置以下环境变量：

CLAUDE_CLIENT_SECRET=your-secure-secret-here
BASE_URL=https://your-deployed-server.com

受保护的MCP端点

Claude Web通过OAuth保护的端点访问MCP功能：

  • SSE 连接: /mcp/sse （需要Bearer代币）
  • 消息处理: /mcp/messages （需要Bearer代币）

OAuth流

  1. Claude Web重定向到 /authorize?client_id=claude-web&response_type=code
  2. 服务器自动批准并使用授权码重定向回
  3. Claude Web在以下地址交换访问令牌代码 /token
  4. 访问令牌对后续MCP请求进行身份验证

OAuth功能：

  • 使用PKCE（代码交换证明密钥）的授权代码流
  • S256代码挑战方法支持
  • 承载令牌身份验证
  • 1小时代币到期
  • 令牌撤销支持
  • 动态Claude Web客户端ID支持(exercise-mcp-client-*)
  • 支持多个作用域： claudeai, mcp:read, mcp:write
  • 正确的重定向URI: https://claude.ai/api/mcp/auth_callback

基本示例

搜索练习

Find me some chest exercises using dumbbells

获取锻炼替代方案

I want alternatives to push-ups that use body weight

验证练习ID

Check if these exercise IDs are valid: 874ce7a1-2022-449f-92c4-742c17be51bb

获取数据库统计信息

Show me statistics about the exercise database

🛠️ MCP工具

服务器提供11个全面的MCP工具：

核心练习工具

search_exercises

具有多个条件和分页的搜索练习。

参数：

  • query （字符串，可选）-在名称和说明之间进行文本搜索
  • equipment （字符串，可选）-按设备类型过滤
  • category （字符串，可选）-按运动类别筛选
  • primaryMuscles （阵列，可选）-按主要肌肉群过滤
  • secondaryMuscles （阵列，可选）-按次级肌群过滤
  • limit （数字，可选）-每页结果（默认值：20，最大值：100）
  • offset （数字，可选）-分页结果偏移

例子：

{
  "name": "search_exercises",
  "arguments": {
    "equipment": "body weight",
    "category": "chest",
    "limit": 10
  }
}

get_exercise_by_id

通过其唯一ID检索特定练习。

参数：

  • id （字符串，必填）-练习UUID

find_exercise_alternatives

根据目标练习找到替代练习。

参数：

  • exerciseId （字符串，必填）-目标练习ID
  • equipment （字符串，可选）-备选方案的首选设备
  • limit （数字，可选）-备选方案数量（默认值：5）

筛选工具

filter_exercises_by_equipment

按照特定设备过滤练习。

参数：

  • equipment （字符串，必填）-设备类型
  • limit （数字，可选）-结果限制
  • offset （数字，可选）-结果偏移

get_exercises_by_category

按类别筛选练习。

参数：

  • category （字符串，必填）-运动类别
  • limit （数字，可选）-结果限制
  • offset （数字，可选）-结果偏移

验证工具

validate_exercise_keys

一次验证多个锻炼ID。

参数：

  • exerciseIds （数组，必填）-要验证的练习ID数组

元数据工具

get_categories

获取所有可用的锻炼类别。

get_equipment_types

获取所有可用的设备类型。

get_muscle_groups

获取所有可用的肌肉群。

健康监测工具

get_database_health

获取全面的数据库运行状况。

get_database_stats

获取详细的数据库统计信息。

参数：

  • limit （数量，可选）-类别细分限制
  • offset （数字，可选）-分页偏移量

get_performance_metrics

获取实时性能指标。

validate_database_integrity

验证数据库完整性并检查是否存在问题。

参数：

  • limit （数量，可选）-重复检查的限制
  • offset （数字，可选）-分页偏移量

get_system_info

获取系统和运行时信息。

reset_performance_metrics

重置绩效跟踪指标。

📚 MCP资源

服务器提供4个MCP资源用于直接数据访问：

exercise://{id}

通过ID直接访问个人练习。

例子： exercise://874ce7a1-2022-449f-92c4-742c17be51bb

exercise://stats

数据库统计和指标。

exercise://health

实时健康状态信息。

exercise://performance

性能指标和监控数据。

📖 api参考

练习数据结构

interface Exercise {
  id: string;                    // UUID identifier
  name: string;                  // Exercise name
  equipment: string;             // Required equipment
  category: string;              // Exercise category
  appleCategory: string;         // Apple HealthKit category
  bodyPart: string;              // Target body part
  primaryMuscles: string[];      // Primary muscle groups
  secondaryMuscles: string[];    // Secondary muscle groups
  instructions: string[];        // Step-by-step instructions
  images: string[];              // Exercise images/GIFs
}

健康检查端点

获取 /health

返回服务器运行状况和基本指标。

答复：

{
  "status": "healthy",
  "service": "Exercise Database MCP Server",
  "version": "1.0.0",
  "exerciseCount": 1324,
  "timestamp": "2025-07-02T22:42:18.406Z"
}

SSE 终端

获取 /sse

为MCP通信建立服务器发送事件连接。

消息端点

发布 /messages

通过HTTP处理MCP消息。

🏗️ 建筑

项目结构

fittality-exercises-mcp/
├── src/
│   ├── main.ts                     # Server entry point
│   ├── types.ts                    # TypeScript interfaces
│   ├── exercise-functions/         # Business logic
│   │   ├── loader.ts              # Data loading & retrieval
│   │   ├── search.ts              # Search & filtering
│   │   ├── validation.ts          # ID validation
│   │   ├── alternatives.ts        # Exercise alternatives
│   │   ├── metadata.ts            # Categories & equipment
│   │   ├── health.ts              # Health monitoring
│   │   └── performance.ts         # Performance tracking
│   └── tools/                     # MCP tool implementations
│       ├── search-tools.ts        # Search functionality
│       ├── lookup-tools.ts        # ID lookups & validation
│       ├── filter-tools.ts        # Filtering tools
│       ├── metadata-tools.ts      # Resource listings
│       └── health-tools.ts        # Health monitoring
├── data/
│   └── exercises.json             # Exercise database (1.2MB)
├── dist/                          # Compiled JavaScript
├── package.json                   # Project configuration
├── tsconfig.json                  # TypeScript configuration
└── .env                           # Environment variables

技术栈

  • 运行时间： Node.js 18+
  • 语言： TypeScript 5.8.3
  • Web框架： 快递5.1.0
  • MCP-SDK： @模型上下文协议/sdk 1.13.3
  • 验证： 佐德3.25.69
  • 运输： 服务器发送事件（SSE）
  • 构建工具： TypeScript编译器
  • 包管理器： pnpm

设计模式

  • 领域驱动设计 -按业务领域组织的功能
  • 关注点分离 -MCP工具和业务逻辑之间的明确分离
  • 工厂模式 -工具注册和服务器配置
  • 观察者模式 -SSE事件流
  • 策略模式 -多种搜索和过滤策略

🏥 健康监测

健康检查

服务器提供全面的健康监控：

curl http://localhost:8080/health

性能指标

跟踪关键绩效指标：

  • 搜索延迟 -平均搜索响应时间
  • 内存使用 -当前内存消耗
  • 请求计数 -已处理的请求总数
  • 错误率 -失败请求百分比

数据库完整性

定期完整性检查包括：

  • 副本检测 -查找重复的练习条目
  • 缺少字段 -验证所需字段是否存在
  • 数据一致性 -检查引用完整性
  • 架构验证 -确保数据类型正确

监视工具

使用内置的MCP工具进行监控：

// Get health status
get_database_health()

// Get performance metrics
get_performance_metrics()

// Validate database integrity
validate_database_integrity()

// Get system information
get_system_info()

🛠️ 发展

设置开发环境

# Clone and install
git clone <repository-url>
cd fittality-exercises-mcp
pnpm install

# Start development server with hot reload
pnpm dev

可用脚本

# Build the project
pnpm build

# Start development server
pnpm dev

# Run in production mode
node dist/main.js

# Type checking
tsc --noEmit

# Format code (if prettier is configured)
pnpm format

添加新工具

  1. 创建工具功能 在相应的域文件中 src/exercise-functions/
  2. 添加MCP工具 在相应的文件中 src/tools/
  3. 注册工具 在……里面 src/main.ts
  4. 更新类型 在……里面 src/types.ts 如有需要
  5. 添加测试 和文件

例子：

// src/exercise-functions/my-feature.ts
export function myNewFunction(params: MyParams): MyResult {
  // Implementation
}

// src/tools/my-tools.ts
export function registerMyTools(server: McpServer) {
  server.tool("my_new_tool", {
    description: "Does something useful",
    inputSchema: {
      type: "object",
      properties: {
        param: { type: "string" }
      }
    }
  }, async (request) => {
    // Tool implementation
  });
}

代码的风格

  • TypeScript严格模式 启用
  • ESM模块 遍及
  • 函数式编程 首选图案
  • 全面的错误处理 必需的
  • Zod验证 对于所有输入

测试

虽然不包括正式测试，但使用以下方法验证功能：

# Health check
curl http://localhost:8080/health

# Manual MCP testing via Claude Desktop
# Or create custom test scripts

🚀 部署

生产建设

# Clean build
rm -rf dist/
pnpm build

# Verify build
ls -la dist/

铁路部署

该项目包括一个预配置的 railway.toml 文件以便于部署：

  1. 直接部署：
    railway login
railway link
railway deploy

这 railway.toml 配置包括：

  • Nixpacks构建器 用于Node.js项目
  • 自动TypeScript编译 随着 pnpm build
  • 健康检查 在…上 /health 端点
  • 零停机部署 具有重叠和排水设置
  • 特定于环境的配置 用于生产和分期
  • 智能手表图案 仅在需要时触发重建
  1. 可选JSON配置： A. railway.json 还为喜欢JSON格式的团队提供了该文件。

Heroku部署

  1. 创建 Procfile:

    web: node dist/main.js

  2. 部署：

    heroku create your-app-name
git push heroku main

Docker部署

FROM node:18-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

COPY dist/ ./dist/
COPY data/ ./data/

EXPOSE 8080
CMD ["node", "dist/main.js"]

环境配置

生产环境变量：

NODE_ENV=production
PORT=8080

生产中的健康监测

监视这些端点：

  • 健康： GET /health -基本健康检查
  • SSE： GET /sse -MCP连接
  • 演出 使用MCP工具获取详细指标

⚡ 演出

基准测试

  • 练习加载： <2秒（1324个练习）
  • 搜索响应： <100ms（典型查询）
  • 内存使用情况： <200MB（生产）
  • 并发用户： 100+（取决于硬件）

优化功能

  • 高效的数据结构 -用于快速访问的内存阵列
  • 延迟加载 -按需加载资源
  • 请求缓存 -内置Express缓存
  • 分页 -防止大型结果集
  • 性能跟踪 -实时指标

缩放注意事项

  • 水平缩放： 多个服务器实例
  • 负载平衡： 跨实例分发请求
  • 数据库缓存： Redis用于频繁访问的数据
  • CDN集成： 从CDN提供运动图像

🔧 故障排除

常见问题

服务器无法启动

# Check Node.js version
node --version  # Should be 18+

# Verify build
pnpm build

# Check port availability
lsof -i :8080

运动数据未加载

# Verify file exists
ls -la data/exercises.json

# Check JSON validity
jq . data/exercises.json > /dev/null

MCP连接问题

# Verify SSE endpoint
curl -N http://localhost:8080/sse

# Check health endpoint
curl http://localhost:8080/health

调试模式

启用详细日志记录：

NODE_ENV=development pnpm dev

支持

对于问题和疑问：

  1. 检查 故障排除部分
  2. 查看服务器日志中的错误消息
  3. 验证所有依赖项是否已正确安装
  4. 首先使用健康端点进行测试

🤝 贡献

我们欢迎捐款！请遵循以下指南：

开发过程

  1. 分叉 存储库
  2. 创建 特征分支： git checkout -b feature/my-feature
  3. 制造 使用正确的TypeScript类型进行更改
  4. 测试 你的改变彻底
  5. 文件 任何新功能或API
  6. 提交 pull请求

代码规范

  • TypeScript 严格遵守模式
  • ESM 模块格式
  • 全面的 错误处理
  • 萨德 对所有输入进行验证
  • 清除 函数和变量命名

添加功能

添加新功能时：

  1. 更新类型 在……里面 src/types.ts
  2. 添加业务逻辑 在适当 exercise-functions/ 文件
  3. 创建MCP工具 在相应 tools/ 文件
  4. 注册工具 在……里面 src/main.ts
  5. 更新文档 在README.md中

📄 许可证

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

🙏 致谢

  • 模型上下文协议 优秀的MCP SDK团队
  • 运动数据库 全面锻炼数据的贡献者
  • TypeScript 优秀模具团队
  • Express.js 可靠web框架团队
  • 萨德 运行时类型验证团队

📞 支持

对于问题、议题或贡献：

  • 问题： GitHub问题
  • 文档： 此README和内联代码注释
  • 健康检查： http://localhost:8080/health

内置于❤️ 面向健身和人工智能社区

最后更新日期：2025年7月

相关 MCP