OpenRepair

Inspiration

When something breaks, the hard part is rarely finding another generic tutorial. It is deciding what evidence matters, which component is implicated, what can be preserved, and when a repair should stop. OpenRepair creates that missing shared workbench.

What it does

OpenRepair turns a photo and symptom into visible evidence, confidence-ranked hypotheses, component context, clarifying questions, constraint-aware repair paths, and a checklist only the person can approve.

The challenge build demonstrates the complete protocol with a reviewed bicycle repair pack. A person can correct observations and lock priorities such as budget or parts to preserve. A browser agent then works on the same live page state through eight WebMCP tools. Every change remains visible, stale writes fail, unsafe DIY paths stop, and incompatible replacements are rejected.

In the core example, the user corrects an initial noisy-wheel interpretation: “Actually, the chain skips, but the wheel is straight. Preserve the cassette.” That correction changes the evidence revision, makes drivetrain skipping the leading hypothesis, shifts diagram focus, and reranks repair paths. Immediate cassette replacement becomes incompatible with both budget and preservation constraints. The agent can stage and validate a reversible indexing adjustment, but final approval remains a visible human action.

Why WebMCP

Repair is shared-state work, not a one-shot answer. The useful artifact is an evolving inspection containing evidence, uncertainty, constraints, alternatives, safety checks, and a plan.

WebMCP lets the agent contribute directly to that artifact while OpenRepair remains the source of truth. The person supplies context, corrects observations, locks priorities, and retains final authority. The agent converts visual or conversational context into bounded evidence, focuses relevant components, compares paths, and prepares a validated draft.

Without this shared state, owners must manually reconcile a chat diagnosis, diagrams, estimates, safety advice, and personal constraints. OpenRepair turns those fragments into one inspectable workflow.

How WebMCP was implemented

The React client feature-detects document.modelContext, with a legacy navigator.modelContext fallback, and registers eight narrow tools:

1. get_repair_session reads bounded current state and the next legal action.
2. initialize_repair_workspace creates a visible workspace for a user-identified object.
3. set_inspection_context records bounded observations and confidence changes.
4. show_component_diagram focuses known components without declaring a diagnosis.
5. compare_repair_paths ranks options under locked constraints.
6. stage_repair_plan creates a reversible draft and rejects stale revisions.
7. validate_repair_plan checks evidence, constraints, verification, and safety.
8. export_repair_checklist exports only a current plan explicitly approved on the page.

Zod validates untrusted inputs. WebMCP handlers and visible UI controls use the same typed domain reducer. Raw image bytes never travel through tool results. There is no agent tool for approval, purchasing, booking, or repair execution.

How we built it

OpenRepair is a client-first React, strict TypeScript, Vite, Zod, and SVG application deployed on Vercel. Vitest covers the domain and WebMCP boundaries; Playwright and axe cover complete browser workflows and accessibility.

Codex supported implementation, debugging, test development, WebMCP lifecycle hardening, contest audits, documentation, and submission preparation. ChatGPT with Terra demonstrated the real browser-agent workflow. AI text-to-speech narrates the demo video.

Accomplishments

• Eight WebMCP tools support a non-trivial evidence-to-export lifecycle.
• Human corrections invalidate stale agent writes and rerank visible alternatives.
• Budget and preservation locks deterministically reject incompatible work.
• Agent tools can stage and validate but cannot approve.
• Safety stops prevent professional-only work from reaching approval.
• The product remains useful through reviewed fallback cases when WebMCP is unavailable.

What we learned

Agent-native UX works best when tool activity changes a durable visual artifact rather than only a transcript. Narrow schemas, visible revisions, bounded results, and explicit human gates make collaboration easier to understand and safer to trust.

What's next

Bicycles are the first reviewed repair pack. Future packs can cover appliances, electronics, furniture, vehicles, tools, and community repair knowledge while reusing the same evidence, constraint, revision, planning, and approval protocol.

OpenRepair is an independent open-source project and is not an official OpenAI product.

Built With

• playwright
• react
• typescript
• vercel
• vite
• vitest
• webmcp
• zod