mcp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SpacetimeDB over MCP

通过 MCP 使用 SpacetimeDB

A SpacetimeDB host speaks MCP, so an MCP-aware client can operate a live database with tool calls instead of shell commands. If the client exposes

spacetimedb

tools, use them for anything that reads or changes a running database.

Check the tool list before deciding they are missing. The tools are passive: they appear as

spacetimedb.list_databases

spacetimedb.get_schema

spacetimedb.sql

spacetimedb.call

, and

spacetimedb.ping

, and nothing announces them.

SpacetimeDB 主机支持 MCP，因此支持 MCP 的客户端可以通过工具调用而非 shell 命令来操作实时数据库。如果客户端公开了

spacetimedb

工具，对于任何读取或修改正在运行的数据库的操作，都应使用这些工具。

在判断这些工具是否缺失之前，请先检查工具列表。这些工具是被动提供的：它们以

spacetimedb.list_databases

、

spacetimedb.get_schema

、

spacetimedb.sql

、

spacetimedb.call

和

spacetimedb.ping

的形式出现，不会主动通知其存在。

Which to reach for

该使用哪种方式

Task	Use
List databases, read a schema, run SQL, call a reducer	MCP tools
init, build, publish, generate, start, logs	`spacetime` CLI (see the `cli` skill)

The MCP tools only operate a database that already exists. They cannot scaffold a project, compile a module, publish, or generate bindings, so the two are complementary rather than alternatives. Prefer the tools when they are present: they are typed, they return JSON, and the client can gate the destructive ones. When no MCP client is attached, the equivalent CLI commands are correct.

任务	使用方式
列出数据库、读取 schema、执行 SQL、调用 reducer	MCP 工具
init、build、publish、generate、start、logs	`spacetime` CLI（参见 `cli` skill）

MCP 工具只能操作已经存在的数据库。它们无法创建项目脚手架、编译 module、publish 或生成 bindings，因此两者是互补关系，而不是替代关系。如果存在这些工具，应优先使用：它们的类型明确、返回 JSON，并且客户端可以对破坏性工具设置访问限制。未连接 MCP 客户端时，使用对应的 CLI 命令才是正确做法。

The tools

工具

Tool	Arguments	Returns
`list_databases`	none	the databases you own, with identity and names
`get_schema`	`database`	tables and reducers as JSON
`sql`	`database` , `sql` , optional `confirmed`	rows as JSON
`call`	`database` , `reducer` , optional `args` (JSON array)	the reducer outcome
`ping`	optional `message`	a health check

list_databases

lists only your own databases, so it is empty for an anonymous identity. Start there when you do not know the database name.

工具	参数	返回值
`list_databases`	无	你拥有的数据库，包含身份和名称
`get_schema`	`database`	以 JSON 形式返回表和 reducer
`sql`	`database` 、 `sql` 、可选的 `confirmed`	以 JSON 形式返回数据行
`call`	`database` 、 `reducer` 、可选的 `args` （JSON 数组）	reducer 的执行结果
`ping`	可选的 `message`	健康检查结果

list_databases

只会列出你自己的数据库，因此在匿名身份下返回空结果。不知道数据库名称时，应先调用它。

Two shapes, so read

tools/list

first

两种模式，因此先读取

tools/list

A server is either host-wide or scoped to one database. Do not assume which:

Host-wide (

spacetime mcp

with no database, or

POST /v1/mcp

). Every data tool takes a required

database

argument, a name or an identity, and

list_databases

is offered:

json

{ "name": "sql", "arguments": { "database": "mydb", "sql": "SELECT * FROM message" } }

Scoped (

spacetime mcp <database>

, or

POST /v1/database/<db>/mcp

). The connection fixes the database, so there is no

database

argument and no

list_databases

json

{ "name": "sql", "arguments": { "sql": "SELECT * FROM message" } }

When

spacetime mcp

runs inside a project with a

spacetime.json

that has a single unambiguous

server

, it uses that server unless

--server

--no-config

is passed. It does not infer a database from the config; omitting the database argument still means host-wide mode.

服务器可以是主机级（host-wide），也可以限定到单个数据库（scoped）。不要假设服务器属于哪一种：

主机级（host-wide）（使用不带数据库的

spacetime mcp

，或

POST /v1/mcp

）。每个数据工具都需要必填的

database

参数，该参数可以是名称或 identity，并且会提供

list_databases

：

json

{ "name": "sql", "arguments": { "database": "mydb", "sql": "SELECT * FROM message" } }

