LuckyCola MCP

Um serviço MCP aberto que fornece uma interface padronizada compatível com vários clientes MCP.

Documentação

Serviço LuckyCola MCP

Serviço MCP (Model Context Protocol) baseado nas capacidades abertas da LuckyCola.

Recursos

Interface MCP padronizada, compatível com vários clientes MCP
Configuração por variáveis de ambiente, segura e conveniente
Verificação de conformidade de imagens online, garantindo segurança do conteúdo
Ferramenta de consulta de receitas, obtendo métodos de preparo de pratos
Recursos avançados de operação de arquivos, com suporte a modificação, exclusão, renomeação, etc.
Compressão de imagens, otimizando o tamanho dos arquivos
OCR de imagens, extraindo facilmente informações de texto de imagens

Instalação de dependências

cd luckycola-mcp
yarn install

Compilação do projeto

yarn build

Configuração de variáveis de ambiente

Defina as seguintes variáveis de ambiente:

export LUCKYCOLA_OPEN_KEY="你账户在LuckyCola平台的APPKey"
export LUCKYCOLA_OPEN_UID="你账户在LuckyCola平台的uid"
export MCP_FILE_PATH="希望进行文件/图片操作的目录路径,例如: /Users/yourname/Desktop/testDir"

Versão do Node.js necessária: v21.0.0 ou superior

Obtendo a chave da API e o UID

Acesse Site oficial da LuckyCola - Central do usuário
Após o login, entre na página "Central do usuário" para obter a APPKey e o ID do usuário (uid)
Garanta que a conta tenha as permissões e cotas de API necessárias

Como usar

Execução direta

node build/index.js

Como servidor MCP

Configure este serviço em um cliente MCP (como Claude Desktop, Cursor, etc.):

Uso via 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"
      }
    }
  }
}

Download para uso local

{
  "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"
      }
    }
  }
}

Interface da API

checkImage

Ferramenta para verificar se uma imagem online está em conformidade

Parâmetros:

Nome do parâmetro	Tipo	Descrição
imgUrl	string	URL da imagem a ser verificada

Retorno:

Em caso de sucesso, retorna o resultado da verificação de conformidade da imagem, incluindo status de segurança, pontuação de segurança, detalhes da verificação, etc.
Em caso de falha, retorna mensagem de erro.

Exemplo de retorno:

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

getFoodMenu

Obtém a receita (método de preparo) de um prato

Parâmetros:

Nome do parâmetro	Tipo	Descrição
foodTitle	string	Nome do prato a ser consultado

Retorno:

Em caso de sucesso, retorna os detalhes da receita, incluindo introdução, imagem, etapas, observações, ingredientes, tempo, etc.
Em caso de falha, retorna mensagem de erro.

Exemplo de retorno:

{
  "content": [
    {
      "type": "text",
      "text": "番茄炒蛋的菜谱结果如下：\n\n{\"intro\":\"...\",\"image\":\"...\",\"steps\":[...],\"notice\":\"...\",\"ingredients\":[...],\"duration\":\"...\"}"
    }
  ]
}

Exemplo de uso

// 在MCP客户端中调用
// 检查图片合规
await callTool("checkImage", { imgUrl: "https://example.com/image.jpg" });

// 获取菜谱
await callTool("getFoodMenu", { foodTitle: "番茄炒蛋" });

Ferramenta de operação de arquivos (fileOperation)

Observação importante: Antes de usar a ferramenta de operação de arquivos, recomenda-se dizer à IA ["Por favor, execute as próximas tarefas nos arquivos do diretório MCP_FILE_PATH"], para garantir que a IA saiba claramente o diretório de operação.

A ferramenta fileOperation suporta várias operações em arquivos no diretório MCP_FILE_PATH, incluindo: exclusão, renomeação, leitura, escrita, listagem de arquivos, conversão entre JSON e Excel, compressão de imagens, OCR de imagens, etc. Cada operação possui parâmetros e cenários típicos correspondentes, conforme tabela e exemplos abaixo.

Tipos de operação e descrição de parâmetros

