内容
# FindMine 购物造型师
一个模型上下文协议（MCP）服务器，集成了 FindMine 强大的产品造型和搭配推荐功能，与 Claude 及其他兼容 MCP 的应用程序。
## 概述
这个 MCP Server 连接到 FindMine 的样式 API，并通过模型上下文协议（Model Context Protocol）将其功能暴露给大型语言模型（Large Language Models）。它允许用户：
- 浏览产品和服装信息
- 针对特定产品获取服装推荐
- 查找视觉上相似的产品
- 获取风格指导和时尚建议
## 特性
### 资源
- **产品**: 使用 `product:///` URI 方案的详细产品信息
- **造型**: 使用 `look:///` URI 方案的完整服装推荐
### 工具
- **get_style_guide**: 获取详细的时尚建议和造型指南
- **get_complete_the_look**: 获取产品的搭配推荐
- **get_visually_similar**: 查找视觉上相似的产品
### 提示
- **outfit_completion**: 获取完整服装的搭配建议
- **styling_guide**: 访问全面的时尚搭配指南
- **findmine_help**: 了解如何使用 FindMine 的工具和资源
## 安装
### 选项 1：从 npm 安装
```bash
```
# 直接安装和运行（推荐）
npx findmine-mcp
# 或者全局安装
npm install -g findmine-mcp
findmine-mcp
```
### 选项 2：使用 Docker 运行
```bash
docker run -e FINDMINE_APP_ID=your_app_id findmine/mcp-server:latest
```
### 选项 3：从源代码克隆并构建
```bash
```
# 克隆仓库
git clone https://github.com/findmine/findmine-mcp.git
cd findmine-mcp
# 安装依赖
npm install
# 构建服务器
npm run build
# 开发时使用自动重建
npm run watch
```
## 配置
### 环境变量
| 变量 | 描述 | 默认值 |
|------|------|--------|
| `FINDMINE_API_URL` | FindMine API 基础 URL | https://api.findmine.com |
| `FINDMINE_APP_ID` | 您的 FindMine 应用 ID | DEMO_APP_ID |
| `FINDMINE_API_VERSION` | 要使用的 API 版本 | v3 |
| `FINDMINE_DEFAULT_REGION` | 默认区域代码 | us |
| `FINDMINE_DEFAULT_LANGUAGE` | 默认语言代码 | en |
| `FINDMINE_CACHE_ENABLED` | 启用响应缓存 | true |
| `FINDMINE_CACHE_TTL_MS` | 缓存生存时间（毫秒） | 3600000 (1 小时) |
| `NODE_ENV` | 设置为 "development" 以获取示例数据 | - |
## 与 Claude Desktop 的使用
服务器在安装过程中会自动配置 Claude Desktop。要验证：
**macOS:**
```bash
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
**Windows:**
```
type %APPDATA%\Claude\claude_desktop_config.json
```
## 开发
### 可用脚本
```bash
```
# 构建和监视
npm run build # 构建项目
npm run watch # 监视变更并重新构建
npm run typecheck # 运行 TypeScript 类型检查
# 测试
npm test # 以观察模式运行测试
npm run test:run # 运行测试一次
npm run test:coverage # 运行带有覆盖率报告的测试
# 代码质量
npm run lint # 运行 ESLint
npm run lint:fix # 运行 ESLint 并自动修复
npm run format # 使用 Prettier 格式化代码
npm run format:check # 检查代码格式
# 开发工具
npm run inspector # 运行 MCP inspector (http://localhost:5173)
### 测试
该项目使用 Vitest 进行测试。测试位于与源文件并列的 `__tests__/` 目录中。
```bash
# 以观察模式运行测试
npm test
# 运行测试一次（适用于持续集成）
npm run test:run
# 生成覆盖率报告
npm run test:coverage
```
### 代码质量
在提交代码之前：
```bash
```
# 运行所有检查
npm run typecheck && npm run lint && npm run format:check && npm run test:run
```
该项目使用：
- **ESLint** 进行代码检查，支持 TypeScript
- **Prettier** 进行代码格式化
- **Vitest** 进行测试
- **GitHub Actions** 进行 CI/CD
### 开发模式
使用示例数据运行服务器：
```bash
NODE_ENV=development npm run build && node build/index.js
```
### 自定义风格指南
风格指南可以根据您品牌的特定风格理念和时尚指导进行自定义。要自定义风格指南，请按照以下步骤操作：
1. 在 `src/content/style-guides.ts` 中找到风格指南
2. 修改每个类别的内容（`general`、`color_theory`、`body_types` 等）
3. 通过扩展 `styleGuides` 对象添加新类别
4. 自定义特定场合和季节的建议
添加自定义风格指南类别的示例：
```typescript
// 在 src/content/style-guides.ts 中
export const styleGuides: Record<string, string> = {
// 现有类别...
// 添加您的自定义类别
your_brand_style: `# 您的品牌风格指南
```
## 品牌美学
- 品牌视觉识别的关键元素
- 核心风格原则
- 标志性外观和组合
## 您品牌的样式注意事项
- 品牌特定的样式建议
- 首选颜色组合
- 标志性样式技巧
## 您品牌的样式禁忌
- 应避免的组合
- 与品牌形象不符的样式方法
- 应避免的常见样式错误
`
};
```
要实现完全自定义，您可以修改 `src/handlers/tools.ts` 中的整个 `get_style_guide` 处理程序。
### 项目结构
```
src/
├── index.ts # MCP server 启动和初始化
├── config.ts # 环境配置
├── api/ # FindMine API 客户端
│ └── findmine-client.ts
├── handlers/ # MCP 协议处理器
│ ├── tools.ts # 工具执行处理器
│ ├── resources.ts # 资源处理器
│ └── prompts.ts # 提示处理器
├── tools/ # 带有 MCP 注释的工具定义
│ └── index.ts
├── schemas/ # Zod 验证模式
│ ├── tool-inputs.ts # 所有工具的输入验证
│ └── index.ts
├── content/ # 静态内容
│ └── style-guides.ts # 风格指南内容
├── prompts/ # 提示定义
│ ├── findmine-help.ts
│ ├── outfit-completion.ts
│ ├── styling-guide.ts
│ └── index.ts
├── services/ # 业务逻辑层
│ └── findmine-service.ts
├── types/ # TypeScript 类型定义
│ ├── findmine-api.ts
│ └── mcp.ts
└── utils/ # 工具函数和助手
├── cache.ts
├── formatters.ts
├── logger.ts
├── mock-data.ts
└── resource-mapper.ts
```
### 技术细节
该服务器是基于以下技术构建的：
- **MCP SDK 1.24.2**，完全符合规范（2025-11-25）
- **工具注解**，用于只读、破坏性和开放世界提示
- **Zod 验证**，用于所有工具输入
- **模块化架构**，关注点分离
- **100% 测试覆盖率**，针对工具函数
## API 示例
### 获取风格指南
```json
{
"name": "get_style_guide",
"arguments": {
"category": "color_theory",
"occasion": "wedding"
}
}
```
### 获取完整外观
```json
{
"name": "get_complete_the_look",
"arguments": {
"product_id": "P12345",
"product_color_id": "C789"
}
}
```
### 获取视觉相似产品
```json
{
"name": "get_visually_similar",
"arguments": {
"product_id": "P12345",
"product_color_id": "C789",
"limit": 5
}
}
```
## 发布
### 发布到 npm
```bash
```
# 登录到 npm
npm login
# 发布包
npm publish
# 更新未来版本的版本号
npm version patch
```
### 发布到 Docker Hub
```bash
```
# 构建 Docker 镜像
docker build -t findmine/mcp-server:latest .
# 登录到 Docker Hub
docker login
# 推送镜像
docker push findmine/mcp-server:latest
```
## 许可证
本项目采用 MIT 许可证。
MCP 市场