@frontmcp/react 0.0.1

package/esm/package.json

@@ -0,0 +1,111 @@
+{
+  "name": "@frontmcp/react",
+  "version": "1.0.0",
+  "description": "React hooks, components, and AI SDK integration for FrontMCP",
+  "author": "AgentFront <info@agentfront.dev>",
+  "homepage": "https://docs.agentfront.dev",
+  "license": "Apache-2.0",
+  "keywords": [
+    "mcp",
+    "react",
+    "hooks",
+    "ai",
+    "tools",
+    "openai",
+    "claude",
+    "vercel-ai",
+    "agentfront",
+    "frontmcp"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentfront/frontmcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/agentfront/frontmcp/issues"
+  },
+  "type": "module",
+  "main": "../index.js",
+  "module": "./index.mjs",
+  "types": "../index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    "./package.json": "../package.json",
+    ".": {
+      "require": {
+        "types": "../index.d.ts",
+        "default": "../index.js"
+      },
+      "import": {
+        "types": "../index.d.ts",
+        "default": "./index.mjs"
+      }
+    },
+    "./ai": {
+      "require": {
+        "types": "../ai/index.d.ts",
+        "default": "../ai/index.js"
+      },
+      "import": {
+        "types": "../ai/index.d.ts",
+        "default": "./ai/index.mjs"
+      }
+    },
+    "./router": {
+      "require": {
+        "types": "../router/index.d.ts",
+        "default": "../router/index.js"
+      },
+      "import": {
+        "types": "../router/index.d.ts",
+        "default": "./router/index.mjs"
+      }
+    },
+    "./state": {
+      "require": {
+        "types": "../state/index.d.ts",
+        "default": "../state/index.js"
+      },
+      "import": {
+        "types": "../state/index.d.ts",
+        "default": "./state/index.mjs"
+      }
+    },
+    "./api": {
+      "require": {
+        "types": "../api/index.d.ts",
+        "default": "../api/index.js"
+      },
+      "import": {
+        "types": "../api/index.d.ts",
+        "default": "./api/index.mjs"
+      }
+    }
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "@frontmcp/sdk": "1.0.0",
+    "@frontmcp/utils": "1.0.0",
+    "react-router-dom": "^7.0.0",
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react-router-dom": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@frontmcp/sdk": "1.0.0",
+    "@frontmcp/utils": "1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/esm/router/index.mjs

@@ -0,0 +1,157 @@
+// libs/react/src/router/useRouterBridge.ts
+import { useEffect } from "react";
+import { useNavigate, useLocation } from "react-router-dom";
+
+// libs/react/src/router/router-bridge.ts
+var currentNavigate = null;
+var currentLocation = null;
+function setNavigate(fn) {
+  currentNavigate = fn;
+}
+function setLocation(loc) {
+  currentLocation = loc;
+}
+function getNavigate() {
+  return currentNavigate;
+}
+function getLocation() {
+  return currentLocation;
+}
+function clearBridge() {
+  currentNavigate = null;
+  currentLocation = null;
+}
+
+// libs/react/src/router/useRouterBridge.ts
+function useRouterBridge() {
+  const navigate = useNavigate();
+  const location = useLocation();
+  useEffect(() => {
+    setNavigate(navigate);
+    return () => {
+      clearBridge();
+    };
+  }, [navigate]);
+  useEffect(() => {
+    setLocation({
+      pathname: location.pathname,
+      search: location.search,
+      hash: location.hash
+    });
+  }, [location.pathname, location.search, location.hash]);
+}
+
+// libs/react/src/router/navigate.tool.ts
+var NavigateTool = class {
+  static toolName = "navigate";
+  static description = "Navigate to a URL path in the application";
+  static inputSchema = {
+    type: "object",
+    properties: {
+      path: { type: "string", description: "The URL path to navigate to" },
+      replace: { type: "boolean", description: "Replace current history entry instead of pushing" }
+    },
+    required: ["path"]
+  };
+  static async execute(args) {
+    const navigate = getNavigate();
+    if (!navigate) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: "Router bridge not connected. Ensure useRouterBridge() is called inside a React Router tree."
+          }
+        ]
+      };
+    }
+    navigate(args.path, { replace: args.replace });
+    return {
+      content: [{ type: "text", text: `Navigated to ${args.path}` }]
+    };
+  }
+};
+
+// libs/react/src/router/go-back.tool.ts
+var GoBackTool = class {
+  static toolName = "go_back";
+  static description = "Go back to the previous page in browser history";
+  static inputSchema = {
+    type: "object",
+    properties: {}
+  };
+  static async execute() {
+    const navigate = getNavigate();
+    if (!navigate) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: "Router bridge not connected. Ensure useRouterBridge() is called inside a React Router tree."
+          }
+        ]
+      };
+    }
+    navigate(-1);
+    return {
+      content: [{ type: "text", text: "Navigated back" }]
+    };
+  }
+};
+
+// libs/react/src/router/current-route.resource.ts
+var CurrentRouteResource = class _CurrentRouteResource {
+  static uri = "route://current";
+  static resourceName = "Current Route";
+  static description = "Read the current URL path, search params, and hash";
+  static read() {
+    const location = getLocation();
+    if (!location) {
+      return {
+        contents: [
+          {
+            uri: _CurrentRouteResource.uri,
+            mimeType: "application/json",
+            text: JSON.stringify({
+              error: "Router bridge not connected. Ensure useRouterBridge() is called inside a React Router tree."
+            })
+          }
+        ]
+      };
+    }
+    return {
+      contents: [
+        {
+          uri: _CurrentRouteResource.uri,
+          mimeType: "application/json",
+          text: JSON.stringify({
+            pathname: location.pathname,
+            search: location.search,
+            hash: location.hash,
+            href: `${location.pathname}${location.search}${location.hash}`
+          })
+        }
+      ]
+    };
+  }
+};
+
+// libs/react/src/router/router.entries.ts
+function createRouterEntries() {
+  return {
+    tools: [NavigateTool, GoBackTool],
+    resources: [CurrentRouteResource]
+  };
+}
+export {
+  CurrentRouteResource,
+  GoBackTool,
+  NavigateTool,
+  clearBridge,
+  createRouterEntries,
+  getLocation,
+  getNavigate,
+  setLocation,
+  setNavigate,
+  useRouterBridge
+};

