trailbase-mcp 0.1.1
MCP server for TrailBase
Requires Python: >=3.13

# TrailBase MCP Server

TrailBase 的 Model Context Protocol (MCP) 服务器实现，提供对 TrailBase 数据库、Record API、认证、WASM 组件等功能的完整访问。

## 功能特性

### 数据库工具 (DB)
- `db.query` - 执行 SQL 查询
- `db.explain` - 解释 SQL 查询计划
- `db.tables` - 列出数据库表
- `db.table_info` - 获取表结构信息

### Record API 管理
- `records.list` - 列出记录
- `records.get` - 获取单个记录
- `records.create` - 创建记录
- `records.update` - 更新记录
- `records.delete` - 删除记录
- `records.schema` - 获取 API Schema
- `records.apis` - 列出所有 Record APIs

### 认证与权限 (Auth)
- `auth.users.list` - 列出用户
- `auth.users.create` - 创建用户
- `auth.users.update` - 更新用户
- `auth.users.delete` - 删除用户
- `auth.sessions.invalidate` - 使会话失效
- `auth.token.mint` - 生成认证令牌

### WASM 组件管理
- `wasm.list_available` - 列出可用的 WASM 组件
- `wasm.installed` - 列出已安装的 WASM 组件
- `wasm.add` - 安装 WASM 组件
- `wasm.remove` - 移除 WASM 组件
- `wasm.update_all` - 更新所有 WASM 组件

### Schema 管理 (DDL)
- `schema.tables` - 列出所有表
- `schema.create_table` - 创建表
- `schema.alter_table` - 修改表
- `schema.drop_table` - 删除表
- `schema.indexes` - 获取表的索引

### 定时任务/系统作业
- `jobs.list` - 列出所有作业
- `jobs.update_schedule` - 更新作业调度
- `jobs.enable` - 启用作业
- `jobs.disable` - 禁用作业
- `jobs.run_now` - 立即运行作业
- `jobs.history` - 获取作业运行历史
- `jobs.wasm.list` - 列出 WASM 作业

### 日志与监控
- `logs.query` - 查询日志
- `logs.tail` - 实时日志流
- `metrics.overview` - 获取系统指标概览

### 配置管理
- `config.get` - 获取配置
- `config.update` - 更新配置

### 文件管理
- `files.list` - 列出文件
- `files.delete` - 删除文件
- `files.meta` - 获取文件元数据

### 事务
- `tx.execute` - 执行事务

### 系统信息
- `info.version` - 获取版本信息

### 资源 (Resources)
- `trailbase://config` - TrailBase 服务器配置
- `trailbase://openapi` - TrailBase OpenAPI 文档
- `trailbase://schema/{table}` - 表结构信息

## 安装

1. 确保已安装 `uv`：
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

2. 安装依赖：
```bash
uv sync
```

## 配置

### 环境变量

设置以下环境变量：

- `TRAILBASE_URL` (必填) - TrailBase 服务器地址，例如 `http://localhost:8080`
- `ADMIN_TOKEN` (建议) - 管理员认证令牌或 JWT

### 命令行参数

也可以通过命令行参数传递：

```bash
uv run main.py --trailbase-url http://localhost:8080 --trailbase-token your-token
```

### 远程访问配置

**场景 1：MCP 服务器和 TrailBase 在同一台机器（本地）**

```bash
export TRAILBASE_URL="http://localhost:8080"
uv run main.py --transport http
```

**场景 2：MCP 服务器在远程，TrailBase 在本地**

确保 TrailBase 监听 `0.0.0.0` 而不是 `127.0.0.1`，然后：

```bash
# 在远程机器上运行 MCP 服务器
export TRAILBASE_URL="http://<本地机器IP>:8080"
uv run main.py --transport http --host 0.0.0.0
```

**场景 3：MCP 服务器在本地，TrailBase 在远程**

```bash
# 在本地运行 MCP 服务器
export TRAILBASE_URL="http://<远程机器IP>:8080"
uv run main.py --transport http
```

**场景 4：使用 SSH 隧道**

如果 TrailBase 只监听 localhost，可以通过 SSH 隧道访问：

```bash
# 在本地建立 SSH 隧道
ssh -L 8080:localhost:8080 user@remote-host

# 然后 MCP 服务器连接本地端口
export TRAILBASE_URL="http://localhost:8080"
uv run main.py --transport http
```

## 运行

### Stdio 传输（默认）

```bash
uv run main.py
```

或者直接运行模块：

```bash
uv run python -m trailbase_mcp.server
```

### Streamable HTTP 传输

使用 Streamable HTTP 传输（支持双向全双工通信，适用于长时间 AI 推理等场景）：

```bash
# 安装 uvicorn（如果还没有）
uv add uvicorn

# 运行 HTTP 服务器
uv run main.py --transport http --host 0.0.0.0 --port 9118
```

或者通过环境变量：

