Spacetimedb MCP Server

SpacetimeDB MCP服务器

一个全面的模型上下文协议（MCP）服务器 SpacetimeDB -使AI助手能够与您的SpacetimeDB实例、查询表、调用缩减器进行交互，并管理您的数据库操作。

特性

• 🔌 连接管理：连接到本地或云SpacetimeDB实例
• 📊 表操作：使用筛选、分页和实时订阅查询表
• ⚡ 减速器调用：使用参数调用服务器端函数（reducer）
• 🗂️ 图式反思：探索数据库模式、表和可用的reducer
• 🔍 SQL支持：执行SQL查询（在支持的情况下）
• 🔐 认证：支持基于令牌的身份验证
• 📡 实时订阅：订阅实时数据的表格更新
• 🎯 MCP资源：将表、模式和reducer作为MCP资源公开

什么是SpacetimeDB？

SpacetimeDB是一个充当服务器的数据库，允许您直接在数据库内运行应用程序逻辑。非常适合：

• 多人游戏后端
• 实时协作应用程序
• 聊天和消息系统
• 任何低延迟、状态同步的应用程序

先决条件

• Node.js 18.0.0或更高
• SpacetimeDB命令行界面 已安装并配置(安装指南)
• 正在运行的SpacetimeDB实例（本地或云）

安装

1. 克隆或下载此存储库：

猛击：

   cd spacetimedb-mcp-server

Windows CMD:

   cd spacetimedb-mcp-server

1. 安装依赖项：

Bash/CMD：

   npm install

1. 构建项目：

Bash/CMD：

   npm run build

配置

适用于克劳德桌面

添加到您的Claude Desktop配置文件中：

视窗: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "spacetimedb": {
      "command": "node",
      "args": [
        "E:\\AI\\claude\\spacetimedb-mcp-server\\dist\\index.js"
      ]
    }
  }
}

对于其他MCP客户端

服务器在stdio传输上运行，可以与任何兼容MCP的客户端一起使用：

Bash/CMD：

node dist/index.js

用法

1.连接到SpacetimeDB

首先，建立与SpacetimeDB实例的连接：

// Connect to local instance
spacetimedb_connect({
  uri: "ws://localhost:3000",
  module_name: "my-game-server"
})

// Connect to cloud instance with auth
spacetimedb_connect({
  uri: "wss://testnet.spacetimedb.com",
  module_name: "my-production-module",
  auth_token: "your-token-here"
})

2.列出可用表格

spacetimedb_list_tables({
  include_schema: true
})

3.查询表数据

// Simple query
spacetimedb_query_table({
  table_name: "users"
})

// With filtering and pagination
spacetimedb_query_table({
  table_name: "messages",
  filter: '{"sender": "alice"}',
  limit: 50,
  offset: 0
})

4.呼叫减少器

Reducer是修改数据库状态的服务器端函数：

// Call a reducer with arguments
spacetimedb_call_reducer({
  reducer_name: "send_message",
  args: '["Hello, world!", "general"]'
})

spacetimedb_call_reducer({
  reducer_name: "set_name",
  args: '["Alice"]'
})

5.订阅实时更新

spacetimedb_subscribe_table({
  table_name: "users",
  filter: '{"online": true}'
})

6.获取架构信息

// Get entire database schema
spacetimedb_get_schema({})

// Get specific table schema
spacetimedb_get_schema({
  table_name: "messages"
})

7.列出可用的减速器

spacetimedb_list_reducers({
  include_signatures: true
})

8.执行SQL查询

spacetimedb_execute_sql({
  query: "SELECT * FROM users WHERE online = true"
})

可用工具

MCP资源

服务器公开以下资源：

• spacetimedb://tables/{table_name} -直接访问表数据
• spacetimedb://schema -完整的数据库架构
• spacetimedb://reducers -所有可调用的reducer列表

建筑

连接管理器

这 SpacetimeDBConnectionManager 类句柄：

