mingle98/luckycola-mcp

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

1. 访问 LuckyCola官网-用户中心
2. 登录后进入"用户中心"页面，获取APPKey和用户ID(uid)
3. 确保账号已相关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

检查在线图片是否合规的工具

参数：

返回：

• 成功时返回图片合规性检测结果，包括安全状态、安全分数、检测详情等。
• 失败时返回错误信息。

返回示例：

{
  "content": [
    {
      "type": "text",
      "text": "图片合规检测结果：\n\n提示: ...\n安全状态: 合规\n安全分数: 99.00%\n检测详情: {...}"
    }
  ]
}

getFoodMenu

获取菜品的菜谱（制作方法）

参数：

返回：

• 成功时返回菜谱详情，包括简介、图片、步骤、注意事项、配料、时长等。
• 失败时返回错误信息。

返回示例：

{
  "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识别等。每种操作均有对应参数和典型场景，详见下表和案例。

操作类型与参数说明

详细参数说明

• filename：要操作的文件名（相对于MCP_FILE_PATH）
• newFilename：新文件名（重命名/转换时用）
• content：写入内容或json2xlsx的JSON字符串
• mode：写入模式，append为追加，overwrite为覆盖，默认覆盖
• onlyFiles：list操作时是否只列普通文件，默认false
• quality：图片压缩质量，1-100，默认80
• output：压缩后输出文件名，默认在原文件名后加_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排序。

注意事项

1. 确保网络连接正常，能够访问LuckyCola API
2. API调用需要消耗额度，请注意使用量

故障排除

常见错误

1. 环境变量未设置：确保设置了正确的APPKey和uid
2. 网络连接问题：检查网络连接和防火墙设置
3. API配额不足：检查LuckyCola账户余额和API调用次数
4. 提示词不合规：确保提示词符合内容安全规范
5. npx权限问题：当正确配置但无法成功连接时，可能是npx权限问题，可以在控制台直接执行：【npx -y luckycola-mcp】 查看是否有相关报错提示

许可证

ISC License