package/esm/state/index.mjs

@@ -0,0 +1,450 @@
+// libs/react/src/state/useStoreResource.ts
+import { useContext, useEffect, useRef, useCallback } from "react";
+
+// libs/react/src/provider/FrontMcpContext.ts
+import { createContext } from "react";
+
+// libs/react/src/components/ComponentRegistry.ts
+var ComponentRegistry = class {
+  entries = /* @__PURE__ */ new Map();
+  register(uri, component, meta) {
+    const name = extractName(uri);
+    this.entries.set(uri, { uri, name, component, description: meta?.description });
+  }
+  registerAll(map) {
+    for (const [uri, component] of Object.entries(map)) {
+      this.register(uri, component);
+    }
+  }
+  get(uri) {
+    return this.entries.get(uri)?.component;
+  }
+  /**
+   * Resolve a shorthand name like `'UserCard'` by trying
+   * `component://UserCard`, `element://UserCard`, `page://UserCard`.
+   */
+  resolve(type) {
+    const exact = this.entries.get(type);
+    if (exact) return exact.component;
+    for (const protocol of ["component://", "element://", "page://"]) {
+      const entry = this.entries.get(`${protocol}${type}`);
+      if (entry) return entry.component;
+    }
+    return void 0;
+  }
+  has(uri) {
+    return this.entries.has(uri);
+  }
+  list() {
+    return Array.from(this.entries.values()).map(({ uri, name, description }) => ({
+      uri,
+      name,
+      description
+    }));
+  }
+  clear() {
+    this.entries.clear();
+  }
+};
+function extractName(uri) {
+  const idx = uri.indexOf("://");
+  return idx >= 0 ? uri.slice(idx + 3) : uri;
+}
+
+// libs/react/src/registry/DynamicRegistry.ts
+var DynamicRegistry = class {
+  tools = /* @__PURE__ */ new Map();
+  resources = /* @__PURE__ */ new Map();
+  toolRefCounts = /* @__PURE__ */ new Map();
+  resourceRefCounts = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Set();
+  version = 0;
+  /**
+   * Register a dynamic tool. Returns an unregister function
+   * suitable for useEffect cleanup.
+   *
+   * Multiple registrations of the same name are ref-counted:
+   * subsequent registrations update the definition but the tool
+   * is only removed when every registrant has unregistered.
+   */
+  registerTool(def) {
+    const existing = this.toolRefCounts.get(def.name) ?? 0;
+    this.toolRefCounts.set(def.name, existing + 1);
+    this.tools.set(def.name, def);
+    if (existing === 0) {
+      this.notify();
+    }
+    let called = false;
+    return () => {
+      if (called) return;
+      called = true;
+      this.unregisterTool(def.name);
+    };
+  }
+  unregisterTool(name) {
+    const count = this.toolRefCounts.get(name);
+    if (count == null) return;
+    if (count <= 1) {
+      this.toolRefCounts.delete(name);
+      this.tools.delete(name);
+      this.notify();
+    } else {
+      this.toolRefCounts.set(name, count - 1);
+    }
+  }
+  /**
+   * Register a dynamic resource. Returns an unregister function
+   * suitable for useEffect cleanup.
+   *
+   * Multiple registrations of the same URI are ref-counted.
+   */
+  registerResource(def) {
+    const existing = this.resourceRefCounts.get(def.uri) ?? 0;
+    this.resourceRefCounts.set(def.uri, existing + 1);
+    this.resources.set(def.uri, def);
+    if (existing === 0) {
+      this.notify();
+    }
+    let called = false;
+    return () => {
+      if (called) return;
+      called = true;
+      this.unregisterResource(def.uri);
+    };
+  }
+  unregisterResource(uri) {
+    const count = this.resourceRefCounts.get(uri);
+    if (count == null) return;
+    if (count <= 1) {
+      this.resourceRefCounts.delete(uri);
+      this.resources.delete(uri);
+      this.notify();
+    } else {
+      this.resourceRefCounts.set(uri, count - 1);
+    }
+  }
+  /** Update the execute function for an existing tool (for stale closure prevention). */
+  updateToolExecute(name, execute) {
+    const existing = this.tools.get(name);
+    if (existing) {
+      existing.execute = execute;
+    }
+  }
+  /** Update the read function for an existing resource and notify subscribers. */
+  updateResourceRead(uri, read) {
+    const existing = this.resources.get(uri);
+    if (existing) {
+      existing.read = read;
+      this.notify();
+    }
+  }
+  getTools() {
+    return [...this.tools.values()];
+  }
+  getResources() {
+    return [...this.resources.values()];
+  }
+  findTool(name) {
+    return this.tools.get(name);
+  }
+  findResource(uri) {
+    return this.resources.get(uri);
+  }
+  hasTool(name) {
+    return this.tools.has(name);
+  }
+  hasResource(uri) {
+    return this.resources.has(uri);
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  getVersion() {
+    return this.version;
+  }
+  clear() {
+    if (this.tools.size === 0 && this.resources.size === 0) return;
+    this.tools.clear();
+    this.resources.clear();
+    this.toolRefCounts.clear();
+    this.resourceRefCounts.clear();
+    this.notify();
+  }
+  notify() {
+    this.version++;
+    this.listeners.forEach((l) => {
+      l();
+    });
+  }
+};
+
+// libs/react/src/provider/FrontMcpContext.ts
+var defaultDynamicRegistry = new DynamicRegistry();
+var FrontMcpContext = createContext({
+  name: "default",
+  registry: new ComponentRegistry(),
+  dynamicRegistry: defaultDynamicRegistry,
+  getDynamicRegistry: () => defaultDynamicRegistry,
+  connect: async () => {
+  }
+});
+
+// libs/react/src/state/useStoreResource.ts
+var VALID_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+function useStoreResource(options) {
+  const { name, getState, subscribe, selectors, actions } = options;
+  const { getDynamicRegistry } = useContext(FrontMcpContext);
+  const dynamicRegistry = getDynamicRegistry(options.server);
+  if (!name || !VALID_NAME_RE.test(name)) {
+    throw new Error(`useStoreResource: invalid store name "${name}". Names must match ${VALID_NAME_RE}.`);
+  }
+  const getStateRef = useRef(getState);
+  getStateRef.current = getState;
+  const readState = useCallback(
+    async () => ({
+      contents: [
+        {
+          uri: `state://${name}`,
+          mimeType: "application/json",
+          text: JSON.stringify(getStateRef.current() ?? null)
+        }
+      ]
+    }),
+    [name]
+  );
+  useEffect(() => {
+    const unregister = dynamicRegistry.registerResource({
+      uri: `state://${name}`,
+      name: `${name}-state`,
+      description: `Full state of ${name} store`,
+      mimeType: "application/json",
+      read: readState
+    });
+    const unsubscribe = subscribe(() => {
+      dynamicRegistry.updateResourceRead(`state://${name}`, readState);
+    });
+    return () => {
+      unregister();
+      unsubscribe();
+    };
+  }, [dynamicRegistry, name, subscribe, readState]);
+  useEffect(() => {
+    if (!selectors) return;
+    const cleanups = [];
+    const selectorUris = [];
+    for (const [key, selector] of Object.entries(selectors)) {
+      if (!key || !VALID_NAME_RE.test(key)) {
+        throw new Error(`useStoreResource: invalid selector key "${key}". Keys must match ${VALID_NAME_RE}.`);
+      }
+      const uri = `state://${name}/${key}`;
+      const selectorRef = { current: selector };
+      const readSelector = async () => ({
+        contents: [
+          {
+            uri,
+            mimeType: "application/json",
+            text: JSON.stringify(selectorRef.current(getStateRef.current()) ?? null)
+          }
+        ]
+      });
+      selectorUris.push({ uri, readSelector });
+      cleanups.push(
+        dynamicRegistry.registerResource({
+          uri,
+          name: `${name}-${key}`,
+          description: `Selector "${key}" from ${name} store`,
+          mimeType: "application/json",
+          read: readSelector
+        })
+      );
+    }
+    const unsubscribe = subscribe(() => {
+      for (const { uri, readSelector } of selectorUris) {
+        dynamicRegistry.updateResourceRead(uri, readSelector);
+      }
+    });
+    cleanups.push(unsubscribe);
+    return () => {
+      cleanups.forEach((fn) => {
+        fn();
+      });
+    };
+  }, [dynamicRegistry, name, selectors, subscribe]);
+  useEffect(() => {
+    if (!actions) return;
+    const cleanups = [];
+    for (const [key, action] of Object.entries(actions)) {
+      const toolName = `${name}_${key}`;
+      const execute = async (args) => {
+        const argsArray = args["args"];
+        const result = await (Array.isArray(argsArray) ? action(...argsArray) : action(args));
+        return {
+          content: [{ type: "text", text: JSON.stringify({ success: true, result }) }]
+        };
+      };
+      cleanups.push(
+        dynamicRegistry.registerTool({
+          name: toolName,
+          description: `Action "${key}" on ${name} store`,
+          inputSchema: {
+            type: "object",
+            properties: {
+              args: { type: "array", description: "Arguments to pass to the action" }
+            }
+          },
+          execute
+        })
+      );
+    }
+    return () => {
+      cleanups.forEach((fn) => {
+        fn();
+      });
+    };
+  }, [dynamicRegistry, name, actions]);
+}
+
+// libs/react/src/state/useReduxResource.ts
+import { useMemo } from "react";
+function useReduxResource(options) {
+  const { store, name = "redux", selectors, actions, server } = options;
+  const wrappedActions = useMemo(() => {
+    if (!actions) return void 0;
+    const wrapped = {};
+    for (const [key, actionCreator] of Object.entries(actions)) {
+      wrapped[key] = (...args) => {
+        const action = actionCreator(...args);
+        return store.dispatch(action);
+      };
+    }
+    return wrapped;
+  }, [actions, store]);
+  useStoreResource({
+    name,
+    getState: store.getState.bind(store),
+    subscribe: store.subscribe.bind(store),
+    selectors,
+    actions: wrappedActions,
+    server
+  });
+}
+
+// libs/react/src/state/useValtioResource.ts
+import { useMemo as useMemo2 } from "react";
+function getByPath(obj, path) {
+  const parts = path.split(".");
+  let current = obj;
+  for (const part of parts) {
+    if (current == null || typeof current !== "object") return void 0;
+    current = current[part];
+  }
+  return current;
+}
+function useValtioResource(options) {
+  const { proxy, subscribe: valtioSubscribe, name = "valtio", paths, mutations, server } = options;
+  const selectors = useMemo2(() => {
+    if (!paths) return void 0;
+    const sels = {};
+    for (const [key, path] of Object.entries(paths)) {
+      sels[key] = (state) => getByPath(state, path);
+    }
+    return sels;
+  }, [paths]);
+  const subscribe = useMemo2(() => (cb) => valtioSubscribe(proxy, cb), [proxy, valtioSubscribe]);
+  const actions = useMemo2(() => {
+    if (!mutations) return void 0;
+    const wrapped = {};
+    for (const [key, mutation] of Object.entries(mutations)) {
+      wrapped[key] = (...args) => mutation(...args);
+    }
+    return wrapped;
+  }, [mutations]);
+  const getState = useMemo2(() => () => JSON.parse(JSON.stringify(proxy)), [proxy]);
+  useStoreResource({
+    name,
+    getState,
+    subscribe,
+    selectors,
+    actions,
+    server
+  });
+}
+
+// libs/react/src/state/adapters/reduxAdapter.ts
+function reduxStore(options) {
+  const { store, name = "redux", selectors, actions: rawActions } = options;
+  let actions;
+  if (rawActions) {
+    actions = {};
+    for (const [key, actionCreator] of Object.entries(rawActions)) {
+      actions[key] = (...args) => {
+        const action = actionCreator(...args);
+        return store.dispatch(action);
+      };
+    }
+  }
+  return {
+    name,
+    getState: store.getState.bind(store),
+    subscribe: store.subscribe.bind(store),
+    selectors,
+    actions
+  };
+}
+
+// libs/react/src/state/adapters/valtioAdapter.ts
+function getByPath2(obj, path) {
+  const parts = path.split(".");
+  let current = obj;
+  for (const part of parts) {
+    if (current == null || typeof current !== "object") return void 0;
+    current = current[part];
+  }
+  return current;
+}
+function valtioStore(options) {
+  const { proxy, subscribe: valtioSubscribe, name = "valtio", paths, mutations } = options;
+  let selectors;
+  if (paths) {
+    selectors = {};
+    for (const [key, path] of Object.entries(paths)) {
+      selectors[key] = (state) => getByPath2(state, path);
+    }
+  }
+  let actions;
+  if (mutations) {
+    actions = {};
+    for (const [key, mutation] of Object.entries(mutations)) {
+      actions[key] = (...args) => mutation(...args);
+    }
+  }
+  return {
+    name,
+    getState: () => JSON.parse(JSON.stringify(proxy)),
+    subscribe: (cb) => valtioSubscribe(proxy, cb),
+    selectors,
+    actions
+  };
+}
+
+// libs/react/src/state/adapters/createStore.ts
+function createStore(options) {
+  return {
+    name: options.name,
+    getState: options.getState,
+    subscribe: options.subscribe,
+    selectors: options.selectors,
+    actions: options.actions
+  };
+}
+export {
+  createStore,
+  reduxStore,
+  useReduxResource,
+  useStoreResource,
+  useValtioResource,
+  valtioStore
+};