# UGCmind MCP

![UGCmind MCP](./assets/banner.jpg)

[![Validate](https://github.com/keenocean/ugcmind-mcp/actions/workflows/validate.yml/badge.svg)](https://github.com/keenocean/ugcmind-mcp/actions/workflows/validate.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
[![Node.js 18+](https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white)](./package.json)

[简体中文](docs/README.zh-CN.md)

Open-source MCP server and CLI for AI image and video generation through UGCmind. It lets Claude Code, Cursor, Codex, Windsurf, OpenClaw, Hermes Agent, and any MCP-compatible host search prompt inspiration, enhance rough ideas, submit image/video jobs, poll async project artifacts, and optionally use local ComfyUI or OpenAI-compatible image providers.

UGCmind stays the orchestration layer: the App owns auth, project scope, credits, model routing, provider configuration, asset storage, and generated artifacts. This MCP adapter exposes that runtime safely to local agent hosts.

## Open-source scope

This repository contains the complete local MCP adapter: stdio server, CLI, host setup helpers, MCP tools/resources, optional local providers, tests, and plugin manifests. You can inspect it, run it from source, fork it, and contribute under the MIT License.

It does not contain the hosted UGCmind App backend, user data, provider credentials, billing logic, or private deployment configuration. UGCmind-hosted generation still calls the App API, where authentication, project ownership, credits, model policy, skill grants, and artifact persistence are enforced.

The boundary is intentional:

```text
Claude / Codex / Cursor / other MCP host
                    │ stdio MCP
                    ▼
             ugcmind-mcp (this repo)
              ├─ public discovery and local helpers
              ├─ optional OpenAI-compatible / ComfyUI image providers
              └─ authenticated UGCmind App Runtime calls
                                   │
                                   ▼
               auth · projects · credits · models · tasks · assets
```

See [Architecture](./ARCHITECTURE.md), [Contributing](./CONTRIBUTING.md), [Security](./SECURITY.md), and [Release process](./RELEASING.md).

## Quick start

Requirements: Node.js 18 or newer and an MCP-compatible host. Prompt inspiration, capabilities, and the public model catalog do not require an account. UGCmind-hosted generation requires a user API key.

### One-command host setup

Published npm releases support:

```bash
npx -y ugcmind-mcp@0.3.0 init cursor
npx -y ugcmind-mcp@0.3.0 init claude
npx -y ugcmind-mcp@0.3.0 init windsurf
npx -y ugcmind-mcp@0.3.0 init vscode
npx -y ugcmind-mcp@0.3.0 init roo
```

This installs a standard stdio MCP entry; it does not install UGCmind into the host itself. Restart the host after setup.

### Claude Code

For read-only discovery:

```bash
claude mcp add --scope user ugcmind -- npx -y ugcmind-mcp@0.3.0
```

For generation, keep the key in an environment variable and register it in the user-scoped MCP entry:

```bash
export UGCMIND_API_KEY=sk_...
claude mcp add --scope user \
  -e UGCMIND_API_URL=https://ugcmind.com \
  -e UGCMIND_API_KEY="$UGCMIND_API_KEY" \
  ugcmind -- npx -y ugcmind-mcp@0.3.0
```

### Codex

For read-only discovery:

```bash
codex mcp add ugcmind -- npx -y ugcmind-mcp@0.3.0
```

For generation:

```bash
export UGCMIND_API_KEY=sk_...
codex mcp add \
  --env UGCMIND_API_URL=https://ugcmind.com \
  --env UGCMIND_API_KEY="$UGCMIND_API_KEY" \
  ugcmind -- npx -y ugcmind-mcp@0.3.0
```

### Run from source

Use this path for development or before the first npm release is available:

```bash
git clone https://github.com/keenocean/ugcmind-mcp.git
cd ugcmind-mcp
npm ci
npm test
npm run build
node bin/ugcmind-mcp.js
```

To attach a source checkout to a host, replace `npx -y ugcmind-mcp@0.3.0` in the examples above with `node /absolute/path/to/ugcmind-mcp/bin/ugcmind-mcp.js`.

## What It Does

| Tool                   | Provider config required | Purpose                                                                                                             |
| ---------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `ugcmind_capabilities` | No                       | Discover the live tool catalog, provider availability, access rules, resource URIs, and async task contract.       |
| `search_gallery`       | No                       | Search UGCmind prompt inspiration by query, category, type, model, and locale.                                      |
| `get_inspiration`      | No                       | Fetch the full prompt and images for a selected inspiration entry.                                                  |
| `enhance_prompt`       | No                       | Expand a short idea into a structured image prompt locally.                                                         |
| `list_models`          | No                       | Show the public UGCmind image/video model catalog; authenticated calls may include project-specific overrides.      |
| `manage_preferences`   | No                       | Store local MCP preferences such as style, aspect ratio, provider, and favorites.                                   |
| `find_skill`           | Yes                      | Find available UGCmind skills that match the user's requested workflow.                                             |
| `run_skill`            | Yes                      | Enable a selected skill and obtain its project-scoped tool grant before execution.                                  |
| `generate_image`       | Yes                      | Generate through UGCmind App Runtime, OpenAI-compatible image APIs, or local ComfyUI workflows.                     |
| `generate_video`       | Yes                      | Submit a UGCmind video generation task.                                                                             |
| `get_tool_task_status` | Yes                      | Poll queued or running UGCmind Tool Runtime tasks.                                                                  |
| `comfyui_workflow`     | Local only               | Import, view, modify, list, and delete local ComfyUI workflow templates for `provider: "comfyui"` image generation. |

No API key is needed for inspiration. Read-only prompt inspiration, local prompt enhancement, local preferences, and the public model catalog work against `https://ugcmind.com`. UGCmind-hosted image/video generation requires `UGCMIND_API_KEY`; image generation can alternatively use `OPENAI_API_KEY` or local ComfyUI.

### Skill-aware workflows

UGCmind skills remain ordinary, individually installable Agent Skills. They all use this same MCP server; users do not need a second installer, a skill-specific MCP, or a custom invocation protocol.

For skill-driven work, the agent first calls `find_skill` when discovery is needed, then calls `run_skill` for the selected skill. `run_skill` returns a scoped grant/run descriptor, and the MCP client automatically carries that descriptor into the permitted concrete tools. Direct calls to these tools are rejected until the matching skill is active:

- Research and assets: `web_fetch`, `create_file_by_url`, `search_project_assets`, `read_project_asset`, `prepare_reference_asset`, `search_ugc_actors`.
- Creative production: `visual_design_task`, `video_generation`, `music_generation`, `speech_generation`.
- Documents and media: `transcribe_media`, `write_free_doc`, `create_voice_profile`.

This preserves the same project ownership, skill grants, billing, task queue, and artifact persistence used by UGCmind itself.

### Capability and resource discovery

Third-party agents can inspect the current integration instead of relying on a hardcoded tool list:

- Call `ugcmind_capabilities` with `view: "overview"`, `"discovery"`, `"skills"`, `"generation"`, `"providers"`, or `"all"`.
- Read `ugcmind://capabilities` for the full machine-readable catalog.
- Read `ugcmind://models` for the current public or project-aware model catalog.
- Discover prompt inspiration through `search_gallery` and `get_inspiration`.
- Discover UGC actors, project assets, and brand assets through the paths returned by `ugcmind_capabilities`. These project-aware reads deliberately remain behind `run_skill`; the resource layer does not bypass project ownership or skill grants.

Every App-backed asynchronous result exposes the same agent-facing fields while preserving the original App response: `taskId` and `toolTaskId` aliases, normalized `status`, `nextAction`, `statusTool`, and `statusUrl`. Provider-specific values remain available as `providerStatus` and `runtimeNextAction`. Agents poll `statusTool`; users may open `statusUrl` to inspect the project.

## UGCmind Prompt Library

UGCmind includes a public prompt inspiration library for visual creation. The MCP server can search it before generation so agents do not have to start from a blank prompt.

Prompt Library entries may include:

- A reusable full prompt or prompt template.
- Preview images or media URLs.
- Category, modality, model, and locale metadata.
- Scores and sorting signals for relevance, quality, or freshness.
- A stable id or slug that can be passed to `get_inspiration`.

Use `search_gallery` to discover matching examples:

```text
Find UGCmind prompt inspiration for luxury skincare product photography.
```

Use `get_inspiration` when the user picks a result and needs the full prompt, images, and metadata:

```text
Get the full prompt for the second inspiration result and adapt it for a coffee brand.
```

The prompt library is served by UGCmind APIs. It is not bundled into the npm package, so the package stays small and the library can update independently.

## Installation details

One-command setup without installing the package:

```bash
npx ugcmind-mcp init cursor
npx ugcmind-mcp init claude
npx ugcmind-mcp init windsurf
npx ugcmind-mcp init vscode
npx ugcmind-mcp init roo
```

The npm package is `ugcmind-mcp`, and it exposes the shorter `ugcmind` command. After a global install, you can use the short command directly:

```bash
npm install -g ugcmind-mcp
ugcmind init cursor
ugcmind init claude
```

Or add this server to your MCP host configuration manually:

```json
{
  "mcpServers": {
    "ugcmind": {
      "command": "npx",
      "args": ["-y", "ugcmind-mcp@0.3.0"],
      "env": {
        "UGCMIND_API_URL": "https://ugcmind.com",
        "UGCMIND_API_KEY": "sk_..."
      }
    }
  }
}
```

For read-only inspiration search, you may omit `UGCMIND_API_KEY`:

```json
{
  "mcpServers": {
    "ugcmind": {
      "command": "npx",
      "args": ["-y", "ugcmind-mcp@0.3.0"],
      "env": {
        "UGCMIND_API_URL": "https://ugcmind.com"
      }
    }
  }
}
```

Restart your MCP host after changing its configuration.

## Standalone CLI

Use the standalone CLI when you want one-shot image generation from a shell or script without opening an MCP host:

```bash
export UGCMIND_API_KEY=sk_...

# No install:
npx ugcmind-mcp gen --prompt "a ceramic coffee dripper product photo" --ratio 1:1
npx ugcmind-mcp gen -p "luxury perfume campaign" -m seedream --json
npx ugcmind-mcp gen -p "poster design" --reference https://example.com/ref.png --no-wait

# After `npm install -g ugcmind-mcp`:
ugcmind gen --prompt "a ceramic coffee dripper product photo" --ratio 1:1
```

`ugcmind gen` uses UGCmind App Runtime only. OpenAI-compatible and ComfyUI provider modes are available through the MCP `generate_image` tool.

## Get An API Key

1. Sign in at `https://ugcmind.com`.
2. Open `Settings`.
3. Go to `API Keys`.
4. Click `Create Key`.
5. Name it, for example `Claude MCP` or `UGCmind MCP`.
6. Copy the generated `sk_...` key immediately.

The full key is shown only once. If you lose it, delete that key and create a new one.

## Configuration

Environment variables:

```bash
export UGCMIND_API_URL=https://ugcmind.com
export UGCMIND_API_KEY=sk_...
export UGCMIND_LOCALE=en

# Optional image-only providers
export OPENAI_API_KEY=...
export OPENAI_BASE_URL=https://api.openai.com
export OPENAI_MODEL=gpt-image-2
export COMFYUI_URL=http://localhost:8188
```

Equivalent config file:

```json
{
  "ugcmindApiUrl": "https://ugcmind.com",
  "ugcmindApiKey": "sk_...",
  "ugcmindLocale": "en",
  "openaiApiKey": "...",
  "openaiBaseUrl": "https://api.openai.com",
  "openaiModel": "gpt-image-2",
  "comfyuiUrl": "http://localhost:8188",
  "comfyuiDefaultWorkflow": "default"
}
```

Config path:

```text
~/.config/ugcmind-mcp/config.json
```

Advanced internal deployments may also provide `UGCMIND_USER_ID`, `UGCMIND_PROJECT_ID`, and `UGCMIND_CHAT_ID`, but normal open-source usage should use only `UGCMIND_API_URL` and `UGCMIND_API_KEY`.

## Provider Modes

`generate_image` supports three provider modes:

- `provider: "ugcmind"`: default when `UGCMIND_API_KEY` is configured. Jobs run in UGCmind App Runtime with credits, model policy, project assets, and artifact storage.
- `provider: "openai"`: uses `OPENAI_API_KEY`, `OPENAI_BASE_URL`, and `OPENAI_MODEL` against an OpenAI-compatible `/v1/images/generations` endpoint. Results are saved locally.
- `provider: "comfyui"`: uses local ComfyUI. Import a workflow JSON first with `comfyui_workflow import`; results are saved locally.

Video generation and `get_tool_task_status` are UGCmind App Runtime features and require `UGCMIND_API_KEY`.

## Usage Examples

Search inspiration without an API key:

```text
Find image prompt inspiration for a cyberpunk perfume bottle campaign.
```

List current image/video models:

```text
What image and video models are available in UGCmind?
```

Generate an image with an API key:

```text
Generate a 1:1 premium product photo of a ceramic coffee dripper on a warm stone countertop.
```

Generate a video with an API key:

```text
Generate a 5 second vertical video of ocean waves crashing against black volcanic rocks.
```

Poll async work:

```text
Check the status of tool task <toolTaskId>.
```

Expected agent workflow:

1. Search inspiration first when the brief is broad or exploratory.
2. Enhance short prompts locally when useful.
3. Submit one generation task.
4. If the task is queued or running, call `get_tool_task_status` instead of submitting again.
5. Report the exact task id, status, artifact URLs, and App messages returned by the tool.

## Runtime Notes

- `ugcmind_capabilities`, `search_gallery`, `get_inspiration`, `list_models`, `enhance_prompt`, and `manage_preferences` work without an API key.
- `generate_image` defaults to UGCmind App Runtime, but can use `provider: "openai"` or `provider: "comfyui"` when configured.
- `generate_video` submits UGCmind Tool Runtime tasks. If a task is queued or running, poll with `get_tool_task_status` instead of resubmitting.
- The App validates project/chat ownership, credits, model availability, provider policy, and project asset access server-side for UGCmind-hosted jobs.
- Local reference file upload to UGCmind is intentionally not implemented. Use public URLs or UGCmind project assets for UGCmind/OpenAI-compatible providers. ComfyUI can read local reference paths when the workflow has LoadImage nodes.
- Model availability is controlled by the UGCmind App. Do not hardcode model assumptions in host prompts; call `list_models` or use App defaults.

## Troubleshooting

| Problem                                | Fix                                                                                                             |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| MCP tools are not visible              | Restart the host after adding the MCP config.                                                                   |
| Inspiration works but generation fails | Check `UGCMIND_API_URL`, `UGCMIND_API_KEY`, account credits, and whether the key is still active.               |
| Task is queued or running              | Call `get_tool_task_status` with the returned task id. Do not submit the same prompt again.                     |
| Reference image is a local path        | Use ComfyUI with a LoadImage workflow, or upload it to UGCmind first and use a URL/project asset.               |
| ComfyUI is not available               | Start ComfyUI, set `COMFYUI_URL` if not using `http://localhost:8188`, then import an API-format workflow JSON. |
| Model choices are unclear              | Call `list_models`; App configuration is the source of truth.                                                   |
| The API key was lost after creation    | Create a new key in UGCmind Settings. Full API keys are only shown once.                                        |

## Development

```bash
npm ci
npm test
npm run typecheck
npm run build
npm pack --dry-run
```

Run the local server:

```bash
npm run build
node bin/ugcmind-mcp.js
```

Tests do not require a real UGCmind API key. Live App smoke testing must use a non-production account and sanitized project data. Before opening a pull request, read [CONTRIBUTING.md](./CONTRIBUTING.md).

## Project status and support

- Source repository: [github.com/keenocean/ugcmind-mcp](https://github.com/keenocean/ugcmind-mcp)
- Issues and feature requests: [GitHub Issues](https://github.com/keenocean/ugcmind-mcp/issues)
- Changelog: [CHANGELOG.md](./CHANGELOG.md)
- Roadmap: [ROADMAP.md](./ROADMAP.md)
- Security reports: follow [SECURITY.md](./SECURITY.md); do not disclose vulnerabilities in a public issue.
- If npm returns `E404`, that version has not been published yet. Run from source until the release appears in the npm registry.

## License

MIT. See [LICENSE](./LICENSE) and [NOTICE.md](./NOTICE.md) for attribution and third-party notices.