foodblock-mcp

FoodBlock

食品领域的陌生人达成共识所需的最小语言，没有老板。其他一切都是数据。

一个区块包含三个字段，由作者在自己的设备上签名：

{
  "type": "promise",
  "state": {
    "terms": { "price": { "minor": 450, "currency": "GBP" }, "quantity": { "value": "30", "unit": "{egg}" } },
    "at": "2026-10-15T09:00:00.000Z",
    "audience": "public",
    "seq": 4
  },
  "refs": { "author": "a1b2…", "prev": "c3d4…", "from": "a1b2…", "what": "e5f6…" }
}

这是一份要约：由其 from 一方签名。它的 ID 是其规范形式的哈希（将其写成文本的一种精确方式：RFC 8785）。作者使用 Ed25519（默认套件；p256 和 sm 是另外两种）对相同字节进行签名。谁拥有权限不由任何人的时钟决定。另一方可以验证该权限。没有这些信息，任何内容都无法丢失或伪造而不留下痕迹。

• 规范： spec/protocol.md，FoodBlock 1.6（修订于 2026-10-19）。这是规范性文件：本文其他内容如有冲突，以此为准。相关文件还有：protocol.json（所有列表，供代码加载）、规范形式、传输（电子邮件是信封，FoodBlock 是信件），以及一致性测试向量。协议中没有更早的版本：1.6 是元年。旧数据只能通过转换器导入一次，该转换器不属于协议的一部分。NECESSITY.md 展示了每个字段、术语、动词、封闭类型、引用键和不变量缺失时哪些测试向量会失败；EXPERIMENTS.md 记录了尝试过的精简方案。
• 论文： FoodBlock 白皮书 v1.6（PDF）（DOI 10.5281/zenodo.23457910）：介绍协议存在的原因。如果论文与规范存在差异，以当前规范为准。

语言

七种类型，分为三种语气：

	类型	含义
存在什么	actor	人、自治系统或机器、群体，或联系人
	thing	任何被持有、发现或书写的事物：食物、工具、地点、食谱、份额、模式
是	observe	声明某事确实如此
	transform	某个事物发生变化：输入变成输出，或某个事物被保留且保持原样
	transfer	某个事物更换所有者、持有者或地点
必须	promise	一项承诺，可以主动提出，也可以请求
可以	grant	授予某人的权限

七种动词，用于关联区块的引用：updates、answers（唯一的同意方式）、confirms、defeats、for、derives_from、same_as。prev 和 after 用于说明先后关系。

严格。 只有四种类型携带权限且为封闭类型（actor、promise、transfer、grant）；其他任何词都是开放类型，节点会存储并传递它们。节点只按 1.6 的格式写入和读取：不允许 null、不允许浮点数（金钱表示为 { minor, currency }，数量表示为带十进制字符串的 { value, unit }），时间必须是精确的 UTC 时间，集合必须排序后写入，每个区块都必须位于其密钥对应的链中（state.seq、refs.prev）。节点绝不修复区块：它会拒绝区块，由作者签署一个新区块。

三种规模的节点

每个节点都直接使用协议：手机、机器人厨房、配送货车、无人机、智能冰箱、传感器。机器和人一样，都是节点。任何食品设备都可以接入 SDK、创建自己的身份，并在其持有的授权范围内行动。每个节点分为三种规模（protocol.json peers）：

• Micro，设备：土壤或冰箱传感器、秤、烤箱、机器人的机体。它需要规范形式、SHA-256、Ed25519、写入检查、自有链，以及这些内容对应的向量。能在现实世界中行动的设备还会检查授权，并在收到停止指令时立即停止。
• Edge，本地操作端：农场、厨房、货车或商店里的计算机。它还支持本地发现、与附近节点拉取和推送、自身交易的承诺折叠，并可在离线状态下持续工作。
• Node，持久层级：增加密封信封和承诺，向任何人提供拉取和推送服务、提供签名答复、支持互联网发现，并对其持有的每条记录进行折叠。

只有人和机器持有节点。企业、家庭或社区是由多个节点组成的圈子：它有一个 ID 和一条记录，由成员的节点保存，而不是由自己持有一个节点。

内容

文件夹	内容
spec/	协议、列表、规范形式、传输、配置、向量、预言机和论文
sdk/javascript	参考 SDK
sdk/rust	唯一核心：以 Rust crate、C 库和 WebAssembly 实现的每条规则
sdk/python、sdk/go、sdk/swift、sdk/kotlin	以其他语言实现的相同协议，是核心的轻量封装；每个 SDK 都会运行所有向量章节
server/	一个节点：使用 Postgres 存储区块，通过 HTTP 提供签名的拉取、推送和 .well-known/foodblock
mcp/	一个 MCP 服务，让任何自主系统都能读写签名区块
cli/	fb：创建身份和设备密钥，在其密钥链中写入区块，检查、验证、核验，并一次性转换旧数据
sql/schema.sql	节点存储：仅追加，每个区块都按收到时的原样保存
test/	跨语言规范向量，以及将规范复制到每个 SDK 的脚本

