![Prometheus Main](Prometheus-MAIN.png)

<div align="center">

# Prometheus-MCP

### Creative Director MCP for coding agents

**Deterministic critique that elevates agent-generated UI, 3D scenes, shaders, and game feel.**

[한국어](#한국어) | [English](#english)

</div>

---

## 한국어

Prometheus-MCP는 Claude, GPT, DeepSeek 등 에이전트가 만든 크리에이티브 산출물(웹 UI, Three.js/R3F 씬, 셰이더, 게임 느낌)을 **결정적 크리틱 엔진**(증거 수집 + 60개 규칙 + 16개 품질 차원)으로 평가하고, 우선순위가 매겨진 수정안을 돌려주는 Model Context Protocol 서버입니다.

핵심 원칙: **생성은 호스트 에이전트가, 평가는 Prometheus가.**

### 두 가지 모드

| 모드 | 주 사용처 | 동작 |
|------|-----------|------|
| **호스트 주도 품질 게이트 (권장)** | 대화형 세션 (opencode, Claude Code 등) | 에이전트가 자신의 컨텍스트로 산출물을 생성·수정하고, Prometheus는 `critique_artifact`로 평가만 담당합니다. 네트워크 호출 0, API 키 불필요 |
| **배치 자율 루프** | CI / 헤드리스 파이프라인 | `direct_creative_work`가 생성→평가→개선 루프를 자율 실행합니다. 실제 LLM 프로바이더(API 키) 필요 |

대화형 세션에서 에이전트는 이미 프로젝트 컨텍스트를 갖고 있으므로, MCP 내부 생성기보다 훨씬 좋은 산출물을 만듭니다. 그래서 기본 워크플로는 "에이전트가 생성 → Prometheus가 크리틱 → 에이전트가 수정 → 재크리틱 검증"입니다.

### 5분 온보딩

요구사항: Node.js 20+

```bash
# 1. 설치 및 빌드 (이 저장소 루트에서)
npm install
npm run build
```

```jsonc
// 2. 프로젝트 루트의 opencode.json에 MCP 등록 (절대 경로로!)
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "prometheus": {
      "type": "local",
      "command": ["node", "C:/path/to/Prometheus-MCP/dist/index.js"],
      "enabled": true
    }
  }
}
```

3. opencode를 재시작합니다 (설정은 시작 시 1회 로드됩니다).

4. 첫 크리틱을 요청해 보세요:

> "이 컴포넌트 좀 세련되게 만들어줘" → 이어서 → "방금 만든 것 prometheus로 크리틱하고 상위 수정 적용해줘"

에이전트가 `critique_artifact`를 호출해 점수·findings·우선순위 수정안을 받고, 직접 반영한 뒤 재크리틱으로 검증합니다. 호스트 주도 모드에는 API 키가 전혀 필요 없습니다.

### 호스트 루프 워크플로

```
에이전트가 산출물 생성 (자기 컨텍스트로)
  -> critique_artifact   결정적 평가: 증거 + 규칙 → 점수/findings/수정안
  -> 상위 fix를 직접 적용
  -> critique_artifact 재호출로 검증 (before/after 점수)
  -> critical/major findings가 사라질 때까지 반복
```

### MCP 도구

| 도구 | 모드 | 설명 |
|------|------|------|
| `critique_artifact` | 호스트 | **주력 도구.** 산출물 평가 — 점수, findings, 우선순위 수정안 (결정적, 네트워크 0). `patternId`로 패턴 전용 규칙 추가 |
| `improve_artifact` | 호스트/배치 | 개선 계획 + 수정 프롬프트 생성. **기본은 plan-only** — 적용은 호스트가. `provider` 지정 시 서버가 실제 재생성(배치 경로) |
| `direct_creative_work` | 배치 | 브리프에서 생성→평가→개선 루프를 자율 실행. CI/헤드리스용, 실제 프로바이더 필요 |
| `list_patterns` | 공용 | 패턴 목록 (22개) |
| `get_pattern` | 공용 | 패턴 상세 — 생성 전에 필수 요소/안티패턴 확인 |
| `recall_sessions` | 호스트/배치 | 과거 세션 조회 (배치 실행 + 호스트 크리틱) |
| `get_quality_trends` | 호스트/배치 | 품질 추세 (배치 실행 + 호스트 크리틱이 채움) |

리소스 5개(`pattern://`, `session://`, `trends://quality`, `config://runtime`)와 워크플로 프롬프트 4개(`critique-then-improve`, `generate-fantasy-vfx`, `audit-ui-consistency`, `threejs-scene-review`)도 제공됩니다.

### 호스트 스킬 (권장 설치)

이 저장소에는 `prometheus-critique` 스킬이 포함되어 있습니다(`.opencode/skills/prometheus-critique/`). 이 저장소를 opencode로 열면 자동 인식됩니다.

다른 프로젝트에서도 쓰려면 전역 스킬 디렉터리로 복사하세요:

```bash
# opencode 전역
~/.config/opencode/skills/prometheus-critique/
# 또는 Claude Code / 크로스 런타임
~/.claude/skills/prometheus-critique/
```

복사 후 opencode를 재시작합니다. 스킬은 "이 UI 봐줘", "이 씬 검토해줘" 같은 요청에서 크리틱→수정→재검증 루프를 자동으로 따르게 합니다. 패턴·규칙 데이터는 항상 MCP에서 읽으므로 스킬은 얇은 워크플로 가이드일 뿐입니다.

### 패턴 라이브러리

22개 엑스퍼트 패턴(웹 UI 12 + 3D/게임 10): `modern-landing-page`, `glassmorphism-ui`, `cyberpunk-dashboard`, `fantasy-fireball`, `r3f-postprocessing`, `webgpu-render-pipeline`, `top-down-shooter`, `racing-game` 등. 각 패턴은 필수 요소, 안티패턴, 개선 제안을 정의합니다.

### 한계 (정직 고지)

- **점수는 결정적 휴리스틱 프록시입니다.** 증거 수집은 정규식·구조 측정 기반이며 실제 브라우저 렌더링/실행 검증이 아닙니다. 트렌드 지표로 쓰고, 점수 자체에 집착하지 마세요 — 우선순위가 높은 findings를 고치는 것이 목적입니다.
- **LLM reasoning은 옵트인입니다.** `PROMETHEUS_ENABLE_LLM_REASONING=false`가 아니고 실제 프로바이더 키가 있을 때만 4개 주관 차원에 ±15 이내의 보정을 가합니다.
- **StubProvider는 데모/테스트 전용입니다.** 기본 `direct_creative_work` 결과는 스캐폴딩 수준입니다. 실제 배치 품질이 필요하면 프로바이더를 설정하세요.
- 세션 기록·품질 트렌드는 배치 모드와 호스트 크리틱(`critique_artifact`) 모두에서 채워집니다. 호스트 기록은 `PROMETHEUS_RECORD_HOST_CRITIQUES=false`로 끌 수 있습니다.

### 설정

환경 변수로 런타임 설정을 덮어쓸 수 있습니다.

| 변수 | 기본값 | 설명 |
|------|--------|------|
| `PROMETHEUS_TARGET_SCORE` | 82 | 목표 품질 점수 |
| `PROMETHEUS_MAX_ITERATIONS` | 3 | 최대 개선 반복 |
| `PROMETHEUS_MAX_COST_USD` | 0.5 | 비용 상한 (USD) |
| `PROMETHEUS_DEFAULT_PROVIDER` | stub | 배치 모드 기본 프로바이더 |
| `PROMETHEUS_ENABLE_LLM_REASONING` | true | `"false"`로 LLM 추론 평가 비활성화 |
| `PROMETHEUS_ALLOW_COMMUNITY_PATTERNS` | false | `"true"`로 커뮤니티 패턴 허용 |
| `PROMETHEUS_RECORD_HOST_CRITIQUES` | true | `"false"`로 호스트 크리틱 세션 기록 중지 |

프로바이더 API 키가 있으면 해당 프로바이더가 자동 활성화됩니다: `OPENAI_API_KEY`, `DEEPSEEK_API_KEY`, `MINIMAX_API_KEY`, `DASHSCOPE_API_KEY`(Qwen), `GLM_API_KEY`, `ANTHROPIC_API_KEY`(Claude).

### 개발

```bash
npm run typecheck   # tsc --noEmit
npm test            # vitest (7개 파일)
npm run build       # dist/ 생성
```

### Claude Desktop 연결 (선택)

`claude_desktop_config.json`에 추가:

```json
{
  "mcpServers": {
    "prometheus": {
      "command": "node",
      "args": ["C:/path/to/Prometheus-MCP/dist/index.js"]
    }
  }
}
```

### 기술 스택

- TypeScript (ES Modules), Node.js 20+
- @modelcontextprotocol/sdk 1.29.0
- zod v3 / ajv
- Vitest

### 라이선스

MIT

---

## English

Prometheus-MCP is a Model Context Protocol server that critiques creative artifacts (web UI, Three.js/R3F scenes, shaders, game feel) produced by agents like Claude, GPT, and DeepSeek. It uses a **deterministic critic engine** (evidence collection + 60 rules + 16 quality dimensions) and returns prioritized fixes.

Core principle: **the host agent generates, Prometheus critiques.**

### Two Modes

| Mode | Best for | How it works |
|------|----------|--------------|
| **Host-driven quality gate (recommended)** | Interactive sessions (opencode, Claude Code, ...) | The agent generates and revises with its own context; Prometheus only evaluates via `critique_artifact`. Zero network calls, no API key needed |
| **Batch autonomous loop** | CI / headless pipelines | `direct_creative_work` runs the generate→critique→improve loop unattended. Requires a real LLM provider (API key) |

In interactive sessions the agent already holds the project context, so it produces far better artifacts than an in-server generator. The default workflow is therefore: agent generates → Prometheus critiques → agent applies fixes → re-critique to verify.

### 5-Minute Onboarding

Requires Node.js 20+

```bash
# 1. Install and build (from this repo root)
npm install
npm run build
```

```jsonc
// 2. Register the MCP in opencode.json at your project root (absolute path!)
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "prometheus": {
      "type": "local",
      "command": ["node", "C:/path/to/Prometheus-MCP/dist/index.js"],
      "enabled": true
    }
  }
}
```

3. Restart opencode (config is loaded once at startup).

4. Ask for your first critique:

> "Build this component" → then → "Critique it with prometheus and apply the top fixes"

The agent calls `critique_artifact`, receives scores, findings, and prioritized fixes, applies them, and re-critiques to verify. No API key is needed in host-driven mode.

### Host Loop Workflow

```
Agent generates the artifact (with its own context)
  -> critique_artifact  deterministic evaluation: evidence + rules -> scores/findings/fixes
  -> agent applies the top fixes directly
  -> critique_artifact again to verify (before/after scores)
  -> repeat until no critical/major findings remain
```

### MCP Tools

| Tool | Mode | Description |
|------|------|-------------|
| `critique_artifact` | host | **Primary tool.** Evaluates an artifact — score, findings, prioritized fixes (deterministic, zero network). Pass `patternId` for pattern-specific rules |
| `improve_artifact` | host/batch | Builds an improvement plan + revision prompt. **Plan-only by default** — YOU apply it. Pass `provider` to have the server regenerate instead (batch path) |
| `direct_creative_work` | batch | Runs the full generate→critique→improve loop from a brief. For CI/headless; needs a real provider |
| `list_patterns` | both | Lists available patterns (22) |
| `get_pattern` | both | Pattern detail — check required elements/anti-patterns before generating |
| `recall_sessions` | host/batch | Recalls past sessions (batch runs + host critiques) |
| `get_quality_trends` | host/batch | Quality trends (populated by batch runs + host critiques) |

Also included: 5 resources (`pattern://`, `session://`, `trends://quality`, `config://runtime`) and 4 workflow prompts (`critique-then-improve`, `generate-fantasy-vfx`, `audit-ui-consistency`, `threejs-scene-review`).

### Host Skill (recommended)

This repo ships a `prometheus-critique` skill at `.opencode/skills/prometheus-critique/`. It is picked up automatically when you open this repo with opencode.

To use it in other projects, copy it to a global skills directory:

```bash
# opencode global
~/.config/opencode/skills/prometheus-critique/
# or Claude Code / cross-runtime
~/.claude/skills/prometheus-critique/
```

Restart opencode after copying. The skill makes the critique→fix→re-verify loop automatic for requests like "review this UI" or "look at this scene". Pattern and rule data always come from the MCP, so the skill stays a thin workflow guide.

### Pattern Library

22 expert patterns (12 web UI + 10 3D/game): `modern-landing-page`, `glassmorphism-ui`, `cyberpunk-dashboard`, `fantasy-fireball`, `r3f-postprocessing`, `webgpu-render-pipeline`, `top-down-shooter`, `racing-game`, and more. Each pattern defines required elements, anti-patterns, and improvement suggestions.

### Limitations (honest disclosure)

- **Scores are deterministic heuristic proxies.** Evidence collection is regex/structure-based, not real browser rendering or execution. Use them as trend indicators; do not obsess over the number — the point is fixing high-priority findings.
- **LLM reasoning is opt-in.** Only with `PROMETHEUS_ENABLE_LLM_REASONING` not `"false"` and a real provider key; it adjusts 4 subjective dimensions by at most ±15.
- **The StubProvider is for demo/testing only.** Default `direct_creative_work` output is scaffolding-level. Configure a provider for real batch quality.
- Session history and quality trends are populated by both batch mode and host critiques (`critique_artifact`). Disable host recording with `PROMETHEUS_RECORD_HOST_CRITIQUES=false`.

### Configuration

Environment variables override runtime config.

| Variable | Default | Description |
|----------|---------|-------------|
| `PROMETHEUS_TARGET_SCORE` | 82 | Target quality score |
| `PROMETHEUS_MAX_ITERATIONS` | 3 | Max improvement iterations |
| `PROMETHEUS_MAX_COST_USD` | 0.5 | Cost cap (USD) |
| `PROMETHEUS_DEFAULT_PROVIDER` | stub | Default batch-mode provider |
| `PROMETHEUS_ENABLE_LLM_REASONING` | true | Set `"false"` to disable LLM reasoning |
| `PROMETHEUS_ALLOW_COMMUNITY_PATTERNS` | false | Set `"true"` to allow community patterns |
| `PROMETHEUS_RECORD_HOST_CRITIQUES` | true | Set `"false"` to stop recording host critiques as sessions |

Provider API keys auto-enable their providers: `OPENAI_API_KEY`, `DEEPSEEK_API_KEY`, `MINIMAX_API_KEY`, `DASHSCOPE_API_KEY` (Qwen), `GLM_API_KEY`, `ANTHROPIC_API_KEY` (Claude).

### Development

```bash
npm run typecheck   # tsc --noEmit
npm test            # vitest (7 files)
npm run build       # emits dist/
```

### Claude Desktop (optional)

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "prometheus": {
      "command": "node",
      "args": ["C:/path/to/Prometheus-MCP/dist/index.js"]
    }
  }
}
```

### Tech Stack

- TypeScript (ES Modules), Node.js 20+
- @modelcontextprotocol/sdk 1.29.0
- zod v3 / ajv
- Vitest

### License

MIT