MCP Ragchat

1<p align="center">
2  <h1 align="center">mcp-ragchat</h1>
3  <p align="center">
4    An MCP server that adds RAG-powered AI chat to any website. One command from Claude Code.
5  </p>
6</p>
7 
8<p align="center">
9  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
10  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg" alt="Node.js 20+"></a>
11  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.0-blue.svg" alt="TypeScript"></a>
12  <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-compatible-8A2BE2.svg" alt="MCP"></a>
13  <a href="https://www.npmjs.com/package/mcp-ragchat"><img src="https://img.shields.io/npm/v/mcp-ragchat.svg" alt="npm"></a>
14</p>
15 
16---
17 
18Tell Claude Code _"add AI chat to mysite.com"_ and it will crawl your content, build a local vector store, spin up a chat server, and hand you an embed snippet. No cloud infra. No database. Just one API key.
19 
20## Demo
21 
22```
23You:    "Set up AI chat for mybakery.com using this FAQ and menu content"
24 
25Claude: I'll set up RAG-powered chat for mybakery.com.
26 
27        [1/4] ragchat_setup
28              Splitting content into sections...
29              Generating embeddings for 12 documents...
30              Domain "mybakery.com" configured with 12 documents.
31 
32        [2/4] ragchat_test
33              Query: "What are your hours?"
34              Reply: "We're open Monday-Saturday 7am-6pm, and Sunday 8am-2pm."
35              RAG Sources: mybakery.com-3 (0.91), mybakery.com-7 (0.84)
36              Latency: 340ms
37 
38        [3/4] ragchat_serve
39              Chat server running at http://localhost:3456
40              POST /chat ready.
41 
42        [4/4] ragchat_widget
43              Generated embed code. Paste this into your HTML:
44 
45              <script src="http://localhost:3456/widget.js"></script>
46 
47You:    Done. Live chat on my site in under 60 seconds.
48```
49 
50## Quick Start
51 
52**1. Clone and build**
53 
54```bash
55git clone https://github.com/gogabrielordonez/mcp-ragchat
56cd mcp-ragchat
57npm install && npm run build
58```
59 
60**2. Configure Claude Code** (`~/.claude/mcp.json`)
61 
62```json
63{
64  "mcpServers": {
65    "ragchat": {
66      "command": "node",
67      "args": ["/absolute/path/to/mcp-ragchat/dist/mcp-server.js"],
68      "env": {
69        "OPENAI_API_KEY": "sk-..."
70      }
71    }
72  }
73}
74```
75 
76**3. Use it**
77 
78Open Claude Code and say:
79 
80> "Add AI chat to mysite.com. Here's the content: [paste your markdown]"
81 
82Claude handles the rest.
83 
84## Tools
85 
86| Tool | What it does |
87|------|-------------|
88| `ragchat_setup` | Seed a knowledge base from markdown content. Each `##` section becomes a searchable document with vector embeddings. |
89| `ragchat_test` | Send a test message to verify RAG retrieval and LLM response quality. |
90| `ragchat_serve` | Start a local HTTP chat server with CORS and input sanitization. |
91| `ragchat_widget` | Generate a self-contained `<script>` tag -- a floating chat bubble, no dependencies. |
92| `ragchat_status` | List all configured domains with document counts and config details. |
93 
94## How It Works
95 
96```
97                        +------------------+
98                        |  Your Markdown   |
99                        +--------+---------+
100                                 |
101                          ragchat_setup
102                                 |
103                    +------------v-------------+
104                    |   Local Vector Store      |
105                    |   ~/.mcp-ragchat/domains/ |
106                    |     vectors.json          |
107                    |     config.json           |
108                    +------------+-------------+
109                                 |
110          User Question          |
111               |                 |
112        +------v------+  +------v------+
113        |  Embedding  |  |  Cosine     |
114        |  Provider   +->+  Similarity |
115        +-------------+  +------+------+
116                                |
117                         Top 3 chunks
118                                |
119                    +----------v-----------+
120                    |  System Prompt       |
121                    |  + RAG Context       |
122                    |  + User Message      |
123                    +----------+-----------+
124                               |
125                    +----------v-----------+
126                    |     LLM Provider     |
127                    +----------+-----------+
128                               |
129                            Reply
130```
131 
132Everything runs locally. No cloud infrastructure. Bring your own API key.
133 
134## Supported Providers
135 
136### LLM (chat completions)
137 
138| Provider | Env Var | Default Model |
139|----------|---------|---------------|
140| OpenAI | `OPENAI_API_KEY` | `gpt-4o-mini` |
141| Anthropic | `ANTHROPIC_API_KEY` | `claude-sonnet-4-5-20250929` |
142| Google Gemini | `GEMINI_API_KEY` | `gemini-2.0-flash` |
143 
144### Embeddings (vector search)
145 
146| Provider | Env Var | Default Model |
147|----------|---------|---------------|
148| OpenAI | `OPENAI_API_KEY` | `text-embedding-3-small` |
149| Google Gemini | `GEMINI_API_KEY` | `text-embedding-004` |
150| AWS Bedrock | `AWS_REGION` + IAM | `amazon.titan-embed-text-v2:0` |
151 
152Override defaults with `LLM_MODEL` and `EMBEDDING_MODEL` environment variables.
153 
154## Architecture
155 
156```
157~/.mcp-ragchat/domains/
158  mysite.com/
159    config.json     -- system prompt, settings
160    vectors.json    -- documents + embedding vectors
161```
162 
163- **Vector store** -- Local JSON files with cosine similarity search. Zero external dependencies.
164- **Chat server** -- Node.js HTTP server with CORS and input sanitization.
165- **Widget** -- Self-contained `<script>` tag. No frameworks, no build step.
166 
167## Contributing
168 
169Issues and pull requests are welcome.
170 
171- Found a bug? [Open an issue](https://github.com/gogabrielordonez/mcp-ragchat/issues)
172- Want to add a feature? Fork, branch, PR.
173- Questions? Start a [discussion](https://github.com/gogabrielordonez/mcp-ragchat/discussions)
174 
175## Star History
176 
177[![Star History Chart](https://api.star-history.com/svg?repos=gogabrielordonez/mcp-ragchat&type=Date)](https://star-history.com/#gogabrielordonez/mcp-ragchat&Date)
178 
179---
180 
181### Enterprise
182 
183Need multi-tenancy, security guardrails, audit trails, and managed infrastructure? Check out [Supersonic](https://adwaizer.com/supersonic) -- the enterprise AI platform built on the same RAG pipeline.
184 
185---
186 
187**MIT License** -- Gabriel Ordonez
188