# Mcp Refero

> Refero MCP transport: read-only UI design-reference search (styles, screens, flows) via Code Mode; pairs with sk-design-md-generator for a measured Style Reference (extracted design tokens).

- **Type:** Skill
- **Install:** `agentstack add skill-michelkerkmeester-skilled-harness-spec-driven-agent-loops-mcp-refero`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [MichelKerkmeester](https://agentstack.voostack.com/s/michelkerkmeester)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [MichelKerkmeester](https://github.com/MichelKerkmeester)
- **Source:** https://github.com/MichelKerkmeester/skilled-harness__spec-driven-agent-loops/tree/main/.opencode/skills/mcp-tooling/mcp-refero

## Install

```sh
agentstack add skill-michelkerkmeester-skilled-harness-spec-driven-agent-loops-mcp-refero
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Refero (mcp-refero)

Search **Refero's library of real shipped UI** (150,000+ app screens, 6,000+ user flows per the official repo) from an agent through the **Refero MCP via Code Mode**: styles for visual direction, screens for concrete UI patterns, flows for multi-step journeys. This packet is a read-only TRANSPORT (`packetKind: transport`, `mutatesWorkspace: false`): every read and "write" happens against the external Refero service, never this repo, and it is **never the taste authority**. Any design-affecting use pairs with `sk-design-md-generator` for a measured Style Reference (extracted design tokens). Deep operational detail lives in [`references/tool-surface.md`](references/tool-surface.md) and [`references/mcp-wiring.md`](references/mcp-wiring.md).

> **Naming trap (read first).** Inside `call_tool_chain`, Refero tools resolve with a **DOUBLED prefix**: the callable form is `refero.refero_refero_(...)` (for example `refero.refero_refero_search_styles`), because Code Mode's `{manual}.{manual}_{tool}` rule applies to tools whose own names already begin with `refero_`. **CONFIRMED by live discovery 2026-07-16** (`references/discovery-fixture-2026-07-16.json`): `list_tools` returned all eight registry names in the dotted doubled form `refero.refero.refero_` — pre-auth, no OAuth needed for discovery — and the fixture's `Access as:` line shows the TS callable `refero.refero_refero_search_styles(args)`. Per-session `tool_info` re-confirmation stays mandatory: confirm, then call, and fail closed on drift.
>
> **Access trap.** Live MCP access is paid and authenticated. The Free plan has **no MCP access at all** (denial, not a reduced tool set). Pro is the first tier with MCP and carries a published quota of **8,000 tool calls per month**. Unauthenticated calls return HTTP 401.

---

## 1. WHEN TO USE

### Activation Triggers

**Use when** the user wants to:
- Search Refero for design references: visual styles, real app screens, or user flows.
- Find real-app screen examples for a UI pattern, state, or component ("show me real onboarding screens", "empty-state examples from shipped apps").
- Pull the full detail of a shortlisted style, screen, or flow (metadata, tokens, step goals, screenshots) as evidence for a design decision.
- Research a company's or domain's shipped UI through screen or flow queries and `site` metadata.
- Wire, verify, or troubleshoot the `refero` Code Mode manual, its OAuth or Bearer authentication, or its plan gating.

**Keyword Triggers**: "refero", "refero mcp", "design reference", "ui reference search", "real app screens", "refero styles", "refero flows", "search refero".

### Use Cases

**Styles research (read-only).** Search 3-5 semantic angles for visual direction, inspect metadata, then fetch full style references for shortlisted UUIDs. Styles cover web marketing and product pages only.

**Screens research (read-only).** Literal semantic queries (screen type, component, state, company) plus a required platform (`web` or `ios`); fetch detail for the most relevant UUIDs; similar screens and images only when text cannot answer.

**Flows research (read-only).** Search task journeys, fetch one relevant numeric flow, and use its ordered step goals, actions, and system responses.

**Wiring and auth verification.** Confirm the existing `refero` manual is registered, discovery resolves the doubled-prefix names, and authentication state is what the operator expects. Never repair auth state yourself.

### When NOT to Use

**Skip this skill when:**
- The work is the design judgment itself (palette, type, layout, taste verdicts, accessibility or readiness calls). This packet is only an evidence transport and issues no such verdict.
- The task is app or screen research through Mobbin. That is `mcp-mobbin` (a future sibling transport, not this packet).
- The task is browser automation, live-page inspection, or visual preview of a built page. That is `mcp-chrome-devtools`.
- The work is generic app coding with no design-reference input: use `sk-code`.
- The user asks to change this repo's files, the `.utcp_config.json` manual, or auth state. This transport forbids Write/Edit/Task and never mutates the workspace.

---

## 2. SMART ROUTING

### Primary Detection Signal

Route on **narrow Refero-specific signals only**. Generic "design", "UI", or "screen" phrasing is not a Refero signal; Figma work belongs to `mcp-figma`, and browser work to `mcp-chrome-devtools`.

```bash
# Signal detection (pseudo)
echo "$REQUEST" | grep -qiE 'refero' && ROUTE="MCP_REFERO"
echo "$REQUEST" | grep -qiE 'design reference|ui reference search|real app (screens|examples|flows)' && ROUTE="MCP_REFERO"
# generic design/UI phrasing WITHOUT these signals -> not this packet (Refero signals only)
```

### Phase Detection

```text
TASK CONTEXT
    |
    +- STEP 0: Verify wiring (refero manual registered; Code Mode reachable; auth state operator-confirmed)
    +- STEP 1: Score intent -> STYLES | SCREENS | FLOWS | WIRING_AUTH | TROUBLESHOOT
    +- Phase 1: Design-affecting? -> pair with sk-design-md-generator for a measured Style Reference (extracted tokens), then return here for retrieval
    +- Phase 2: Discovery (list_tools / tool_info confirms the doubled-prefix callables)   [MANDATORY]
    +- Phase 3: Retrieval funnel (search -> metadata shortlist -> get_* detail -> similar -> image last)
    +- Phase 4: Verify (evidence cited by source URL; unknown fields preserved; no invented limits)
```

### Resource Domains

The router discovers markdown resources recursively from `references/` and `assets/`, then applies intent scoring. This skill uses a **flat intent router**: no keyed `references//` subdirectories. References are the primary loaded resources; the single asset is the paste-ready manual snapshot.

```text
references/tool-surface.md      # the 8-tool surface, args/bounds, workflows, plan gating
references/mcp-wiring.md        # manual, mcp-remote bridge, OAuth/Bearer, naming, discovery
references/troubleshooting.md   # failure modes + fixes
assets/utcp-refero-manual.md    # verified manual snapshot (already registered) + Bearer alternative
```

### Resource Loading Levels

| Level | When to Load | Resources |
| ----- | ------------ | --------- |
| CONDITIONAL | Research intent (styles/screens/flows) | `references/tool-surface.md` (tool contract + workflow baseline) |
| CONDITIONAL | Wiring / auth intent | `references/mcp-wiring.md`, `assets/utcp-refero-manual.md` |
| CONDITIONAL | Setup / error intent | `references/troubleshooting.md` |
| FALLBACK | Zero-score routes only | `references/tool-surface.md` suggested (never auto-loaded) |
| ALWAYS (design work) | Retrieved evidence feeds a design decision | `sk-design-md-generator`, for a measured Style Reference (extracted design tokens) |

### Smart Router Pseudocode

> Resilience pattern: see [sk-doc smart-router template](../../sk-doc/sk-create-skill/assets/skill/skill-smart-router.md). Guard paths, discover at runtime, score intents, and fall back when unsure. Because this skill has no keyed resource subdirectories, intent selects from the flat resource inventory below.

```python
from pathlib import Path

SKILL_ROOT = Path(__file__).resolve().parent
RESOURCE_BASES = (SKILL_ROOT / "references", SKILL_ROOT / "assets")
DEFAULT_RESOURCE = "references/tool-surface.md"
# Fallback-only: DEFAULT_RESOURCE is a defer-time suggestion, never unioned
# into a route's loaded set. Scored routes load exactly RESOURCE_MAP[intent];
# zero-score routes load nothing and ask for disambiguation instead.
DEFAULT_RESOURCE_SEMANTICS = "fallback-only"
MIN_CONFIDENCE = 1
AMBIGUITY_DELTA = 1

INTENT_MODEL = {
    "STYLES":       {"keywords": [("style", 4), ("visual direction", 4), ("design reference", 3), ("aesthetic", 3), ("look and feel", 3), ("design language", 3), ("landing page", 2), ("typography reference", 2), ("palette reference", 2)]},
    "SCREENS":      {"keywords": [("screen", 4), ("ui pattern", 4), ("similar screens", 4), ("real app", 3), ("empty state", 3), ("component example", 3), ("screenshot", 3), ("modal", 2), ("dashboard", 2), ("onboarding", 2), ("settings", 2), ("ui element", 2)]},
    "FLOWS":        {"keywords": [("flow", 4), ("user flow", 4), ("journey", 4), ("multi-step", 3), ("steps", 2), ("checkout", 2), ("cancel subscription", 2), ("signup process", 2)]},
    "WIRING_AUTH":  {"keywords": [("wiring", 4), ("utcp", 4), ("oauth", 4), ("bearer", 4), ("mcp-remote", 4), ("authenticate", 4), ("manual", 3), ("token", 3), ("register", 3), ("plan", 2), ("subscription", 2), ("install", 2), ("setup", 2)]},
    "TROUBLESHOOT": {"keywords": [("error", 4), ("failed", 4), ("401", 4), ("connection closed", 4), ("not resolving", 4), ("not working", 4), ("sigsegv", 4), ("429", 3), ("quota", 3), ("timeout", 3), ("broken", 3), ("unauthorized", 3)]},
}

# Benchmark-facing mirror of INTENT_MODEL in the standard {weight, keywords} shape
# the skill-benchmark router-replay reads (the tuple form above parses to zero
# intents there). Runtime scoring uses INTENT_MODEL; this block changes no routing.
# Per-intent weight = the MAX per-keyword weight in INTENT_MODEL for that intent
# (all five resolve to 4). Keys and keywords MUST stay identical to INTENT_MODEL;
# keep the two blocks in sync whenever either one is edited.
INTENT_SIGNALS = {
    "STYLES":       {"weight": 4, "keywords": ["style", "visual direction", "design reference", "aesthetic", "look and feel", "design language", "landing page", "typography reference", "palette reference"]},
    "SCREENS":      {"weight": 4, "keywords": ["screen", "ui pattern", "similar screens", "real app", "empty state", "component example", "screenshot", "modal", "dashboard", "onboarding", "settings", "ui element"]},
    "FLOWS":        {"weight": 4, "keywords": ["flow", "user flow", "journey", "multi-step", "steps", "checkout", "cancel subscription", "signup process"]},
    "WIRING_AUTH":  {"weight": 4, "keywords": ["wiring", "utcp", "oauth", "bearer", "mcp-remote", "authenticate", "manual", "token", "register", "plan", "subscription", "install", "setup"]},
    "TROUBLESHOOT": {"weight": 4, "keywords": ["error", "failed", "401", "connection closed", "not resolving", "not working", "sigsegv", "429", "quota", "timeout", "broken", "unauthorized"]},
}

RESOURCE_MAP = {
    "STYLES":       ["references/tool-surface.md"],
    "SCREENS":      ["references/tool-surface.md"],
    "FLOWS":        ["references/tool-surface.md"],
    "WIRING_AUTH":  ["references/mcp-wiring.md", "assets/utcp-refero-manual.md"],
    "TROUBLESHOOT": ["references/troubleshooting.md", "references/mcp-wiring.md"],
}

UNKNOWN_FALLBACK_CHECKLIST = [
    "Confirm the layer: styles (visual direction), screens (UI patterns), or flows (journeys)",
    "Confirm the refero manual is registered and discovery (tool_info) confirms the doubled-prefix callables",
    "Confirm the account has a Pro (or higher) plan; Free has no MCP access at all",
    "If the evidence will influence a design decision, pair with sk-design-md-generator for a measured Style Reference (extracted design tokens); this transport never decides taste",
]

def _guard_in_skill(relative_path: str) -> str:
    resolved = (SKILL_ROOT / relative_path).resolve()
    resolved.relative_to(SKILL_ROOT)               # raises if path escapes the skill
    if resolved.suffix.lower() != ".md":
        raise ValueError(f"Only markdown resources are routable: {relative_path}")
    return resolved.relative_to(SKILL_ROOT).as_posix()

def discover_markdown_resources() -> set[str]:
    docs = []
    for base in RESOURCE_BASES:
        if base.exists():
            docs.extend(p for p in base.rglob("*.md") if p.is_file())
    return {d.relative_to(SKILL_ROOT).as_posix() for d in docs}

def classify_intents(request: str):
    text = (request or "").lower()
    scores = {i: 0 for i in INTENT_MODEL}
    for intent, cfg in INTENT_MODEL.items():
        for kw, w in cfg["keywords"]:
            if kw in text:
                scores[intent] += w
    ranked = sorted(scores.items(), key=lambda kv: kv[1], reverse=True)
    primary, top = ranked[0]
    if top == 0:
        return (None, None, scores)   # unrouted -> no intent selected; fallback branch disambiguates
    secondary, second = ranked[1]
    if second > 0 and (top - second)  bool:
        guarded = _guard_in_skill(rel)
        if guarded in inventory and guarded not in seen:
            load(guarded); loaded.append(guarded); seen.add(guarded)
            return True
        if guarded not in inventory:
            notices.append(f"Resource not found in inventory: {guarded}")
        return False

    if max(scores.values() or [0]) `) is **confirmed by live registry evidence** (2026-07-16 discovery fixture, `references/discovery-fixture-2026-07-16.json`): all eight tools were live-listed pre-auth as `refero.refero.refero_{search_styles,search_screens,get_style,get_similar_screens,get_screen_image,get_screen,search_flows,get_flow}`, resolving the research record's conflicting derivations — the single-prefix derivation is dead. Discovery is pre-auth; authenticated CALLS remain operator-gated. The per-session `tool_info` confirmation step is still not optional. If discovery shows the eight tools missing, renamed, or expanded, **fail closed**: report the drift; a changed provider surface requires a reviewed packet update, not an improvised call.

