@mcp-b/global 1.0.4 → 1.0.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +452 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,452 @@
|
|
|
1
|
+
# @mcp-b/global
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@mcp-b/global)
|
|
4
|
+
[](https://opensource.org/licenses/MIT)
|
|
5
|
+
|
|
6
|
+
**Add AI superpowers to any website with just one script tag!**
|
|
7
|
+
|
|
8
|
+
The `@mcp-b/global` package provides the simplest way to integrate MCP-B (Model Context Protocol for Browsers) into any website. No build tools, no complex setup - just add a script tag and start exposing AI tools.
|
|
9
|
+
|
|
10
|
+
## ✨ Features
|
|
11
|
+
|
|
12
|
+
- 🚀 **Zero Configuration** - Works immediately in any browser
|
|
13
|
+
- 🏷️ **Script Tag Ready** - Perfect for CDN usage via unpkg
|
|
14
|
+
- 🔧 **Global API** - Automatically creates `window.mcp` when loaded
|
|
15
|
+
- 📦 **Multiple Formats** - Supports ESM, CommonJS, and UMD
|
|
16
|
+
- 🎯 **TypeScript Support** - Full type definitions included
|
|
17
|
+
- 🌐 **Framework Agnostic** - Works with vanilla JS, React, Vue, or any framework
|
|
18
|
+
|
|
19
|
+
## 🚀 Quick Start
|
|
20
|
+
|
|
21
|
+
### Option 1: Script Tag (Recommended)
|
|
22
|
+
|
|
23
|
+
The easiest way to get started - just add this to your HTML:
|
|
24
|
+
|
|
25
|
+
```html
|
|
26
|
+
<!DOCTYPE html>
|
|
27
|
+
<html>
|
|
28
|
+
<head>
|
|
29
|
+
<title>My AI-Powered Website</title>
|
|
30
|
+
</head>
|
|
31
|
+
<body>
|
|
32
|
+
<h1>Hello World</h1>
|
|
33
|
+
|
|
34
|
+
<!-- The magic script tag -->
|
|
35
|
+
<script src="https://unpkg.com/@mcp-b/global@latest/dist/index.js"></script>
|
|
36
|
+
|
|
37
|
+
<!-- Your app code -->
|
|
38
|
+
<script>
|
|
39
|
+
// Wait for MCP to initialize, then register tools
|
|
40
|
+
function setupAI() {
|
|
41
|
+
if (!window.mcp?.registerTool) {
|
|
42
|
+
setTimeout(setupAI, 100);
|
|
43
|
+
return;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
// Register your first AI tool
|
|
47
|
+
window.mcp.registerTool('getPageInfo', {
|
|
48
|
+
title: 'Get Page Information',
|
|
49
|
+
description: 'Get information about the current page'
|
|
50
|
+
}, async () => {
|
|
51
|
+
return {
|
|
52
|
+
content: [{
|
|
53
|
+
type: 'text',
|
|
54
|
+
text: JSON.stringify({
|
|
55
|
+
title: document.title,
|
|
56
|
+
url: window.location.href,
|
|
57
|
+
timestamp: new Date().toISOString()
|
|
58
|
+
})
|
|
59
|
+
}]
|
|
60
|
+
};
|
|
61
|
+
});
|
|
62
|
+
|
|
63
|
+
console.log('🎉 AI tools ready!');
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
// Start setup when page loads
|
|
67
|
+
document.addEventListener('DOMContentLoaded', setupAI);
|
|
68
|
+
</script>
|
|
69
|
+
</body>
|
|
70
|
+
</html>
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### Option 2: npm Install
|
|
74
|
+
|
|
75
|
+
For TypeScript projects or when you need more control:
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
npm install @mcp-b/global
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
```typescript
|
|
82
|
+
import '@mcp-b/global'; // For global type declarations
|
|
83
|
+
import { z } from 'zod';
|
|
84
|
+
// or
|
|
85
|
+
import { initializeGlobalMCP } from '@mcp-b/global';
|
|
86
|
+
|
|
87
|
+
// Initialize MCP manually
|
|
88
|
+
initializeGlobalMCP();
|
|
89
|
+
|
|
90
|
+
// Wait for initialization then register tools
|
|
91
|
+
function setupMCP() {
|
|
92
|
+
if (!window.mcp?.registerTool) {
|
|
93
|
+
setTimeout(setupMCP, 100);
|
|
94
|
+
return;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
window.mcp.registerTool('myTool', {
|
|
98
|
+
title: 'My Custom Tool',
|
|
99
|
+
description: 'Does something useful',
|
|
100
|
+
inputSchema: {
|
|
101
|
+
message: z.string().describe('Message to process')
|
|
102
|
+
}
|
|
103
|
+
}, async ({ message }) => {
|
|
104
|
+
return { content: [{ type: 'text', text: `Tool executed with: ${message}` }] };
|
|
105
|
+
});
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
setupMCP();
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
## 🛠️ API Reference
|
|
112
|
+
|
|
113
|
+
### Global Object
|
|
114
|
+
|
|
115
|
+
When loaded, the package automatically creates `window.mcp` with the following interface:
|
|
116
|
+
|
|
117
|
+
```typescript
|
|
118
|
+
interface Window {
|
|
119
|
+
mcp: McpServer; // The global MCP server instance
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
### Core Functions
|
|
124
|
+
|
|
125
|
+
#### `window.mcp.registerTool(name, definition, handler)`
|
|
126
|
+
|
|
127
|
+
Register a new AI tool that can be called by AI assistants.
|
|
128
|
+
|
|
129
|
+
```typescript
|
|
130
|
+
import { z } from 'zod';
|
|
131
|
+
|
|
132
|
+
window.mcp.registerTool('toolName', {
|
|
133
|
+
title: 'Human-readable title',
|
|
134
|
+
description: 'What this tool does',
|
|
135
|
+
inputSchema: {
|
|
136
|
+
param1: z.string().describe('Parameter description')
|
|
137
|
+
}
|
|
138
|
+
}, async ({ param1 }) => {
|
|
139
|
+
// Your tool logic here
|
|
140
|
+
return {
|
|
141
|
+
content: [{
|
|
142
|
+
type: 'text',
|
|
143
|
+
text: `Tool result with ${param1}`
|
|
144
|
+
}]
|
|
145
|
+
};
|
|
146
|
+
});
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
#### Manual Initialization (Optional)
|
|
150
|
+
|
|
151
|
+
```typescript
|
|
152
|
+
import { initializeGlobalMCP, cleanupGlobalMCP } from '@mcp-b/global';
|
|
153
|
+
|
|
154
|
+
// Initialize manually (automatic in script tag mode)
|
|
155
|
+
initializeGlobalMCP();
|
|
156
|
+
|
|
157
|
+
// Cleanup (useful for testing or hot reload)
|
|
158
|
+
cleanupGlobalMCP();
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
### TypeScript Support
|
|
162
|
+
|
|
163
|
+
The package includes full TypeScript definitions:
|
|
164
|
+
|
|
165
|
+
```typescript
|
|
166
|
+
import '@mcp-b/global'; // Augments global Window interface
|
|
167
|
+
import { z } from 'zod';
|
|
168
|
+
|
|
169
|
+
declare global {
|
|
170
|
+
interface Window {
|
|
171
|
+
// Add your custom global tools
|
|
172
|
+
myCustomFunction: () => void;
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
// Use with full type safety
|
|
177
|
+
window.mcp.registerTool('typedTool', {
|
|
178
|
+
title: 'Typed Tool',
|
|
179
|
+
description: 'A tool with proper typing',
|
|
180
|
+
inputSchema: {
|
|
181
|
+
value: z.number().describe('A numeric value to process')
|
|
182
|
+
}
|
|
183
|
+
}, async ({ value }) => {
|
|
184
|
+
return { content: [{ type: 'text', text: `Typed result: ${value * 2}` }] };
|
|
185
|
+
});
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
## 📖 Complete Example
|
|
189
|
+
|
|
190
|
+
Here's a full working example that creates a simple todo app with AI tools:
|
|
191
|
+
|
|
192
|
+
```html
|
|
193
|
+
<!DOCTYPE html>
|
|
194
|
+
<html lang="en">
|
|
195
|
+
<head>
|
|
196
|
+
<meta charset="UTF-8">
|
|
197
|
+
<title>AI Todo App</title>
|
|
198
|
+
<style>
|
|
199
|
+
body { font-family: system-ui; max-width: 600px; margin: 50px auto; padding: 20px; }
|
|
200
|
+
.todo { padding: 10px; margin: 5px 0; background: #f0f0f0; border-radius: 5px; }
|
|
201
|
+
.ai-action { background: #4CAF50; color: white; padding: 15px; border-radius: 10px; margin: 10px 0; }
|
|
202
|
+
</style>
|
|
203
|
+
</head>
|
|
204
|
+
<body>
|
|
205
|
+
<h1>🤖 AI Todo App</h1>
|
|
206
|
+
<div id="status">Loading AI...</div>
|
|
207
|
+
<div id="todos"></div>
|
|
208
|
+
|
|
209
|
+
<!-- Load MCP-B Global -->
|
|
210
|
+
<script src="https://unpkg.com/@mcp-b/global@latest/dist/index.js"></script>
|
|
211
|
+
<!-- Load Zod for schema validation -->
|
|
212
|
+
<script src="https://unpkg.com/zod@latest/lib/index.umd.js"></script>
|
|
213
|
+
|
|
214
|
+
<script>
|
|
215
|
+
// Access Zod from global
|
|
216
|
+
const { z } = window.Zod;
|
|
217
|
+
|
|
218
|
+
// Simple todo state
|
|
219
|
+
const todos = ['Learn MCP-B', 'Build awesome AI tools'];
|
|
220
|
+
|
|
221
|
+
// Show AI action feedback
|
|
222
|
+
function showAIAction(message) {
|
|
223
|
+
const div = document.createElement('div');
|
|
224
|
+
div.className = 'ai-action';
|
|
225
|
+
div.textContent = `🤖 ${message}`;
|
|
226
|
+
document.body.insertBefore(div, document.getElementById('todos'));
|
|
227
|
+
setTimeout(() => div.remove(), 3000);
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
// Render todos
|
|
231
|
+
function renderTodos() {
|
|
232
|
+
document.getElementById('todos').innerHTML = todos
|
|
233
|
+
.map((todo, i) => `<div class="todo">${i + 1}. ${todo}</div>`)
|
|
234
|
+
.join('');
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
// Setup AI tools
|
|
238
|
+
function setupAI() {
|
|
239
|
+
if (!window.mcp?.registerTool) {
|
|
240
|
+
setTimeout(setupAI, 100);
|
|
241
|
+
return;
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
// Add todo tool
|
|
245
|
+
window.mcp.registerTool('addTodo', {
|
|
246
|
+
title: 'Add Todo',
|
|
247
|
+
description: 'Add a new todo item',
|
|
248
|
+
inputSchema: {
|
|
249
|
+
text: z.string().describe('Todo text to add')
|
|
250
|
+
}
|
|
251
|
+
}, async ({ text }) => {
|
|
252
|
+
showAIAction(`Adding todo: "${text}"`);
|
|
253
|
+
todos.push(text);
|
|
254
|
+
renderTodos();
|
|
255
|
+
return { content: [{ type: 'text', text: `✅ Added: "${text}"` }] };
|
|
256
|
+
});
|
|
257
|
+
|
|
258
|
+
// Get todos tool
|
|
259
|
+
window.mcp.registerTool('getTodos', {
|
|
260
|
+
title: 'Get All Todos',
|
|
261
|
+
description: 'Get all current todo items'
|
|
262
|
+
}, async () => {
|
|
263
|
+
showAIAction('Getting all todos');
|
|
264
|
+
return {
|
|
265
|
+
content: [{
|
|
266
|
+
type: 'text',
|
|
267
|
+
text: `📋 Current todos: ${JSON.stringify(todos)}`
|
|
268
|
+
}]
|
|
269
|
+
};
|
|
270
|
+
});
|
|
271
|
+
|
|
272
|
+
// Delete todo tool
|
|
273
|
+
window.mcp.registerTool('deleteTodo', {
|
|
274
|
+
title: 'Delete Todo',
|
|
275
|
+
description: 'Delete a todo by its number (1-based index)',
|
|
276
|
+
inputSchema: {
|
|
277
|
+
index: z.number().describe('Todo number to delete (1, 2, 3...)')
|
|
278
|
+
}
|
|
279
|
+
}, async ({ index }) => {
|
|
280
|
+
const i = index - 1; // Convert to 0-based
|
|
281
|
+
if (i >= 0 && i < todos.length) {
|
|
282
|
+
const deleted = todos.splice(i, 1)[0];
|
|
283
|
+
showAIAction(`Deleted todo: "${deleted}"`);
|
|
284
|
+
renderTodos();
|
|
285
|
+
return { content: [{ type: 'text', text: `🗑️ Deleted: "${deleted}"` }] };
|
|
286
|
+
} else {
|
|
287
|
+
return { content: [{ type: 'text', text: `❌ Todo ${index} not found` }] };
|
|
288
|
+
}
|
|
289
|
+
});
|
|
290
|
+
|
|
291
|
+
// Update status
|
|
292
|
+
document.getElementById('status').innerHTML = '✅ AI Ready! 3 tools available';
|
|
293
|
+
document.getElementById('status').style.background = '#d4edda';
|
|
294
|
+
document.getElementById('status').style.color = '#155724';
|
|
295
|
+
document.getElementById('status').style.padding = '10px';
|
|
296
|
+
document.getElementById('status').style.borderRadius = '5px';
|
|
297
|
+
|
|
298
|
+
console.log('🎉 AI tools registered successfully!');
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
// Initialize
|
|
302
|
+
document.addEventListener('DOMContentLoaded', () => {
|
|
303
|
+
renderTodos();
|
|
304
|
+
setupAI();
|
|
305
|
+
});
|
|
306
|
+
</script>
|
|
307
|
+
</body>
|
|
308
|
+
</html>
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
## 🎯 Try It Out
|
|
312
|
+
|
|
313
|
+
1. **Install the MCP-B Extension**: Get it from the [Chrome Web Store](https://chromewebstore.google.com/detail/mcp-b/daohopfhkdelnpemnhlekblhnikhdhfa)
|
|
314
|
+
|
|
315
|
+
2. **Save the example above** as an HTML file and open it in Chrome
|
|
316
|
+
|
|
317
|
+
3. **Chat with AI**: Open the extension and try commands like:
|
|
318
|
+
- *"Add a todo: Buy groceries"*
|
|
319
|
+
- *"Show me all my todos"*
|
|
320
|
+
- *"Delete todo number 2"*
|
|
321
|
+
|
|
322
|
+
4. **Watch the magic**: See AI interact with your website directly!
|
|
323
|
+
|
|
324
|
+
## 🌟 When to Use This Package
|
|
325
|
+
|
|
326
|
+
**Perfect for:**
|
|
327
|
+
- 🏃♂️ **Rapid Prototyping** - Get AI tools working in minutes
|
|
328
|
+
- 🎯 **Landing Pages** - Add AI capabilities without build complexity
|
|
329
|
+
- 🔄 **Legacy Sites** - Retrofit existing HTML with AI tools
|
|
330
|
+
- 📚 **Learning** - Understand MCP-B concepts quickly
|
|
331
|
+
- 🚀 **MVP Development** - Ship AI features fast
|
|
332
|
+
|
|
333
|
+
**For larger applications**, consider the [TypeScript transport package](https://www.npmjs.com/package/@mcp-b/transports) with full build tool integration.
|
|
334
|
+
|
|
335
|
+
## 📦 Package Formats
|
|
336
|
+
|
|
337
|
+
This package is distributed in multiple formats for maximum compatibility:
|
|
338
|
+
|
|
339
|
+
- **UMD** (`dist/index.umd.js`) - For script tags and AMD loaders
|
|
340
|
+
- **ESM** (`dist/index.js`) - For modern ES modules
|
|
341
|
+
- **CommonJS** (`dist/index.cjs`) - For Node.js and older bundlers
|
|
342
|
+
- **TypeScript** (`dist/index.d.ts`) - Full type definitions
|
|
343
|
+
|
|
344
|
+
```html
|
|
345
|
+
<!-- UMD via CDN -->
|
|
346
|
+
<script src="https://unpkg.com/@mcp-b/global@latest/dist/index.js"></script>
|
|
347
|
+
|
|
348
|
+
<!-- ESM via CDN -->
|
|
349
|
+
<script type="module">
|
|
350
|
+
import '@mcp-b/global';
|
|
351
|
+
// window.mcp is now available
|
|
352
|
+
</script>
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
```javascript
|
|
356
|
+
// CommonJS
|
|
357
|
+
const { initializeGlobalMCP } = require('@mcp-b/global');
|
|
358
|
+
const { z } = require('zod');
|
|
359
|
+
|
|
360
|
+
// ESM
|
|
361
|
+
import { initializeGlobalMCP } from '@mcp-b/global';
|
|
362
|
+
import { z } from 'zod';
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
## 🔧 Advanced Usage
|
|
366
|
+
|
|
367
|
+
### Custom Initialization
|
|
368
|
+
|
|
369
|
+
```typescript
|
|
370
|
+
import { initializeGlobalMCP, cleanupGlobalMCP } from '@mcp-b/global';
|
|
371
|
+
import { z } from 'zod';
|
|
372
|
+
|
|
373
|
+
// Initialize with custom configuration
|
|
374
|
+
initializeGlobalMCP();
|
|
375
|
+
|
|
376
|
+
// Later, cleanup if needed (useful for SPA route changes)
|
|
377
|
+
cleanupGlobalMCP();
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
### Error Handling
|
|
381
|
+
|
|
382
|
+
```javascript
|
|
383
|
+
window.mcp.registerTool('riskyOperation', {
|
|
384
|
+
title: 'Risky Operation',
|
|
385
|
+
description: 'An operation that might fail',
|
|
386
|
+
inputSchema: {
|
|
387
|
+
data: z.string().describe('Data to process')
|
|
388
|
+
}
|
|
389
|
+
}, async ({ data }) => {
|
|
390
|
+
try {
|
|
391
|
+
const result = await doSomethingRisky(data);
|
|
392
|
+
return { content: [{ type: 'text', text: `Success: ${result}` }] };
|
|
393
|
+
} catch (error) {
|
|
394
|
+
return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
|
|
395
|
+
}
|
|
396
|
+
});
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
### Dynamic Tool Registration
|
|
400
|
+
|
|
401
|
+
```javascript
|
|
402
|
+
function registerUserSpecificTools(user) {
|
|
403
|
+
if (user.isAdmin) {
|
|
404
|
+
window.mcp.registerTool('adminAction', {
|
|
405
|
+
title: 'Admin Action',
|
|
406
|
+
description: 'Administrative function',
|
|
407
|
+
inputSchema: {
|
|
408
|
+
action: z.string().describe('Admin action to perform')
|
|
409
|
+
}
|
|
410
|
+
}, async ({ action }) => {
|
|
411
|
+
return { content: [{ type: 'text', text: `Admin action executed: ${action}` }] };
|
|
412
|
+
});
|
|
413
|
+
}
|
|
414
|
+
|
|
415
|
+
if (user.isPremium) {
|
|
416
|
+
window.mcp.registerTool('premiumFeature', {
|
|
417
|
+
title: 'Premium Feature',
|
|
418
|
+
description: 'Premium user functionality',
|
|
419
|
+
inputSchema: {
|
|
420
|
+
feature: z.string().describe('Premium feature to activate')
|
|
421
|
+
}
|
|
422
|
+
}, async ({ feature }) => {
|
|
423
|
+
return { content: [{ type: 'text', text: `Premium feature activated: ${feature}` }] };
|
|
424
|
+
});
|
|
425
|
+
}
|
|
426
|
+
}
|
|
427
|
+
```
|
|
428
|
+
|
|
429
|
+
## 🚨 Important Notes
|
|
430
|
+
|
|
431
|
+
- **Browser Only**: This package is designed for browser environments only
|
|
432
|
+
- **Extension Required**: Users need the MCP-B browser extension to interact with your tools
|
|
433
|
+
- **Security**: Tools run in your website's context with the same permissions as your JavaScript
|
|
434
|
+
- **Initialization**: Always wait for `window.mcp` to be available before registering tools
|
|
435
|
+
|
|
436
|
+
## 🔗 Related Packages
|
|
437
|
+
|
|
438
|
+
- **[@mcp-b/transports](https://www.npmjs.com/package/@mcp-b/transports)** - Core transport layer for advanced usage
|
|
439
|
+
- **[@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk)** - Official MCP SDK
|
|
440
|
+
- **[MCP-B Extension](https://chromewebstore.google.com/detail/mcp-b/daohopfhkdelnpemnhlekblhnikhdhfa)** - Browser extension for interacting with tools
|
|
441
|
+
|
|
442
|
+
## 📄 License
|
|
443
|
+
|
|
444
|
+
MIT - see [LICENSE](https://github.com/MiguelsPizza/WebMCP/blob/main/LICENSE)
|
|
445
|
+
|
|
446
|
+
## 🤝 Contributing
|
|
447
|
+
|
|
448
|
+
Contributions welcome! See the [main repository](https://github.com/MiguelsPizza/WebMCP) for guidelines.
|
|
449
|
+
|
|
450
|
+
---
|
|
451
|
+
|
|
452
|
+
**Ready to give your website AI superpowers?** Just add the script tag and start building! 🚀
|