mcp-mobbin

Mobbin (mcp-mobbin)

Search Mobbin's library of real app UI screenshots ("the world's largest library of real app UI screenshots" per the official repo) from an agent through the Mobbin MCP via Code Mode: one documented tool, search_screens, answering app, screen, flow, and element research as query intents. This packet is a read-only TRANSPORT (packetKind: transport, mutatesWorkspace: false): every call goes against the external hosted Mobbin service, never this repo, and it produces no design tokens or Style Reference of its own. When a measured Style Reference of real, extracted design tokens is also wanted, pair with sk-design-md-generator. Deep operational detail lives in references/tool-surface.md and references/mcp-wiring.md.

Discovery status (read first). The mobbin Code Mode manual IS REGISTERED in this repo's .utcp_config.json (registered 2026-07-16 by an operator; this packet never edits the config), and live discovery RAN 2026-07-16, pre-auth (fixture: references/discovery-fixture-2026-07-16.json): list_tools returned THREE read tools — registry names mobbin.mobbin.{search_screens,search_flows,search_sections} (dot-separated), TS callables mobbin.mobbin_search_screens(...) etc. per the fixture's Access as: lines — superseding the research's one-public-tool baseline. Operator browser OAuth is still pending for CALLS. Per-session tool_info re-confirmation stays MANDATORY before relying on any name: confirm, then call, and fail closed on drift.

Access trap. Mobbin MCP access is documented for Pro, Team, and Enterprise — not Free. Authentication is browser OAuth only (DCR + PKCE S256, openid scope): no static API key or auth env var exists for MCP — that question is answered in the negative, not open. Unauthenticated calls return HTTP 401. The service is rate-limited to 60 requests per 60 seconds per user.

1. WHEN TO USE

Activation Triggers

Use when the user wants to:

• Search Mobbin for real-app design references: screens for a UI pattern or state, apps for category comparison, flows for journey steps, or elements for component behavior in context.
• Find screen examples from shipped apps ("show me iOS banking onboarding screens", "web empty-state dashboard examples").
• Research how real products handle a flow or journey through screen evidence ("first-run onboarding progression", "forgot-password recovery").
• Wire, verify, or troubleshoot the registered mobbin Code Mode manual, its OAuth authentication, its plan gating, or its rate limit.

Keyword Triggers: "mobbin", "mobbin mcp", "app design research", "screen examples", "ux flow references", "real app screenshots", "search mobbin".

Use Cases

App research (read-only). Name the app, company, or category plus the comparison goal ("banking apps onboarding identity verification"); compare app_name, platform, structure, and visible patterns across results. Multiple results are evidence, not a design chooser.

Screen research (read-only). Name the concrete screen, state, or job ("iOS subscription cancellation confirmation"); start at 5 results; cite each mobbin_url used.

Flow research (read-only). Describe the journey and target step. The public contract returns screens, not an ordered flow object — reconstruct sequence only when visual evidence supports it, and label the reconstruction as inference.

Element research (read-only). Name component plus context/state ("bottom-sheet destructive confirmation", "inline validation on signup"); analyze element behavior within returned screens.

Wiring and auth verification. Report the manual's registration state honestly (presence is the healthy result; absence is a failure symptom to escalate), explain the OAuth-only model and plan gate, and never repair auth state yourself.

When NOT to Use

Skip this skill when:

• The work is measured design-reference extraction: turning a live website's real CSS into a Style Reference DESIGN.md of named design tokens (type scale, components, Quick-Start CSS/Tailwind). That is sk-design-md-generator; this packet only retrieves Mobbin screenshot evidence.
• The task is styles, screens, or flows research through Refero. That is mcp-refero, the sibling transport.
• The task is Figma work (inspect, tokens, render, Code Connect). That is mcp-figma.
• 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 target is Mobbin's documentation search. docs.mobbin.com/mcp is a separate Mintlify docs-search MCP, not the design-reference server; this packet targets api.mobbin.com/mcp only.
• The user asks to change this repo's files, edit the registered .utcp_config.json manual, or repair auth state. This transport forbids Write/Edit/Task, never mutates the workspace, and the registered manual is operator-owned.

2. SMART ROUTING

Primary Detection Signal

Route on narrow Mobbin-specific signals only. Generic "design", "UI", or "screen" phrasing is not a Mobbin signal; measured live-site extraction belongs to sk-design-md-generator, Refero references to mcp-refero, Figma work to mcp-figma, and browser work to mcp-chrome-devtools.

