simple-webmcp 0.1.0

package/.agents/skills/webmcp-simple/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: simple-webmcp
+description: Expose existing JS/TS functions as WebMCP agent tools with minimal boilerplate — function-first, works with vanilla JS, TS, React, Vite, Next.js. Use when the user wants to make functions callable by LLM agents via WebMCP (document.modelContext).
+---
+
+# simple-webmcp Skill
+
+## When to use
+
+Trigger this skill when the user wants to:
+- Expose a JS/TS function to LLM / agentic tool calling via WebMCP
+- Make `addToCart`, `searchCustomers`, `updateCustomer`, etc. available as `document.modelContext` tools
+- Support plain JS, TypeScript, React (scoped lifecycle), or Next.js (server actions) without heavy boilerplate
+
+Do **not** use for consuming external APIs — this skill is for *exposing* your own functions as tools.
+
+## Quick Start
+
+### 1. Vanilla / Vite — 1 line
+
+```ts
+import { webmcp } from 'simple-webmcp';
+
+async function searchCustomers({ query, limit = 20 }: { query: string; limit?: number }) {
+  return customers.filter(c => c.name.includes(query)).slice(0, limit);
+}
+
+// still callable as before, but also a WebMCP tool descriptor
+export const searchTool = webmcp(searchCustomers, {
+  description: 'Search customers in current account',
+  fields: {
+    query: { description: 'Name, email, or ID' },
+    limit: { type: 'integer', minimum: 1, maximum: 50, description: 'Max results' },
+  },
+});
+
+// vanilla global register (outside React)
+await searchTool.register(); // => document.modelContext.registerTool(...)
+searchTool.unregister();
+
+// still callable like original
+await searchTool({ query: 'alice' });
+```
+
+### 2. React — component lifecycle
+
+```tsx
+'use client';
+import { webmcp } from 'simple-webmcp';
+import { useWebMCP, Scope } from 'simple-webmcp/react';
+
+const addToCartTool = webmcp(addToCart, { description: 'Add product to cart' });
+
+export function ProductPage() {
+  // exposed only while component mounted — maps to AbortSignal
+  useWebMCP(addToCartTool);
+  return <div>...</div>;
+}
+
+// Or route/component subtree (also works for Next.js layouts)
+export function CustomersLayout({ children }: { children: React.ReactNode }) {
+  return <Scope tools={[searchTool]}>{children}</Scope>;
+}
+```
+
+### 3. Zod / StandardSchema — per-field or whole
+
+```ts
+import { z } from 'zod';
+import { webmcp } from 'simple-webmcp';
+
+// whole schema
+webmcp(fn, { description: '…', schema: z.object({ query: z.string().min(1), limit: z.number().max(50).optional() }) });
+
+// per-field mix — Lean + Zod
+webmcp(searchCustomers, {
+  description: 'Search',
+  fields: {
+    query: z.string().describe('Name or email'),          // StandardSchema
+    limit: { type: 'integer', minimum: 1, maximum: 50 },  // FieldDef (Partial<JsonSchema>)
+  },
+});
+```
+
+In all cases `schema` (whole) establishes contract; `fields` patches it (adds descriptions, min/max) but does not silently change core type.
+
+### 4. Polyfill (non-Chrome)
+
+```ts
+// before importing tools — no-op in Chrome with native WebMCP
+import 'simple-webmcp/polyfill';
+// or programmatic: import { installPolyfill } from 'simple-webmcp/polyfill'; installPolyfill();
+```
+
+### 5. Global vs Scoped
+
+```ts
+import { webmcp } from 'simple-webmcp';
+// scoped (default) — inert until useWebMCP or .register()
+webmcp(fn, { description: '…' });
+// global — registers on import (client only)
+webmcp(fn, { description: '…', global: true });
+webmcp.global(fn, { description: '…' }); // alias
+```
+
+## Progression Ladder (teach stepwise)
+
+1. **Beginner:** `webmcp(fn)` done.
+2. **Better desc:** `webmcp(fn, { description: '…' })`
+3. **Field docs:** `webmcp(fn, { fields: { query: { description: '…' } } })`
+4. **Full control:** `webmcp(fn, { schema: z.object({…}) })`
+5. **Lifecycle:** `useWebMCP(tool)` / `<Scope tools>`
+
+## Rules
+
+- Always provide `description` (or JSDoc); warning if missing.
+- Prefer single object param `fn({query, limit})` for tools — best inference. Multi-arg legacy deferred to `webmcp.bind` (0.4).
+- Use `readOnlyHint`/`destructiveHint` in `annotations` for agent hints; annotations are extensible `Record<string,unknown>`.
+- Registration is async: `await tool.register()` → `() => void` unregister. React hook handles AbortSignal.
+- `strict:true` makes ambiguous runtime inference a build error instead of warn.
+
+## Inference
+
+- **Runtime** (0.1): param names + defaults → low-confidence `{type:'object'}` placeholder.
+- **Build** (0.2 `simple-webmcp/unplugin` for Vite/Webpack): TS types + JSDoc before erasure. Same API.
+- Never pretend `function search(query)` alone is fully known — warn if no type/schema/fields.
+
+## Next.js Server Actions — experimental (0.3, requires spike)
+
+Do not assume transparent bridge works yet. The spike must verify `webmcp.server(action)` reference survives server/client boundary. Until then, keep server tools as described in docs but behind experimental flag.
+
+## References
+
+- `references/api.md` — full API surface
+- `references/recipes.md` — vanilla, React, Vite, Next patterns
+- `references/build.md` — unplugin inference

