LuckyCola MCP 服务
基于LuckyCola开放能力的MCP（Model Context Protocol）服务。
功能特性
- 标准化的MCP接口，兼容各种MCP客户端
- 环境变量配置，安全便捷
- 在线图片合规性检查，确保内容安全
- 菜谱查询工具，获取菜品制作方法
- 丰富的文件操作功能，支持文件修改、删除、重命名等
- 图片压缩功能，优化图片大小
- 图片OCR功能,轻松获取图片中的文字信息
安装依赖
cd luckycola-mcp
yarn install
编译项目
yarn build
环境变量配置
设置以下环境变量：
export LUCKYCOLA_OPEN_KEY="你账户在LuckyCola平台的APPKey"
export LUCKYCOLA_OPEN_UID="你账户在LuckyCola平台的uid"
export MCP_FILE_PATH="希望进行文件/图片操作的目录路径,例如: /Users/yourname/Desktop/testDir"
nodejs版本要求：v21.0.0及以上
获取API密钥和UID
- 访问 LuckyCola官网-用户中心
- 登录后进入"用户中心"页面，获取APPKey和用户ID(uid)
- 确保账号已相关API权限及额度
使用方法
直接运行
node build/index.js
作为MCP服务器
在MCP客户端（如Claude Desktop、Cursor等）中配置此服务：
npx方式使用
{
"mcpServers": {
"luckycola-mcp": {
"command": "npx",
"args": ["-y", "luckycola-mcp"],
"env": {
"LUCKYCOLA_OPEN_KEY": "你的APPKey",
"LUCKYCOLA_OPEN_UID": "你的UID",
"MCP_FILE_PATH": "希望进行文件/图片操作的目录路径,例如: /Users/yourname/Desktop/testDir"
}
}
}
}
或
下载到本地使用
{
"mcpServers": {
"luckycola-mcp": {
"command": "node",
"args": ["/path/to/luckycola-mcp/build/index.js"],
"env": {
"LUCKYCOLA_OPEN_KEY": "你的APPKey",
"LUCKYCOLA_OPEN_UID": "你的UID",
"MCP_FILE_PATH": "希望进行文件/图片操作的目录路径,例如: /Users/yourname/Desktop/testDir"
}
}
}
}
API接口
checkImage
检查在线图片是否合规的工具
参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| imgUrl | string | 需要检查的图片URL |
返回：
- 成功时返回图片合规性检测结果，包括安全状态、安全分数、检测详情等。
- 失败时返回错误信息。
返回示例：
{
"content": [
{
"type": "text",
"text": "图片合规检测结果：\n\n提示: ...\n安全状态: 合规\n安全分数: 99.00%\n检测详情: {...}"
}
]
}
getFoodMenu
获取菜品的菜谱（制作方法）
参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| foodTitle | string | 需要查询的菜品名称 |
返回：
- 成功时返回菜谱详情，包括简介、图片、步骤、注意事项、配料、时长等。
- 失败时返回错误信息。
返回示例：
{
"content": [
{
"type": "text",
"text": "番茄炒蛋的菜谱结果如下：\n\n{\"intro\":\"...\",\"image\":\"...\",\"steps\":[...],\"notice\":\"...\",\"ingredients\":[...],\"duration\":\"...\"}"
}
]
}
使用示例
// 在MCP客户端中调用
// 检查图片合规
await callTool("checkImage", { imgUrl: "https://example.com/image.jpg" });
// 获取菜谱
await callTool("getFoodMenu", { foodTitle: "番茄炒蛋" });
文件操作工具（fileOperation）
重要说明: 使用文件操作工具前，建议先对AI说【"请对MCP_FILE_PATH目录下的文件进行接下来的任务"】，以确保AI明确操作目录。
fileOperation工具支持对MCP_FILE_PATH目录下的文件进行多种操作，包括：删除、重命名、读取、写入、列出文件、JSON与Excel互转、图片压缩、图片OCR识别等。每种操作均有对应参数和典型场景，详见下表和案例。
操作类型与参数说明
| 操作类型(operation) | 说明 | 主要参数 | 典型场景与提示词示例 |
|---|---|---|---|
| delete | 删除指定文件 | filename | 删除test.txt文件： "请删除test.txt文件" |
| rename | 重命名文件 | filename, newFilename | 文件重命名： "请把a.docx重命名为b.docx" |
| read | 读取文件内容（支持docx纯文本） | filename | 读取内容： "请读取test.txt的内容" "请读取word文档a.docx内容" |
| write | 写入/追加内容到文件（支持docx） | filename, content, mode | 覆盖写入： "请将'你好世界'写入test.txt" 追加写入： "请在test.txt追加'再见'" |
| list | 列出目录下文件（可只列文件） | onlyFiles | 查看文件列表： "请列出目录下所有文件" "只列出普通文件" |
| json2xlsx | JSON转Excel（.xlsx） | filename, content | "请将以下JSON内容保存为excel文件data.xlsx：{...}" |
| xlsx2json | Excel转JSON | filename, newFilename | "请将data.xlsx转换为JSON文件" |
| compressImage | 图片压缩（支持jpg/png/gif） | filename, quality, output | "请压缩图片a.png，质量80，输出为a_compressed.png" |
| ocrToImageBase64 | 图片OCR识别（jpg/png，≤2M） | filename | "请识别图片a.jpg中的文字" |
详细参数说明
filename：要操作的文件名（相对于MCP_FILE_PATH）newFilename：新文件名（重命名/转换时用）content：写入内容或json2xlsx的JSON字符串mode：写入模式，append为追加，overwrite为覆盖，默认覆盖onlyFiles：list操作时是否只列普通文件，默认falsequality：图片压缩质量，1-100，默认80output：压缩后输出文件名，默认在原文件名后加_compressed
使用案例与推荐提示词
1. 删除文件
请删除test.txt文件
2. 重命名文件
请把a.docx重命名为b.docx
3. 读取文件内容
请读取test.txt的内容
请读取word文档a.docx内容
4. 写入/追加内容到文件
请将"你好世界"写入test.txt
请在test.txt追加"再见"
5. 列出目录下文件
请列出目录下所有文件
只列出普通文件
6. JSON转Excel
请将以下JSON内容保存为excel文件data.xlsx：[{"姓名":"张三","年龄":18},{"姓名":"李四","年龄":20}]
7. Excel转JSON
请将data.xlsx转换为JSON文件
8. 图片压缩
请压缩图片a.png，质量80，输出为a_compressed.png
9. 图片OCR识别
请识别图片a.jpg中的文字
注意事项：
- 文件操作均在MCP_FILE_PATH指定目录下进行，确保有读写权限。
- 图片OCR仅支持jpg/png格式且文件≤2M。
- 图片压缩支持jpg/png/gif，gif为动图时会自动处理色彩数。
- Excel/Word操作请确保文件扩展名正确（.xlsx/.docx）。
- 若遇权限错误，请参考下方"故障排除"章节。
项目结构
luckycola-mcp/
├── build/ # 编译后输出目录
├── src/ # 源码目录
│ ├── api/ # API接口配置
│ │ └── index.ts
│ ├── config/ # 配置相关
│ │ └── constants.ts
│ ├── services/ # 业务服务
│ │ └── service.ts
│ ├── types/ # 类型定义
│ │ └── index.ts
│ ├── utils/ # 工具函数
│ │ └── index.ts
│ └── index.ts # 入口文件
├── package.json
├── tsconfig.json
├── LICENSE
└── README.md
工具函数说明
formatQuery(parameters: Record<string, string>): string
用于将对象参数格式化为URL查询字符串，按key排序。
注意事项
- 确保网络连接正常，能够访问LuckyCola API
- API调用需要消耗额度，请注意使用量
故障排除
常见错误
- 环境变量未设置：确保设置了正确的APPKey和uid
- 网络连接问题：检查网络连接和防火墙设置
- API配额不足：检查LuckyCola账户余额和API调用次数
- 提示词不合规：确保提示词符合内容安全规范
- npx权限问题：当正确配置但无法成功连接时，可能是npx权限问题，可以在控制台直接执行：【npx -y luckycola-mcp】 查看是否有相关报错提示
许可证
ISC License