限定到单个数据库（scoped）（使用

spacetime mcp <database>

，或

POST /v1/database/<db>/mcp

）。连接已经确定了数据库，因此不需要

database

参数，也不会提供

list_databases

：

json

{ "name": "sql", "arguments": { "sql": "SELECT * FROM message" } }

如果在包含

spacetime.json

的项目中运行

spacetime mcp

，并且配置中只有一个明确无歧义的

server

，那么它会使用该 server，除非传入

--server

或

--no-config

。它不会根据配置推断数据库；省略数据库参数仍然表示主机级模式。

Rules that do not change

始终不变的规则

The tools run with your identity, exactly as the HTTP API does. The model is the same as everywhere else, so the

concepts

skill still governs:

Reducers are the write path. Use
```
call
```
to change data. It runs in a transaction that either fully commits or fully rolls back.
SQL writes require ownership.
```
sql
```
reads public tables; writing through it needs you to own the database. Prefer
```
call
```
.
Private tables are not client-readable.
```
get_schema
```
still shows a private table's declaration, so a
```
no such table
```
error from
```
sql
```
usually means the table is private rather than missing. Access depends on your identity, so do not assume a private table is readable.
Tool errors come back in band. A failed reducer or a bad query returns a result with
```
isError: true
```
and the message as text, not a transport failure. Read the text before retrying.

这些工具使用你的身份运行，与 HTTP API 完全一致。这里的模型与其他地方使用的模型相同，因此仍由

concepts

skill 负责约束：

Reducer 是写入路径。 使用
```
call
```
修改数据。它在事务中运行，事务要么完全提交，要么完全回滚。
通过 SQL 写入需要数据库所有权。
```
sql
```
可以读取 public 表，但通过它写入需要你拥有该数据库。优先使用
```
call
```
。
私有表对客户端不可读。
```
get_schema
```
仍会显示私有表的声明，因此
```
sql
```
返回
```
no such table
```
错误通常意味着该表是私有的，而不是不存在。访问权限取决于你的身份，因此不要假设私有表可读。
工具错误会带内返回。 reducer 执行失败或查询无效时，返回的是一个包含
```
isError: true
```
且以文本形式提供消息的结果，而不是传输层失败。重试前应先读取文本消息。

Inspecting a database

检查数据库

list_databases {}
get_schema     { "database": "mydb" }
sql            { "database": "mydb", "sql": "SELECT * FROM message" }
call           { "database": "mydb", "reducer": "send_message", "args": ["hello"] }

Pass

"confirmed": true

sql

to wait for a durably confirmed read.

list_databases {}
get_schema     { "database": "mydb" }
sql            { "database": "mydb", "sql": "SELECT * FROM message" }
call           { "database": "mydb", "reducer": "send_message", "args": ["hello"] }

向

sql

传入

"confirmed": true

，即可等待获得持久化确认的读取结果。

Troubleshooting

故障排查

Message	Meaning
`database argument must be a string`	The server is host-wide and you omitted `database`
`unknown tool: list_databases`	The server is scoped to one database already
`x` not found	No such database on this server, or a name where an identity was meant
`no such table: x`	The table is private, or you are querying the wrong database
No `spacetimedb` tools at all	No MCP server is connected. Use the CLI instead ( `cli` skill)

spacetime mcp

is UNSTABLE and subject to breaking changes. If a client cannot start it, fall back to the CLI commands in the

cli

skill.

Reference: https://spacetimedb.com/docs

消息	含义
`database argument must be a string`	服务器为主机级模式，但你省略了 `database`
`unknown tool: list_databases`	服务器已经限定到单个数据库
`x` not found	此服务器上不存在该数据库，或者应使用 identity 的地方使用了名称
`no such table: x`	该表是私有表，或者你查询了错误的数据库
完全没有 `spacetimedb` 工具	未连接 MCP 服务器。请改用 CLI（ `cli` skill）

spacetime mcp

仍处于 UNSTABLE 状态，可能会发生破坏性变更。如果客户端无法启动它，请回退到

cli

skill 中的 CLI 命令。

参考：https://spacetimedb.com/docs

mcp

Original

Translation

SpacetimeDB over MCP

通过 MCP 使用 SpacetimeDB

Which to reach for

该使用哪种方式

The tools

工具

Two shapes, so read
`tools/list`
first

两种模式，因此先读取
`tools/list`

Rules that do not change

始终不变的规则

Inspecting a database

检查数据库

Troubleshooting

故障排查