使用说明

MCP测试 - 人工智能+数据库集成

一个完整的堆栈，用于使用 Supabase、Cloudflare Workers 和 React 构建 AI 驱动的应用程序。

🏗️ 建筑

数据库Supabase（PostgreSQL + pgvector）
MCP服务器Cloudflare Workers（TypeScript）
前端React + Vite + TypeScript（译文保持原样，因为这是一个技术栈的组合名称，直接翻译并无实际意义，但为符合要求，可表述为“React 加上 Vite 再加上 TypeScript”）
认证使用GitHub OAuth的Supabase认证
部署GitHub Actions → Cloudflare（可翻译为：“GitHub 动作 → Cloudflare”）

🚀 快速入门

先决条件

Node.js 20多个版本
Supabase 命令行界面 (CLI)npm install -g supabase）
Cloudflare 账户（用于生产环境）
Supabase 账户（用于云数据库）

1. 设置

# Clone and install dependencies
git clone <your-repo>
cd mcp-test
make setup

# Copy environment variables
cp env.example .env
# Edit .env with your API keys (see SUPABASE_SETUP.md)

2. Supabase 云服务设置

重要的这个项目现在使用Supabase Cloud，而不是本地Docker。请按照详细的设置指南进行操作：

👉 请参阅 SUPABASE_SETUP.md 获取完整的设置说明

快速步骤：

在（某处）创建一个Supabase项目 supabase.com（可译为“苏帕斯数据库网站”或保持原样作为域名使用）
获取您的项目URL和API密钥
更新您的 .env 文件
链接您的项目： make supabase-link
推动你的模式（或架构）： make supabase-push

3. 本地开发

# Start all development services
make dev

# Or start individually:
make dev-worker  # Cloudflare Worker
make dev-web     # React web app

4. 访问您的应用程序

网络应用http://localhost:3000 翻译为中文是：“本地主机：3000” 或 “本机：3000（端口）”。不过，在中文语境中，我们通常更倾向于说“访问本地主机的3000端口”或“打开本机的3000端口”，以更准确地表达这个网址的含义。但简化的说法“本地主机：3000”或“本机：3000”也是可以接受的
工人http://localhost:8787（本地主机的8787端口）
Supabase 控制台您的云项目仪表板

📁 项目结构

mcp-test/
├── supabase/           # Supabase configuration
│   ├── config.toml
│   ├── migrations/
│   └── seed.sql
├── worker/             # Cloudflare Worker (MCP Server)
│   ├── src/
│   ├── package.json
│   └── wrangler.toml
├── web/                # React frontend
│   ├── src/
│   ├── package.json
│   └── vite.config.ts
├── .github/workflows/  # CI/CD
├── SUPABASE_SETUP.md   # Supabase cloud setup guide
└── Makefile           # Development commands

🔧 配置

环境变量

复制 env.example 到 .env 并进行配置：

# Supabase (cloud)
SUPABASE_URL=https://your-project-id.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# OpenAI
OPENAI_API_KEY=sk-your-openai-key

# OpenAI Models (optional)
OPENAI_EMBEDDING_MODEL=text-embedding-ada-002
OPENAI_CHAT_MODEL=gpt-4o-mini

# Cloudflare (production)
CLOUDFLARE_API_TOKEN=your-token
CLOUDFLARE_ACCOUNT_ID=your-account-id

# CORS Configuration (production)
ALLOWED_ORIGINS=https://your-project.pages.dev,https://mcptest.bldhosting.com

Supabase 设置

云设置 （推荐）：

关注 SUPABASE_SETUP.md（文件名，可译为“Supabase设置指南.md”或保持原样，根据上下文决定是否需要具体翻译文件名）以获取详细说明
在（指定位置）创建一个Supabase项目 supabase.com（可译为“苏帕巴斯网站”或直接保留原域名，根据上下文决定是否需要具体翻译）
链接您的项目： make supabase-link
推送模式（或推送架构）： make supabase-push

🚀 部署

GitHub Actions 设置

在你的GitHub仓库中添加密钥 （设置 → 密钥和变量 → 动作）：
- CLOUDFLARE_API_TOKEN 您的Cloudflare API令牌
- CLOUDFLARE_ACCOUNT_ID - 您的Cloudflare账户ID
- SUPABASE_URL - 您的Supabase项目URL
- SUPABASE_ANON_KEY - 您的Supabase匿名密钥
- OPENAI_API_KEY - 您的OpenAI API密钥
- WORKER_URL - 您已部署的工作节点URL（例如。， https://mcp-server-production.your-subdomain.workers.dev)
- ALLOWED_ORIGINS - 以逗号分隔的允许域名列表（例如。， https://mcp-web.pages.dev,https://mcp.bldhosting.com)
- OPENAI_EMBEDDING_MODEL （可选）- 默认值： text-embedding-3-small
- OPENAI_CHAT_MODEL （可选）- 默认： gpt-5-nano
推送到主分支 触发部署：
```
git push origin main
```
监控部署 在您的GitHub仓库的“操作”选项卡中