# Signal detection (pseudo)
echo "$REQUEST" | grep -qiE 'mobbin' && ROUTE="MCP_MOBBIN"
echo "$REQUEST" | grep -qiE 'app design research|real app (screenshots|screens)|ux flow reference' && ROUTE="MCP_MOBBIN"
# generic design/UI phrasing WITHOUT these signals -> not this packet (measured extraction -> sk-design-md-generator)

Phase Detection

TASK CONTEXT
    |
    +- STEP 0: Verify wiring state (mobbin manual registered; presence expected — absence is a failure to escalate)
    +- STEP 1: Score intent -> APPS | SCREENS | FLOWS | ELEMENTS | WIRING_AUTH | TROUBLESHOOT
    +- Phase 1: Measured Style Reference also wanted? -> pair sk-design-md-generator (extracted design tokens); retrieval stays here
    +- Phase 2: Discovery (list_tools / tool_info confirms the callable name)   [MANDATORY; needs a fresh Code Mode session]
    +- Phase 3: Retrieval (search_screens with intent-shaped query; limit 5; platform ios|web)
    +- Phase 4: Verify (evidence cited by mobbin_url; failed[] reported; unknowns preserved; no invented tools)

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/<key>/ subdirectories. References are the primary loaded resources; the single asset is the registered manual's reference shape.

references/tool-surface.md      # the one-tool surface, args, response shape, workflows, plan gating
references/mcp-wiring.md        # registered manual, mcp-remote bridge, OAuth/DCR/PKCE, naming, discovery
references/troubleshooting.md   # failure modes + fixes
assets/utcp-mobbin-manual.md    # Registered manual's reference shape + post-registration checklist

Resource Loading Levels

Smart Router Pseudocode