Tipo de operação (operation)	Descrição	Parâmetros principais	Cenário típico e exemplo de prompt
delete	Excluir arquivo especificado	filename	Excluir arquivo test.txt: "Por favor, exclua o arquivo test.txt"
rename	Renomear arquivo	filename, newFilename	Renomear arquivo: "Por favor, renomeie a.docx para b.docx"
read	Ler conteúdo do arquivo (suporta texto puro de docx)	filename	Ler conteúdo: "Por favor, leia o conteúdo de test.txt" "Por favor, leia o conteúdo do documento Word a.docx"
write	Escrever/adicionar conteúdo ao arquivo (suporta docx)	filename, content, mode	Sobrescrever: "Por favor, escreva 'Olá mundo' em test.txt" Adicionar: "Por favor, adicione 'Tchau' em test.txt"
list	Listar arquivos do diretório (pode listar apenas arquivos)	onlyFiles	Ver lista de arquivos: "Por favor, liste todos os arquivos do diretório" "Liste apenas arquivos comuns"
json2xlsx	Converter JSON para Excel (.xlsx)	filename, content	"Por favor, salve o seguinte conteúdo JSON como arquivo Excel data.xlsx: {...}"
xlsx2json	Converter Excel para JSON	filename, newFilename	"Por favor, converta data.xlsx para arquivo JSON"
compressImage	Compressão de imagem (suporta jpg/png/gif)	filename, quality, output	"Por favor, comprima a imagem a.png, qualidade 80, saída como a_compressed.png"
ocrToImageBase64	OCR de imagem (jpg/png, ≤2M)	filename	"Por favor, reconheça o texto na imagem a.jpg"

Descrição detalhada dos parâmetros

filename: Nome do arquivo a ser operado (relativo a MCP_FILE_PATH)
newFilename: Novo nome do arquivo (usado em renomeação/conversão)
content: Conteúdo a ser escrito ou string JSON para json2xlsx
mode: Modo de escrita, append para adicionar, overwrite para sobrescrever, padrão é sobrescrever
onlyFiles: Se deve listar apenas arquivos comuns na operação list, padrão false
quality: Qualidade da compressão de imagem, 1-100, padrão 80
output: Nome do arquivo de saída após compressão, padrão adiciona _compressed ao nome original

Exemplos de uso e prompts recomendados

1. Excluir arquivo

请删除test.txt文件

2. Renomear arquivo

请把a.docx重命名为b.docx

3. Ler conteúdo do arquivo

请读取test.txt的内容
请读取word文档a.docx内容

4. Escrever/adicionar conteúdo ao arquivo

请将"你好世界"写入test.txt
请在test.txt追加"再见"

5. Listar arquivos do diretório

请列出目录下所有文件
只列出普通文件

6. Converter JSON para Excel

请将以下JSON内容保存为excel文件data.xlsx：[{"姓名":"张三","年龄":18},{"姓名":"李四","年龄":20}]

7. Converter Excel para JSON

请将data.xlsx转换为JSON文件

8. Compressão de imagem

请压缩图片a.png，质量80，输出为a_compressed.png

9. OCR de imagem

请识别图片a.jpg中的文字

Observações:

As operações de arquivo são realizadas no diretório especificado por MCP_FILE_PATH, garantindo permissões de leitura e escrita.

O OCR de imagem suporta apenas formatos jpg/png e arquivos ≤2M.

A compressão de imagem suporta jpg/png/gif; para gifs animados, o número de cores é tratado automaticamente.

Para operações com Excel/Word, garanta que a extensão do arquivo esteja correta (.xlsx/.docx).

Se houver erro de permissão, consulte a seção "Solução de problemas" abaixo.

Estrutura do projeto

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

Descrição das funções utilitárias

formatQuery(parameters: Record<string, string>): string
Usada para formatar parâmetros de objeto como string de consulta de URL, ordenados por chave.

Observações

Garanta conexão de rede adequada para acessar a API da LuckyCola
As chamadas de API consomem cota, fique atento ao uso

Solução de problemas

Erros comuns

Variáveis de ambiente não definidas: Garanta que a APPKey e o uid corretos estejam definidos
Problemas de conexão de rede: Verifique a conexão de rede e as configurações de firewall
Cota de API insuficiente: Verifique o saldo da conta LuckyCola e o número de chamadas de API
Prompt não conforme: Garanta que o prompt esteja em conformidade com as normas de segurança de conteúdo
Problema de permissão do npx: Quando configurado corretamente mas sem conexão, pode ser um problema de permissão do npx. Execute diretamente no console: 【npx -y luckycola-mcp】 para verificar se há mensagens de erro relacionadas

Licença

Licença ISC