webmcp-types 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 each contributor listed at the beginning of each definition file.
+
+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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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

@@ -0,0 +1,66 @@
+# Typescript Type Definitions for WebMCP
+
+This package defines Typescript types (`.d.ts`) for the [WebMCP specification](https://webmachinelearning.github.io/webmcp).
+
+Use this package to augment the ambient [`"dom"`](https://www.typescriptlang.org/docs/handbook/compiler-options.html#compiler-options) type definitions with the new definitions for WebMCP.
+
+## What are declaration files?
+
+See the [TypeScript handbook](http://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html).
+
+
+## How can I use them?
+
+### Install
+
+- npm: `npm install --save-dev webmcp-types`
+- yarn: `yarn add --dev webmcp-types`
+- pnpm: `pnpm add -D webmcp-types`
+
+### Configure
+
+Since this package is outside DefinitelyTyped, the dependency won't be picked up automatically.
+There are several ways to add a additional TypeScript type definition dependencies to your TypeScript project:
+
+#### TypeScript `tsc` and `tsc`-based bundlers
+
+In `tsconfig.json`:
+
+```js
+{
+  // ...
+  "compilerOptions": {
+    // ...
+    "types": ["webmcp-types"]
+  }
+}
+```
+
+Or you can use `typeRoots`:
+
+```js
+{
+  // ...
+  "compilerOptions": {
+    // ...
+    "typeRoots": ["./node_modules/webmcp-types", "./node_modules/@types"]
+  }
+}
+```
+
+#### Inline in TypeScript
+
+This may work better if your toolchain doesn't read `tsconfig.json`.
+
+```ts
+/// <reference types="webmcp-types" />
+```
+
+#### Webpack
+
+If you use Webpack and the options above aren't sufficient (this has not been verified),
+you may need the following in `webpack.config.js`:
+
+```js
+"types": ["webmcp-types"]
+```

package/index.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The WebMCP API enables web apps to provide JavaScript-based tools to AI agents.
+ */
+declare namespace WebMCP {
+    /**
+     * Callback for tool execution.
+     * @param input The input parameters for the tool, as defined by its inputSchema.
+     * @returns A promise that resolves with the tool's output.
+     */
+    type ToolExecuteCallback = (input: object) => Promise<any>;
+
+    /**
+     * Metadata about a tool's behavior.
+     */
+    interface ToolAnnotations {
+        /**
+         * If `true`, the tool does not modify any state and only reads data.
+         * @default false
+         */
+        readOnlyHint?: boolean;
+        /**
+         * If `true`, indicates the tool may return content from untrusted sources.
+         * @default false
+         */
+        untrustedContentHint?: boolean;
+    }
+
+    /**
+     * Describes a tool to be registered with the model context.
+     */
+    interface ModelContextTool {
+        /**
+         * The name of the tool. Must be 1-128 characters, ASCII alphanumeric, '_', '-', or '.'.
+         */
+        name: string;
+        /**
+         * A human-readable title for the tool.
+         */
+        title?: string;
+        /**
+         * Natural-language description of what the tool does.
+         */
+        description: string;
+        /**
+         * A JSON Schema describing the tool's input parameters.
+         */
+        inputSchema?: object;
+        /**
+         * The function to execute when the tool is called.
+         */
+        execute: ToolExecuteCallback;
+        /**
+         * Metadata about the tool's behavior.
+         */
+        annotations?: ToolAnnotations;
+    }
+
+    /**
+     * Options for registering a tool.
+     */
+    interface ModelContextRegisterToolOptions {
+        /**
+         * An AbortSignal that can be used to unregister the tool.
+         */
+        signal?: AbortSignal;
+        /**
+         * A list of origins that are allowed to call this tool.
+         */
+        exposedTo?: string[];
+    }
+
+    interface ModelContextEventMap {
+        "toolchange": Event;
+    }
+
+    /**
+     * The ModelContext interface provides methods for registering tools.
+     */
+    interface ModelContext extends EventTarget {
+        /**
+         * Registers a new tool.
+         * @param tool The tool definition.
+         * @param options Registration options.
+         */
+        registerTool(tool: ModelContextTool, options?: ModelContextRegisterToolOptions): Promise<void>;
+        /**
+         * Event handler for the toolchange event.
+         */
+        ontoolchange: ((this: ModelContext, ev: Event) => any) | null;
+
+        addEventListener<K extends keyof ModelContextEventMap>(type: K, listener: (this: ModelContext, ev: ModelContextEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+        removeEventListener<K extends keyof ModelContextEventMap>(type: K, listener: (this: ModelContext, ev: ModelContextEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    }
+}
+
+interface Document {
+    /**
+     * The model context for the current document.
+     * May be undefined if the browser doesn't support WebMCP.
+     */
+    readonly modelContext?: WebMCP.ModelContext;
+}

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "webmcp-types",
+  "version": "0.1.0",
+  "repository": "webmachinelearning/webmcp-types",
+  "homepage": "https://github.com/webmachinelearning/webmcp-types",
+  "bugs": "https://github.com/webmachinelearning/webmcp-types/issues",
+  "description": "TypeScript type definitions for WebMCP",
+  "main": "",
+  "types": "index.d.ts",
+  "keywords": [
+    "webmcp",
+    "typescript",
+    "types"
+  ],
+  "license": "MIT"
+}