inshow-ai-content-mcp/README.md

MCP服务器，用于连接Supabase数据库并提供表结构查询功能

# Inshow AI Query MCP

Inshow AI Query MCP 是一个基于 MCP (Model Context Protocol) 协议的supabase 服务，支持 Streamable HTTP 和 STDIO 两种运行模式，可用于 AI 辅助数据库查询和分析。

本项目仅作为MCP学习项目用途

## 功能特性

- 支持最新的 Streamable HTTP 协议（与 Cherry Studio 兼容）
- 支持 STDIO 模式，方便集成到其他应用
- 提供数据库查询工具
- 支持数据分析工具和提示
- 基于 Supabase 的数据存储

## 安装

```bash
# 克隆仓库
git clone https://github.com/zhycx1995/inshow-ai-query-mcp.git
cd inshow-ai-query-mcp

# 安装依赖
npm install

# 准备环境变量
cp .env.example .env
# 编辑 .env 文件，填入你的 Supabase 配置
```

## 使用方法

### STDIO 模式 (默认)

```bash
npm start
# 或者
node src/index.js
```

### STDIO inspector调试模式

```bash
npm run inspect
```

### Streamable HTTP 模式

```bash
# 基本启动
npm start -- -m http -p 9000

# 带调试信息的启动
npm start -- -m http -p 9000 -d

# 完整配置启动
npm start -- -m http -p 9000 -d --allow-anonymous --session-timeout 60
```

## 命令行参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `-p, --port <number>` | 服务端口号 | `9000` |
| `-m, --mode <string>` | 运行模式 (stdio\|http) | `stdio` |
| `-d, --debug` | 启用调试模式 | `false` |
| `-e, --env <path>` | 环境变量文件路径 | `.env` |
| `--supabase-url <url>` | Supabase项目URL | - |
| `--supabase-key <key>` | Supabase项目API密钥 | - |
| `--supabase-config <path>` | Supabase配置文件路径（JSON） | - |
| `--allow-anonymous` | 允许匿名SSE连接（仅HTTP模式） | `false` |
| `--session-timeout <minutes>` | HTTP会话超时时间（分钟） | `30` |
| `--disable-session-cleanup` | 禁用HTTP会话自动清理 | `false` |
| `--cors-origin <origin>` | 允许的CORS来源 | `*` |

## 与 Cherry Studio 集成

本服务完全支持最新的 Streamable HTTP 协议，可以与 Cherry Studio 无缝集成。

### 测试集成

我们提供了一个测试脚本，可以验证服务器是否正确实现了Streamable HTTP协议，并且可以与Cherry Studio集成：

```bash
# 先启动服务器
npm run start:streamable

# 在另一个终端运行测试
npm run test:cherry

# 或者使用一条命令同时启动服务器和运行测试
npm run cherry:test-with-server
```

### 在 Cherry Studio 中添加 MCP 服务

1. 确保你的服务已在 HTTP 模式下运行
   ```bash
   npm run start:streamable
   ```

2. 打开 Cherry Studio 客户端 (v1.2.7 或更高版本)

3. 点击 "MCP 服务器" 添加新服务器：
   - **名称**：inshow-ai-query
   - **类型**：Streamable HTTP
   - **URL**：http://localhost:9000/mcp
   - 如果需要，可以添加鉴权请求头

4. 点击保存，然后在工具面板中应该可以看到可用的数据库查询工具

### 会话和调试

- 会话自动管理：服务器会生成会话ID并保持会话状态
- 会话自动清理：默认30分钟没有活动的会话会被自动清理
- 断线恢复支持：如果连接断开，Cherry Studio 可以使用相同的会话ID重新连接并继续交互
- 健康检查：访问 http://localhost:9000/health 可查看服务状态

## 技术实现

本服务基于 MCP 协议的最新规范实现，包括：

- 使用统一的 `/mcp` 端点处理所有请求
- POST 请求用于初始化和发送查询
- GET 请求用于建立 SSE 流接收流式响应
- DELETE 请求用于终止会话
- 支持会话状态恢复和无状态操作
- 提供丰富的错误处理和调试信息

## 贡献

欢迎提交问题报告和请求功能。请随时提出 Pull Request。

## 许可证

MIT