Resilience pattern: see sk-doc smart-router template. 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 = {
    "APPS":         {"keywords": [("app design research", 4), ("app research", 4), ("competitor", 3), ("app comparison", 3), ("banking apps", 2), ("category", 2), ("how do apps", 2), ("real apps", 3)]},
    "SCREENS":      {"keywords": [("screen", 4), ("screen examples", 4), ("ui pattern", 3), ("empty state", 3), ("first open", 3), ("onboarding screen", 3), ("component example", 3), ("screenshot", 3), ("paywall", 2), ("settings", 2), ("dashboard", 2)]},
    "FLOWS":        {"keywords": [("flow", 4), ("ux flow", 4), ("user flow", 4), ("journey", 4), ("start to finish", 3), ("multi-step", 3), ("progression", 2), ("forgot password", 2), ("checkout", 2), ("signup process", 2)]},
    "ELEMENTS":     {"keywords": [("element", 4), ("bottom sheet", 3), ("inline validation", 3), ("component behavior", 3), ("button state", 2), ("tab bar", 2), ("modal", 2), ("confirmation dialog", 2)]},
    "WIRING_AUTH":  {"keywords": [("wiring", 4), ("utcp", 4), ("oauth", 4), ("mcp-remote", 4), ("authenticate", 4), ("pkce", 3), ("manual", 3), ("register", 3), ("token", 3), ("plan", 2), ("install", 2), ("setup", 2)]},
    "TROUBLESHOOT": {"keywords": [("error", 4), ("failed", 4), ("401", 4), ("not working", 4), ("not resolving", 4), ("429", 3), ("rate limit", 3), ("timeout", 3), ("unauthorized", 3), ("denied", 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 six 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 = {
    "APPS":         {"weight": 4, "keywords": ["app design research", "app research", "competitor", "app comparison", "banking apps", "category", "how do apps", "real apps"]},
    "SCREENS":      {"weight": 4, "keywords": ["screen", "screen examples", "ui pattern", "empty state", "first open", "onboarding screen", "component example", "screenshot", "paywall", "settings", "dashboard"]},
    "FLOWS":        {"weight": 4, "keywords": ["flow", "ux flow", "user flow", "journey", "start to finish", "multi-step", "progression", "forgot password", "checkout", "signup process"]},
    "ELEMENTS":     {"weight": 4, "keywords": ["element", "bottom sheet", "inline validation", "component behavior", "button state", "tab bar", "modal", "confirmation dialog"]},
    "WIRING_AUTH":  {"weight": 4, "keywords": ["wiring", "utcp", "oauth", "mcp-remote", "authenticate", "pkce", "manual", "register", "token", "plan", "install", "setup"]},
    "TROUBLESHOOT": {"weight": 4, "keywords": ["error", "failed", "401", "not working", "not resolving", "429", "rate limit", "timeout", "unauthorized", "denied"]},
}

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

UNKNOWN_FALLBACK_CHECKLIST = [
    "Confirm the research intent: apps, screens, flows, or elements (all are query intents over search_screens)",
    "Confirm the mobbin manual's registration state (registered; absence is a failure symptom to escalate, never repair)",
    "Confirm the account has a paid plan (Pro, Team, or Enterprise); Free has no MCP access",
    "If a measured Style Reference of extracted design tokens is also wanted, pair sk-design-md-generator; this transport only retrieves Mobbin screenshot evidence",
]

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) <= AMBIGUITY_DELTA:
        return (primary, secondary, scores)
    return (primary, None, scores)

def route_mobbin_resources(request: str):
    inventory = discover_markdown_resources()
    primary, secondary, scores = classify_intents(request)
    intents = [i for i in (primary, secondary) if i]
    loaded, seen, notices = [], set(), []

    def load_if_available(rel: str) -> 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]) < MIN_CONFIDENCE:
        # Fallback-only: nothing is loaded on a zero-score route; the default
        # reference is offered as a suggestion beside the disambiguation ask.
        return {"intents": intents, "load_level": "UNKNOWN_FALLBACK", "needs_disambiguation": True,
                "disambiguation_checklist": UNKNOWN_FALLBACK_CHECKLIST,
                "suggested_fallback": DEFAULT_RESOURCE, "resources": loaded, "notices": notices}
    for intent in intents:
        for rel in RESOURCE_MAP.get(intent, []):
            load_if_available(rel)
    return {"intents": intents, "intent_scores": scores, "resources": loaded, "notices": notices}

3. HOW IT WORKS

First Step (Always): report the wiring state honestly

The mobbin manual is registered in this repo's .utcp_config.json (registered 2026-07-16 by an operator, never by this packet). scripts/doctor.sh reports the state read-only: manual presence is the healthy result, and absence is now an ERROR (a broken or reverted registration to escalate, never repair). Because manuals load at Code Mode startup and OAuth is still pending, discovery through a fresh Code Mode session is mandatory before any call:

// Live-confirmed dotted discovery names (2026-07-16 fixture):
//   mobbin.mobbin.search_screens · mobbin.mobbin.search_flows · mobbin.mobbin.search_sections
const all = await list_tools();
// MANDATORY per session: confirm the exact callable + schema before relying on any name
const info = await tool_info({ tool_name: "mobbin.mobbin_search_screens" });

Both the dotted discovery names and the callable form are CONFIRMED by live discovery 2026-07-16 (references/discovery-fixture-2026-07-16.json; the convention-derived prediction held exactly). Discovery ran pre-auth — tools/list and schemas needed no OAuth; authenticated CALLS remain operator-gated. If a future discovery shows different names, missing tools, unexpected new tools, or a mutation-capable tool, fail closed: report the drift; a changed provider surface requires a reviewed packet update, not an improvised call.

The live three-tool surface (supersedes the one-tool baseline, 2026-07-16)

The research's one publicly documented tool baseline is superseded: live pre-auth discovery on 2026-07-16 listed three read-only search tools. All three passed the mutation-refusal check (no mutation-capable tool in the listing). Full fixture schemas and the completeness boundary: references/tool-surface.md.

Declared search_screens output (fixture): { query, screens: [{ id, image_url, mobbin_url, app_name, platform }] } — the research-documented index/failed[] fields do not appear in the declared schema; verify the actual response shape on the first authenticated call. The deep conflict is RESOLVED: search mode is a client-settable input on search_screens ("deep" = AI-powered relevance pipeline for nuanced queries; "standard" = low latency; "fast" = deprecated alias for standard). Never invent search_apps, search_elements, or any detail/image-download/mutation tool beyond the discovered inventory.

Calling through Code Mode

Callable-name status. The callable is confirmed by live discovery 2026-07-16 (references/discovery-fixture-2026-07-16.json): registry name mobbin.mobbin.search_screens, TS callable mobbin.mobbin_search_screens(args). The call below quotes the confirmed form; the live RESPONSE behavior is still unexercised (authenticated calls pend operator OAuth), so re-confirm with tool_info per session.

call_tool_chain({
  code: `
    const result = await mobbin.mobbin_search_screens({
      query: "iOS banking app onboarding identity verification",
      platform: "ios",
      limit: 5
    });
    return { success: true, data: result, errors: [], timestamp: new Date().toISOString() };
  `
});

Mandatory discovery-first sequence: list_tools() or search_tools({ task_description: "Mobbin screen design research", limit: 10 }) -> filter to the mobbin manual -> tool_info() on the exact dotted name -> only then call_tool_chain({ code }). Cite every selected reference by its mobbin_url.

Research workflows (query intents over the three live tools)

App, screen, and element research remain intent-specific query designs over search_screens; flow and website-section research now have dedicated live-discovered tools (2026-07-16):

1. App research — name the app/company/category and comparison goal ("banking apps onboarding identity verification"); compare app_name, platform, structure, visible patterns.
2. Screen research — name the concrete screen/state/job ("iOS subscription cancellation confirmation", "web empty-state dashboard"); start at 5 results; cite each mobbin_url used.
3. Flow research — use search_flows: describe one user journey ("onboarding with personalization steps"); it returns ordered flow objects (screens[].position, actions[], screen_count), superseding the old screens-only reconstruction guidance. Label anything beyond the returned ordering as inference.
4. Element research — name component + context/state ("bottom-sheet destructive confirmation", "inline validation on signup"); analyze element behavior within returned screens; never fabricate an element-detail tool.
5. Website-section research — use search_sections: describe one section ("pricing page with plan comparison table"); results carry site_name and section images.

Official skill operating sequence: derive query terms from the user's actual words -> infer ios vs web from app context (unclear -> ask) -> announce a short search plan -> call search_screens in the same turn -> visually inspect returned references (observe content, structure, styling, interaction; compare repeats and meaningful differences; synthesize principles) -> answer from evidence tied to returned screens. The official skill's optional evidence-board writer is excluded from this transport (read-only boundary).

Context discipline: start limit: 5; ask before widening materially (do not exceed ~15 just for variety); report failed[] entries and missing images as partial success, never silently discard; retain mobbin_url as provenance for every selected reference.

Auth, plans, and limits

• Auth: browser OAuth only — protected-resource discovery, Dynamic Client Registration (RFC 7591), authorization-code + PKCE S256, openid scope. No static Mobbin API key exists for MCP; the API-key Bearer model belongs to the separate Team/Enterprise REST API and must never be conflated with MCP. Client access is revocable from Mobbin Account Settings -> MCP. Adapter auth state persists under ~/.mcp-auth (or MCP_REMOTE_CONFIG_DIR) and is operator-owned: never inspect, clear, or repair it. A live unauthenticated probe returned HTTP 401 with a WWW-Authenticate pointer to the protected-resource metadata — a pre-authorization 401 is the expected challenge, not a missing-key error. End-to-end OAuth through the local Code Mode + mcp-remote bridge is Inferred, not verified: no operator has completed the flow in this repo's record.
• Plans: MCP on Pro, Team, and Enterprise; Free is excluded (state "MCP starts at Pro"; the exact Free denial status/payload/UX is UNVERIFIED — do not guess failure semantics). No reviewed source documents different MCP tool sets per paid tier — do not invent per-tool tier gates. Per-plan usage caps within eligible tiers are undocumented; Finance+ is a separate paid add-on whose MCP result coverage is unestablished.
• Rate limit: 60 requests per 60 seconds per user; on 429 honor Retry-After, then exponential backoff with jitter.
• Transport: the provider itself is a hosted remote server over Streamable HTTP at https://api.mobbin.com/mcp — there is no local package to install; the official repo is metadata-only. The local bridge is npx -y mcp-remote over stdio (HTTP-first, SSE fallback only on HTTP 404; experimental, externally versioned; Node 18+ and working npx are prerequisites).

4. RULES

✅ ALWAYS

1. ALWAYS confirm callables with tool_info before first use. The mobbin.mobbin_search_screens form is CONFIRMED by live discovery 2026-07-16 (fixture references/discovery-fixture-2026-07-16.json; registry names are dotted mobbin.mobbin.<tool>). Fail closed on any drift from the live three-tool baseline (search_screens, search_flows, search_sections).
2. ALWAYS route measured-extraction needs to sk-design-md-generator, and pair it when a measured Style Reference is also wanted. This packet is the transport; sk-design-md-generator is its cross-hub measured-extraction companion, turning a live site's real CSS into a Style Reference DESIGN.md of named design tokens. Transport output is Mobbin screenshot evidence and never a design-token set or Style Reference by itself.
3. ALWAYS report the manual's registration state honestly. The mobbin manual is registered in .utcp_config.json: presence means verify read-only and proceed to discovery; absence is a failure symptom (a broken or reverted registration) to escalate to the operator, never to repair from this packet.
4. ALWAYS follow the documented input contract: query from the user's actual words, platform ios|web (infer from context; unclear -> ask), limit starting at 5 and never exceeding ~15 without asking. Preserve unknown response fields untouched.
5. ALWAYS cite evidence by mobbin_url and report failed[] entries and missing images as partial success, never silently discarding them.
6. ALWAYS treat this packet as read-only against this repo (mutatesWorkspace: false). All reads happen against the external Mobbin service; Write, Edit, and Task are forbidden tools for this transport.

⛔ NEVER

1. 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.
2. NEVER edit, re-draft, or re-add the mobbin manual in .utcp_config.json. The registered entry is operator-owned. The reference shape in assets/utcp-mobbin-manual.md exists for verification and escalation, not for this packet to apply or repair.
3. NEVER invent an API key or auth env var. No MOBBIN_API_KEY or any MCP auth env var exists — the manual's env stays empty, and the auth env-var question is answered in the negative, not open. Never accept credentials in prompts or tool arguments; never print Authorization headers, OAuth codes, token responses, adapter debug logs, or auth-cache contents.
4. 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 — reauthorization is an explicit operator action.
5. NEVER invent tool schemas or tool families beyond the discovered inventory. The live pre-auth listing (2026-07-16) contains exactly search_screens, search_flows, and search_sections. No search_apps, search_elements, detail, image-download, or mutation tools exist to call. The deep question is resolved — mode: "deep" | "standard" | "fast" is a real client input on search_screens — but do not assume undeclared parameters on any tool.
6. NEVER target docs.mobbin.com/mcp. That is a separate Mintlify docs-search MCP; the design-reference server this packet owns is api.mobbin.com/mcp only. Likewise never conflate the OAuth MCP with the separate API-key REST API.
7. NEVER treat search rank or image appeal as a taste verdict, never average strong references into a generic middle, and never copy or cache third-party reference content (screenshots, images) into this repo.

⚠️ ESCALATE IF

1. ESCALATE IF authentication is required (HTTP 401 beyond the expected pre-auth challenge, OAuth prompt, browser round-trip). Completing browser OAuth is operator-only; surface the step and wait. Headless sessions need an operator-visible escalation, never a workaround.
2. ESCALATE IF discovery shows catalog drift: a different callable name than the inferred form, unexpected new tools, or any mutation-capable tool. Refuse mutation-capable tools outright; a provider-surface change requires a reviewed packet update.
3. ESCALATE IF the account is Free-tier or rate-limited (entitlement denial or 429 beyond the Retry-After + backoff protocol), reporting the provider's message verbatim without guessing denial semantics.
4. ESCALATE IF the manual is missing or malformed in .utcp_config.json. The registered entry is operator-owned; a broken or reverted registration is reported with the reference shape in the asset, and any config change stops with the operator.
5. ESCALATE IF retrieved Mobbin evidence conflicts with a sk-design-md-generator Style Reference (its extracted design tokens), asking which source prevails before any conclusion is drawn.

5. REFERENCES

Core References

• tool-surface.md - The live three-tool contract (fixture schemas for search_screens, search_flows, search_sections), the resolved deep mode, the query-intent workflows, plan gating, the completeness boundary, and the open questions.
• mcp-wiring.md - The registered mobbin manual, the mcp-remote bridge (remote Streamable HTTP vs local stdio adapter), OAuth/DCR/PKCE, the confirmed naming (2026-07-16 fixture), and the discovery-first contract, with CONFIRMED/INFERRED/UNKNOWN tagging.
• troubleshooting.md - Failure modes and fixes (pre-auth 401, no tools resolving, 429, Free-account denial, drift).

Templates and Assets

• utcp-mobbin-manual.md - The registered manual's reference shape exactly as researched (registered 2026-07-16, byte-identical to the live config), plus the post-registration checklist (doc-side items executed; live items pending).

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 Section 2 (SMART ROUTING) as the single routing authority.

6. SUCCESS CRITERIA

Wiring reporting complete when:

• ✅ The manual's registration state was reported honestly (presence verified read-only; absence escalated as a failure), nothing in .utcp_config.json was touched, and discovery (list_tools / tool_info) either confirmed the callable or the session/auth/entitlement blocker was escalated to the operator.

Retrieval complete when:

• ✅ Discovery preceded any call, the documented input contract was honored (query, platform, limit starting at 5), results were cited by mobbin_url, failed[] and missing images were reported as partial success, and no invented tool or parameter was used.

Measured-reference pairing complete when:

• ✅ sk-design-md-generator owned any measured Style Reference (extracted design tokens), the transport supplied only requested Mobbin evidence, and no design-token set or Style Reference was fabricated from transport output.

Always:

• ✅ No workspace file changed, no credential was invented, printed, or cached, no auth state was touched, no unpublished limit or schema was invented, and every capability claim stayed within the documented record or was labeled Inferred/UNKNOWN.

7. INTEGRATION POINTS

Tool Usage Guidelines

• Code Mode (mcp__code_mode__call_tool_chain) owns every Mobbin call, including discovery (list_tools, search_tools, tool_info) — the registered manual resolves in a fresh Code Mode session (manuals load at startup).
• Read/Grep/Glob load references and check the manual's registration state in .utcp_config.json read-only.
• Bash runs only the read-only scripts/doctor.sh diagnostics; 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 measured-extraction companion: it turns a live website's real CSS into a Style Reference DESIGN.md of named design tokens (type scale, components, Quick-Start CSS/Tailwind). The pairing: this packet retrieves cited Mobbin screens through Code Mode as reference evidence, and sk-design-md-generator produces the measured Style Reference of extracted tokens from an actual live site. The transport issues no design tokens or Style Reference of its own; pure setup/doctor or factual tool-surface reporting stays purely retrieval.
• mcp-code-mode is the substrate: manuals, {manual}.{manual}_{tool} naming, discovery, and the error-envelope discipline all come from it. The current local config surface documents stdio/sse manual shapes, which is why the registered manual bridges through mcp-remote rather than declaring direct Streamable HTTP.
• mcp-refero is the closest sibling: another remote-MCP-via-mcp-remote, read-only, OAuth-gated design-research transport in this hub. mcp-figma is the hub's original Figma transport. Neither overlaps this packet's Mobbin surface.

External Tools

• Mobbin MCP (https://api.mobbin.com/mcp): the external, paid, hosted design-research service (manifest identity com.mobbin/mobbin v1.0.1; provider transport Streamable HTTP). Not vendored, not mirrored, no local package exists.
• mcp-remote (npm, experimental, externally versioned): the stdio-to-HTTP bridge Code Mode launches via npx from the registered manual. HTTP-first transport strategy with SSE fallback only on HTTP 404; Node 18+ required.
• Official Mobbin skills repo (github.com/mobbin/skills, MIT): contains exactly one skill, mobbin-search, the authoritative usage contract for search_screens. npx skills add mobbin/skills installs guidance only; it does not replace the MCP manual or OAuth.

Knowledge Base Dependencies

Required: references/tool-surface.md (tool contract baseline). Conditional: mcp-wiring.md + assets/utcp-mobbin-manual.md (wiring/auth), troubleshooting.md (errors).

8. QUICK REFERENCE

9. REFERENCES AND RELATED RESOURCES

The router (Section 2) 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-mobbin-manual.md (the registered manual's reference shape, byte-identical to the researched sol/luna drafts and to the live .utcp_config.json entry), loaded for wiring/auth intent.

Scripts: scripts/doctor.sh (read-only, non-interactive diagnostics; manual absence now reported as an ERROR — a broken or reverted registration; optional endpoint probe gated behind MOBBIN_DOCTOR_LIVE=1, expecting the documented HTTP 401) and scripts/install.sh (non-interactive verify-only posture check: Node 18+/npx, manual presence, and the operator-only OAuth pointer).

Examples: examples/README.md plus worked Code Mode walkthroughs (smoke search, platform-filtered flow research, element intent), all quoting the 2026-07-16 discovery-confirmed callables with the mandatory per-session tool_info confirmation first.

Related skills: sk-design-md-generator (the measured-extraction companion), mcp-code-mode (the substrate), mcp-refero (the closest sibling transport), mcp-figma (the hub's 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 Mobbin MCP is the hosted paid service at api.mobbin.com/mcp (docs at docs.mobbin.com/mcp; the official mobbin/mobbin-mcp-server repository is registration metadata only). The official mobbin/skills repository (MIT) holds the single mobbin-search skill; this packet references it and deliberately does not vendor it.