Refero (mcp-refero)
Search Refero's library of real shipped UI. The official repo reports 150,000+ app screens and 6,000+ user flows.
An agent can use the Refero MCP via Code Mode to find styles for visual direction, screens for concrete UI patterns and 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. The packet is never the taste authority.
Pair any design-affecting use with sk-design-md-generator for a measured Style Reference (extracted design tokens). Deep operational detail lives in references/tool-surface.md and references/mcp-wiring.md.
Naming trap (read first). Refero tools inside call_tool_chain use a DOUBLED prefix. Their callable form is refero.refero_refero_<tool>(...), for example refero.refero_refero_search_styles.
Code Mode's {manual}.{manual}_{tool} rule applies because these tools' names already begin with refero_.
CONFIRMED by live discovery 2026-07-16 (references/discovery-fixture-2026-07-16.json). Pre-auth list_tools returned all eight registry names in the dotted doubled form refero.refero.refero_<tool>. Discovery needed no OAuth.
The fixture's Access as: line shows the TypeScript callable refero.refero_refero_search_styles(args).
Per-session tool_info re-confirmation stays mandatory. Confirm, then call. 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", "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 (the sibling Mobbin 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
mcp-tooling routes a Refero design-reference request here when the request names Refero, or asks for real shipped app screens, user journeys, or a UI reference search.
The hub's mcp-refero mode signal selects this packet, and generic design, UI or screen wording does not.
A scored route loads the documents its intent maps to. references/tool-surface.md is the default resource: the three research routes load it, and a zero-score route offers it as a suggestion.
Read ROUTER.md before selecting skill-local resources; open only the matched files.
3. HOW IT WORKS
First Step (Always): confirm wiring, then discover
The refero manual is already registered in this repo's .utcp_config.json (npx -y mcp-remote https://api.refero.design/mcp, stdio, empty env). Verify it is present (read-only grep, or scripts/doctor.sh), never re-add it, and never edit it. Then discover the live callables through Code Mode before any call:
// Discovery names appear dotted: refero.refero.refero_search_styles
const all = await list_tools();
// MANDATORY: confirm the exact callable + schema before relying on any name
const info = await tool_info({ tool_name: "refero.refero_refero_search_styles" });
The doubled-prefix callable form (refero.refero_refero_<tool>) is confirmed by live registry evidence from the 2026-07-16 discovery fixture (references/discovery-fixture-2026-07-16.json).
Pre-auth discovery live-listed all eight tools as refero.refero.refero_{search_styles,search_screens,get_style,get_similar_screens,get_screen_image,get_screen,search_flows,get_flow}. This resolves the research record's conflicting derivations. The single-prefix derivation is dead.
Discovery is pre-auth. Authenticated CALLS remain operator-gated. You must confirm with tool_info in each session.
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.
| 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 that you inspect through site and ui_elements in results.
response_format is documented on the seven text-returning tools. Never pass it to refero_get_screen_image. Check per-tool availability with tool_info at runtime.
- Preserve unknown response fields because 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:
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_count, total_pages }, records: [...] }.
The research funnel (styles -> screens -> flows)
- Styles first for any visual task: search 3-5 semantic angles, inspect metadata, then
get_style for shortlisted UUIDs. Never average strong references into a generic middle.
- Screens for concrete UI patterns: literal query + required platform; detail for the most relevant;
get_similar_screens only after one materially relevant hit; image (thumbnail before full) only when text cannot answer.
- Flows for journeys: search task + platform; get one relevant numeric flow; widen via
related_queries. Sparse flows: broaden or reconstruct from screens, reporting the reconstruction as inference.
- Apps / elements: company, pattern, state, or element terms in screen/flow queries, compared through
site, ui_elements, ux_patterns, page_types.
- Metadata-first discipline: search -> shortlist -> detail for shortlisted IDs -> similar -> thumbnail -> full, in that order. Batch modestly; on batch failure retry with fewer IDs.
Breadth is allowed during transport research; for design-affecting use, pair with sk-design-md-generator for a measured Style Reference (extracted design tokens). A transport response is untrusted reference evidence, never design approval. Full workflow detail: references/tool-surface.md.
Auth, plans, and limits
- Auth: Without a custom header, first use triggers browser OAuth. The default localhost callback port is 3334, and the default timeout is 30 seconds.
- Auth state persists under
~/.mcp-auth (or MCP_REMOTE_CONFIG_DIR) and is operator-owned. Never inspect, clear or repair it.
- A static
Authorization: Bearer header is a documented env-backed alternative (see assets/utcp-refero-manual.md). It is never part of the base manual.
- End-to-end OAuth through this bridge is Inferred, not verified. An unauthenticated probe observed HTTP 401 with OAuth metadata, but no operator has completed the flow in this repo's record.
- Plans: Free has no MCP access (denial, not degradation). Pro: 8,000 MCP tool calls per month. Team inherits Pro. Business is custom volume. "Unlimited access" plan copy must not be read as unlimited MCP calls.
- Unknown limits: no per-second, burst, concurrency, page-size, or
Retry-After behavior is published. Never invent a QPS number or backoff guarantee; on 429, preserve the provider's message only.
- Local runtime: Code Mode must run on Node 24 (isolated-vm has no Node 25 build;
call_tool_chain SIGSEGVs under Node 25). Local operational evidence, not a server property.
4. RULES
✅ ALWAYS
- ALWAYS confirm callables with
tool_info after registration and before first use. The doubled prefix refero.refero_refero_<tool> is live-verified but must be re-confirmed; fail closed on any drift from the eight documented tools.
- ALWAYS pair with
sk-design-md-generator for a measured Style Reference on any design-affecting request. This packet is the transport; sk-design-md-generator is the cross-hub pairing that extracts a live site's real CSS into named design tokens (a Style Reference DESIGN.md). Transport output can never satisfy taste, accessibility, responsiveness, or readiness gates by itself.
- ALWAYS validate documented unions, enums, and bounds before calling: exactly-one-of ID unions, UUID vs numeric ID typing, the
platform enum, page >= 1, similar-screens limit 1-20, and the image-size enum. Pass unknown response fields through untouched.
- ALWAYS follow the metadata-first funnel: search and shortlist on metadata, fetch detail only for shortlisted IDs, similar screens only after one relevant hit, images last (
thumbnail before full).
- ALWAYS call synchronously inside the
call_tool_chain body (no top-level await) and cite results by their source URL (url / refero_url).
- ALWAYS treat this packet as read-only against this repo (
mutatesWorkspace: false). Reads and writes happen against the external Refero service only; Write, Edit, and Task are forbidden tools for this transport.
⛔ NEVER
- NEVER use Write, Edit, or Task through this packet. It is a TRANSPORT: it retrieves external evidence and changes nothing in this workspace. Hand file changes to the owning workflow skill.
- NEVER edit
.utcp_config.json's refero manual. It is validated as-is (verify, do not re-add, do not modify), and never add a second Refero manual or a Bearer token to the base manual.
- NEVER claim OAuth works end-to-end. It is Inferred pending an operator-completed authorization; report it as such. Never inspect, clear, or repair
~/.mcp-auth / MCP_REMOTE_CONFIG_DIR, and never accept, print, or cache credentials.
- NEVER invent rate limits, page sizes, retry contracts, or backoff numbers. Only the monthly Pro quota (8,000 calls) is published; on 429, relay the provider's own message.
- NEVER pass
response_format to refero_get_screen_image, and never use the deprecated legacy surface: _tool-suffixed names, get_design_guidance, numeric screen IDs, limit/offset search pagination, or image_size/include_similar on refero_get_screen.
- NEVER treat search rank or similarity as a taste verdict, never average strong references into a generic middle, and never copy or cache third-party reference content into this repo.
- NEVER model Free-plan access as a reduced tool set. Free has no MCP access at all; report the entitlement denial and stop.
⚠️ ESCALATE IF
- ESCALATE IF authentication is required (HTTP 401, OAuth prompt, token needs). Completing browser OAuth or obtaining a Bearer token is operator-only; surface the step and wait.
- ESCALATE IF discovery shows catalog drift: a documented tool missing or renamed, unexpected new tools, or schemas that contradict
references/tool-surface.md. A provider-surface change requires a reviewed packet update.
- ESCALATE IF the account is Free-tier or quota-limited (entitlement denial, 429, or quota exhaustion), reporting the provider's message verbatim.
- ESCALATE IF
call_tool_chain drops the connection (-32000 Connection closed), which locally indicates a Node 25 runtime; the Node 24 pin is an operator-side fix.
- ESCALATE IF retrieved evidence conflicts with a
sk-design-md-generator Style Reference (its extracted design tokens), asking which source prevails before any design conclusion is drawn.
5. REFERENCES
Core References
- tool-surface.md - The 8-tool contract: arguments, bounds, ID typing, result shapes, the research funnel, plan gating, and the deprecated-surface negative knowledge.
- mcp-wiring.md - The registered
refero manual, the mcp-remote bridge (transport strategy, OAuth, auth state), the doubled-prefix naming rule, and the discovery-first contract.
- troubleshooting.md - Failure modes and fixes (401, tools not resolving, Node 25 SIGSEGV, sparse flows, quota, batch failures).
Templates and Assets
- utcp-refero-manual.md - The verified
.utcp_config.json manual snapshot (already registered: verify, do not re-add) plus the env-backed Bearer-header alternative, marked alternative-only.
Reference Loading Notes
tool-surface.md is the baseline (always). Load mcp-wiring.md and the manual asset for wiring/auth intent, troubleshooting.md for errors.
- Keep the SMART ROUTING summary and
ROUTER.md as the single routing authority.
6. SUCCESS CRITERIA
Wiring verification complete when:
- ✅ The
refero manual was confirmed present in .utcp_config.json read-only (no edit, no re-add), and discovery (list_tools / tool_info) confirmed the doubled-prefix callables, or the auth/entitlement blocker was escalated to the operator.
Retrieval complete when:
- ✅ The funnel order was followed (search -> metadata shortlist -> detail -> similar -> image last), IDs matched their documented typing, results were cited by source URL, and unknown fields were preserved.
Design-affecting use complete when:
- ✅
sk-design-md-generator was paired for a measured Style Reference, the transport supplied only requested evidence, and no taste, accessibility, or readiness verdict was issued from transport output.
Always:
- ✅ No workspace file changed, no credential was printed or cached, no auth state was touched, no unpublished limit was invented, and every capability claim stayed within the documented or live-confirmed record.
7. INTEGRATION POINTS
Tool Usage Guidelines
- Code Mode (
mcp__code_mode__call_tool_chain) owns every Refero call, including discovery (list_tools, search_tools, tool_info).
- Read/Grep/Glob load references and verify the manual's presence in
.utcp_config.json read-only.
- Bash runs only the read-only helpers:
scripts/doctor.sh diagnostics and the verify-only scripts/install.sh posture check. This transport has no other shell role (Code Mode owns the stdio process launch, so the packet never runs npx itself).
Cross-Workflow Contracts
sk-design-md-generator is the cross-hub design pairing: it extracts a live website's real CSS into a measured Style Reference DESIGN.md (named design tokens, type scale, components). This packet retrieves only requested shipped-UI evidence and returns it to that measured-extraction pairing.
mcp-code-mode is the substrate: manuals, {manual}.{manual}_{tool} naming, prefixed env vars (refero_<NAME> if a token is ever wired via env), discovery, and the error-envelope discipline all come from it.
mcp-figma is the sibling Figma transport in this hub; mcp-mobbin is the sibling transport for Mobbin research. Neither overlaps this packet's Refero surface.
External Tools
- Refero MCP (
https://api.refero.design/mcp): the external, paid, read-only design-reference service. Requires a Pro (or higher) plan and authentication; not vendored, not mirrored.
- mcp-remote (npm, intentionally unpinned in the manual; version 0.1.38 at research time, self-described experimental): the stdio-to-HTTP bridge Code Mode launches via
npx. HTTP-first transport strategy; do not force SSE.
Knowledge Base Dependencies
Required: references/tool-surface.md (tool contract baseline). Conditional: mcp-wiring.md + assets/utcp-refero-manual.md (wiring/auth), troubleshooting.md (errors).
8. QUICK REFERENCE
| Item |
Value |
| Endpoint |
https://api.refero.design/mcp (remote HTTP; bridged by npx -y mcp-remote) |
| Manual |
refero in .utcp_config.json (already registered; verify, never edit) |
| Callable form |
refero.refero_refero_<tool>(...) (doubled prefix — confirmed by 2026-07-16 discovery fixture; registry names are dotted refero.refero.refero_<tool>; re-confirm via tool_info per session) |
| Layers |
Styles (2 tools) · Screens (4 tools) · Flows (2 tools) |
| ID typing |
Styles/screens: UUID strings · Flows: numeric IDs |
response_format |
Seven text tools only; never on refero_get_screen_image |
| Funnel |
styles -> screens -> flows; metadata first; image last (thumbnail before full) |
| Style batches |
3-4 UUIDs per get_style (each ~10-15k chars) |
| Plans |
Free: NO MCP · Pro: 8,000 calls/month · Team: inherits Pro · Business: custom |
| Unknowns |
Per-second/burst/concurrency/429 behavior unpublished; OAuth end-to-end Inferred |
| Local runtime |
Code Mode on Node 24 (Node 25 SIGSEGVs); synchronous calls, no top-level await |
| Design pairing |
sk-design-md-generator, for a measured Style Reference (extracted design tokens) |
9. REFERENCES AND RELATED RESOURCES
The router (ROUTER.md) discovers reference and asset docs dynamically. Start from references/tool-surface.md for the tool contract and workflows, references/mcp-wiring.md for the bridge and auth model, and references/troubleshooting.md for failures.
Assets: assets/utcp-refero-manual.md (the verified, already-registered manual snapshot plus the Bearer alternative), loaded for wiring/auth intent.
Scripts: scripts/doctor.sh (read-only, non-interactive diagnostics; optional endpoint probe gated behind REFERO_DOCTOR_LIVE=1) and scripts/install.sh (verify-only posture check: runtime prerequisites, manual presence read-only, operator-only auth boundaries; nothing is installed or modified).
Examples: examples/ carries worked Code Mode walkthroughs (the full styles -> screens -> flows funnel, a metadata-first lookup, and a screen-image fetch), each opening with the mandatory tool_info confirmation and marking OAuth-gated steps SKIP-valid.
Related skills: sk-design-md-generator (the measured Style Reference pairing — extracted design tokens), mcp-code-mode (the substrate), mcp-figma (the sibling Figma transport), mcp-chrome-devtools (browser preview only), sk-code (adapting evidence into an app), and system-spec-kit when packet documentation or memory continuity applies.
Install guide: INSTALL-GUIDE.md.
Upstream: the Refero MCP is the paid service at refero.design/mcp (docs at doc.refero.design). The official referodesign/refero_skill repository (MIT, default branch master) is a design methodology skill and a peer of sk-design-md-generator; this packet deliberately does not vendor or duplicate it.
1---2name: mcp-refero3description: "Refero MCP transport: read-only UI reference search via Code Mode, paired with sk-design-md-generator for a Style Reference."4compatibility: Requires a Refero Pro plan (Free has no MCP access), the npx mcp-remote bridge, and Node.js >=18; this project's Code Mode currently runs on Node 24.5allowed-tools: [Read, Bash, Grep, Glob, mcp__code_mode__call_tool_chain]6version: 1.1.8.07user-invocable: true8metadata:9 source: https://skillmd.com/skills/michelkerkmeester/mcp-refero10---1112# Refero (mcp-refero)1314Search **Refero's library of real shipped UI**. The official repo reports 150,000+ app screens and 6,000+ user flows.15An agent can use the **Refero MCP via Code Mode** to find styles for visual direction, screens for concrete UI patterns and flows for multi-step journeys.16This packet is a read-only TRANSPORT (`packetKind: transport`, `mutatesWorkspace: false`). Every read and "write" happens against the external Refero service, never this repo. The packet is **never the taste authority**.17Pair any design-affecting use 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).1819> **Naming trap (read first).** Refero tools inside `call_tool_chain` use a **DOUBLED prefix**. Their callable form is `refero.refero_refero_<tool>(...)`, for example `refero.refero_refero_search_styles`.20> Code Mode's `{manual}.{manual}_{tool}` rule applies because these tools' names already begin with `refero_`.21> **CONFIRMED by live discovery 2026-07-16** (`references/discovery-fixture-2026-07-16.json`). Pre-auth `list_tools` returned all eight registry names in the dotted doubled form `refero.refero.refero_<tool>`. Discovery needed no OAuth.22> The fixture's `Access as:` line shows the TypeScript callable `refero.refero_refero_search_styles(args)`.23> Per-session `tool_info` re-confirmation stays mandatory. Confirm, then call. Fail closed on drift.24>25> **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.2627---2829## 1. WHEN TO USE3031### Activation Triggers3233**Use when** the user wants to:34- Search Refero for design references: visual styles, real app screens, or user flows.35- Find real-app screen examples for a UI pattern, state, or component ("show me real onboarding screens", "empty-state examples from shipped apps").36- Pull the full detail of a shortlisted style, screen, or flow (metadata, tokens, step goals, screenshots) as evidence for a design decision.37- Research a company's or domain's shipped UI through screen or flow queries and `site` metadata.38- Wire, verify, or troubleshoot the `refero` Code Mode manual, its OAuth or Bearer authentication, or its plan gating.3940**Keyword Triggers**: "refero", "refero mcp", "ui reference search", "real app screens", "refero styles", "refero flows", "search refero".4142### Use Cases4344**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.4546**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.4748**Flows research (read-only).** Search task journeys, fetch one relevant numeric flow, and use its ordered step goals, actions, and system responses.4950**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.5152### When NOT to Use5354**Skip this skill when:**55- 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.56- The task is app or screen research through Mobbin. That is `mcp-mobbin` (the sibling Mobbin transport, not this packet).57- The task is browser automation, live-page inspection, or visual preview of a built page. That is `mcp-chrome-devtools`.58- The work is generic app coding with no design-reference input: use `sk-code`.59- 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.6061---6263## 2. SMART ROUTING6465`mcp-tooling` routes a Refero design-reference request here when the request names Refero, or asks for real shipped app screens, user journeys, or a UI reference search.66The hub's `mcp-refero` mode signal selects this packet, and generic design, UI or screen wording does not.6768A scored route loads the documents its intent maps to. `references/tool-surface.md` is the default resource: the three research routes load it, and a zero-score route offers it as a suggestion.6970Read [`ROUTER.md`](./ROUTER.md) before selecting skill-local resources; open only the matched files.7172---7374## 3. HOW IT WORKS7576### First Step (Always): confirm wiring, then discover7778The `refero` manual is **already registered** in this repo's `.utcp_config.json` (`npx -y mcp-remote https://api.refero.design/mcp`, stdio, empty env). Verify it is present (read-only grep, or `scripts/doctor.sh`), never re-add it, and never edit it. Then discover the live callables through Code Mode before any call:7980```typescript81// Discovery names appear dotted: refero.refero.refero_search_styles82const all = await list_tools();83// MANDATORY: confirm the exact callable + schema before relying on any name84const info = await tool_info({ tool_name: "refero.refero_refero_search_styles" });85```8687The doubled-prefix callable form (`refero.refero_refero_<tool>`) is **confirmed by live registry evidence** from the 2026-07-16 discovery fixture (`references/discovery-fixture-2026-07-16.json`).88Pre-auth discovery live-listed all eight tools as `refero.refero.refero_{search_styles,search_screens,get_style,get_similar_screens,get_screen_image,get_screen,search_flows,get_flow}`. This resolves the research record's conflicting derivations. The single-prefix derivation is dead.89Discovery is pre-auth. Authenticated CALLS remain operator-gated. You must confirm with `tool_info` in each session.90If 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.9192### The 8-tool surface (three layers)9394The 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).9596| Layer | Tool | Required args | Notes |97|---|---|---|---|98| Styles | `refero_search_styles` | `query` | `page` (default 1) pagination |99| Styles | `refero_get_style` | exactly one of `style_id` \| `style_ids[]` | Full styles are ~10-15k chars each; batch 3-4 |100| Screens | `refero_search_screens` | `query`, `platform: "web"\|"ios"` | Returns UUID records with `site`, `ux_patterns`, `ui_elements` |101| Screens | `refero_get_screen` | exactly one of `screen_id` \| `screen_ids[]` | Never pass `image_size` or `include_similar` here |102| Screens | `refero_get_similar_screens` | `screen_id` | `limit` 1-20, default 10 (the only tool with `limit`) |103| Screens | `refero_get_screen_image` | `screen_id` | `image_size: "thumbnail"\|"full"` (default thumbnail); returns raw image |104| Flows | `refero_search_flows` | `query`, `platform: "web"\|"ios"` | Returns **numeric** flow IDs |105| Flows | `refero_get_flow` | exactly one of `flow_id` \| `flow_ids[]` (numbers) | Ordered steps: goal, action, system response |106107Hard constraints:108- Styles and screens use **UUID strings**. Flows use **numeric IDs**. The two are not interchangeable.109- Search pagination uses `page`, never legacy `limit`/`offset`.110- There are **no** `search_apps`/`get_app`/`search_elements`/`get_element` tools. Apps and elements are query facets that you inspect through `site` and `ui_elements` in results.111- `response_format` is documented on the **seven text-returning tools**. Never pass it to `refero_get_screen_image`. Check per-tool availability with `tool_info` at runtime.112- Preserve unknown response fields because the provider documents that fields can grow.113114### Calling through Code Mode115116Call **synchronously inside the `call_tool_chain` body** (no top-level `await`), per the live-verified pattern:117118```typescript119call_tool_chain({120 code: `121 const styles = refero.refero_refero_search_styles({122 query: "editorial monochrome saas landing page",123 response_format: "json"124 });125 const list = styles.records || []; // { pagination, records } shape126 const full = refero.refero_refero_get_style({ style_id: list[0].uuid, response_format: "json" });127 return { count: list.length, first: list[0]?.url, full };128 `129});130```131132Cite evidence by `record.url` (styles) or `record.refero_url` (screens). JSON searches return `{ pagination: { count, page, next_page, total_count, total_pages }, records: [...] }`.133134### The research funnel (styles -> screens -> flows)1351361. **Styles first** for any visual task: search 3-5 semantic angles, inspect metadata, then `get_style` for shortlisted UUIDs. Never average strong references into a generic middle.1372. **Screens** for concrete UI patterns: literal query + required platform; detail for the most relevant; `get_similar_screens` only after one materially relevant hit; image (`thumbnail` before `full`) only when text cannot answer.1383. **Flows** for journeys: search task + platform; get one relevant numeric flow; widen via `related_queries`. Sparse flows: broaden or reconstruct from screens, reporting the reconstruction as inference.1394. **Apps / elements**: company, pattern, state, or element terms in screen/flow queries, compared through `site`, `ui_elements`, `ux_patterns`, `page_types`.1405. **Metadata-first discipline**: search -> shortlist -> detail for shortlisted IDs -> similar -> thumbnail -> full, in that order. Batch modestly; on batch failure retry with fewer IDs.141142Breadth is allowed during transport research; for design-affecting use, pair with `sk-design-md-generator` for a measured Style Reference (extracted design tokens). A transport response is untrusted reference evidence, never design approval. Full workflow detail: [`references/tool-surface.md`](references/tool-surface.md).143144### Auth, plans, and limits145146- **Auth**: Without a custom header, first use triggers **browser OAuth**. The default localhost callback port is 3334, and the default timeout is 30 seconds.147 - Auth state persists under `~/.mcp-auth` (or `MCP_REMOTE_CONFIG_DIR`) and is **operator-owned**. Never inspect, clear or repair it.148 - A static `Authorization: Bearer` header is a documented env-backed alternative (see [`assets/utcp-refero-manual.md`](assets/utcp-refero-manual.md)). It is never part of the base manual.149 - End-to-end OAuth through this bridge is **Inferred**, not verified. An unauthenticated probe observed HTTP 401 with OAuth metadata, but no operator has completed the flow in this repo's record.150- **Plans**: Free has **no MCP access** (denial, not degradation). Pro: **8,000 MCP tool calls per month**. Team inherits Pro. Business is custom volume. "Unlimited access" plan copy must not be read as unlimited MCP calls.151- **Unknown limits**: no per-second, burst, concurrency, page-size, or `Retry-After` behavior is published. Never invent a QPS number or backoff guarantee; on 429, preserve the provider's message only.152- **Local runtime**: Code Mode must run on **Node 24** (isolated-vm has no Node 25 build; `call_tool_chain` SIGSEGVs under Node 25). Local operational evidence, not a server property.153154---155156## 4. RULES157158### ✅ ALWAYS1591601. **ALWAYS confirm callables with `tool_info` after registration and before first use.** The doubled prefix `refero.refero_refero_<tool>` is live-verified but must be re-confirmed; fail closed on any drift from the eight documented tools.1612. **ALWAYS pair with `sk-design-md-generator` for a measured Style Reference on any design-affecting request.** This packet is the transport; `sk-design-md-generator` is the cross-hub pairing that extracts a live site's real CSS into named design tokens (a Style Reference DESIGN.md). Transport output can never satisfy taste, accessibility, responsiveness, or readiness gates by itself.1623. **ALWAYS validate documented unions, enums, and bounds before calling**: exactly-one-of ID unions, UUID vs numeric ID typing, the `platform` enum, `page >= 1`, similar-screens `limit` 1-20, and the image-size enum. Pass unknown response fields through untouched.1634. **ALWAYS follow the metadata-first funnel**: search and shortlist on metadata, fetch detail only for shortlisted IDs, similar screens only after one relevant hit, images last (`thumbnail` before `full`).1645. **ALWAYS call synchronously inside the `call_tool_chain` body** (no top-level `await`) and cite results by their source URL (`url` / `refero_url`).1656. **ALWAYS treat this packet as read-only against this repo** (`mutatesWorkspace: false`). Reads and writes happen against the external Refero service only; Write, Edit, and Task are forbidden tools for this transport.166167### ⛔ NEVER1681691. **NEVER use Write, Edit, or Task through this packet.** It is a TRANSPORT: it retrieves external evidence and changes nothing in this workspace. Hand file changes to the owning workflow skill.1702. **NEVER edit `.utcp_config.json`'s `refero` manual.** It is validated as-is (verify, do not re-add, do not modify), and never add a second Refero manual or a Bearer token to the base manual.1713. **NEVER claim OAuth works end-to-end.** It is **Inferred** pending an operator-completed authorization; report it as such. Never inspect, clear, or repair `~/.mcp-auth` / `MCP_REMOTE_CONFIG_DIR`, and never accept, print, or cache credentials.1724. **NEVER invent rate limits, page sizes, retry contracts, or backoff numbers.** Only the monthly Pro quota (8,000 calls) is published; on 429, relay the provider's own message.1735. **NEVER pass `response_format` to `refero_get_screen_image`**, and never use the deprecated legacy surface: `_tool`-suffixed names, `get_design_guidance`, numeric screen IDs, `limit`/`offset` search pagination, or `image_size`/`include_similar` on `refero_get_screen`.1746. **NEVER treat search rank or similarity as a taste verdict**, never average strong references into a generic middle, and never copy or cache third-party reference content into this repo.1757. **NEVER model Free-plan access as a reduced tool set.** Free has no MCP access at all; report the entitlement denial and stop.176177### ⚠️ ESCALATE IF1781791. **ESCALATE IF authentication is required** (HTTP 401, OAuth prompt, token needs). Completing browser OAuth or obtaining a Bearer token is **operator-only**; surface the step and wait.1802. **ESCALATE IF discovery shows catalog drift**: a documented tool missing or renamed, unexpected new tools, or schemas that contradict [`references/tool-surface.md`](references/tool-surface.md). A provider-surface change requires a reviewed packet update.1813. **ESCALATE IF the account is Free-tier or quota-limited** (entitlement denial, 429, or quota exhaustion), reporting the provider's message verbatim.1824. **ESCALATE IF `call_tool_chain` drops the connection** (`-32000 Connection closed`), which locally indicates a Node 25 runtime; the Node 24 pin is an operator-side fix.1835. **ESCALATE IF retrieved evidence conflicts with a `sk-design-md-generator` Style Reference (its extracted design tokens)**, asking which source prevails before any design conclusion is drawn.184185---186187## 5. REFERENCES188189### Core References190191- [tool-surface.md](references/tool-surface.md) - The 8-tool contract: arguments, bounds, ID typing, result shapes, the research funnel, plan gating, and the deprecated-surface negative knowledge.192- [mcp-wiring.md](references/mcp-wiring.md) - The registered `refero` manual, the mcp-remote bridge (transport strategy, OAuth, auth state), the doubled-prefix naming rule, and the discovery-first contract.193- [troubleshooting.md](references/troubleshooting.md) - Failure modes and fixes (401, tools not resolving, Node 25 SIGSEGV, sparse flows, quota, batch failures).194195### Templates and Assets196197- [utcp-refero-manual.md](assets/utcp-refero-manual.md) - The verified `.utcp_config.json` manual snapshot (already registered: verify, do not re-add) plus the env-backed Bearer-header alternative, marked alternative-only.198199### Reference Loading Notes200201- `tool-surface.md` is the baseline (always). Load `mcp-wiring.md` and the manual asset for wiring/auth intent, `troubleshooting.md` for errors.202- Keep the SMART ROUTING summary and `ROUTER.md` as the single routing authority.203204---205206## 6. SUCCESS CRITERIA207208**Wiring verification complete when:**209- ✅ The `refero` manual was confirmed present in `.utcp_config.json` read-only (no edit, no re-add), and discovery (`list_tools` / `tool_info`) confirmed the doubled-prefix callables, or the auth/entitlement blocker was escalated to the operator.210211**Retrieval complete when:**212- ✅ The funnel order was followed (search -> metadata shortlist -> detail -> similar -> image last), IDs matched their documented typing, results were cited by source URL, and unknown fields were preserved.213214**Design-affecting use complete when:**215- ✅ `sk-design-md-generator` was paired for a measured Style Reference, the transport supplied only requested evidence, and no taste, accessibility, or readiness verdict was issued from transport output.216217**Always:**218- ✅ No workspace file changed, no credential was printed or cached, no auth state was touched, no unpublished limit was invented, and every capability claim stayed within the documented or live-confirmed record.219220---221222## 7. INTEGRATION POINTS223224### Tool Usage Guidelines225226- **Code Mode** (`mcp__code_mode__call_tool_chain`) owns every Refero call, including discovery (`list_tools`, `search_tools`, `tool_info`).227- **Read/Grep/Glob** load references and verify the manual's presence in `.utcp_config.json` read-only.228- **Bash** runs only the read-only helpers: `scripts/doctor.sh` diagnostics and the verify-only `scripts/install.sh` posture check. This transport has no other shell role (Code Mode owns the stdio process launch, so the packet never runs `npx` itself).229230### Cross-Workflow Contracts231232- **`sk-design-md-generator`** is the cross-hub design pairing: it extracts a live website's real CSS into a measured Style Reference DESIGN.md (named design tokens, type scale, components). This packet retrieves only requested shipped-UI evidence and returns it to that measured-extraction pairing.233- **`mcp-code-mode`** is the substrate: manuals, `{manual}.{manual}_{tool}` naming, prefixed env vars (`refero_<NAME>` if a token is ever wired via env), discovery, and the error-envelope discipline all come from it.234- **`mcp-figma`** is the sibling Figma transport in this hub; **`mcp-mobbin`** is the sibling transport for Mobbin research. Neither overlaps this packet's Refero surface.235236### External Tools237238- **Refero MCP** (`https://api.refero.design/mcp`): the external, paid, read-only design-reference service. Requires a Pro (or higher) plan and authentication; not vendored, not mirrored.239- **mcp-remote** (npm, intentionally unpinned in the manual; version 0.1.38 at research time, self-described experimental): the stdio-to-HTTP bridge Code Mode launches via `npx`. HTTP-first transport strategy; do not force SSE.240241### Knowledge Base Dependencies242243**Required**: `references/tool-surface.md` (tool contract baseline). **Conditional**: `mcp-wiring.md` + `assets/utcp-refero-manual.md` (wiring/auth), `troubleshooting.md` (errors).244245---246247## 8. QUICK REFERENCE248249| Item | Value |250|---|---|251| Endpoint | `https://api.refero.design/mcp` (remote HTTP; bridged by `npx -y mcp-remote`) |252| Manual | `refero` in `.utcp_config.json` (already registered; verify, never edit) |253| Callable form | `refero.refero_refero_<tool>(...)` (doubled prefix — confirmed by 2026-07-16 discovery fixture; registry names are dotted `refero.refero.refero_<tool>`; re-confirm via `tool_info` per session) |254| Layers | Styles (2 tools) · Screens (4 tools) · Flows (2 tools) |255| ID typing | Styles/screens: UUID strings · Flows: numeric IDs |256| `response_format` | Seven text tools only; never on `refero_get_screen_image` |257| Funnel | styles -> screens -> flows; metadata first; image last (`thumbnail` before `full`) |258| Style batches | 3-4 UUIDs per `get_style` (each ~10-15k chars) |259| Plans | Free: NO MCP · Pro: 8,000 calls/month · Team: inherits Pro · Business: custom |260| Unknowns | Per-second/burst/concurrency/429 behavior unpublished; OAuth end-to-end Inferred |261| Local runtime | Code Mode on Node 24 (Node 25 SIGSEGVs); synchronous calls, no top-level `await` |262| Design pairing | `sk-design-md-generator`, for a measured Style Reference (extracted design tokens) |263264---265266## 9. REFERENCES AND RELATED RESOURCES267268The router (`ROUTER.md`) discovers reference and asset docs dynamically. Start from `references/tool-surface.md` for the tool contract and workflows, `references/mcp-wiring.md` for the bridge and auth model, and `references/troubleshooting.md` for failures.269270Assets: `assets/utcp-refero-manual.md` (the verified, already-registered manual snapshot plus the Bearer alternative), loaded for wiring/auth intent.271272Scripts: `scripts/doctor.sh` (read-only, non-interactive diagnostics; optional endpoint probe gated behind `REFERO_DOCTOR_LIVE=1`) and `scripts/install.sh` (verify-only posture check: runtime prerequisites, manual presence read-only, operator-only auth boundaries; nothing is installed or modified).273274Examples: `examples/` carries worked Code Mode walkthroughs (the full styles -> screens -> flows funnel, a metadata-first lookup, and a screen-image fetch), each opening with the mandatory `tool_info` confirmation and marking OAuth-gated steps SKIP-valid.275276Related skills: `sk-design-md-generator` (the measured Style Reference pairing — extracted design tokens), `mcp-code-mode` (the substrate), `mcp-figma` (the sibling Figma transport), `mcp-chrome-devtools` (browser preview only), `sk-code` (adapting evidence into an app), and `system-spec-kit` when packet documentation or memory continuity applies.277278Install guide: [INSTALL-GUIDE.md](INSTALL-GUIDE.md).279280Upstream: the Refero MCP is the paid service at [refero.design/mcp](https://refero.design/mcp) (docs at doc.refero.design). The official [referodesign/refero_skill](https://github.com/referodesign/refero_skill) repository (MIT, default branch `master`) is a design **methodology** skill and a peer of `sk-design-md-generator`; this packet deliberately does not vendor or duplicate it.281