• 与SpacetimeDB实例的WebSocket连接
• CLI命令执行操作
• 查询和订阅管理
• 模式缓存和自检

双重实施方法

此MCP服务器使用 混合方法:

1. 基于CLI的操作：用于模块管理、部署和管理任务
2. 基于SDK的操作：用于实时连接和订阅（生成绑定时）

这为开发和生产使用提供了最大的灵活性。

用例

用于游戏开发

// Check online players
spacetimedb_query_table({
  table_name: "players",
  filter: '{"online": true}'
})

// Send player action
spacetimedb_call_reducer({
  reducer_name: "player_move",
  args: '[100, 200, 50]'  // x, y, z coordinates
})

用于聊天应用程序

// Get recent messages
spacetimedb_query_table({
  table_name: "messages",
  limit: 100
})

// Send new message
spacetimedb_call_reducer({
  reducer_name: "send_message",
  args: '["Hello everyone!", "general"]'
})

用于实时仪表板

// Subscribe to live metrics
spacetimedb_subscribe_table({
  table_name: "system_metrics"
})

// Query historical data
spacetimedb_execute_sql({
  query: "SELECT * FROM metrics WHERE timestamp > NOW() - INTERVAL '1 hour'"
})

发展

建筑

Bash/CMD：

npm run build

开发模式（热重载）

Bash/CMD：

npm run dev

观看模式

Bash/CMD：

npm run watch

故障排除

“找不到时空命令”

确保已安装SpacetimeDB CLI：

Bash/Linux/macOS：

curl -fsSL https://install.spacetimedb.com | bash

Windows PowerShell：

iwr https://install.spacetimedb.com -useb | iex

Windows CMD:

rem Visit https://spacetimedb.com/install for the installer

连接失败

• 验证SpacetimeDB是否正在运行： spacetime start
• 检查URI格式（本地为ws://，云为wss://）
• 确保模块名称与部署的模块匹配
• 对于云实例，验证身份验证令牌

“找不到模块”

列出可用模块：

Bash/CMD：

spacetime list

部署您的模块：

Bash/CMD：

spacetime publish your-module-name --project-path ./path/to/module

SpacetimeDB模块开发

要有效地使用此MCP服务器，您需要SpacetimeDB模块。这里有一个快速的例子：

Rust模块示例

use spacetimedb::{table, reducer, SpacetimeType};

#[table(name = users)]
pub struct User {
    #[primarykey]
    pub identity: Identity,
    pub name: String,
    pub online: bool,
}

#[reducer]
pub fn set_name(ctx: &ReducerContext, name: String) -> Result {
    let user = User {
        identity: ctx.sender,
        name,
        online: true,
    };
    ctx.db.users().insert(user)?;
    Ok(())
}

编译并发布：

Bash/CMD：

spacetime publish my-module --project-path ./my-module

性能注意事项

• 连接池：跨操作重用连接
• 查询限制：对大型数据集使用分页
• 订阅管理：不再需要时取消订阅
• 架构缓存：缓存架构信息以减少开销

安全

• 认证：始终对生产实例使用身份验证令牌
• 网络：使用WSS（WebSocket安全）进行云连接
• SQL注入：使用时对查询进行参数化 execute_sql
• 访问控制：尊重SpacetimeDB的行级安全性

贡献

欢迎投稿！此MCP服务器可以通过以下方式进行增强：

• WebSocket连接池
• 更好的错误处理和重试
• 自动生成模块绑定
• 流式查询结果
• 交易支持
• 高级订阅过滤

相关资源

• SpacetimeDB文档
• 模型上下文协议
• SpacetimeDB TypeScript SDK
• SpacetimeDB Rust指南

许可证

麻省理工学院

支持

• SpacetimeDB不一致： 不一致.gg/spacetimedb
• SpacetimeDB问题：
• MCP文件： 模型上下文协议.io

______________________________________________________________________

内置❤️ SpacetimeDB和MCP社区