From fff09795d59e447238a019ecca5e6c9c731eb83e Mon Sep 17 00:00:00 2001
From: Kashish Hora <kashishhora@gmail.com>
Date: Fri, 16 Oct 2026 14:42:19 -0400
Subject: [PATCH] docs: explain the clash with webmcp-types

---
 CHANGELOG.md |  8 ++++++++
 README.md    |  4 ++++
 docs/api.md  | 19 +++++++++++++++++++
 3 files changed, 31 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4c9f876..7115d96 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,14 @@ All notable changes to `webmcp-react` are documented here. The format is based o
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+### Deprecated
+
+- **Global `Document.modelContext` type.** Clashes with Google's `webmcp-types`, which
+  declares the same global differently. It'll be removed in 2.0.0. Until then see
+  "TypeScript and webmcp-types" in `docs/api.md`.
+
 ## 1.2.1
 
 ### Added
diff --git a/README.md b/README.md
index 3c92da8..9f83dc3 100644
--- a/README.md
+++ b/README.md
@@ -213,6 +213,10 @@ useMcpTool({
 });
 ```
 
+### TypeScript
+
+`webmcp-react` already types `document.modelContext`, so theres no need to add Google's `webmcp-types` as well. The two packages declare the same global differently and clash if you install both, see [TypeScript and webmcp-types](./docs/api.md#typescript-and-webmcp-types) for details and a workaround.
+
 ### SSR
 
 The library works with Next.js, Remix, and any server-rendering framework. The build includes a `"use client"` banner, so no extra configuration is needed.
diff --git a/docs/api.md b/docs/api.md
index 4d77163..815ed34 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -195,3 +195,22 @@ The polyfill fires only `toolchange`. It does not dispatch `toolactivated` or `t
 An already-aborted `AbortSignal` also rejects: `registerTool` rejects with the signal's abort reason and skips registration, matching the WebMCP spec and native Chrome 152+. Validation errors take precedence — the aborted-signal check runs after the checks above.
 
 The hook routes these rejections into `state.error` and fires `onError`, except `AbortError` (lifecycle teardown), which is ignored.
+
+## TypeScript and `webmcp-types`
+
+Heads up: webmcp-react already declares `document.modelContext` globally (`registerTool`, `getTools`, `executeTool`, the events etc), so you don't need Google's [`webmcp-types`](https://github.com/webmachinelearning/webmcp-types) on top of it.
+
+If you do install both, things get a bit messy. webmcp-types declares the same property as `readonly` with its own `WebMCP.ModelContext` type, and TypeScript wants every declaration of a global property to be indentical. With `skipLibCheck` off you'll get TS2687 and TS2717 errors from the two `.d.ts` files. With it on (Vite and Next.js have it on by default) you won't see any errors, TypeScript just quietly picks whichever decleration it sees first.
+
+If you're using the `"types": ["webmcp-types"]` setup from their README, ours wins. Honestly the only reason to want theirs is if you're calling `document.modelContext.registerTool` directly and want handler args inferred from `inputSchema`. If thats you, create a `webmcp-types.d.ts` with `/// <reference types="webmcp-types" />` in it and put it first in `include`:
+
+```json
+{
+  "compilerOptions": { "skipLibCheck": true },
+  "include": ["webmcp-types.d.ts", "src"]
+}
+```
+
+This depends on file order so it's worth double checking if you move files around. Quick way to tell which one you got: `getTools` and `executeTool` are optional in our type but required in theirs.
+
+We're dropping our global declaration in 2.0, so after that the two packages should play nicely together.