package/.agents/skills/webmcp-simple/references/api.md

@@ -0,0 +1,77 @@
+# API Reference — simple-webmcp 0.1
+
+## Core
+
+```ts
+import { webmcp } from 'simple-webmcp';
+
+function webmcp<F extends (...args:any)=>any>(fn: F, options?: WebMCPOptions<F>): WebMCPTool<F>
+namespace webmcp { function global<F>(fn:F, opts?: Omit<WebMCPOptions<F>,'global'>): WebMCPTool<F> }
+
+type WebMCPTool<F> = F & {
+  __webmcpBrand: true;
+  tool: ToolContract; definition: ToolContract;
+  register(opts?: {signal?:AbortSignal}): Promise<()=>void>;
+  unregister(): void;
+  status: 'unregistered'|'registering'|'registered'|'unregistering'|'error';
+  registration: Promise<void>|null;
+  isRegistered(): boolean;
+}
+
+type WebMCPOptions<F> = {
+  name?: string; description?: string;
+  schema?: JsonSchema | StandardSchemaV1; // whole contract (Zod, Valibot etc or JSON)
+  outputSchema?: JsonSchema | StandardSchemaV1;
+  fields?: Record<string, FieldDef|StandardSchemaV1>; // FieldDef = Partial<JsonSchema>
+  annotations?: Record<string,unknown> & {readOnlyHint?, destructiveHint?, openWorldHint?, title?}
+  scope?: 'global'|'scoped'|'manual'; global?: boolean; enabled?: boolean; strict?: boolean;
+}
+
+type ToolContract = { name:string; description:string; inputSchema:JsonSchema; outputSchema?:JsonSchema; annotations?:Record<string,unknown> }
+```
+
+Hierarchy: `schema` (whole) → inferred (runtime 0.1 / build 0.2) → `fields` patch → metadata.
+
+`fields` example:
+
+```ts
+fields: {
+  query: { description:'Name or email' },
+  limit: { type:'integer', minimum:1, maximum:50 }
+  // or per-field Zod: query: z.string().describe('...')
+}
+```
+
+Errors: `SimpleWebMCPError` → `NotSupportedError`, `NotAllowedError` (Permissions Policy), `RegistrationError`, `ValidationError`, `ConfigurationError` — each `code` + `cause`.
+
+Utils:
+
+```ts
+import { isWebMCPSupported, getModelContext, toSnakeCase, registry } from 'simple-webmcp';
+```
+
+## React
+
+```ts
+import { useWebMCP, Scope } from 'simple-webmcp/react'; // 'use client'
+
+function useWebMCP<F>(tool: WebMCPTool<F>, opts?:{enabled?:boolean}): {supported:boolean; registered:boolean; error:Error|null; isPolyfilled:boolean; status:string}
+function Scope({tools, enabled, children}: {tools:WebMCPTool<any>[]; enabled?:boolean; children?:React.ReactNode}): JSX.Element
+```
+
+## Polyfill
+
+```ts
+import 'simple-webmcp/polyfill'; // auto
+import { installPolyfill, isPolyfilled } from 'simple-webmcp/polyfill';
+```
+
+## Next (experimental, 0.3)
+
+```ts
+// after spike passes
+import { webmcp } from 'simple-webmcp/next';
+const tool = webmcp.server(action, opts); // action is 'use server' fn
+```
+
+Not in 0.1 — do not depend yet.

package/.agents/skills/webmcp-simple/references/recipes.md

