Mcp Refero

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.

# 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

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.

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.

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, nextpage, totalcou

…

Source & license

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

• Author: MichelKerkmeester
• Source: MichelKerkmeester/skilled-harness_spec-driven-agent-loops
• License: MIT

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