手动部署

# Deploy worker
cd worker
npm run deploy

# Deploy web app
cd web
npm run build
# Upload dist/ to Cloudflare Pages

自动部署

该项目使用GitHub Actions进行自动部署：

工人部署到 Cloudflare Workers
网络应用部署到 Cloudflare Pages
质量检查TypeScript + ESLint + 构建验证
环境来自GitHub密钥的Worker URL

🧪 测试

# Test the worker
curl http://localhost:8787/health

# Test embedding
curl -X POST http://localhost:8787/embed \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world"}'

# Test search
curl -X POST http://localhost:8787/search \
  -H "Content-Type: application/json" \
  -d '{"query": "supabase", "limit": 5}'

📚 API 端点

工作端点

GET /health - 健康检查
POST /embed - 生成嵌入表示
POST /search - 搜索文档
POST /chat - 与AI聊天

数据库模式

documents - 存储带有嵌入表示的文档
chat_sessions - 聊天对话会话
chat_messages - 单个聊天消息

🔐 认证与安全

该应用使用Supabase Auth结合GitHub OAuth进行身份验证：

用户使用GitHub登录
JWT令牌用于API认证
行级安全性（RLS）保护用户数据

安全特性

JWT 认证所有受保护的端点都需要有效的令牌
速率限制每个IP每分钟10个请求
输入验证XSS保护和长度限制
CORS 保护限制为允许的来源
用户隔离用户只能访问自己的数据

🛠️ 开发

添加新功能

数据库添加迁移文件到 supabase/migrations/
工人添加端点到 worker/src/index.ts
前端添加组件到 web/src/

开发命令

# Setup everything
npm run setup

# Development
npm run dev              # All services
npm run dev:worker       # Worker only
npm run dev:web          # Web app only

# Quality checks
npm run type-check       # TypeScript checking
npm run lint             # ESLint checking
npm run build            # Build everything
npm run check            # All quality checks

本地测试

# Test worker
make dev-worker

# Test frontend
make dev-web

# Check all services
make health

代码质量

# Type check everything
npm run type-check

# Lint everything
npm run lint

# Build everything
npm run build

# Check everything (type + lint + build)
npm run check

📖 文档

SUPABASE_SETUP.md（文件名，可译为“Supabase 设置指南.md”或保持原样，具体取决于上下文和文件用途） - Supabase 云设置指南
OPENAI_SETUP.md（可翻译为）：OPENAI配置指南/设置文件.md - 使用成本效益高的选项设置OpenAI API
MODEL_CONFIGURATION.md 翻译为中文是：“模型配置文件.md” - 可配置的OpenAI模型，附带真实定价
RAG_ARCHITECTURE.md（文件名可译为“RAG架构说明文件”或保持原样，具体根据上下文决定是否翻译文件名） - RAG（检索增强生成）与上下文工程架构
`SECURITY_ANALYSIS.md` 翻译为中文是：`安全分析.md` - 安全分析及建议
DEPLOYMENT.md 翻译为中文是：“部署指南.md” 或 “部署文件.md”（具体翻译可能根据上下文有所调整，但“DEPLOYMENT”通常指的是与部署相关的文档或说明文件，而“.md”是Markdown文件格式的标识） - 环境变量和部署指南
CLOUDFLARE_DEPLOYMENT.md 翻译为中文是：“CLOUDFLARE 部署说明.md” 或者 “关于 CLOUDFLARE 部署的说明文件.md”。这里，“.md”通常表示这是一个Markdown格式的文件，用于编写简洁易读的文档 - Cloudflare 部署指南
WEB_WORKER_CONNECTION.md 翻译为中文是：WEB工作线程连接.md - 网页应用如何连接到工作节点
DOMAIN_OPTIONS.md（文件名，可译为“域名选项说明文件”或根据上下文简化为“域名选项文件”） - 域配置选项
Supabase 文档
Cloudflare Workers（中文可译为“Cloudflare 工作线程”或“Cloudflare 无服务器函数”，但根据常见用法，“Cloudflare Workers”通常直接保留原名，不直接翻译）
OpenAI API

🤝 贡献

为仓库创建分支（或“克隆仓库”）
创建一个特性分支
做出你的更改
进行质量检查： npm run check
本地测试： npm run dev
提交一个拉取请求

开发工作流程

# 1. Setup
git clone <your-fork>
cd mcp-test
npm run setup

# 2. Development
npm run dev

# 3. Quality checks
npm run check

# 4. Test
npm run dev:worker
npm run dev:web

# 5. Commit
git add .
git commit -m "feat: your changes"
git push origin your-branch

📄 许可证

MIT 许可证 - 详情请参见 LICENSE 文件。