-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathindex.html
More file actions
422 lines (373 loc) · 19.5 KB
/
index.html
File metadata and controls
422 lines (373 loc) · 19.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>MCP-Frontend — Connect AI Agents to your App Runtime</title>
<meta name="description"
content="MCP-FE enables local and remote AI agents to query real-time frontend context via WebMCP-compatible edge nodes in the browser, bridged to the network through a session-aware proxy server." />
<link rel="icon" href="favicon.svg" type="image/svg+xml" />
<link rel="stylesheet" href="style.css" />
</head>
<body>
<main>
<header>
<h1><svg width="48" height="48" viewBox="0 0 64 64" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
<line x1="17" y1="14" x2="30" y2="30" stroke="#9daaf5" stroke-width="2.5"/>
<line x1="32" y1="53" x2="32" y2="41" stroke="#9daaf5" stroke-width="2.5"/>
<line x1="47" y1="17" x2="34" y2="30" stroke="#9daaf5" stroke-width="2.5"/>
<circle cx="17" cy="14" r="5" fill="#7aa2f7"/>
<circle cx="32" cy="53" r="5" fill="#7aa2f7"/>
<circle cx="47" cy="17" r="5" fill="#7aa2f7"/>
<circle cx="32" cy="35" r="7" fill="#4a6fd4"/>
<circle cx="32" cy="35" r="4" fill="#c9d4ff"/>
</svg><span class="h1-text">MCP-FrontEnd</span></h1>
<div class="tagline">The missing link between AI Agent reasoning and frontend reality</div>
<p class="header-subtitle">
Stop scraping HTML. Start querying runtime. Transform your web app into a high-fidelity context engine for AI Agents.
</p>
</header>
<video class="demo-video" width="100%" height="auto" controls>
<source src="./mcp-fe-demo.mp4" type="video/mp4" />
Your browser does not support the video tag.
</video>
<div class="demo-banner">
<h2>Try the Live Demo</h2>
<p>
Explore a fully functional React app with MCP-FE integrated — then connect Claude or any MCP client
and watch it query real-time frontend state directly from the browser.
</p>
<a class="demo-cta-btn" href="https://demo.mcp-fe.ai" target="_blank" rel="noopener noreferrer">
Open Interactive Demo →
</a>
<div class="demo-features">
<span>No install required</span>
<span>Live form & state inspection</span>
<span>User event tracking</span>
<span>Works with Claude</span>
</div>
</div>
<section class="section">
<h2>What is MCP-Frontend?</h2>
<p>
<strong>Current AI agents are Runtime-Blind.</strong> They interact with the web through a "straw"—using brittle screen scraping, slow vision models, or surface-level DOM analysis. They can see what a button looks like, but they don't know what it <em>does</em>, what's in the application state, or why an internal validation failed.
</p>
<div class="highlight-box highlight-box--accent">
<h3>From "Guessing" to "Querying"</h3>
<p>
MCP-Frontend is the missing communication layer that transforms your web application from a passive UI into an <strong>Active Context Engine</strong>. By integrating it directly into your frontend code, you give AI agents a direct neural link to your app's internal runtime:
</p>
<ul class="feature-list">
<li><strong>Deep Context (The Eyes):</strong> Agents can query live React/Zustand state, read exact form values, and inspect user navigation history with 100% accuracy.</li>
<li><strong>Precise Actions (The Hands):</strong> Agents can programmatically navigate your app, fill complex forms, or trigger side-effects safely through your predefined, type-safe tools.</li>
</ul>
</div>
<p>
Built on the <strong>Model Context Protocol (MCP)</strong>, this infrastructure is accessible both to <strong>in-browser agents</strong> natively, and to <strong>remote agents</strong> (like Claude Desktop or cloud-hosted bots) through our session-aware proxy server.
</p>
<div class="webmcp-note">
<h3>🌐 Aligned with WebMCP Standards</h3>
<p>
The emerging <a href="https://github.com/webmachinelearning/webmcp" target="_blank" class="link-accent">WebMCP specification</a>
is a future standard for browser-based AI. While it is currently experimental and limited to local contexts,
<strong>MCP-Frontend bridges the gap today.</strong>
</p>
<p>
By using reliable Web APIs (SharedWorker, WebSockets), we provide a production-ready experience for
<strong>both local and remote agents</strong> right now—no experimental flags required.
As WebMCP matures, MCP-Frontend will seamlessly adopt it as a core transport layer.
</p>
</div>
</section>
<section class="section">
<h2>The Current Reality of Browser-Based AI</h2>
<p>Building AI agents that interact with web applications is currently a mess of trade-offs. Existing approaches fall short because they treat the UI as a static image or a flat document, ignoring the rich logic underneath.</p>
<div class="package-grid">
<div class="use-case-card">
<div class="use-case-name">Vision is Expensive & Slow</div>
<div class="use-case-desc">Sending screenshots to Multimodal LLMs costs a fortune in tokens and takes seconds to process. It's too slow for real-time assistance.</div>
</div>
<div class="use-case-card">
<div class="use-case-name">Scraping is Brittle</div>
<div class="use-case-desc">DOM structures change. Classes are obfuscated. One CSS update can break your entire agentic workflow overnight.</div>
</div>
<div class="use-case-card">
<div class="use-case-name">Backend is Blind</div>
<div class="use-case-desc">Backend MCP servers can't see what's happening in the user's browser. They miss local state, unsaved forms, and UI errors.</div>
</div>
<div class="use-case-card">
<div class="use-case-name">Analytics are Passive</div>
<div class="use-case-desc">Logs tell you what <em>happened</em>. MCP-FE lets agents ask what is <em>happening right now</em> and intervene before the user leaves.</div>
</div>
</div>
<div class="highlight-box highlight-box--accent">
<h3>The Evolution: Context-on-Demand</h3>
<p>
MCP-Frontend shifts the paradigm from <strong>guessing from HTML</strong> to <strong>querying the runtime</strong>.
It's the difference between trying to understand a car by looking at its shell and plugging into its OBD-II diagnostic port.
</p>
</div>
</section>
<section class="section">
<h2>Where MCP-Frontend Shines</h2>
<p>Stop treating AI as an external observer. Start building applications where the AI is an integrated collaborator that understands the context of every click.</p>
<div class="package-grid grid-2col">
<div class="use-case-card">
<div class="use-case-name">AI copilot built into your product</div>
<p class="use-case-desc">
Your agent knows what's in the database. With MCP-FE it also knows what the user is doing right now — which page they're on, what they've filled in, where they're stuck. Browser context is just another tool alongside the rest.
Agent calls <code>get_current_page_state</code> or <code>get_form_progress</code> and responds in context.
</p>
</div>
<div class="use-case-card">
<div class="use-case-name">Support with "X-Ray Vision"</div>
<p class="use-case-desc">
Instead of asking for screenshots, your support bot queries <code>get_validation_errors</code> or <code>get_app_state</code>.
It identifies why a user is stuck in seconds, not hours.
</p>
</div>
<div class="use-case-card">
<div class="use-case-name">Onboarding assistant</div>
<p class="use-case-desc">
A new user is lost in a complex product. The agent sees exactly where they are, what they've already done, and guides them through the next step — no screenshots, no guessing.
Agent calls <code>get_user_events</code> to understand the journey so far and <code>navigate_to</code> to take them where they need to go.
</p>
</div>
<div class="use-case-card">
<div class="use-case-name">Reproducible Bug Reports</div>
<p class="use-case-desc">
QA agents can extract <code>get_event_history</code> (via <code>@mcp-fe/event-tracker</code>) to see the exact runtime sequence that led to a crash. No more "cannot reproduce" tickets.
</p>
</div>
</div>
</section>
<section class="section">
<h2>The Power of @mcp-fe/react-tools</h2>
<p>
Standard MCP servers are static. <strong>MCP-FE is alive.</strong> With our React integration,
your AI agent gains new capabilities dynamically based on the user's current view.
</p>
<div class="highlight-box">
<h3>`useMCPTool` — Real-time Component Access</h3>
<p>Expose local state, props, or even DOM refs directly to your agent with a simple hook.</p>
<pre><code>// This tool only exists while the ProductDetail component is active
function ProductDetail({ productId }) {
const { data } = useQuery(['product', productId]);
useMCPTool(
'get_current_product_specs',
'Returns technical specs of the product currently on screen',
async () => ({
name: data.name,
inStock: data.inventory > 0,
specs: data.technicalDetails
})
);
return <div>...</div>;
}</code></pre>
</div>
<div class="feature-grid feature-grid--compact">
<div class="use-case use-case--flush">
<strong>Contextual Lifecycle:</strong> Tools automatically deregister when components unmount. No ghost tools.
</div>
<div class="use-case use-case--flush">
<strong>Zero Data Leakage:</strong> Sensitive data stays in your app until the agent explicitly asks for it.
</div>
</div>
</section>
<section class="section">
<h2>Quick Start</h2>
<div class="quick-start">
<h3>1. Start the MCP Proxy Server</h3>
<div class="docker-command">
docker pull ghcr.io/mcp-fe/mcp-fe/mcp-server:main<br>
docker run -p 3001:3001 ghcr.io/mcp-fe/mcp-fe/mcp-server:main
</div>
<h3>2. Install in Your React App</h3>
<pre><code>npm install @mcp-fe/react-tools @mcp-fe/mcp-worker</code></pre>
<h3>3. Set up worker files</h3>
<pre>
<code>// For example in rspack.config.json
entry: {
main: './src/main.tsx',
'mcp-service-worker': 'node_modules/@mcp-fe/mcp-worker/mcp-service-worker.ts',
'mcp-shared-worker': 'node_modules/@mcp-fe/mcp-worker/mcp-shared-worker.ts',
},</code></pre>
<h3>4. Create a tool</h3>
<pre><code>import { useMCPTool } from '@mcp-fe/react-tools';
function Dashboard() {
// AI Agent can now ask for internal metrics directly from this component
useMCPTool('get_internal_metrics', 'Returns current dashboard KPIs', async () => ({
activeUsers: state.activeUsers,
systemLoad: state.systemLoad,
}));
return <DashboardUI />;
}</code></pre>
<h3>5. Query from AI Agents</h3>
<p>AI agents can now query real-time frontend state through standard MCP tools:</p>
<ul>
<li><code>get_connection_status</code> - Check browser session status</li>
<li><code>get_user_events</code> - Query user interactions and navigation</li>
<li><code>get_internal_metrics</code> - Get current component state</li>
</ul>
</div>
</section>
<section class="section">
<h2>Production-Ready Architecture</h2>
<p>MCP-Frontend isn't just a prototype; it's a modular system designed to integrate your web app into the global AI ecosystem.</p>
<div class="feature-grid">
<div class="feature-item">
<h3>🔌 Universal Connectivity</h3>
<p>By using the standard <strong>Model Context Protocol (MCP)</strong>, your frontend becomes instantly compatible with any agent—from <strong>Claude Desktop</strong> to custom autonomous bots.</p>
</div>
<div class="feature-item">
<h3>⚡ Zero-Latency Context</h3>
<p>By leveraging <strong>SharedWorkers</strong>, we eliminate unnecessary server round-trips. Agents query the local runtime in milliseconds, ensuring a fluid user experience.</p>
</div>
<div class="feature-item">
<h3>📦 Framework Agnostic</h3>
<p>While we provide first-class <strong>React hooks</strong>, the core <code>@mcp-fe/mcp-worker</code> is built on vanilla Web APIs, making it compatible with Vue, Angular, or any JS application.</p>
</div>
<div class="feature-item">
<h3>🌐 Future-Proof (WebMCP)</h3>
<p>Fully aligned with the emerging <strong>WebMCP</strong> standard. Use it today via existing Web APIs, and switch to native browser support as it rolls out across browsers.</p>
</div>
</div>
</section>
<section class="section">
<h2>Security & Privacy First</h2>
<div class="highlight-box">
<p>
Unlike traditional analytics or screen-sharing tools, <strong>MCP-Frontend is passive and local-first</strong>.
It doesn't stream your data to any cloud; it empowers your application to speak for itself.
</p>
<div class="security-grid">
<div class="security-pillar">
<strong>Strict Pull Model</strong>
<p>Context never leaves the browser unless an authenticated agent explicitly calls a tool you provided.</p>
</div>
<div class="security-pillar">
<strong>Developer-Controlled</strong>
<p>You have total control. You decide exactly which state, props, or actions are exposed to the agent.</p>
</div>
<div class="security-pillar">
<strong>Native Auth Context</strong>
<p>Tool handlers run inside your app's runtime, respecting your existing authentication and permissions.</p>
</div>
<div class="security-pillar">
<strong>No Invasiveness</strong>
<p>No pixel-scraping, no screen recording. Only structured, purposeful data exchange via standardized protocol.</p>
</div>
</div>
</div>
</section>
<section class="section">
<h2>High-Level Architecture</h2>
<p>MCP-FE introduces a frontend edge layer that participates in the MCP ecosystem through two complementary access paths:</p>
<img class="architecture-img" src="./mcp-fe-architecture.png" alt="MCP-FE Architecture Diagram" />
<p>
<strong>Local path:</strong> In-browser agents can call MCP tools directly through a Web Worker built on
existing Web APIs (SharedWorker, ServiceWorker, IndexedDB) — <strong>no experimental browser flags required.</strong>
When native WebMCP is available by default, MCP-FE will adopt it seamlessly.
</p>
<p>
<strong>Remote path (Proxy):</strong> The backend MCP server acts as a session-aware proxy, bridging browser context
to the network via WebSocket. This allows cloud-hosted agents, or any standard
MCP client to query the same real-time frontend state over the wire.
</p>
<p>
Both paths expose identical tools and context. The developer defines capabilities once; MCP-FE makes them
available locally and remotely with zero extra configuration.
</p>
</section>
<section class="section">
<h2>Package Ecosystem</h2>
<p>MCP-FE is built as a modular ecosystem with packages for different use cases and frameworks:</p>
<div class="full-bleed">
<div class="full-bleed-inner">
<div class="package-grid">
<div class="package-card">
<div class="package-name">
<a href="https://www.npmjs.com/package/@mcp-fe/mcp-worker" target="_blank">@mcp-fe/mcp-worker</a>
</div>
<div class="package-desc">Core browser-based MCP server — WebMCP-compatible, with WebSocket bridge for remote agents</div>
<ul class="feature-list">
<li>SharedWorker + ServiceWorker support</li>
<li>IndexedDB storage</li>
<li>WebSocket transport</li>
<li>Authentication & session management</li>
</ul>
</div>
<div class="package-card">
<div class="package-name">
<a href="https://www.npmjs.com/package/@mcp-fe/react-tools" target="_blank">@mcp-fe/react-tools</a>
</div>
<div class="package-desc">React-first hooks for dynamic tool registration and state access.</div>
<ul class="feature-list">
<li><code>useMCPTool</code> hook</li>
<li>Automatic cleanup on unmount</li>
<li>React-safe state snapshots</li>
</ul>
</div>
<div class="package-card">
<div class="package-name">
<a href="https://www.npmjs.com/package/@mcp-fe/event-tracker" target="_blank">@mcp-fe/event-tracker</a>
</div>
<div class="package-desc">Framework-agnostic event tracking API</div>
<ul class="feature-list">
<li>Simple tracking functions</li>
<li>Navigation, click, input events</li>
<li>Custom event support</li>
<li>Connection status monitoring</li>
</ul>
</div>
<div class="package-card">
<div class="package-name">
<a href="https://www.npmjs.com/package/@mcp-fe/react-event-tracker" target="_blank">@mcp-fe/react-event-tracker</a>
</div>
<div class="package-desc">React hooks for automatic event tracking</div>
<ul class="feature-list">
<li>React Router integration</li>
<li>TanStack Router support</li>
<li>Zero-config setup</li>
<li>Automatic UI interaction tracking</li>
</ul>
</div>
</div>
</div>
</div>
</section>
<section class="section">
<h2>Roadmap</h2>
<p>MCP-FE is currently published as an open-source reference implementation. The focus is on:</p>
<ul>
<li>✅ <strong>Core Architecture Validation</strong> — Browser-based MCP servers working in production</li>
<li>✅ <strong>Package Ecosystem</strong> — Modular libraries for different frameworks and use cases</li>
<li>✅ <strong>Docker Distribution</strong> — Ready-to-use proxy server container</li>
<li>🔄 <strong>Production readiness</strong> — Performance optimization, security hardening</li>
<li>🔄 <strong>Community Adoption</strong> — Gathering feedback and real-world usage patterns</li>
</ul>
</section>
<section class="section section--cta">
<h2>Ready to give your AI eyes?</h2>
<p>Start building AI-Native applications today</p>
<div class="links">
<a href="https://demo.mcp-fe.ai" target="_blank" rel="noopener noreferrer" class="btn-primary">Try Live Demo</a>
<a href="https://github.com/mcp-fe/mcp-fe" class="btn-secondary">Get Started on GitHub</a>
</div>
<div class="links">
<a href="https://github.com/mcp-fe/mcp-fe" target="_blank">📚 Documentation</a>
<a href="https://www.npmjs.com/package/@mcp-fe/mcp-worker" target="_blank">📦 npm Packages</a>
<a href="https://github.com/mcp-fe/mcp-fe/pkgs/container/mcp-fe%2Fmcp-server" target="_blank">🐳 Docker Image</a>
</div>
</section>
<footer>
<p>
MCP-FE is an open source architectural exploration that bridges the gap between AI agents and real-time frontend context.<br>
Feedback, discussion, and contributions are welcome.
</p>
<p class="footer-copyright">© 2026 Michal Kopecký • Licensed under Apache 2.0</p>
</footer>
</main>
<script defer src='https://static.cloudflareinsights.com/beacon.min.js' data-cf-beacon='{"token": "d35e8e10810a4ffcb2e9a0a673ebf045"}'></script>
</body>
</html>