使用说明

@tscodex/mcp图像

MCP（模型上下文协议）服务器，用于全面的图像处理、股票图像搜索和AI图像生成。使用TypeScript和Sharp构建，用于高性能图像处理。

建立在 @tscodex/mcp-sdk -该项目使用官方的TSCodex MCP SDK进行服务器基础设施、身份验证、配置管理和协议处理。

🚀 快速链接

📦 MCP经理 | 🌉 MCP电桥

用于管理MCP服务器的桌面应用程序|VS代码/光标扩展桥

🎯 这是什么？

这是一个 MCP服务器 建立在 @tscodex/mcp-sdk 它提供了强大的图像处理能力。它可以通过两种方式工作：

单独模式：直接通过运行 npx 或 npm，传递环境变量和配置
管理模式：与一起使用 MCP经理 用于工作空间隔离、可视化配置以及与Cursor的无缝集成

架构概述

┌─────────────────────────────────────────────────────────────┐
│                    Cursor (IDE Editor)                      │
│  ┌───────────────────────────────────────────────────────┐  │
│  │         MCP Manager Bridge Extension                  │  │
│  │  - Auto-registers workspace                           │  │
│  │  - Syncs with MCP Manager                             │  │
│  │  - Updates Cursor mcp.json                            │  │
│  └───────────────────────────────────────────────────────┘  │
│                         │                                    │
│              HTTP API + WebSocket                            │
│                         │                                    │
└─────────────────────────┼────────────────────────────────────┘
                          │
┌─────────────────────────┼────────────────────────────────────┐
│              MCP Manager (Desktop App)                        │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  - Process Management                                  │  │
│  │  - Workspace Isolation (Proxy)                        │  │
│  │  - Visual Configuration UI                            │  │
│  │  - Secrets Management (3-level override)              │  │
│  │  - Permissions System                                 │  │
│  │  - AI Agent Proxy                                     │  │
│  │  - MCP Tools (Dynamic Server)                         │  │
│  └───────────────────────────────────────────────────────┘  │
│                         │                                    │
│         ┌────────────────┴────────────────┐                  │
│         │                                 │                  │
│  ┌──────▼──────┐                  ┌──────▼──────┐          │
│  │ MCP Tools   │                  │ MCP Servers │          │
│  │ (Dynamic)   │                  │ (e.g. this) │          │
│  └──────┬──────┘                  └──────┬──────┘          │
│         │                                 │                  │
└─────────┼─────────────────────────────────┼──────────────────┘
          │                                 │
          └────────────┬────────────────────┘
                       │
          ┌────────────▼────────────┐
          │  @tscodex/mcp-sdk       │
          │  (Core SDK)              │
          └─────────────────────────┘

运作原理

问题：实际项目要求每个Cursor工作区使用自己的工作区上下文。例如，此映像服务器需要当前项目的根路径来创建和处理映像。但是，您不能为每个项目运行单独的服务器实例。

解决方案: MCP经理 允许您：

跑 一个服务器实例 （例如。， @tscodex/mcp-images)
创建 多个工作区代理 使用工作区上下文转发请求
SDK从当前工作区接收标头，并允许一个服务器处理不同的工作区

桥: MCP经理桥 自动：

按项目路径在MCP管理器中注册工作区
将游标与管理器同步
在本地注册代理MCP服务器 mcp.json
在工作空间之间提供完美的封装和连接

🎨 特性

🖼️ 图像处理：调整大小、裁剪、优化、转换格式、应用过滤器、旋转、水印
🔍 库存图片搜索：从Pexels和Pixabay搜索和下载图像
🤖 AI图像生成：使用OpenAI DALL-E生成图像
🎨 颜色提取：提取主色并生成调色板
📦 多种格式：支持WebP、JPEG、PNG、AVIF
⚡ 高性能：由夏普提供技术支持，可实现快速图像处理

📦 安装

选项1：独立（通过npx）

npx @tscodex/mcp-images@latest

选项2：全局安装

npm install -g @tscodex/mcp-images

选项3：管理模式（推荐）

与一起使用 MCP经理 为了获得最佳体验：

安装MCP管理器：从下载 GitHub发布
安装桥架延伸部分: MCP经理桥来自VS代码市场
添加服务器：在MCP管理器中，添加 @tscodex/mcp-images 作为新服务器
配置：使用可视化UI配置服务器（基于JSON模式）
启用：在Cursor中为您的工作区启用服务器

管理模式的好处：

✅ 可视化配置：无需手动编辑JSON文件
✅ 工作区隔离：每个项目都有自己的工作区代理
✅ 安全的秘密：3级秘密覆盖（全局→ 工作区→ 服务器）
✅ 权限控制：对每个服务器可以访问的内容进行精细控制
✅ AI代理集成：在不向服务器公开API密钥的情况下使用AI代理
✅ 令牌统计：透明地跟踪AI使用情况
✅ 自动同步：网桥自动与光标同步

🚀 快速开始

单独模式

# Start server with default settings
npx @tscodex/mcp-images@latest

# Server will start on port 3848 by default (host: 0.0.0.0)
# MCP endpoint: http://localhost:3848/mcp

