@ubuligan/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jsznpm
+
+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/dist/index.d.ts

@@ -0,0 +1,91 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import * as _modelcontextprotocol_sdk_client from '@modelcontextprotocol/sdk/client';
+import { CallToolResult, ListPromptsResult, ListResourcesResult, ListToolsResult } from '@modelcontextprotocol/sdk/types.js';
+
+interface MCPContextValue {
+    /** The connected SDK client, or null until the connection is established. */
+    client: Client | null;
+    connected: boolean;
+    error: Error | null;
+}
+interface MCPProviderProps {
+    /** Streamable HTTP endpoint of the MCP server. */
+    url: string;
+    /** Optional request headers (e.g. auth). */
+    headers?: Record<string, string>;
+    /** Client identity advertised to the server. */
+    name?: string;
+    version?: string;
+    children: ReactNode;
+}
+/**
+ * Connects to an MCP server over Streamable HTTP and exposes the client via
+ * context. Browser-only transport — stdio is not available in the browser.
+ */
+declare function MCPProvider({ url, headers, name, version, children }: MCPProviderProps): react.JSX.Element;
+/** Access the raw MCP context (client + connection state). */
+declare function useMCPContext(): MCPContextValue;
+
+/** The connected client plus connection state. */
+declare function useMCPClient(): {
+    client: _modelcontextprotocol_sdk_client.Client<{
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }> | null;
+    connected: boolean;
+    error: Error | null;
+};
+interface AsyncState<T> {
+    data: T | null;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => void;
+}
+/** List the server's tools. Re-runs when the connection changes. */
+declare function useTools(): AsyncState<ListToolsResult>;
+/** List the server's resources. */
+declare function useResources(): AsyncState<ListResourcesResult>;
+/** List the server's prompts. */
+declare function usePrompts(): AsyncState<ListPromptsResult>;
+interface UseToolResult {
+    call: (args?: Record<string, unknown>) => Promise<CallToolResult | undefined>;
+    data: CallToolResult | null;
+    loading: boolean;
+    error: Error | null;
+}
+/** Get a typed `call` function plus state for a single tool. */
+declare function useTool(name: string): UseToolResult;
+
+export { type MCPContextValue, MCPProvider, type MCPProviderProps, type UseToolResult, useMCPClient, useMCPContext, usePrompts, useResources, useTool, useTools };

package/dist/index.js

