@protocoltooling/fullcalendar 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robertonevarez
+
+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,159 @@
+# FullCalendar WebMCP
+
+**FullCalendar WebMCP** is published by **Protocol Tooling**.
+
+It exposes standard WebMCP calendar tools (`calendar_get_context`, `calendar_list_events`, `calendar_get_event`, `calendar_create_event`, `calendar_update_event`, `calendar_delete_event`) over existing FullCalendar React instances and host persistence without altering the application's UI, mutation workflows, or database architecture.
+
+## Installation
+
+```bash
+npm install @protocoltooling/fullcalendar
+```
+
+### Local / Tarball Installation (Development)
+
+```bash
+npm pack
+npm install /path/to/protocoltooling-fullcalendar-0.1.0.tgz
+```
+
+### Peer Dependencies
+
+Ensure host peer dependencies are installed:
+
+- `react`: `>=17 <20`
+- `@fullcalendar/react`: `^6.0.0 || ^7.0.0`
+
+---
+
+## Minimal Integration
+
+```tsx
+import FullCalendar from "@fullcalendar/react"; // v6 or v7
+import { useCallback, useRef, useState } from "react";
+import {
+  useFullCalendarWebMCP,
+  type CalendarEvent,
+  type CalendarEventRepository,
+} from "@protocoltooling/fullcalendar";
+
+export function MyCalendar() {
+  const calendarRef = useRef<FullCalendar>(null);
+  const [events, setEvents] = useState<CalendarEvent[]>([]);
+
+  const reloadEvents = useCallback(async () => {
+    const data = await eventRepository.list();
+    setEvents(data);
+    return data;
+  }, []);
+
+  useFullCalendarWebMCP({
+    calendarRef,
+    events: eventRepository,
+    onEventsChanged: reloadEvents,
+  });
+
+  return (
+    <FullCalendar
+      ref={calendarRef}
+      events={events}
+      /* ... other FullCalendar options */
+    />
+  );
+}
+```
+
+---
+
+## Repository Contract
+
+The host provides an object implementing `CalendarEventRepository` mapped to its existing database or API:
+
+```ts
+import type {
+  CalendarEvent,
+  CalendarEventQuery,
+  CalendarEventRepository,
+  CreateCalendarEventInput,
+  UpdateCalendarEventInput,
+} from "@protocoltooling/fullcalendar";
+
+export const eventRepository: CalendarEventRepository = {
+  async list(query?: CalendarEventQuery, options?: { signal?: AbortSignal }): Promise<CalendarEvent[]> {
+    return api.events.list(query, options);
+  },
+  async get(id: string, options?: { signal?: AbortSignal }): Promise<CalendarEvent | null> {
+    return api.events.get(id, options);
+  },
+  async create(input: CreateCalendarEventInput, options?: { signal?: AbortSignal }): Promise<CalendarEvent> {
+    return api.events.create(input, options);
+  },
+  async update(id: string, input: UpdateCalendarEventInput, options?: { signal?: AbortSignal }): Promise<CalendarEvent> {
+    return api.events.update(id, input, options);
+  },
+  async delete(id: string, options?: { signal?: AbortSignal }): Promise<void> {
+    return api.events.delete(id, options);
+  },
+};
+```
+
+---
+
+## Persistence Model
+
+> **FullCalendar WebMCP does not persist calendar events itself. The host application's persistence remains authoritative.**
+
+Agent mutations and human interactions (e.g. dragging, resizing, modal editing) converge on the host application's authoritative persistence. The integration maintains no secondary event ledger.
+
+---
+
+## Supported Architecture
+
+- **React:** React 17, 18, and 19.
+- **FullCalendar React:** FullCalendar React v6 class instances (`RefObject<FullCalendar | null>`) and FullCalendar React v7 handles (`RefObject<CalendarRef | null>`).
+- **Runtime:** WebMCP runtime required for tool registration (`document.modelContext.registerTool`).
+- **Framework Agnostic:** Compatible with Next.js (App Router & Pages Router), Vite, Remix / React Router, TanStack Start, or pure client SPAs.
+- **Backend Agnostic:** Works with Server Actions, REST, GraphQL, Supabase / PostgreSQL, ORMs, or custom APIs.
+
+---
+
+## Server-Side Rendering (SSR) & Lifecycle
+
+- **SSR-Safe:** The package contains no top-level browser global (`window`, `document`) access. Server rendering completes without error.
+- **Client Lifecycle:** Tool registration occurs inside `useEffect` via an `AbortController`. React Strict Mode replay and unmount cleanup properly unregister tools with zero orphaned state.
+- **Delayed Runtime:** Automatically waits for late-injected WebMCP runtime if not immediately present at mount time.
+- **React Server Components (RSC):** The package entry includes the `'use client';` directive for seamless import into Next.js App Router client components.
+
+---
+
+## Package migration
+
+Previous package: `protocoltooling`  
+Current package: `@protocoltooling/fullcalendar`  
+The old package is deprecated.
+
+---
+
+## Development & Verification
+
+```bash
+# Build library package (dist/index.js, dist/index.d.ts)
+npm run build:lib
+
+# Run unit, integration, public type, and SSR tests
+npm test
+
+# Run typecheck & linter
+npm run typecheck
+npm run lint
+
+# Build package tarball and test in external Vite and Next.js consumers
+npm run test:pack
+
+# Run interactive dev example
+npm run dev
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,92 @@
+import { RefObject } from 'react';
+
+/**
+ * Normalized calendar event model.
+ */
+interface CalendarEvent {
+    id: string;
+    title: string;
+    start: string;
+    end: string | null;
+    allDay: boolean;
+}
+/**
+ * Input payload for creating a new calendar event.
+ */
+interface CreateCalendarEventInput {
+    title: string;
+    start: string;
+    end?: string | null;
+    allDay?: boolean;
+}
+/**
+ * Input payload for updating an existing calendar event.
+ */
+interface UpdateCalendarEventInput {
+    title?: string;
+    start?: string;
+    end?: string | null;
+    allDay?: boolean;
+}
+/**
+ * Filter criteria for querying calendar events.
+ */
+interface CalendarEventQuery {
+    start?: string;
+    end?: string;
+    text?: string;
+}
+/**
+ * Authoritative host repository contract for calendar event persistence.
+ * The host application implements this interface over its existing storage or backend API.
+ */
+interface CalendarEventRepository {
+    list(query?: CalendarEventQuery, options?: {
+        signal?: AbortSignal;
+    }): Promise<CalendarEvent[]>;
+    get(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<CalendarEvent | null>;
+    create(input: CreateCalendarEventInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<CalendarEvent>;
+    update(id: string, input: UpdateCalendarEventInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<CalendarEvent>;
+    delete(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+/**
+ * Minimal structural FullCalendar surface required by WebMCP tools.
+ * Compatible with FullCalendar React v6 class instances and v7 CalendarRef handles.
+ */
+interface FullCalendarHandle {
+    getApi(): {
+        getOption(name: string): unknown;
+        view: {
+            type: string;
+            activeStart: Date;
+            activeEnd: Date;
+        };
+    };
+}
+/**
+ * Options for the useFullCalendarWebMCP hook.
+ */
+interface FullCalendarWebMCPOptions {
+    calendarRef: RefObject<FullCalendarHandle | null>;
+    events: CalendarEventRepository;
+    onEventsChanged: () => unknown | Promise<unknown>;
+    onRegistrationError?: (error: unknown) => void;
+}
+
+/**
+ * Primary React hook integrating FullCalendar with the browser WebMCP model context.
+ *
+ * Provides safe client-side registration, unmount cleanup, and continuous
+ * binding to host persistence callbacks without re-registering tools across renders.
+ */
+declare function useFullCalendarWebMCP(options: FullCalendarWebMCPOptions): void;
+
+export { type CalendarEvent, type CalendarEventQuery, type CalendarEventRepository, type CreateCalendarEventInput, type FullCalendarHandle, type FullCalendarWebMCPOptions, type UpdateCalendarEventInput, useFullCalendarWebMCP };

package/dist/index.js

@@ -0,0 +1,229 @@
+'use client';
+import { useRef, useEffect } from 'react';
+
+// src/use-fullcalendar-webmcp.ts
+
+// src/tool-definitions.ts
+var emptySchema = {
+  type: "object",
+  properties: {},
+  additionalProperties: false
+};
+var eventProperties = {
+  title: {
+    type: "string",
+    minLength: 1,
+    description: "The human-readable event title."
+  },
+  start: {
+    type: "string",
+    format: "date-time",
+    description: "Inclusive event start as ISO 8601 with an explicit offset."
+  },
+  end: {
+    type: ["string", "null"],
+    format: "date-time",
+    description: "Exclusive event end as ISO 8601 with an explicit offset, or null."
+  },
+  allDay: {
+    type: "boolean",
+    description: "Whether the event is an all-day event."
+  }
+};
+function readAnnotations() {
+  return { readOnlyHint: true, untrustedContentHint: true };
+}
+function writeAnnotations() {
+  return { readOnlyHint: false, untrustedContentHint: true };
+}
+function createCalendarTools(readOptions) {
+  return [
+    {
+      name: "calendar_get_context",
+      title: "Get calendar context",
+      description: "Get the current time, resolved browser timezone, FullCalendar timezone, visible date range, and active view. Call this before interpreting relative dates such as Wednesday or tomorrow.",
+      inputSchema: emptySchema,
+      annotations: readAnnotations(),
+      async execute() {
+        const api = readOptions().calendarRef.current?.getApi();
+        return {
+          now: (/* @__PURE__ */ new Date()).toISOString(),
+          browserTimeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+          fullCalendarTimeZone: api?.getOption("timeZone") ?? "local",
+          view: api?.view.type ?? null,
+          visibleRange: api ? {
+            start: api.view.activeStart.toISOString(),
+            end: api.view.activeEnd.toISOString()
+          } : null
+        };
+      }
+    },
+    {
+      name: "calendar_list_events",
+      title: "List calendar events",
+      description: "List persisted calendar events, optionally filtered by an inclusive start, exclusive end, or case-insensitive title text. Use an end boundary one day after the requested day.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          start: {
+            type: "string",
+            format: "date-time",
+            description: "Inclusive ISO 8601 lower bound."
+          },
+          end: {
+            type: "string",
+            format: "date-time",
+            description: "Exclusive ISO 8601 upper bound."
+          },
+          text: {
+            type: "string",
+            description: "Optional case-insensitive title substring."
+          }
+        },
+        additionalProperties: false
+      },
+      annotations: readAnnotations(),
+      async execute(query, { signal }) {
+        const events = await readOptions().events.list(query, { signal });
+        return { events };
+      }
+    },
+    {
+      name: "calendar_get_event",
+      title: "Get calendar event",
+      description: "Get one persisted calendar event by its stable event ID.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string", minLength: 1, description: "Stable event ID." }
+        },
+        required: ["id"],
+        additionalProperties: false
+      },
+      annotations: readAnnotations(),
+      async execute(input, { signal }) {
+        const { id } = input;
+        const event = await readOptions().events.get(id, { signal });
+        return { event };
+      }
+    },
+    {
+      name: "calendar_create_event",
+      title: "Create calendar event",
+      description: "Create and persist a generic calendar event. Times must be ISO 8601 values with explicit offsets. Returns the host-assigned stable event ID.",
+      inputSchema: {
+        type: "object",
+        properties: eventProperties,
+        required: ["title", "start"],
+        additionalProperties: false
+      },
+      annotations: writeAnnotations(),
+      async execute(rawInput, { signal }) {
+        const input = rawInput;
+        const options = readOptions();
+        const event = await options.events.create(input, { signal });
+        await options.onEventsChanged();
+        return { event };
+      }
+    },
+    {
+      name: "calendar_update_event",
+      title: "Update calendar event",
+      description: "Update selected fields on one persisted calendar event using its stable event ID. Omitted fields remain unchanged.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string", minLength: 1, description: "Stable event ID." },
+          ...eventProperties
+        },
+        required: ["id"],
+        minProperties: 2,
+        additionalProperties: false
+      },
+      annotations: writeAnnotations(),
+      async execute(rawInput, { signal }) {
+        const { id, ...input } = rawInput;
+        const options = readOptions();
+        const event = await options.events.update(id, input, { signal });
+        await options.onEventsChanged();
+        return { event };
+      }
+    },
+    {
+      name: "calendar_delete_event",
+      title: "Delete calendar event",
+      description: "Delete one persisted calendar event by its stable event ID.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string", minLength: 1, description: "Stable event ID." }
+        },
+        required: ["id"],
+        additionalProperties: false
+      },
+      annotations: writeAnnotations(),
+      async execute(input, { signal }) {
+        const { id } = input;
+        const options = readOptions();
+        await options.events.delete(id, { signal });
+        await options.onEventsChanged();
+        return { deleted: true, id };
+      }
+    }
+  ];
+}
+
+// src/register-tools.ts
+var RUNTIME_POLL_INTERVAL_MS = 250;
+function registerCalendarToolsWhenAvailable(readOptions, lifecycleSignal) {
+  let retryTimer;
+  const register = async () => {
+    if (lifecycleSignal.aborted) return;
+    const modelContext = document.modelContext;
+    if (!modelContext) {
+      retryTimer = window.setTimeout(register, RUNTIME_POLL_INTERVAL_MS);
+      return;
+    }
+    const registration = new AbortController();
+    const unregister = () => registration.abort(lifecycleSignal.reason);
+    lifecycleSignal.addEventListener("abort", unregister, { once: true });
+    try {
+      await Promise.all(
+        createCalendarTools(readOptions).map(
+          (tool) => modelContext.registerTool(tool, { signal: registration.signal })
+        )
+      );
+    } catch (error) {
+      registration.abort();
+      if (!lifecycleSignal.aborted) {
+        readOptions().onRegistrationError?.(error);
+      }
+    }
+  };
+  void register();
+  lifecycleSignal.addEventListener(
+    "abort",
+    () => {
+      if (retryTimer !== void 0) window.clearTimeout(retryTimer);
+    },
+    { once: true }
+  );
+}
+
+// src/use-fullcalendar-webmcp.ts
+function useFullCalendarWebMCP(options) {
+  const latestOptions = useRef(options);
+  latestOptions.current = options;
+  useEffect(() => {
+    const lifecycle = new AbortController();
+    registerCalendarToolsWhenAvailable(
+      () => latestOptions.current,
+      lifecycle.signal
+    );
+    return () => lifecycle.abort();
+  }, []);
+}
+
+export { useFullCalendarWebMCP };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/tool-definitions.ts","../src/register-tools.ts","../src/use-fullcalendar-webmcp.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/// <reference types=\"webmcp-types\" />\n\nimport type {\n  CreateCalendarEventInput,\n  FullCalendarWebMCPOptions,\n  UpdateCalendarEventInput,\n} from \"./types\";\n\ntype OptionsReader = () => FullCalendarWebMCPOptions;\n\nconst emptySchema = {\n  type: \"object\",\n  properties: {},\n  additionalProperties: false,\n} as const;\n\nconst eventProperties = {\n  title: {\n    type: \"string\",\n    minLength: 1,\n    description: \"The human-readable event title.\",\n  },\n  start: {\n    type: \"string\",\n    format: \"date-time\",\n    description: \"Inclusive event start as ISO 8601 with an explicit offset.\",\n  },\n  end: {\n    type: [\"string\", \"null\"],\n    format: \"date-time\",\n    description: \"Exclusive event end as ISO 8601 with an explicit offset, or null.\",\n  },\n  allDay: {\n    type: \"boolean\",\n    description: \"Whether the event is an all-day event.\",\n  },\n} as const;\n\nfunction readAnnotations(): WebMCP.ToolAnnotations {\n  return { readOnlyHint: true, untrustedContentHint: true };\n}\n\nfunction writeAnnotations(): WebMCP.ToolAnnotations {\n  return { readOnlyHint: false, untrustedContentHint: true };\n}\n\nexport function createCalendarTools(\n  readOptions: OptionsReader,\n): WebMCP.ModelContextTool[] {\n  return [\n    {\n      name: \"calendar_get_context\",\n      title: \"Get calendar context\",\n      description:\n        \"Get the current time, resolved browser timezone, FullCalendar timezone, visible date range, and active view. Call this before interpreting relative dates such as Wednesday or tomorrow.\",\n      inputSchema: emptySchema,\n      annotations: readAnnotations(),\n      async execute() {\n        const api = readOptions().calendarRef.current?.getApi();\n        return {\n          now: new Date().toISOString(),\n          browserTimeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,\n          fullCalendarTimeZone: api?.getOption(\"timeZone\") ?? \"local\",\n          view: api?.view.type ?? null,\n          visibleRange: api\n            ? {\n                start: api.view.activeStart.toISOString(),\n                end: api.view.activeEnd.toISOString(),\n              }\n            : null,\n        };\n      },\n    },\n    {\n      name: \"calendar_list_events\",\n      title: \"List calendar events\",\n      description:\n        \"List persisted calendar events, optionally filtered by an inclusive start, exclusive end, or case-insensitive title text. Use an end boundary one day after the requested day.\",\n      inputSchema: {\n        type: \"object\",\n        properties: {\n          start: {\n            type: \"string\",\n            format: \"date-time\",\n            description: \"Inclusive ISO 8601 lower bound.\",\n          },\n          end: {\n            type: \"string\",\n            format: \"date-time\",\n            description: \"Exclusive ISO 8601 upper bound.\",\n          },\n          text: {\n            type: \"string\",\n            description: \"Optional case-insensitive title substring.\",\n          },\n        },\n        additionalProperties: false,\n      },\n      annotations: readAnnotations(),\n      async execute(\n        query: { start?: string; end?: string; text?: string },\n        { signal },\n      ) {\n        const events = await readOptions().events.list(query, { signal });\n        return { events };\n      },\n    },\n    {\n      name: \"calendar_get_event\",\n      title: \"Get calendar event\",\n      description: \"Get one persisted calendar event by its stable event ID.\",\n      inputSchema: {\n        type: \"object\",\n        properties: {\n          id: { type: \"string\", minLength: 1, description: \"Stable event ID.\" },\n        },\n        required: [\"id\"],\n        additionalProperties: false,\n      },\n      annotations: readAnnotations(),\n      async execute(input, { signal }) {\n        const { id } = input as { id: string };\n        const event = await readOptions().events.get(id, { signal });\n        return { event };\n      },\n    },\n    {\n      name: \"calendar_create_event\",\n      title: \"Create calendar event\",\n      description:\n        \"Create and persist a generic calendar event. Times must be ISO 8601 values with explicit offsets. Returns the host-assigned stable event ID.\",\n      inputSchema: {\n        type: \"object\",\n        properties: eventProperties,\n        required: [\"title\", \"start\"],\n        additionalProperties: false,\n      },\n      annotations: writeAnnotations(),\n      async execute(rawInput, { signal }) {\n        const input = rawInput as unknown as CreateCalendarEventInput;\n        const options = readOptions();\n        const event = await options.events.create(input, { signal });\n        await options.onEventsChanged();\n        return { event };\n      },\n    },\n    {\n      name: \"calendar_update_event\",\n      title: \"Update calendar event\",\n      description:\n        \"Update selected fields on one persisted calendar event using its stable event ID. Omitted fields remain unchanged.\",\n      inputSchema: {\n        type: \"object\",\n        properties: {\n          id: { type: \"string\", minLength: 1, description: \"Stable event ID.\" },\n          ...eventProperties,\n        },\n        required: [\"id\"],\n        minProperties: 2,\n        additionalProperties: false,\n      },\n      annotations: writeAnnotations(),\n      async execute(rawInput, { signal }) {\n        const { id, ...input } = rawInput as unknown as UpdateCalendarEventInput & {\n          id: string;\n        };\n        const options = readOptions();\n        const event = await options.events.update(id, input, { signal });\n        await options.onEventsChanged();\n        return { event };\n      },\n    },\n    {\n      name: \"calendar_delete_event\",\n      title: \"Delete calendar event\",\n      description: \"Delete one persisted calendar event by its stable event ID.\",\n      inputSchema: {\n        type: \"object\",\n        properties: {\n          id: { type: \"string\", minLength: 1, description: \"Stable event ID.\" },\n        },\n        required: [\"id\"],\n        additionalProperties: false,\n      },\n      annotations: writeAnnotations(),\n      async execute(input, { signal }) {\n        const { id } = input as { id: string };\n        const options = readOptions();\n        await options.events.delete(id, { signal });\n        await options.onEventsChanged();\n        return { deleted: true, id };\n      },\n    },\n  ];\n}\n","import { createCalendarTools } from \"./tool-definitions\";\nimport type { FullCalendarWebMCPOptions } from \"./types\";\n\nconst RUNTIME_POLL_INTERVAL_MS = 250;\n\nexport function registerCalendarToolsWhenAvailable(\n  readOptions: () => FullCalendarWebMCPOptions,\n  lifecycleSignal: AbortSignal,\n) {\n  let retryTimer: number | undefined;\n\n  const register = async () => {\n    if (lifecycleSignal.aborted) return;\n\n    const modelContext = document.modelContext;\n    if (!modelContext) {\n      retryTimer = window.setTimeout(register, RUNTIME_POLL_INTERVAL_MS);\n      return;\n    }\n\n    const registration = new AbortController();\n    const unregister = () => registration.abort(lifecycleSignal.reason);\n    lifecycleSignal.addEventListener(\"abort\", unregister, { once: true });\n\n    try {\n      await Promise.all(\n        createCalendarTools(readOptions).map((tool) =>\n          modelContext.registerTool(tool, { signal: registration.signal }),\n        ),\n      );\n    } catch (error) {\n      registration.abort();\n      if (!lifecycleSignal.aborted) {\n        readOptions().onRegistrationError?.(error);\n      }\n    }\n  };\n\n  void register();\n\n  lifecycleSignal.addEventListener(\n    \"abort\",\n    () => {\n      if (retryTimer !== undefined) window.clearTimeout(retryTimer);\n    },\n    { once: true },\n  );\n}\n","import { useEffect, useRef } from \"react\";\nimport { registerCalendarToolsWhenAvailable } from \"./register-tools\";\nimport type { FullCalendarWebMCPOptions } from \"./types\";\n\n/**\n * Primary React hook integrating FullCalendar with the browser WebMCP model context.\n *\n * Provides safe client-side registration, unmount cleanup, and continuous\n * binding to host persistence callbacks without re-registering tools across renders.\n */\nexport function useFullCalendarWebMCP(options: FullCalendarWebMCPOptions): void {\n  const latestOptions = useRef(options);\n  latestOptions.current = options;\n\n  useEffect(() => {\n    const lifecycle = new AbortController();\n    registerCalendarToolsWhenAvailable(\n      () => latestOptions.current,\n      lifecycle.signal,\n    );\n    return () => lifecycle.abort();\n  }, []);\n}\n"]}

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@protocoltooling/fullcalendar",
+  "version": "0.1.0",
+  "description": "Add WebMCP tools to FullCalendar React applications.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "webmcp",
+    "fullcalendar",
+    "react",
+    "mcp",
+    "model-context-protocol",
+    "calendar",
+    "ai-agents"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/robertonevarez/protocoltooling.git"
+  },
+  "homepage": "https://github.com/robertonevarez/protocoltooling#readme",
+  "bugs": {
+    "url": "https://github.com/robertonevarez/protocoltooling/issues"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "dev": "vite",
+    "build": "npm run build:lib && vite build",
+    "build:lib": "tsup",
+    "prepublishOnly": "npm run build:lib",
+    "docs:dev": "blume dev",
+    "docs:build": "blume build",
+    "docs:check": "blume check",
+    "docs:validate": "blume validate",
+    "docs:audit": "blume audit",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:types": "tsc --noEmit -p tsconfig.json",
+    "test:pack": "node ./scripts/test-pack.js"
+  },
+  "peerDependencies": {
+    "@fullcalendar/react": "^6.0.0 || ^7.0.0",
+    "react": ">=17 <20"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@fullcalendar/react": "7.0.2",
+    "@testing-library/jest-dom": "7.0.1",
+    "@testing-library/react": "16.3.3",
+    "@types/node": "24.10.13",
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
+    "@vitejs/plugin-react": "6.1.1",
+    "blume": "^1.5.3",
+    "eslint": "10.0.1",
+    "globals": "17.11.0",
+    "jsdom": "30.0.1",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "temporal-polyfill": "1.0.1",
+    "tsup": "8.5.1",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.68.0",
+    "vite": "8.2.2",
+    "vitest": "4.1.11",
+    "webmcp-types": "0.1.5"
+  }
+}