# With custom host and port
npx @tscodex/mcp-images@latest --host 127.0.0.1 --port 3000

# With project root (REQUIRED for standalone mode)
npx @tscodex/mcp-images@latest --host 127.0.0.1 --port 4040 --root /path/to/project

# Get server metadata (for MCP Manager integration)
npx @tscodex/mcp-images@latest --meta

管理模式

启动MCP管理器 桌面应用程序
打开的游标 与您的项目
桥楼伸展平台 自动：
- 注册您的工作区
- 连接到MCP管理器
- 将已启用的服务器同步到Cursor的 mcp.json
启用服务器：单击播放图标 @tscodex/mcp-images 在桥接面板中
配置：使用MCP管理器UI配置服务器（如果需要）

⚙️ 配置

配置文件

创建 .mcp-images.json 在项目根目录中：

{
  "root": ".",
  "defaultProvider": "pexels",
  "defaultFormat": "webp",
  "defaultMaxWidth": 1920,
  "defaultQuality": 80,
  "saveMetadata": true,
  "embedExif": false
}

配置选项：

root （字符串，可选）：项目根目录
- 使用 "." 使用 MCP_PROJECT_ROOT 环境变量（管理模式）
- 独立模式使用绝对路径
defaultProvider ("pexels" | "pixabay" | "openai" | "auto"，默认值： "auto")：默认图像提供程序
defaultFormat ("webp" | "jpeg" | "png" | "avif"，默认值： "webp")：默认图像格式
defaultMaxWidth （数字，默认值： 1920)：默认最大宽度（1-10000）
defaultQuality （数字，默认值： 80)：默认质量（1-100）
saveMetadata （布尔值，默认值： true)：将JSON元数据与图像一起保存
embedExif （布尔值，默认值： false)：在EXIF数据中嵌入元数据

秘密管理

⚠️ 安全说明： API密钥存储为秘密（环境变量 SECRET_ 前缀）而不是在配置文件中。

在独立模式下：

export SECRET_PEXELS_API_KEY=your_pexels_api_key
export SECRET_PIXABAY_API_KEY=your_pixabay_api_key
export SECRET_OPENAI_API_KEY=your_openai_api_key

在管理模式下： MCP管理器提供 三级秘密覆盖系统:

全球：所有服务器都有秘密
工作区：特定于工作空间的秘密
服务器：特定于服务器实例的秘密

这允许对每个服务器可以访问的秘密进行细粒度控制。

获取API密钥：

像素: https://www.pexels.com/api/
Pixabay: https://pixabay.com/api/docs/
开放人工智能: https://platform.openai.com/api-keys

🔒 安全和权限

安全功能

MCP经理 提供企业级安全：

OS钥匙链存储：秘密存储在操作系统的安全密钥链中（Windows凭据管理器、macOS密钥链、Linux特勤局）
无关键风险：API密钥从不直接传递给MCP服务器。需要AI访问的服务器使用AI代理代理机制
进程隔离：每台服务器都在自己的进程中运行，环境隔离
权限系统：对每个服务器可以访问的内容进行精细控制

权限系统

MCP Manager的权限系统允许您配置：

环境变量：服务器可以使用哪些环境变量
秘密访问：服务器可以访问哪些机密
AI代理访问：服务器是否可以使用AI Agent代理
文件系统访问：工作区根访问权限（始终限于项目）

权限配置示例：

{
  "envVars": ["NODE_ENV", "DEBUG"],
  "secrets": ["SECRET_PEXELS_API_KEY", "SECRET_PIXABAY_API_KEY"],
  "aiAgent": {
    "enabled": true,
    "allowedModels": ["gpt-4", "gpt-3.5-turbo"]
  }
}

🤖 AI代理集成

MCP管理器包括一个内置 AI 代理 即：

注册与OpenAI兼容的API：通过配置 baseUrl 和API密钥
提供代理：服务器可以在不直接访问API密钥的情况下使用AI
令牌统计：透明地跟踪所有AI使用情况
基于权限的：每台服务器必须在权限中启用AI代理访问

工作原理：

注册AI提供商 在MCP管理器中：
- 基本URL: https://api.openai.com/v1
- API密钥：（安全存储在操作系统密钥链中）
- 型号： gpt-4, gpt-3.5-turbo等等。
为服务器启用：在服务器权限中，启用AI代理访问

在服务器中使用：SDK提供了访问AI代理的方法：

const aiResponse = await server.getAiAgent().chat({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Generate image prompt' }]
});

轨道使用情况：所有令牌使用情况都会在MCP管理器中跟踪和显示

优点：

✅ 没有API密钥暴露给服务器
✅ 集中式人工智能使用跟踪
✅ 易于切换的AI提供商
✅ 成本监控

🛠️ 可用工具

图像处理