### The 8-tool surface (three layers)

The expected contract (authoritative docs baseline; `tool_info` is the final live schema). Full args, bounds, and result shapes: [`references/tool-surface.md`](references/tool-surface.md).

| Layer | Tool | Required args | Notes |
|---|---|---|---|
| Styles | `refero_search_styles` | `query` | `page` (default 1) pagination |
| Styles | `refero_get_style` | exactly one of `style_id` \| `style_ids[]` | Full styles are ~10-15k chars each; batch 3-4 |
| Screens | `refero_search_screens` | `query`, `platform: "web"\|"ios"` | Returns UUID records with `site`, `ux_patterns`, `ui_elements` |
| Screens | `refero_get_screen` | exactly one of `screen_id` \| `screen_ids[]` | Never pass `image_size` or `include_similar` here |
| Screens | `refero_get_similar_screens` | `screen_id` | `limit` 1-20, default 10 (the only tool with `limit`) |
| Screens | `refero_get_screen_image` | `screen_id` | `image_size: "thumbnail"\|"full"` (default thumbnail); returns raw image |
| Flows | `refero_search_flows` | `query`, `platform: "web"\|"ios"` | Returns **numeric** flow IDs |
| Flows | `refero_get_flow` | exactly one of `flow_id` \| `flow_ids[]` (numbers) | Ordered steps: goal, action, system response |