@@ -0,0 +1,124 @@
+// src/context.tsx
+import { createContext, useContext, useEffect, useRef, useState } from "react";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { jsx } from "react/jsx-runtime";
+var MCPContext = createContext(null);
+function MCPProvider({ url, headers, name, version, children }) {
+  const [client, setClient] = useState(null);
+  const [error, setError] = useState(null);
+  const activeRef = useRef(0);
+  useEffect(() => {
+    const token = ++activeRef.current;
+    const c = new Client({ name: name ?? "mcp-toolkit-react", version: version ?? "0.1.0" });
+    const transport = new StreamableHTTPClientTransport(new URL(url), {
+      requestInit: headers ? { headers } : void 0
+    });
+    setClient(null);
+    setError(null);
+    c.connect(transport).then(() => {
+      if (token === activeRef.current) setClient(c);
+      else void c.close();
+    }).catch((e) => {
+      if (token === activeRef.current) setError(e instanceof Error ? e : new Error(String(e)));
+    });
+    return () => {
+      activeRef.current++;
+      void c.close().catch(() => {
+      });
+    };
+  }, [url, headers, name, version]);
+  return /* @__PURE__ */ jsx(MCPContext.Provider, { value: { client, connected: client !== null, error }, children });
+}
+function useMCPContext() {
+  const ctx = useContext(MCPContext);
+  if (!ctx) throw new Error("useMCPContext must be used within <MCPProvider>");
+  return ctx;
+}
+
+// src/hooks.ts
+import { useCallback, useEffect as useEffect2, useState as useState2 } from "react";
+function useMCPClient() {
+  const { client, connected, error } = useMCPContext();
+  return { client, connected, error };
+}
+function useListQuery(fetcher) {
+  const [data, setData] = useState2(null);
+  const [loading, setLoading] = useState2(false);
+  const [error, setError] = useState2(null);
+  const [nonce, setNonce] = useState2(0);
+  useEffect2(() => {
+    const signal = { cancelled: false };
+    const promise = fetcher(signal);
+    if (!promise) return;
+    setLoading(true);
+    setError(null);
+    promise.then((result) => {
+      if (!signal.cancelled) setData(result);
+    }).catch((e) => {
+      if (!signal.cancelled) setError(e instanceof Error ? e : new Error(String(e)));
+    }).finally(() => {
+      if (!signal.cancelled) setLoading(false);
+    });
+    return () => {
+      signal.cancelled = true;
+    };
+  }, [nonce, fetcher]);
+  const refresh = useCallback(() => setNonce((n) => n + 1), []);
+  return { data, loading, error, refresh };
+}
+function useTools() {
+  const { client } = useMCPContext();
+  const fetcher = useCallback(() => client ? client.listTools() : null, [client]);
+  return useListQuery(fetcher);
+}
+function useResources() {
+  const { client } = useMCPContext();
+  const fetcher = useCallback(() => client ? client.listResources() : null, [client]);
+  return useListQuery(fetcher);
+}
+function usePrompts() {
+  const { client } = useMCPContext();
+  const fetcher = useCallback(() => client ? client.listPrompts() : null, [client]);
+  return useListQuery(fetcher);
+}
+function useTool(name) {
+  const { client } = useMCPContext();
+  const [data, setData] = useState2(null);
+  const [loading, setLoading] = useState2(false);
+  const [error, setError] = useState2(null);
+  const call = useCallback(
+    async (args) => {
+      if (!client) {
+        const err = new Error("MCP client is not connected");
+        setError(err);
+        throw err;
+      }
+      setLoading(true);
+      setError(null);
+      try {
+        const result = await client.callTool({ name, arguments: args ?? {} });
+        setData(result);
+        return result;
+      } catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        setError(err);
+        throw err;
+      } finally {
+        setLoading(false);
+      }
+    },
+    [client, name]
+  );
+  return { call, data, loading, error };
+}
+export {
+  MCPProvider,
+  useMCPClient,
+  useMCPContext,
+  usePrompts,
+  useResources,
+  useTool,
+  useTools
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/context.tsx","../src/hooks.ts"],"sourcesContent":["import { createContext, useContext, useEffect, useRef, useState, type ReactNode } from \"react\";\nimport { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\nimport { StreamableHTTPClientTransport } from \"@modelcontextprotocol/sdk/client/streamableHttp.js\";\n\nexport interface MCPContextValue {\n  /** The connected SDK client, or null until the connection is established. */\n  client: Client | null;\n  connected: boolean;\n  error: Error | null;\n}\n\nconst MCPContext = createContext<MCPContextValue | null>(null);\n\nexport interface MCPProviderProps {\n  /** Streamable HTTP endpoint of the MCP server. */\n  url: string;\n  /** Optional request headers (e.g. auth). */\n  headers?: Record<string, string>;\n  /** Client identity advertised to the server. */\n  name?: string;\n  version?: string;\n  children: ReactNode;\n}\n\n/**\n * Connects to an MCP server over Streamable HTTP and exposes the client via\n * context. Browser-only transport — stdio is not available in the browser.\n */\nexport function MCPProvider({ url, headers, name, version, children }: MCPProviderProps) {\n  const [client, setClient] = useState<Client | null>(null);\n  const [error, setError] = useState<Error | null>(null);\n  // Avoid double-connect under React 18 StrictMode dev double-invoke.\n  const activeRef = useRef(0);\n\n  useEffect(() => {\n    const token = ++activeRef.current;\n    const c = new Client({ name: name ?? \"mcp-toolkit-react\", version: version ?? \"0.1.0\" });\n    const transport = new StreamableHTTPClientTransport(new URL(url), {\n      requestInit: headers ? { headers } : undefined,\n    });\n\n    setClient(null);\n    setError(null);\n\n    c.connect(transport)\n      .then(() => {\n        if (token === activeRef.current) setClient(c);\n        else void c.close();\n      })\n      .catch((e) => {\n        if (token === activeRef.current) setError(e instanceof Error ? e : new Error(String(e)));\n      });\n\n    return () => {\n      activeRef.current++;\n      void c.close().catch(() => {});\n    };\n  }, [url, headers, name, version]);\n\n  return (\n    <MCPContext.Provider value={{ client, connected: client !== null, error }}>\n      {children}\n    </MCPContext.Provider>\n  );\n}\n\n/** Access the raw MCP context (client + connection state). */\nexport function useMCPContext(): MCPContextValue {\n  const ctx = useContext(MCPContext);\n  if (!ctx) throw new Error(\"useMCPContext must be used within <MCPProvider>\");\n  return ctx;\n}\n","import { useCallback, useEffect, useState } from \"react\";\nimport type {\n  CallToolResult,\n  ListPromptsResult,\n  ListResourcesResult,\n  ListToolsResult,\n} from \"@modelcontextprotocol/sdk/types.js\";\nimport { useMCPContext } from \"./context.js\";\n\n/** The connected client plus connection state. */\nexport function useMCPClient() {\n  const { client, connected, error } = useMCPContext();\n  return { client, connected, error };\n}\n\ninterface AsyncState<T> {\n  data: T | null;\n  loading: boolean;\n  error: Error | null;\n  refresh: () => void;\n}\n\nfunction useListQuery<T>(fetcher: (signal: { cancelled: boolean }) => Promise<T> | null): AsyncState<T> {\n  const [data, setData] = useState<T | null>(null);\n  const [loading, setLoading] = useState(false);\n  const [error, setError] = useState<Error | null>(null);\n  const [nonce, setNonce] = useState(0);\n\n  useEffect(() => {\n    const signal = { cancelled: false };\n    const promise = fetcher(signal);\n    if (!promise) return;\n    setLoading(true);\n    setError(null);\n    promise\n      .then((result) => {\n        if (!signal.cancelled) setData(result);\n      })\n      .catch((e) => {\n        if (!signal.cancelled) setError(e instanceof Error ? e : new Error(String(e)));\n      })\n      .finally(() => {\n        if (!signal.cancelled) setLoading(false);\n      });\n    return () => {\n      signal.cancelled = true;\n    };\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [nonce, fetcher]);\n\n  const refresh = useCallback(() => setNonce((n) => n + 1), []);\n  return { data, loading, error, refresh };\n}\n\n/** List the server's tools. Re-runs when the connection changes. */\nexport function useTools(): AsyncState<ListToolsResult> {\n  const { client } = useMCPContext();\n  const fetcher = useCallback(() => (client ? client.listTools() : null), [client]);\n  return useListQuery(fetcher);\n}\n\n/** List the server's resources. */\nexport function useResources(): AsyncState<ListResourcesResult> {\n  const { client } = useMCPContext();\n  const fetcher = useCallback(() => (client ? client.listResources() : null), [client]);\n  return useListQuery(fetcher);\n}\n\n/** List the server's prompts. */\nexport function usePrompts(): AsyncState<ListPromptsResult> {\n  const { client } = useMCPContext();\n  const fetcher = useCallback(() => (client ? client.listPrompts() : null), [client]);\n  return useListQuery(fetcher);\n}\n\nexport interface UseToolResult {\n  call: (args?: Record<string, unknown>) => Promise<CallToolResult | undefined>;\n  data: CallToolResult | null;\n  loading: boolean;\n  error: Error | null;\n}\n\n/** Get a typed `call` function plus state for a single tool. */\nexport function useTool(name: string): UseToolResult {\n  const { client } = useMCPContext();\n  const [data, setData] = useState<CallToolResult | null>(null);\n  const [loading, setLoading] = useState(false);\n  const [error, setError] = useState<Error | null>(null);\n\n  const call = useCallback(\n    async (args?: Record<string, unknown>) => {\n      if (!client) {\n        const err = new Error(\"MCP client is not connected\");\n        setError(err);\n        throw err;\n      }\n      setLoading(true);\n      setError(null);\n      try {\n        const result = (await client.callTool({ name, arguments: args ?? {} })) as CallToolResult;\n        setData(result);\n        return result;\n      } catch (e) {\n        const err = e instanceof Error ? e : new Error(String(e));\n        setError(err);\n        throw err;\n      } finally {\n        setLoading(false);\n      }\n    },\n    [client, name],\n  );\n\n  return { call, data, loading, error };\n}\n"],"mappings":"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","names":["useEffect","useState","useState","useEffect"]}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@ubuligan/react",
+  "version": "0.1.0",
+  "description": "React hooks for MCP servers over Streamable HTTP (useMCPClient, useTools, useTool)",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@ubuligan/shared": "^0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.18",
+    "react": "^18.3.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "jsznpm",
+  "homepage": "https://github.com/jsznpm/create-mcp-toolkit#readme",
+  "bugs": {
+    "url": "https://github.com/jsznpm/create-mcp-toolkit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jsznpm/create-mcp-toolkit.git",
+    "directory": "packages/react"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "llm",
+    "react",
+    "hooks",
+    "nextjs"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}