每个 SDK 的 README 都会说明其涵盖的配置。

面向自主系统

FoodBlock 旨在供人、自主系统和机器协同使用。自主系统可以直接读取和写入：

• MCP 服务：mcp/，适用于 Claude、Cursor、Windsurf、Gemini CLI 和任何兼容 MCP 的自主系统
• 单文件规范：spec/protocol.md，所有列表均可通过机器读取，见 spec/protocol.json
• 大模型速查：https://foodx.network/llms.txt
• 关于 FoodX：https://foodx.network

快速开始

const fb = require('@foodxdev/foodblock') // in this repository: require('./sdk/javascript/src/index.cjs')
const keys = fb.generateKeypair()                  // one key is the whole ceremony
const me = fb.identity.genesis(keys)               // who you are: its hash is your id
const eggs = fb.write('thing', { kind: 'eggs', name: 'Free-range eggs' }, {}, { author: me.hash, key: keys, held: [me] })
fb.valid(eggs, [me])                               // [] : sound, signed by a key of its author, in its chain

在终端中：

cd cli && npm install
node bin/fb.js init me.json
node bin/fb.js create thing eggs --state '{"name":"Free-range eggs"}' --identity me.json

节点之间

任何人都可以带着自己签署的所有内容离开一个节点。对等节点通过两条消息交换区块（spec/modules/nodes.md）：

• Pull { since, limit, filter, heads }：按到达编号获取之后的所有匹配项，按时间从早到晚排列，从不排序。 heads: true 仅返回最新区块。经过签名的拉取请求还能证明请求者的身份，因此会收到密封给他们的副本。
• Push { messages, for }：节点会保留其作者签署的内容，以及所有者的准入规则允许的内容。 如果缺少前一区块，该区块会暂缓处理。同一密钥的两个区块指向同一个 prev，即可证明存在谎言。
• 签名请求携带 counter 或 challenge（GET /challenge），不携带时间。
• 每个响应都由节点持有者（个人或机器）的密钥签名。
• 发现：.well-known/foodblock 会说明节点的身份、所持内容、代表谁发言，以及准入规则。在本地网络中，也可以用更简短的形式公布这些信息。

使用 docker compose -f server/docker-compose.yml up 运行，或在 DATABASE_URL 指向 Postgres 且 NODE_KEY 指向由 fb key 生成的密钥文件时，运行 cd server && npm install && npm start。

测试

内容	命令
一致性测试向量	node spec/run-vectors.cjs
SDK 与规范完全一致	node test/sync-spec.cjs --check
JS SDK	cd sdk/javascript && npm test
Python SDK	cd sdk/python && python3 -m unittest discover -s tests
Go SDK	cd sdk/go && CGO_ENABLED=0 go test ./...
Swift SDK	sdk/swift/scripts/build-xcframework.sh --macos && swift test（在根目录运行）
Rust 核心	cd sdk/rust && cargo test
Kotlin SDK	cd sdk/kotlin && ./gradlew :foodblock:test（需要 JDK 17）；捆绑库检查：scripts/build-natives.sh jvm && ./gradlew :foodblock:testBundled
仅根据规范文本编写的预言机	node spec/oracle/run.cjs
针对预言机审计所有折叠操作	node test/audit/run.cjs
没有列出的内容是无用或未经测试的	node test/necessity.cjs（完整测量需要十分钟：node tools/necessity.cjs）
将存储的区块与当前核心进行比对	node tools/replay-check.cjs <export>（仅显示计数和原因代码；参见 DISTRIBUTION.md）
节点	cd server && npm test（使用内存中的 Postgres；如需使用真实数据库，请设置 TEST_DATABASE_URL）
MCP 服务	cd mcp && npm test
CLI	cd cli && npm test

许可证

MIT。版权所有者为 FOODX WORLD LIMITED（英格兰和威尔士，注册公司编号 16406719），该公司拥有此代码仓库。实现此协议无需任何人的许可。

如何提出变更以及版本如何运作：GOVERNANCE.md。我们如何彼此相处，以及哪些内容不被允许：CODE_OF_CONDUCT.md。报告安全弱点：SECURITY.md。

引用 FoodBlock，请参见 CITATION.cff。