时空数据库mcp
SpacetimeDB的模型上下文协议（MCP）服务器。直接从启用MCP的AI助手查询数据库、调用reducer、检查模式和管理SpacetimeDB实例。
特性
- 🔍 查询模式：获取有关数据库表和reducer的详细信息
- 🗄️ 运行SQL查询：执行SQL查询以检查和修改数据
- ⚡ 呼叫减少器：调用数据库上的reducer函数
- 📋 查看日志：获取并解析数据库日志
- ✅ 测试连接：验证与SpacetimeDB实例的连接
安装
npm install spacetimedb-mcp配置
将服务器添加到您的 mcp.json 配置文件（通常位于您的主目录下 .config/mcp.json 或类似，具体取决于您的MCP客户端）。
基本配置（全局安装）
如果您已全局安装该软件包(npm install -g spacetimedb-mcp)，使用以下方法之一：
选项1：使用npx（推荐）
{
"mcpServers": {
"spacetimedb": {
"command": "npx",
"args": ["-y", "spacetimedb-mcp"],
"env": {
"SPACETIMEDB_HOST": "http://localhost:3000",
"SPACETIMEDB_TOKEN": "your-token-here",
"SPACETIMEDB_DEFAULT_DATABASE": "strc"
}
}
}
}选项2：使用全局包路径
首先，找到全局node_modules路径：
npm root -g然后在配置中使用该路径：
{
"mcpServers": {
"spacetimedb": {
"command": "node",
"args": ["C:/nvm4w/nodejs/node_modules/spacetimedb-mcp/dist/index.js"],
"env": {
"SPACETIMEDB_HOST": "http://localhost:3000",
"SPACETIMEDB_TOKEN": "your-token-here",
"SPACETIMEDB_DEFAULT_DATABASE": "strc"
}
}
}
}注： 替换 C:/nvm4w/nodejs/node_modules 使用您的实际全局npm根路径 npm root -g.
本地安装
如果您更喜欢在项目中本地安装：
npm install spacetimedb-mcp然后配置：
{
"mcpServers": {
"spacetimedb": {
"command": "node",
"args": ["node_modules/spacetimedb-mcp/dist/index.js"],
"env": {
"SPACETIMEDB_HOST": "http://localhost:3000",
"SPACETIMEDB_TOKEN": "your-token-here",
"SPACETIMEDB_DEFAULT_DATABASE": "strc"
}
}
}
}环境变量
| 变量 | 必填 | 默认 | 描述 |
|---|---|---|---|
SPACETIMEDB_HOST | 没有 | http://localhost:3000 | SpacetimeDB实例的基本URL |
SPACETIMEDB_TOKEN | 是 | - | 身份验证令牌（承载令牌） |
SPACETIMEDB_DEFAULT_DATABASE | 否 | - | 未在工具调用中指定时使用的默认数据库名称 |
提示： 您可以使用 spacetime login show --token 获取您的身份验证令牌。可用工具
test_connection
测试与SpacetimeDB实例的连接。
例子：
{
"tool": "test_connection"
}答复：
{
"status": "connected",
"host": "http://localhost:3000"
}get_schema
获取数据库的架构，包括所有表和reducer。
参数：
database（字符串，可选）：数据库名称（如果未指定，则使用默认值）
例子：
{
"tool": "get_schema",
"arguments": {
"database": "strc"
}
}答复： 格式化模式，显示带列的表和带参数的缩减器。
sql_query
对数据库运行SQL查询。
参数：
database（字符串，可选）：数据库名称（如果未指定，则使用默认值）query（字符串，必填）：要执行的SQL查询format（字符串，可选）：输出格式(json或markdown，默认值json)
例子：
{
"tool": "sql_query",
"arguments": {
"database": "strc",
"query": "SELECT * FROM users LIMIT 10",
"format": "markdown"
}
}答复： 带有模式和行的查询结果。
（已删除发布部分）
describe_database
获取数据库的元数据。
参数：
database（字符串，可选）：数据库名称（如果未指定，则使用默认值）
例子：
{
"tool": "describe_database",
"arguments": {
"database": "strc"
}
}答复： JSON格式的数据库元数据。
get_database_identity
获取数据库名称的标识。
参数：
database（字符串，可选）：数据库名称（如果未指定，则使用默认值）
例子：
{
"tool": "get_database_identity",
"arguments": {
"database": "strc"
}
}答复： 数据库的标识字符串。
delete_database
删除数据库。
参数：
database（字符串，可选）：数据库名称（如果未指定，则使用默认值）
例子：
{
"tool": "delete_database",
"arguments": {
"database": "strc"
}
}答复： 删除操作的结果。
list_databases
列出标识所拥有的数据库。
参数：
identity（字符串，必填）：SpacetimeDB标识
例子：
{
"tool": "list_databases",
"arguments": {
"identity": "0xabc123"
}
}答复： 数据库地址数组。
add_database_alias
为数据库标识添加友好别名。
参数：
identity（字符串，必填）：数据库标识name（字符串，必填）：要添加的别名
例子：
{
"tool": "add_database_alias",
"arguments": {
"identity": "0xabc123",
"name": "chat-app"
}
}答复： 别名创建的结果。
get_database_aliases
列出数据库标识的别名。
参数：
identity（字符串，必填）：数据库标识
例子：
{
"tool": "get_database_aliases",
"arguments": {
"identity": "0xabc123"
}
}答复： 别名数组。
call_reducer
调用数据库上的reducer函数。
参数：
database（字符串，可选）：数据库名称（如果未指定，则使用默认值）reducer（string，必填）：减速器函数的名称args（array，必填）：reducer的参数为JSON数组
例子：
{
"tool": "call_reducer",
"arguments": {
"database": "strc",
"reducer": "CreateUser",
"args": [
"username_123",
"user@example.com"
]
}
}答复： reducer调用的结果（对于void返回，可能为空）。
get_logs
从数据库中获取最近的日志。
参数：
database（字符串，可选）：数据库名称（如果未指定，则使用默认值）count（number，可选）：要获取的日志行数（默认值：50）
例子：
{
"tool": "get_logs",
"arguments": {
"database": "strc",
"count": 20
}
}答复： 带有时间戳、级别和消息的格式化日志行。
使用示例
入门指南
- 安装软件包：
npm install spacetimedb-mcp- 配置您的
mcp.json使用您的SpacetimeDB凭据
- 重新启动MCP客户端（例如Cursor、Claude Desktop）
- 通过你的人工智能助手开始使用这些工具！
常见工作流
检查数据库架构：
Use get_schema to see all tables and reducers in the database查询数据：
Use sql_query to SELECT data from tables创建实体：
Use call_reducer to invoke reducer functions like CreateUser监控活动：
Use get_logs to see recent database activity故障排除
连接错误
如果您看到连接错误：
- 验证
SPACETIMEDB_HOST是正确的 - 检查您的SpacetimeDB实例是否正在运行
- 确保
SPACETIMEDB_TOKEN有效
身份验证错误
如果你收到401/403错误：
- 验证您的
SPACETIMEDB_TOKEN是有效的不记名代币 - 检查数据库操作的令牌权限
未找到数据库
如果数据库操作出现404错误：
- 验证数据库名称是否正确
- 检查SpacetimeDB实例上是否存在该数据库
- 确保您的令牌可以访问数据库
SQL分析器错误
某些SQL查询可能不受支持。解析器在以下方面存在局限性：
- 复杂
ORDER BY条款 - 某些
WHERE子句格式 - 一些高级SQL功能
如果遇到解析器错误，请尝试简化查询。
发展
建筑
npm run build这将TypeScript源文件编译为 dist/index.js.
测试
npm test出版
手动发布助手（构建、测试、打包、发布）：
npm run publish-release项目结构
spacetimedb-mcp/
├── src/
│ ├── client.ts # SpacetimeDB HTTP client
│ ├── index.ts # CLI entry point
│ ├── server.ts # MCP server wiring
│ └── types.ts # Shared type definitions
├── dist/
│ └── index.js # Compiled output
├── tests/
│ ├── client.test.ts # Client unit tests
│ └── server-handlers.test.ts # Server handler unit tests
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── README.md需求
- Node.js>=18.0.0
- 访问SpacetimeDB实例
- 有效的SpacetimeDB身份验证令牌
许可证
麻省理工学院
链接
-