Hard constraints: styles and screens use **UUID strings**, flows use **numeric IDs**; the two are not interchangeable. Search pagination uses `page`, never legacy `limit`/`offset`. There are **no** `search_apps`/`get_app`/`search_elements`/`get_element` tools; apps and elements are query facets, inspected through `site` and `ui_elements` in results. `response_format` is documented on the **seven text-returning tools** and must **never** be passed to `refero_get_screen_image`; treat per-tool availability as a `tool_info` runtime check. Preserve unknown response fields; the provider documents that fields can grow.

### Calling through Code Mode

Call **synchronously inside the `call_tool_chain` body** (no top-level `await`), per the live-verified pattern:

```typescript
call_tool_chain({
  code: `
    const styles = refero.refero_refero_search_styles({
      query: "editorial monochrome saas landing page",
      response_format: "json"
    });
    const list = styles.records || [];   // { pagination, records } shape
    const full = refero.refero_refero_get_style({ style_id: list[0].uuid, response_format: "json" });
    return { count: list.length, first: list[0]?.url, full };
  `
});
```

Cite evidence by `record.url` (styles) or `record.refero_url` (screens). JSON searches return `{ pagination: { count, page, next_page, total_cou

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [MichelKerkmeester](https://github.com/MichelKerkmeester)
- **Source:** [MichelKerkmeester/skilled-harness__spec-driven-agent-loops](https://github.com/MichelKerkmeester/skilled-harness__spec-driven-agent-loops)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** yes
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-michelkerkmeester-skilled-harness-spec-driven-agent-loops-mcp-refero
- Seller: https://agentstack.voostack.com/s/michelkerkmeester
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.