@handsforbots/expose-webmcp 0.0.0-stage → 2.0.0-alpha.0

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/LICENSE.md ADDED
@@ -0,0 +1,9 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright © 2024 Alex Lana and Hands for Bots contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
6
+
7
+ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
8
+
9
+ THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,21 @@
1
- # Temporary Holding Version
1
+ # @handsforbots/expose-webmcp
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Expose Hands for Bots actions to browser agents through WebMCP (document.modelContext).
4
+
5
+ Part of [Hands for Bots](https://github.com/handsforbots/handsforbots), a headless multimodal and action layer between users, GUIs and agents.
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ npm install @handsforbots/expose-webmcp@alpha @handsforbots/core@alpha
11
+ ```
12
+
13
+ ## Documentation
14
+
15
+ - [This package](https://github.com/handsforbots/handsforbots/blob/main/docs/en-us/plugins.md#expose-webmcp)
16
+ - [Getting started](https://github.com/handsforbots/handsforbots/blob/main/docs/en-us/getting-started.md)
17
+ - [Documentação em português](https://github.com/handsforbots/handsforbots/blob/main/docs/pt-br/README.md)
18
+
19
+ ## License
20
+
21
+ MIT
@@ -0,0 +1,46 @@
1
+ /** The subset of the WebMCP API (W3C CG draft, 2026) this plugin uses. */
2
+ export type ModelContextTool = {
3
+ name: string;
4
+ description: string;
5
+ inputSchema?: Record<string, unknown>;
6
+ annotations?: {
7
+ readOnlyHint?: boolean;
8
+ untrustedContentHint?: boolean;
9
+ };
10
+ execute(input: Record<string, unknown>, context?: {
11
+ signal?: AbortSignal;
12
+ }): Promise<string>;
13
+ };
14
+ export type ModelContext = {
15
+ registerTool(tool: ModelContextTool, options?: {
16
+ signal?: AbortSignal;
17
+ }): unknown;
18
+ };
19
+ export type WebMCPOptions = {
20
+ /**
21
+ * Which actions agents can see. 'explicit' (default): only actions whose
22
+ * `exposeTo` includes 'agent'. 'all': every action not hidden from agents.
23
+ */
24
+ include?: 'explicit' | 'all';
25
+ /** Prefix tool names, e.g. 'shop.' (avoids clashes with other scripts). */
26
+ prefix?: string;
27
+ /** Override API discovery (tests, polyfills). */
28
+ modelContext?: ModelContext;
29
+ };
30
+ export type WebMCPState = {
31
+ supported: boolean;
32
+ tools: string[];
33
+ };
34
+ export type WebMCPService = {
35
+ getState(): WebMCPState;
36
+ subscribe(listener: () => void): () => void;
37
+ };
38
+ declare module '@handsforbots/core' {
39
+ interface Services {
40
+ webmcp: WebMCPService;
41
+ }
42
+ }
43
+ /** document.modelContext (current draft) or navigator.modelContext (deprecated location). */
44
+ export declare function findModelContext(): ModelContext | undefined;
45
+ export declare const webmcp: (config?: WebMCPOptions | undefined) => import("@handsforbots/core").Plugin<WebMCPOptions | undefined>;
46
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,0EAA0E;AAC1E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACrC,WAAW,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAC;QAAC,oBAAoB,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;IACxE,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CAC7F,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,YAAY,CAAC,IAAI,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAA;CAClF,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,UAAU,GAAG,KAAK,CAAA;IAC5B,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,iDAAiD;IACjD,YAAY,CAAC,EAAE,YAAY,CAAA;CAC5B,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AAEjE,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,IAAI,WAAW,CAAA;IACvB,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;CAC5C,CAAA;AAED,OAAO,QAAQ,oBAAoB,CAAC;IAClC,UAAU,QAAQ;QAChB,MAAM,EAAE,aAAa,CAAA;KACtB;CACF;AAED,6FAA6F;AAC7F,wBAAgB,gBAAgB,IAAI,YAAY,GAAG,SAAS,CAK3D;AAED,eAAO,MAAM,MAAM,wGAyEjB,CAAA"}
package/dist/index.js ADDED
@@ -0,0 +1,78 @@
1
+ import { definePlugin, toJsonSchema } from '@handsforbots/core';
2
+ /** document.modelContext (current draft) or navigator.modelContext (deprecated location). */
3
+ export function findModelContext() {
4
+ const fromDocument = typeof document !== 'undefined' ? document.modelContext : undefined;
5
+ const fromNavigator = typeof navigator !== 'undefined' ? navigator.modelContext : undefined;
6
+ const mc = fromDocument ?? fromNavigator;
7
+ return mc && typeof mc.registerTool === 'function' ? mc : undefined;
8
+ }
9
+ export const webmcp = definePlugin({
10
+ name: 'expose-webmcp',
11
+ provides: ['webmcp'],
12
+ apply(ctx, options = {}) {
13
+ const modelContext = options.modelContext ?? findModelContext();
14
+ const registered = new Map();
15
+ const listeners = new Set();
16
+ let state = { supported: !!modelContext, tools: [] };
17
+ const changed = () => {
18
+ state = { ...state, tools: [...registered.keys()] };
19
+ for (const listener of listeners)
20
+ listener();
21
+ };
22
+ ctx.provide('webmcp', {
23
+ getState: () => state,
24
+ subscribe(listener) {
25
+ listeners.add(listener);
26
+ return () => listeners.delete(listener);
27
+ },
28
+ });
29
+ if (!modelContext)
30
+ return;
31
+ const visible = (action) => options.include === 'all' ? !action.exposeTo || action.exposeTo.includes('agent') : !!action.exposeTo?.includes('agent');
32
+ const register = (action) => {
33
+ const name = `${options.prefix ?? ''}${action.name}`;
34
+ const controller = new AbortController();
35
+ registered.set(name, { action, controller });
36
+ void Promise.resolve(modelContext.registerTool({
37
+ name,
38
+ description: action.description,
39
+ inputSchema: action.parameters ?? toJsonSchema(action.input) ?? { type: 'object', properties: {} },
40
+ annotations: { readOnlyHint: action.readOnly ?? false },
41
+ // Runs through the kernel queue: validation, `action.before`, confirmation
42
+ // for the `agent` origin, and a visible trace in history.
43
+ execute: async (input) => {
44
+ const outcome = await ctx.app.runAction(action.name, input ?? {}, { origin: 'agent' });
45
+ if (outcome.error)
46
+ throw new Error(outcome.error);
47
+ return typeof outcome.result === 'string' ? outcome.result : JSON.stringify(outcome.result ?? null);
48
+ },
49
+ }, { signal: controller.signal })).catch((error) => {
50
+ registered.delete(name);
51
+ ctx.emit('error', { error, source: `webmcp:${name}` });
52
+ changed();
53
+ });
54
+ };
55
+ const sync = () => {
56
+ const wanted = new Map(ctx.app.actions.list('agent').filter(visible).map((a) => [`${options.prefix ?? ''}${a.name}`, a]));
57
+ for (const [name, entry] of registered) {
58
+ if (wanted.get(name) !== entry.action) {
59
+ entry.controller.abort();
60
+ registered.delete(name);
61
+ }
62
+ }
63
+ for (const [name, action] of wanted)
64
+ if (!registered.has(name))
65
+ register(action);
66
+ changed();
67
+ };
68
+ sync();
69
+ ctx.effect(() => ctx.app.actions.subscribe(sync));
70
+ ctx.onDispose(() => {
71
+ for (const entry of registered.values())
72
+ entry.controller.abort();
73
+ registered.clear();
74
+ listeners.clear();
75
+ });
76
+ },
77
+ });
78
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,40 @@
1
1
  {
2
2
  "name": "@handsforbots/expose-webmcp",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "2.0.0-alpha.0",
4
+ "description": "Expose Hands for Bots actions to browser agents through WebMCP (document.modelContext).",
5
+ "license": "MIT",
6
+ "homepage": "https://github.com/handsforbots/handsforbots/blob/main/docs/en-us/plugins.md#expose-webmcp",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/handsforbots/handsforbots.git",
10
+ "directory": "packages/expose-webmcp"
11
+ },
12
+ "bugs": {
13
+ "url": "https://github.com/handsforbots/handsforbots/issues"
14
+ },
15
+ "type": "module",
16
+ "sideEffects": false,
17
+ "exports": {
18
+ ".": {
19
+ "types": "./dist/index.d.ts",
20
+ "import": "./dist/index.js"
21
+ }
22
+ },
23
+ "publishConfig": {
24
+ "access": "public"
25
+ },
26
+ "files": [
27
+ "dist"
28
+ ],
29
+ "peerDependencies": {
30
+ "@handsforbots/core": "^2.0.0-alpha.0"
31
+ },
32
+ "devDependencies": {
33
+ "jsdom": "^27.0.0",
34
+ "@handsforbots/core": "^2.0.0-alpha.0"
35
+ },
36
+ "scripts": {
37
+ "build": "tsc -p tsconfig.build.json",
38
+ "typecheck": "tsc -p tsconfig.json --noEmit"
39
+ }
6
40
  }