Thingiverse MCP 服务器

一个模型上下文协议 (MCP) 服务器，提供与 Thingiverse API 交互的工具，允许 AI 助手搜索、浏览和检索 3D 打印模型。

🌟 概述

此 MCP 服务器使用 Puppeteer 封装 Thingiverse API，以创建一个可靠的接口，供 AI 助手使用。它提供以下工具：

• 搜索 3D 打印模型
• 获取随机 3D 模型
• 浏览类别
• 从特定类别获取模型

🚀 功能

• 🔍 模型搜索：使用关键字搜索 Thingiverse 的 3D 打印模型数据库
• 🗂️ 类别浏览：按类别浏览模型
• 🎲 随机模型：从 Thingiverse 发现随机 3D 模型
• 🌐 完整 API 访问：获取有关模型的详细信息，包括描述、文件、图像等
• 🤖 AI 助手集成：旨在通过模型上下文协议与 AI 助手协同工作

📋 前提条件

• Node.js (v14 或更高版本)
• npm 或 yarn
• Thingiverse API 令牌

🔧 安装

1. 克隆存储库

   git clone <repository-url>
   cd thingiverse-mcp
   

2. 安装依赖项

   npm install
   

3. 设置环境变量

   # 创建开发环境文件
   cp .env.example .env.development
   # 创建生产环境文件
   cp .env.example .env.production
   

4. 配置 API 令牌

   • 从 Thingiverse 开发者门户 获取 Thingiverse App Token
   • 将您的令牌添加到 .env.development 和 .env.production 文件中：

     APP_TOKEN=your_api_token_here
     

🎮 用法

开发模式

npm run dev

这将在开发模式下启动 MCP 服务器，并启用热重载。

生产模式

npm run build
npm start

或者使用简写：

npm run prod

🔗 与 Claude Desktop 集成

要将此 MCP 服务器添加到 Claude Desktop 并启用 Thingiverse 浏览功能，请执行以下操作：

1. 启动 MCP 服务器 确保您的服务器在本地或 Claude Desktop 可以访问的远程主机上运行。

2. 打开 Claude Desktop 设置

   • 启动 Claude Desktop
   • 单击右上角的个人资料图片或图标
   • 从下拉菜单中选择“设置”

3. 导航到扩展设置

   • 在“设置”侧边栏中，单击“扩展”
   • 选择“添加自定义 MCP”

4.1 配置 MCP 连接

• 名称：Thingiverse MCP（或您喜欢的任何名称）
• URL：输入您的 MCP 服务器正在运行的 URL（例如，本地开发为 http://localhost:3000）
• 单击“添加 MCP”

4.2 替代配置 MCP 连接

• 您首先需要构建项目并提供您的完整路径 C:/.../Thingiverse/dist/index.js

"thingiverse": {
   "command": "node",
   "args": [
     "YOUR_CUSTOM_PATH/Thingiverse/dist/index.js"
   ]
 }

5. 启用 MCP

   • 切换您新添加的 Thingiverse MCP 旁边的开关以启用它
   • Claude Desktop 将尝试连接到您的 MCP 服务器

6. 验证连接

   • 与 Claude 开始新的对话
   • 键入“你能帮我在 Thingiverse 上找到一些 3D 模型吗？”
   • Claude 现在应该能够使用 Thingiverse 工具来搜索和浏览模型

7. 故障排除

   • 如果 Claude 无法连接到您的 MCP 服务器，请检查：
     • 服务器正在运行并且可以从 Claude Desktop 访问
     • 在 Claude Desktop 设置中配置了正确的 URL
     • 您的 API 令牌有效并且已在服务器中正确配置

与 Claude 的使用示例

连接后，您可以要求 Claude：

• “在 Thingiverse 上找到一些 3D 打印的智能手机支架”
• “向我展示一些小工具类别中流行的 3D 模型”
• “从 Thingiverse 获取一个随机 3D 模型”
• “Thingiverse 上有哪些 3D 模型类别？”

🧠 可用工具

服务器公开了几个可供 AI 助手使用的工具：

get-things

根据搜索词搜索 3D 模型。

参数：

• term：搜索词（必需）
• categoryId：可选类别 ID，用于缩小搜索范围

get-random-thing

从 Thingiverse 检索随机 3D 模型。

get-categories

从 Thingiverse 获取所有可用类别。

get-random-thing-from-category

从特定类别获取随机 3D 模型。

参数：

• categorySlug：类别 slug（必需）

🔍 工作原理

服务器使用带有 Stealth 插件的 Puppeteer 与 Thingiverse API 交互。 这种方法：

1. 通过 API 令牌处理身份验证
2. 向各种 Thingiverse 端点发出请求
3. 以结构化格式解析并返回数据
4. 将端点公开为可由 AI 助手调用的 MCP 工具

🛠️ 项目结构

src/
  ├── class/
  │   └── thingiverser.class.ts    # Thingiverse API 的主要 Puppeteer 客户端
  ├── endpoints/
  │   ├── getCategories.ts         # 获取所有类别
  │   ├── getRandomThing.ts        # 获取随机事物
  │   ├── getThings.ts             # 搜索事物
  │   └── getThingsFromCategory.ts # 从类别中获取事物
  ├── types/
  │   ├── category.d.ts            # 类别的类型定义
  │   ├── files.d.ts               # 文件的类型定义
  │   └── things.d.ts              # 事物的类型定义
  └── index.ts                     # 入口点和 MCP 服务器设置

⚙️ 开发

环境配置

服务器对开发和生产使用不同的环境文件：

• .env.development - 在开发模式下运行时使用
• .env.production - 在生产模式下运行时使用

测试

使用以下命令运行测试套件：

npm test

Linting 和格式化

# 运行 ESLint
npm run lint

# 修复 ESLint 错误
npm run lint:fix

# 使用 Prettier 格式化代码
npm run format

📝 部署注意事项

部署到生产环境时：

1. 确保您的 .env.production 文件包含有效的 Thingiverse API 令牌
2. 构建过程会将此令牌嵌入到编译后的代码中
3. 使用 npm run prod 构建并启动生产服务器

📄 许可证

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。