react-mcp-chatbot 0.0.5 β†’ 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,31 @@
1
+ # Changelog
2
+
3
+ All notable changes are documented here. This project follows [Semantic Versioning](https://semver.org/).
4
+
5
+ ## 1.0.0
6
+
7
+ First stable release. Public API (`MCPAgent`, `useChat`, `ChatEngine`, config types) is now covered by semantic versioning.
8
+
9
+ ### Added
10
+ - `ChatEngine`: provider-neutral core with a native tool-calling loop, client-side history, system prompt and `clear()`.
11
+ - Declarative backend description via `api` (`baseURL`, `headers`, `endpoints`) – endpoints become tools automatically.
12
+ - OpenAPI / Swagger import via `api.openapi`.
13
+ - Providers: Anthropic, OpenRouter, Mistral, xAI, Together and any OpenAI-compatible endpoint, alongside OpenAI, Gemini, DeepSeek, Groq and Ollama.
14
+ - `useChat` headless hook, `ref` handle (`clear`, `send`, `stop`), Clear button, `persist` option.
15
+ - `beforeToolCall` / `onToolCall` / `onError` hooks, `maxToolRounds`, `maxHistoryMessages`, `maxToolResultChars`.
16
+ - CommonJS build, test suite, CI, `LICENSE`, `defaultOpen` and `suggestions` props.
17
+ - Live demo (GitHub Pages) with an in-browser mock backend: see `demo/`.
18
+
19
+ ### Changed (breaking)
20
+ - Tool selection now uses each provider's native function calling instead of a prompt-based two-step flow.
21
+ - Removed the exported `Agent` class and `MARKDOWN_SYSTEM_PROMPT`; the default system prompt no longer restricts answers to tool output.
22
+ - Gemini API key is sent in the `x-goog-api-key` header instead of the URL.
23
+
24
+ ### Fixed
25
+ - `require("react-mcp-chatbot")` works on every supported Node version: the CommonJS build bundles the ESM-only Markdown dependencies instead of `require()`-ing them (which throws on Node < 20.19).
26
+ - Chat window no longer overflows narrow (phone) viewports.
27
+ - `require()` previously pointed at an ES module.
28
+ - The send icon is inlined, so bundlers no longer have to resolve a separate `.svg` asset.
29
+
30
+ ## 0.0.6
31
+ - DeepSeek support.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Tigran Zakharyan
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -5,6 +5,13 @@
5
5
  <a href="https://www.npmjs.com/package/react-mcp-chatbot">
6
6
  <img src="https://img.shields.io/npm/dm/react-mcp-chatbot" alt="npm downloads" />
7
7
  </a>
8
+ <a href="https://github.com/TigranZakharyan/react-mcp-chatbot/actions/workflows/ci.yml">
9
+ <img src="https://github.com/TigranZakharyan/react-mcp-chatbot/actions/workflows/ci.yml/badge.svg" alt="CI status" />
10
+ </a>
11
+ <a href="https://bundlephobia.com/package/react-mcp-chatbot">
12
+ <img src="https://img.shields.io/bundlephobia/minzip/react-mcp-chatbot" alt="minzipped size" />
13
+ </a>
14
+ <img src="https://img.shields.io/npm/types/react-mcp-chatbot" alt="TypeScript types included" />
8
15
  <a href="https://github.com/TigranZakharyan/react-mcp-chatbot/blob/main/LICENSE">
9
16
  <img src="https://img.shields.io/npm/l/react-mcp-chatbot" alt="license" />
10
17
  </a>
@@ -19,175 +26,220 @@
19
26
  <h1 align="center">πŸ€– React MCP Chatbot</h1>
20
27
 
21
28
  <p align="center">
22
- <strong>AI-powered React chatbot with intelligent API tool calling</strong>
29
+ <strong>An AI chatbot that talks to your backend APIs – with no backend of its own</strong>
23
30
  </p>
24
31
 
25
32
  <p align="center">
26
- A production-ready chat widget that understands user intent, selects the correct API,
27
- executes it, and responds with clean Markdown-formatted answers.
28
- </p>
29
-
30
- <hr />
31
-
32
- <h2>✨ What is React MCP Chatbot?</h2>
33
-
34
- <p>
35
- <strong>React MCP Chatbot</strong> is a customizable AI chatbot component that connects
36
- <strong>natural language user requests</strong> to <strong>real API calls</strong>
37
- using an LLM-powered agent.
33
+ Describe your existing REST endpoints. The model decides when to call them, the browser executes the calls, and the answer comes back as Markdown. History, system prompt and tool calling all live client-side.
38
34
  </p>
39
35
 
40
- <p>
41
- Instead of writing complex conditional logic, you simply define
42
- <strong>tools (API functions)</strong> β€”
43
- the AI automatically decides <strong>when and how</strong> to call them.
44
- </p>
45
-
46
- <p>
47
- This makes it ideal for <strong>real-world, data-driven AI applications</strong>.
36
+ <p align="center">
37
+ <a href="https://tigranzakharyan.github.io/react-mcp-chatbot/"><b>β–Ά Live demo</b></a> Β·
38
+ <a href="#quick-start">Quick start</a> Β·
39
+ <a href="#faq">FAQ</a> Β·
40
+ <a href="./CHANGELOG.md">Changelog</a>
48
41
  </p>
49
42
 
50
43
  <hr />
51
44
 
52
- <h2>πŸŽ₯ Demo</h2>
53
-
54
- <p>
55
- Example: user asks a question β†’ AI decides β†’ API is called β†’ formatted response
56
- </p>
45
+ ## Demo
57
46
 
58
47
  <p align="center">
59
- <img src="./assets/demo.gif" alt="React MCP Chatbot Demo" width="800" />
48
+ <img src="./assets/demo.gif" alt="Chatbot listing and cancelling orders through a described REST API" width="800" />
60
49
  </p>
61
50
 
62
- <hr />
63
-
64
- <h2>πŸš€ Features</h2>
65
-
66
- <ul>
67
- <li>πŸ€– AI-driven tool selection</li>
68
- <li>πŸ”Œ Pluggable API tools</li>
69
- <li>🧠 LLM-powered intent detection</li>
70
- <li>🧩 Fully typed (TypeScript)</li>
71
- <li>🎨 Modern floating chat UI</li>
72
- <li>πŸŒ— Dark & Light themes</li>
73
- <li>πŸ“ Highly customizable</li>
74
- <li>πŸ“ Markdown responses (tables, lists, code)</li>
75
- <li>⚑ Ollama / Groq / OpenAI / Gemini</li>
76
- <li>πŸ›  Optional & validated tool parameters</li>
77
- </ul>
78
-
79
- <hr />
80
-
81
- <h2>🧠 How It Works</h2>
82
-
83
- <pre><code>
84
- User Message
85
- ↓
86
- LLM analyzes intent
87
- ↓
88
- Tool decision (or no tool)
89
- ↓
90
- API function executed
91
- ↓
92
- Markdown-formatted response
93
- </code></pre>
94
-
95
- <hr />
96
-
97
- <h2>πŸ“¦ Installation</h2>
98
-
99
- <pre><code>npm install react-mcp-chatbot</code></pre>
100
-
101
- <p>or</p>
102
-
103
- <pre><code>yarn add react-mcp-chatbot</code></pre>
51
+ Recorded with a local `llama3.1` via Ollama (no API key, no scripted replies). The assistant lists the processing orders, asks permission before the `POST`, cancels order 1002, and the table on the page updates. Its only knowledge of the backend is the three endpoint descriptions in [`demo/src/main.tsx`](./demo/src/main.tsx).
104
52
 
105
- <hr />
53
+ **[Try it live](https://tigranzakharyan.github.io/react-mcp-chatbot/)** – bring your own API key (it stays in your browser tab), or run it locally. The demo ships an in-browser fake orders API, so no backend is needed:
106
54
 
107
- <h2>⚑ Quick Start</h2>
55
+ ```bash
56
+ git clone https://github.com/TigranZakharyan/react-mcp-chatbot
57
+ cd react-mcp-chatbot/demo
58
+ npm install
59
+ npm run dev
60
+ ```
61
+
62
+ Choose a provider, paste a key (or pick `ollama` with a tool-capable model running locally) and try *"Which orders are still processing?"* or *"Cancel order 1002"*.
63
+
64
+ ## Why this exists
65
+
66
+ Adding "chat with our app" to a product usually means building a chatbot backend: a proxy for the LLM, a tool-calling loop, session storage, and glue that re-implements the endpoints you already have. **react-mcp-chatbot removes that layer.**
108
67
 
109
- <pre><code>import { MCPAgent } from "react-mcp-chatbot";
68
+ | Without | With react-mcp-chatbot |
69
+ | --- | --- |
70
+ | A server that holds the conversation and runs the tool loop | The loop, history and system prompt run in the browser |
71
+ | Re-wrapping every REST endpoint as an LLM tool | Describe the endpoint once (or import your OpenAPI spec) |
72
+ | Provider-specific code for each LLM vendor | One config, native function calling for 10+ providers |
73
+ | Backend auth plumbing for the bot | Requests use the signed-in user's own credentials, so existing permissions apply |
110
74
 
111
- &lt;MCPAgent
112
- provider="ollama" // or "groq"
113
- providerURL="http://localhost:11434"
114
- model="llama3"
115
- tools={tools}
116
- /&gt;
117
- </code></pre>
75
+ **Good fit:** admin panels, internal tools, SaaS dashboards, prototypes, local-first apps. **Not a fit:** anything that needs the LLM key to stay secret without a proxy – see [client-side caveats](#things-to-know-about-running-fully-client-side).
118
76
 
119
- <hr />
77
+ ## FAQ
78
+
79
+ **How do I add an AI chatbot to my React app without writing a backend?**
80
+ Install the package, render `<MCPAgent />` with a provider, a model and your endpoint list. See [Quick start](#quick-start).
81
+
82
+ **How can an LLM call my existing REST API from the browser?**
83
+ Each endpoint you describe (or each OpenAPI operation) is sent to the model as a function-calling tool. The model returns which one to call; the package performs the `fetch` and feeds the result back.
120
84
 
121
- <h2>πŸ›  Defining API Tools</h2>
122
-
123
- <pre><code>import type { MCPTool } from "react-mcp-chatbot";
124
-
125
- const weatherTool: MCPTool = {
126
- name: "get_weather",
127
- description: "Get current weather for a city",
128
- parameters: {
129
- city: {
130
- type: "string",
131
- description: "City name",
132
- },
133
- units: {
134
- type: "string",
135
- optional: true,
136
- description: "metric or imperial",
137
- },
138
- },
139
- call: async ({ city, units }) =&gt; {
140
- const res = await fetch(
141
- `https://api.example.com/weather?q=${city}&units=${units ?? "metric"}`
142
- );
143
- return res.json();
144
- },
145
- };
146
- </code></pre>
85
+ **Does it work with a local model?**
86
+ Yes – use `provider="ollama"` with a tool-capable model such as `llama3.1`. No API key needed.
147
87
 
148
- <hr />
88
+ **How do I stop the bot from making destructive calls?**
89
+ Use `beforeToolCall` to confirm or block, `include`/`exclude` to limit which OpenAPI operations are exposed, and only describe endpoints you are happy for the user to trigger.
90
+
91
+ **Does it support CommonJS and ESM, with TypeScript types?**
92
+ Both, and types are bundled.
93
+
94
+ ## How it compares
149
95
 
150
- <h2>🎨 UI Customization</h2>
96
+ Most chat toolkits assume a server route that runs the model and tools. This one is deliberately the opposite. A rough guide (check each project's docs – they evolve):
97
+
98
+ | | react-mcp-chatbot | Server-centric chat SDKs (e.g. Vercel AI SDK `useChat`, CopilotKit runtime) |
99
+ | --- | --- | --- |
100
+ | Where the tool-calling loop runs | Browser | Typically your server |
101
+ | Needs a chat backend / API route | No | Usually yes |
102
+ | Tools defined from | REST endpoint descriptions or an OpenAPI spec, called with the user's own session | Server-side functions you write |
103
+ | LLM key exposure | Visible to the client unless you add a proxy | Kept on the server |
104
+ | Best for | Dashboards, internal tools, prototypes, local-first apps | Public products where the key and tools must stay private |
151
105
 
152
- <pre><code>&lt;MCPAgent
153
- title="Support Assistant"
154
- align="right"
155
- theme="dark"
156
- width={420}
157
- height={640}
158
- primaryColor="#6366f1"
159
- borderRadius={20}
160
- placeholder="Ask me anything…"
161
- /&gt;
162
- </code></pre>
163
-
164
- <hr />
106
+ Pick the server-centric route when secrets or business logic must not reach the browser; pick this when your existing API already enforces permissions and you just want a chat front-end for it.
165
107
 
166
- <h2>🧭 Use Cases</h2>
108
+ ## Install
167
109
 
168
- <ul>
169
- <li>AI customer support bots</li>
170
- <li>Internal admin dashboards</li>
171
- <li>API copilots</li>
172
- <li>SaaS onboarding assistants</li>
173
- <li>Analytics chatbots</li>
174
- <li>Developer tools</li>
175
- <li>Portfolio projects</li>
176
- </ul>
110
+ ```bash
111
+ npm install react-mcp-chatbot
112
+ ```
113
+
114
+ ## Quick start
115
+
116
+ ```tsx
117
+ import { MCPAgent } from "react-mcp-chatbot";
118
+
119
+ <MCPAgent
120
+ provider="openai" // openai | anthropic | gemini | deepseek | groq | ollama | openrouter | mistral | xai | together | openai-compatible
121
+ model="gpt-4o-mini"
122
+ apiKey={...}
123
+ systemPrompt="You are the support assistant for Acme. Be concise."
124
+ api={{
125
+ baseURL: "https://api.acme.com",
126
+ headers: () => ({ Authorization: `Bearer ${getToken()}` }),
127
+ endpoints: [
128
+ {
129
+ name: "get_order",
130
+ description: "Look up an order by id",
131
+ path: "/orders/{id}",
132
+ parameters: { id: { type: "string", description: "Order id" } },
133
+ },
134
+ {
135
+ name: "cancel_order",
136
+ description: "Cancel an order",
137
+ method: "POST",
138
+ path: "/orders/{id}/cancel",
139
+ parameters: {
140
+ id: { type: "string" },
141
+ reason: { type: "string", optional: true },
142
+ },
143
+ },
144
+ ],
145
+ }}
146
+ />
147
+ ```
148
+
149
+ That is the whole integration. The model gets native function-calling schemas generated from your descriptions, picks endpoints, fills arguments, chains several calls if needed, reads the responses and answers. Tool errors (HTTP 4xx/5xx, missing arguments) are returned to the model so it can retry or explain.
150
+
151
+ Parameters go to `path` if `{name}` is in the path, otherwise `query` (GET/DELETE) or JSON `body` (POST/PUT/PATCH). Override per parameter with `in: "path" | "query" | "body" | "header"`.
152
+
153
+ ### Already have an OpenAPI / Swagger spec?
154
+
155
+ ```tsx
156
+ <MCPAgent
157
+ provider="gemini" model="gemini-2.5-flash" apiKey={...}
158
+ api={{
159
+ baseURL: "https://api.acme.com",
160
+ openapi: "https://api.acme.com/openapi.json", // URL or object
161
+ exclude: ["deleteUser"], // or include: [...]
162
+ }}
163
+ />
164
+ ```
165
+
166
+ Every operation becomes a tool (`operationId` is the tool name, `summary`/`description` the description).
167
+
168
+ ### Custom JS tools
169
+
170
+ Still supported, and can be mixed with `api`:
171
+
172
+ ```tsx
173
+ tools={[{
174
+ name: "get_cart",
175
+ description: "Current contents of the user's cart",
176
+ parameters: {},
177
+ call: async () => store.getState().cart,
178
+ }]}
179
+ ```
180
+
181
+ ## History, system prompt, clearing
182
+
183
+ - **History** is kept in the browser and sent with every request (last `maxHistoryMessages`, default 40, cut at a turn boundary so tool exchanges are never split).
184
+ - **Persistence**: `persist` saves it to `localStorage` (`persist` or `persist="my-key"`). Off by default – on shared computers a saved chat can expose data returned by your API.
185
+ - **System prompt**: `systemPrompt="..."` replaces the default.
186
+ - **Clear**: built-in *Clear* button in the header (`showClearButton={false}` to hide), or via ref:
187
+
188
+ ```tsx
189
+ const ref = useRef<MCPAgentHandle>(null);
190
+ <MCPAgent ref={ref} ... />
191
+ ref.current?.clear();
192
+ ```
193
+
194
+ ## Headless usage
195
+
196
+ ```tsx
197
+ import { useChat } from "react-mcp-chatbot";
198
+
199
+ const { messages, send, clear, stop, loading, status } = useChat({ provider, model, apiKey, api });
200
+ ```
201
+
202
+ `ChatEngine` (the same core, no React) is exported too.
203
+
204
+ ## Options
205
+
206
+ | Prop | Description |
207
+ | --- | --- |
208
+ | `provider`, `model` | Required. |
209
+ | `apiKey` | Required for hosted providers. |
210
+ | `providerURL` | Override base URL (your proxy, Azure, vLLM, LM Studio…). Required for `openai-compatible`; default `http://localhost:11434` for `ollama`. |
211
+ | `systemPrompt` | Instructions for the assistant. |
212
+ | `api` | `{ baseURL, headers?, credentials?, endpoints?, openapi?, include?, exclude?, maxResponseChars? }` |
213
+ | `tools` | Custom tools. |
214
+ | `persist` | `boolean \| string` – save history to localStorage. |
215
+ | `maxHistoryMessages` | Default 40. |
216
+ | `maxToolRounds` | Max tool round-trips per message. Default 8. |
217
+ | `maxToolResultChars` | Default 8000. Long API responses are truncated before going to the model. |
218
+ | `beforeToolCall` | `({name, args, method}) => boolean \| Promise<boolean>` – return `false` to block. Use it to confirm writes. |
219
+ | `onToolCall`, `onError` | Observability hooks. |
220
+ | `temperature`, `headers` | Passed to the provider. |
221
+ | UI | `title`, `align`, `theme`, `primaryColor`, `width`, `height`, `borderRadius`, `placeholder`, `buttonLabel`, `showClearButton`, `defaultOpen`, `suggestions` (clickable starter prompts) |
222
+
223
+ ## Things to know about running fully client-side
224
+
225
+ - **API keys are visible to your users.** For anything public, point `providerURL` at a thin proxy that adds the key (or use per-user keys / a local model such as Ollama). The proxy needs no chatbot logic – it just forwards.
226
+ - **The assistant acts with the user's own credentials.** Tool calls are plain `fetch` calls from the browser, so your backend's normal auth, CORS and permissions apply. Expose only the endpoints you want the model to reach, and use `beforeToolCall` to confirm mutating calls.
227
+ - **CORS**: your backend must allow the page's origin; so must the LLM provider (OpenAI, Anthropic, Gemini, Groq work from browsers; for Ollama set `OLLAMA_ORIGINS`).
228
+ - Models must support tool calling (e.g. Ollama `llama3.1`+, not every local model does).
229
+
230
+ ## Contributing
231
+
232
+ Issues and PRs are welcome. To work on the package:
233
+
234
+ ```bash
235
+ git clone https://github.com/TigranZakharyan/react-mcp-chatbot
236
+ cd react-mcp-chatbot && npm install
237
+ npm test # unit tests (mocked providers, no keys needed)
238
+ cd demo && npm install && npm run dev
239
+ ```
240
+
241
+ Ideas that would make good first contributions: response streaming, a Vue / vanilla-JS wrapper around `ChatEngine`, a per-endpoint `confirm` flag, markdown theming props, and more provider tests. See the [CHANGELOG](./CHANGELOG.md) for what changed between versions.
242
+
243
+ ## License
177
244
 
178
- <hr />
179
-
180
- <h2>πŸ“œ License</h2>
181
-
182
- <p>
183
- MIT Β© <a href="https://github.com/TigranZakharyan">Tigran Zakharyan</a>
184
- </p>
185
-
186
- <hr />
187
-
188
- <h2>⭐ Star the Project</h2>
189
-
190
- <p>
191
- If this project helped you or inspired you, please consider giving it a star ⭐<br />
192
- It helps a lot and motivates further development.
193
- </p>
245
+ MIT Β© [Tigran Zakharyan](https://github.com/TigranZakharyan)