@@ -0,0 +1,113 @@
+# Recipes
+
+## Vanilla JS (Vite, plain TS)
+
+```ts
+import { webmcp } from 'simple-webmcp';
+import 'simple-webmcp/polyfill'; // dev only
+
+export async function addToCart({ productId, quantity }: { productId: string; quantity: number }) {
+  cart.push({ productId, quantity });
+  return { ok: true };
+}
+
+export const addToCartTool = webmcp(addToCart, {
+  description: 'Add product to shopping cart',
+  fields: {
+    productId: { description: 'Product ID' },
+    quantity: { type: 'integer', minimum: 1 },
+  },
+  annotations: { readOnlyHint: false },
+});
+
+// outside React — register programmatically
+await addToCartTool.register();
+// still call directly
+await addToCartTool({ productId: 'p_123', quantity: 2 });
+```
+
+## TypeScript + Zod (per-field)
+
+```ts
+import { z } from 'zod';
+import { webmcp } from 'simple-webmcp';
+
+async function searchCustomers({ query, limit }: { query: string; limit?: number }) {
+  // ...
+}
+
+export const searchTool = webmcp(searchCustomers, {
+  description: 'Search customers',
+  fields: {
+    query: z.string().min(1).describe('Name, email, or ID'),
+    limit: z.number().int().min(1).max(50).optional().describe('Max results'),
+  },
+});
+```
+
+## Zod whole schema
+
+```ts
+webmcp(fn, { description: '…', schema: z.object({ query: z.string(), limit: z.number().optional() }) });
+```
+
+## React — page level
+
+```tsx
+'use client';
+import { webmcp } from 'simple-webmcp';
+import { useWebMCP } from 'simple-webmcp/react';
+
+const searchTool = webmcp(searchCustomers, { description: 'Search' });
+
+export function SearchPage() {
+  useWebMCP(searchTool);
+  return <SearchUI />;
+}
+```
+
+## React — layout/route scope
+
+```tsx
+'use client';
+import { Scope } from 'simple-webmcp/react';
+import { searchTool, updateTool } from '@/lib/tools';
+
+export function CustomersLayout({ children }: { children: React.ReactNode }) {
+  // Tools exposed while layout mounted → natural route scope in Next.js layouts
+  return <Scope tools={[searchTool, updateTool]}>{children}</Scope>;
+}
+```
+
+## Global (entire app)
+
+```ts
+import { webmcp } from 'simple-webmcp';
+webmcp.global(searchCustomers, { description: 'Global search' });
+// or
+webmcp(searchCustomers, { description: 'Search', global: true });
+```
+
+## Strict mode (warn vs error)
+
+```ts
+// default: dev warn if no type/schema/fields
+webmcp(fnWithoutTypes, { description: '…' }); // warn
+
+// strict: throw
+webmcp(fnWithoutTypes, { description: '…', strict: true }); // throws ConfigurationError
+```
+
+## Inference tips
+
+- Best: `async function fn({query, limit}:{query:string, limit?:number})` — runtime sees `query` required, `limit` optional default
+- Better with build (0.2 `simple-webmcp/unplugin`): TS type + JSDoc `@param query ...` → full schema, no manual `fields`
+- Fallback for plain JS: add `fields` or `schema` explicitly
+
+## Global registry for tests
+
+```ts
+import { registry } from 'simple-webmcp';
+registry.list(); // [{name, status}]
+registry.clear();
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muhammed Emin Gure (https://github.com/emingure)
+
+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,136 @@
+# simple-webmcp
+
+> Turn any JS/TS function into a WebMCP tool — `webmcp(fn)` stays callable, auto-registers with React lifecycle or globally. Minimal, typed, framework-agnostic.
+
+```ts
+import { webmcp } from 'simple-webmcp';
+
+async function searchCustomers({ query, limit = 20 }: { query: string; limit?: number }) {
+  return customers.filter(c => c.name.includes(query)).slice(0, limit);
+}
+
+// One line — same function, now also a tool
+export const searchTool = webmcp(searchCustomers, {
+  description: 'Search customers in current account',
+  fields: { query: { description: 'Name, email, or ID' } },
+});
+
+await searchTool({ query: 'alice' }); // still just a function
+await searchTool.register(); // => document.modelContext.registerTool(...)
+// or React: useWebMCP(searchTool) → mounted = exposed
+```
+
+Works with plain JS, TS, React, Vite… (Next.js Server Actions experimental 0.3). Open source, lean (`sideEffects:false`, core no React dep).
+
+**Docs:** https://emingure.github.io/simple-webmcp/ (via GitHub Pages)
+
+## Install
+
+```bash
+npm i simple-webmcp
+# React is optional peer (≥18) only if you import simple-webmcp/react
+# Repo: https://github.com/emingure/simple-webmcp
+```
+
+## Quick Start
+
+| Need | Code |
+|------|------|
+| Vanilla — global | `webmcp(fn,{description, global:true})` or `await tool.register()` |
+| Vanilla — manual | `tool.register()` / `tool.unregister()` |
+| React — page | `useWebMCP(tool)` while component mounted |
+| React — layout / route | `<Scope tools={[a,b]}>{children}</Scope>` |
+| Rate-limited / disabled | `webmcp(fn,{enabled:false})` |
+| Polyfill (Firefox/Safari) | `import 'simple-webmcp/polyfill'` |
+
+## Schema
+
+Hierarchy **corrected per review**: `schema` (whole) → inferred (runtime 0.1 / build 0.2 TS/JSDoc) → `fields` patch → metadata override.
+
+```ts
+// prefer single object param fn({query, limit}) for best inference
+webmcp(fn, { description:'…', fields:{ query:{description:'…'}, limit:{type:'integer', maximum:50} } });
+
+// whole Zod / StandardSchema — requires `simple-webmcp/zod` side-effect (keeps core lean)
+import { z } from 'zod';
+import 'simple-webmcp/zod'; // enables Zod → JSON Schema in core
+webmcp(fn, { description:'…', schema: z.object({ query: z.string().min(1) }) });
+
+// per-field mix — same import enables it
+webmcp(fn, { fields:{ query: z.string().describe('…'), limit:{type:'integer'} } });
+
+// JSON Schema directly
+webmcp(fn, { schema:{type:'object', properties:{query:{type:'string'}}, required:['query']} });
+```
+
+`fields` is a **patch** (`Partial<JsonSchema>` or per-field `StandardSchema`) — annotates, does not silently replace core type. Provide `strict:true` to make ambiguous runtime inference throw instead of warn.
+
+## React
+
+```tsx
+'use client';
+import { webmcp } from 'simple-webmcp';
+import { useWebMCP, Scope } from 'simple-webmcp/react';
+
+const tool = webmcp(fn, { description:'…' });
+
+export function Page() {
+  const { supported, registered, error } = useWebMCP(tool);
+  return null; // exposed while mounted — maps to AbortSignal
+}
+
+// layout-level route scope (Next.js app/layout.tsx naturally gives route scope)
+<Scope tools={[toolA, toolB]}>{children}</Scope>
+```
+
+## Polyfill
+
+`simple-webmcp/polyfill` is an adapter entry (not hard-coded to one impl). It installs a thin in-memory shim if `document.modelContext` missing, shielding spec churn. For full MCP transport, install `@mcp-b/global` before.
+
+```ts
+import 'simple-webmcp/polyfill';
+import { installPolyfill } from 'simple-webmcp/polyfill'; // programmatic
+```
+
+## API
+
+See `.agents/skills/webmcp-simple/references/api.md` and examples `examples/`.
+
+### Core
+
+- `webmcp(fn, opts)` → `WebMCPTool<F>` (callable + `tool/definition/register/unregister/status`)
+- `webmcp.global(fn, opts)` alias
+- `isWebMCPSupported()`, `toSnakeCase`, `registry.list()/clear()`
+- Errors: `NotSupportedError`, `NotAllowedError` (Permissions Policy), `RegistrationError`, `ValidationError`, `ConfigurationError`
+
+### React
+
+- `useWebMCP(tool, {enabled})`
+- `<Scope tools>`
+
+### Errors & Lifecycle
+
+`register()` is async `Promise<()=>void>` per current WebMCP types. `status: 'unregistered'|'registering'|'registered'|'unregistering'|'error'`. Use `tool.status` / `tool.isRegistered()`; hook exposes `supported/registered/error`.
+
+## Development
+
+```bash
+npm run build      # tsup ESM+CJS+DTS
+npm test           # vitest jsdom
+npm run typecheck
+```
+
+## Versioning
+
+- **0.1** — `webmcp()` + `useWebMCP` + `Scope` + runtime fallback + polyfill adapter + tests (this release)
+- **0.2** — `simple-webmcp/unplugin` TS/JSDoc build inference (Vite/Webpack)
+- **0.3** — `simple-webmcp/next` `webmcp.server()` — experimental, gated behind working `fixtures/next-app` spike (verifies Server Action reference survival)
+- **0.4** — `webmcp.bind()`, DevTools, CLI
+
+## Skills (Agent)
+
+This package ships `.agents/skills/webmcp-simple/SKILL.md` for auto-discovery by OpenCode/Claude. No install needed — agents discover via `.agents/skills/`.
+
+## License
+
+MIT