运动数据库MCP服务器

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

![TypeScript](https://www.typescriptlang.org/) ![MCP SDK](https://github.com/modelcontextprotocol/sdk) ![Express](https://expressjs.com/) ![License](LICENSE)

📋 目录

概述
特性
快速开始
安装
用法
MCP工具
MCP资源
api参考
建筑
健康监测
发展
部署
演出
贡献
许可证

🎯 概述

运动数据库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 
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+（包含在开发依赖项中）

环境设置

克隆并安装：

   git clone 
   cd fittality-exercises-mcp
   pnpm install

配置环境（可选）：

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

构建项目：

   pnpm build

启动服务器：

   # 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流

Claude Web重定向到 /authorize?client_id=claude-web&response_type=code
服务器自动批准并使用授权码重定向回
Claude Web在以下地址交换访问令牌代码 /token
访问令牌对后续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 
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

添加新工具

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

例子：

// 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 文件以便于部署：

直接部署：

   railway login
   railway link
   railway deploy

这 railway.toml 配置包括：

Nixpacks构建器 用于Node.js项目
自动TypeScript编译 随着 pnpm build
健康检查 在…上 /health 端点
零停机部署 具有重叠和排水设置
特定于环境的配置 用于生产和分期
智能手表图案 仅在需要时触发重建

可选JSON配置：

A. railway.json 还为喜欢JSON格式的团队提供了该文件。

Heroku部署

创建 Procfile:

   web: node dist/main.js

部署：

   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工具获取详细指标

⚡ 演出

基准测试

练习加载： \ /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. 检查 [故障排除部分](#troubleshooting)
1. 查看服务器日志中的错误消息
1. 验证所有依赖项是否已正确安装
1. 首先使用健康端点进行测试

## 🤝 贡献

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

### 开发过程

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

### 代码规范

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

### 添加功能

添加新功能时：

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

## 📄 许可证

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

## 🙏 致谢

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

## 📞 支持

对于问题、议题或贡献：

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

______________________________________________________________________

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

*最后更新日期：2025年7月*

Fittality Exercises MCP

快速接入

详细介绍

运动数据库MCP服务器

📋 目录

🎯 概述

什么是MCP？

关键能力

✨ 特性

运动数据库

搜索和筛选

健康与监测

MCP集成

🚀 快速开始

📦 安装

先决条件

环境设置

环境变量

🎮 用法

Claude桌面集成

克劳德网络集成（OAuth 2.0）

OAuth端点

OAuth配置

受保护的MCP端点

OAuth流

基本示例

搜索练习

获取锻炼替代方案

验证练习ID

获取数据库统计信息

🛠️ MCP工具

核心练习工具

search_exercises

get_exercise_by_id

find_exercise_alternatives

筛选工具

filter_exercises_by_equipment

get_exercises_by_category

验证工具

validate_exercise_keys

元数据工具

get_categories

get_equipment_types

get_muscle_groups

健康监测工具

get_database_health

get_database_stats

get_performance_metrics

validate_database_integrity

get_system_info

reset_performance_metrics

📚 MCP资源

exercise://{id}

exercise://stats

exercise://health

exercise://performance

📖 api参考

练习数据结构

健康检查端点

SSE 终端

消息端点

🏗️ 建筑

项目结构

技术栈

设计模式

🏥 健康监测

健康检查

性能指标

数据库完整性

监视工具

🛠️ 发展

设置开发环境

可用脚本

添加新工具

代码的风格

测试

🚀 部署

生产建设

铁路部署

Heroku部署

`search_exercises`

`get_exercise_by_id`

`find_exercise_alternatives`

`filter_exercises_by_equipment`

`get_exercises_by_category`

`validate_exercise_keys`

`get_categories`

`get_equipment_types`

`get_muscle_groups`

`get_database_health`

`get_database_stats`

`get_performance_metrics`

`validate_database_integrity`

`get_system_info`

`reset_performance_metrics`

`exercise://{id}`

`exercise://stats`

`exercise://health`

`exercise://performance`