image_process_local -处理本地图像：调整大小、裁剪、转换格式、优化
image_analyze -分析本地图像：尺寸、格式、文件大小、元数据
image_optimize -自动优化本地图像：压缩，转换为最佳格式
image_create_placeholder -创建显示尺寸的占位符图像
image_create_favicon -从图像创建favicon（多种尺寸）
image_add_watermark -为图像（文本或图像）添加水印
image_apply_filters -应用滤镜：模糊、锐化、灰度、棕褐色、亮度、对比度
image_rotate -按指定角度旋转图像
image_crop_custom -按精确坐标裁剪图像

库存图像

images_provider_status -检查图像提供程序的状态
stock_images_search -搜索来自Pexels或Pixabay的图像
stock_images_download_to_project -将图像从提供商下载并保存到项目

人工智能一代

ai_generate_image -使用OpenAI DALL-E生成图像

颜色提取

image_extract_colors_local -从局部图像中提取主色和调色板
generate_color_palette_image -从本地图像生成视觉调色板图像

📚 示例用法

示例1：搜索和下载股票图片

# 1. Search for images
# Tool: stock_images_search
# Query: "cozy coffee shop interior"

# 2. Download image to project
# Tool: stock_images_download_to_project
# Photo ID: 123456
# Target Path: public/images/hero.webp
# Format: webp
# Max Width: 1920

示例2：处理本地图像

# Tool: image_process_local
# Image Path: public/images/photo.jpg
# Output Path: public/images/photo-optimized.webp
# Format: webp
# Max Width: 1920
# Quality: 85

示例3：生成AI图像

# Tool: ai_generate_image
# Prompt: "a cozy coffee shop interior with warm lighting"
# Size: large (1024x1024px)
# Target Path: public/images/generated.webp
# Format: webp

🔧 环境变量

所有环境变量都是可选的，具有合理的默认值：

# Server settings
MCP_PORT=3848              # Server port (default: 3848)
MCP_HOST=0.0.0.0          # Server host (default: 0.0.0.0)
MCP_PATH=/mcp             # MCP endpoint path (default: /mcp)
MCP_PROJECT_ROOT=/path     # Project root directory

# Configuration (alternative to config file)
DEFAULT_PROVIDER=pexels
DEFAULT_FORMAT=webp
DEFAULT_MAX_WIDTH=1920
DEFAULT_QUALITY=80
SAVE_METADATA=true
EMBED_EXIF=false

# API Keys (required for stock images and AI generation)
SECRET_PEXELS_API_KEY=your_key
SECRET_PIXABAY_API_KEY=your_key
SECRET_OPENAI_API_KEY=your_key
SECRET_OPENAI_ORGANIZATION_ID=your_org_id

🏗️ 基于@tscodex/mcp-sdk构建

该项目建立在 @tscodex/mcp-sdk，它提供：

✅ MCP服务器基础架构：HTTP传输、协议处理、请求路由
✅ 身份验证和会话管理：安全会话处理
✅ 配置加载：CLI参数、环境变量、具有优先级系统的配置文件
✅ 秘密管理: SECRET_* 环境变量处理
✅ 工作区上下文：自动工作区根检测和标头处理
✅ AI代理集成：内置对AI代理代理的支持
✅ 类型安全：TypeBox模式完全支持TypeScript

SDK的主要功能：

基于HTTP的快速MCP服务器创建
无需数据库-无状态设计
使用或不使用MCP Manager
从标题自动生成工作区上下文
基于JSON模式的配置

🧪 发展

# Clone repository
git clone https://github.com/unbywyd/tscodex-mcp-images.git
cd tscodex-mcp-images

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

# Run production build
npm start

# Get metadata (for MCP Manager)
npm run meta

📁 项目结构

cursor-stock-images-mcp-v2/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # Server setup
│   ├── config.ts             # Configuration schema
│   ├── config-loader.ts      # Config loading logic
│   ├── tools/                # MCP tools
│   │   ├── image-processing.ts
│   │   ├── stock-images.ts
│   │   ├── ai-generation.ts
│   │   └── color-extraction.ts
│   ├── providers/            # Image providers
│   │   ├── pexels.ts
│   │   ├── pixabay.ts
│   │   └── openai.ts
│   ├── image-processor.ts    # Image processing logic
│   ├── color-extractor.ts    # Color extraction logic
│   └── utils.ts              # Utilities
├── dist/                     # Compiled JavaScript
├── package.json
└── README.md

📋 需求

Node.js>=18.0.0
供应商的API密钥（可选，但库存图像和AI生成需要）

🔗 相关项目

MCP经理 -用于MCP服务器管理的桌面应用程序
MCP经理桥 -VS代码/光标扩展桥
@tscodex/mcp-sdk -用于构建MCP服务器的SDK
MCP图像（本项目） -图像处理MCP服务器

📄 许可证

麻省理工学院

👤 作者

生命

网站: tscodex.com

🔗 链接

GitHub: https://github.com/unbywyd/tscodex-mcp-images
NPM: https://www.npmjs.com/package/@tscodex/mcp图像
问题: https://github.com/unbywyd/tscodex-mcp-images/issues
MCP-SDK: https://www.npmjs.com/package/@tscodex/mcp-sdk
MCP经理: https://github.com/unbywyd/tscodex-mcp-manager-app
MCP电桥: https://github.com/unbywyd/tscodex-mcp-manager-bridge