```bash
export MCP_TRANSPORT=http
export MCP_HOST=0.0.0.0
export MCP_PORT=9118
uv run main.py
```

**Web 展示页面：**

启动 Streamable HTTP 服务器后，在浏览器中访问 `http://localhost:9118` 可以查看：
- 服务器状态和统计信息
- 所有可用工具的列表（按分类组织）
- 可用资源列表
- 服务器信息

展示页面使用 Tailwind CSS 构建，提供现代化的 UI 界面。

## MCP 客户端配置

### Streamable HTTP 传输（推荐，最新标准）

**步骤 1：启动 HTTP 服务器**

首先启动 MCP HTTP 服务器：

```bash
# 安装依赖（如果还没安装）
uv add -e ".[http]"

# 启动服务器
cd /home/throne/Project/trailbase/trailbase-mcp
uv run main.py --transport http --host 0.0.0.0 --port 9118
```

或者通过环境变量：

```bash
export MCP_TRANSPORT=http
export MCP_HOST=0.0.0.0
export MCP_PORT=9118
export TRAILBASE_URL=http://localhost:9822
export ADMIN_TOKEN=your-admin-token
uv run main.py
```

**步骤 2：配置 MCP 客户端**

在 MCP 客户端（如 Cursor）的配置文件中使用 URL：

```json
{
  "mcpServers": {
    "trailbase-mcp": {
      "url": "http://localhost:9118",
      "env": {
        "TRAILBASE_URL": "http://localhost:9822",
        "ADMIN_TOKEN": "your-admin-token"
      }
    }
  }
}
```

**注意：** Streamable HTTP 是 MCP 2025-03-26 最新标准，支持：
- 统一端点设计（`/message`）
- 按需流式传输
- 会话管理和状态恢复
- 更好的性能和可靠性

### Stdio 传输（传统方式，向后兼容）

如果需要使用 stdio 传输（适用于本地开发或简单场景）：

```json
{
  "mcpServers": {
    "trailbase-mcp": {
      "command": "sh",
      "args": ["-c", "cd /home/throne/Project/trailbase/trailbase-mcp && uv run main.py"],
      "env": {
        "TRAILBASE_URL": "http://localhost:9822",
        "ADMIN_TOKEN": "your-admin-token"
      }
    }
  }
}
```

## 传输协议

TrailBase MCP 服务器支持两种传输协议：

1. **stdio（标准输入输出）** - 默认传输方式
   - 通过标准输入输出流进行 JSON-RPC 通信
   - 适用于本地进程间通信
   - 简单可靠，无需额外依赖

2. **Streamable HTTP** - 最新标准（MCP 2025-03-26），推荐使用
   - MCP 协议的最新传输标准，2025年3月引入
   - 支持双向全双工通信
   - 统一端点设计，按需流式传输
   - 支持会话管理和状态恢复
   - 可在单个 HTTP 连接内分块回写数据
   - 必要时自动升级为 SSE（Server-Sent Events）
   - 适用于长时间的 AI 推理或实时数据分析等场景
   - 需要安装 `uvicorn`：`uv add -e ".[http]"` 或 `uv add uvicorn`

## 项目结构

```
trailbase-mcp/
├── src/
│   └── trailbase_mcp/
│       ├── __init__.py
│       ├── server.py          # MCP 服务器入口
│       ├── client/             # TrailBase HTTP 客户端
│       │   ├── __init__.py
│       │   ├── client.py      # 主客户端类
│       │   ├── http.py        # HTTP 客户端与重试逻辑
│       │   ├── auth.py        # 认证中间件
│       │   └── errors.py      # 统一异常处理
│       ├── tools/              # MCP 工具实现
│       │   ├── __init__.py
│       │   ├── db.py          # 数据库工具
│       │   ├── records.py     # Record API 工具
│       │   ├── auth.py        # 认证工具
│       │   ├── wasm.py        # WASM 工具
│       │   ├── schema.py      # Schema 工具
│       │   ├── jobs.py        # Jobs 工具
│       │   ├── logs.py        # 日志工具
│       │   ├── config.py      # 配置工具
│       │   ├── files.py       # 文件工具
│       │   ├── tx.py          # 事务工具
│       │   └── info.py        # 系统信息工具
│       └── models/            # Pydantic 模型（预留）
│           └── __init__.py
├── main.py                     # 入口文件
├── pyproject.toml              # 项目配置
└── README.md                   # 本文档
```

## 开发

### 代码检查

```bash
ruff check .
```

### 代码格式化

```bash
ruff format .
```

## 注意事项

1. **HTTP 超时**：默认连接超时 10 秒，读取超时 30 秒
2. **重试机制**：429 和 5xx 错误会自动重试，最多 3 次，使用指数退避
3. **API 端点**：某些功能（如 WASM 组件管理）可能需要在服务器端实现对应的 Admin API，否则会返回错误提示使用 CLI 命令
4. **安全性**：确保 `ADMIN_TOKEN` 具有足够的权限执行所需操作