Foodblock MCP

What FoodXDevelopment/foodblock-mcp does

FoodXDevelopment/foodblock-mcp gives MCP-compatible AI clients an interface for creating and reading FoodBlocks. A FoodBlock is organized around three fields: a type, a state containing its properties, and refs linking it to other blocks. The server's food-oriented model covers actors such as people and organizations, places, ingredients and products, processing or cooking transforms, transfers such as sales and deliveries, and observations such as reviews or certifications.

The natural-language tool, foodblock_fb, accepts descriptions such as a product with a price and allergen information, a farm with acreage and crops, a temperature reading, or a flour order. It returns structured FoodBlocks without requiring the caller to select types, fields, or hashes. Applications that need exact control can use the lower-level creation and query tools instead.

Blocks are content-addressed with SHA-256 hashes. Updates are represented as new blocks rather than in-place edits, preserving a chain from the newest version back to the original. References can also connect related blocks into a provenance tree, such as a finished food linked to a transformation, its ingredients, and their source.

How it works

Start with foodblock_info to inspect server information, the number of stored blocks, and a protocol summary. Create records with foodblock_create, retrieve them by hash with foodblock_get, or search by type, reference, or head status using foodblock_query. foodblock_heads lists the latest block for each entity or item, while foodblock_chain follows version history and foodblock_tree recursively follows all references.

foodblock_update creates a replacement version and records the previous block through refs.updates. Its state argument replaces the complete prior state; it is not merged with the existing state. foodblock_batch accepts multiple blocks, orders them by dependency, and reports inserted, duplicate, and failed items.

The server also supports agent-mediated workflows. foodblock_create_agent registers an AI agent with an Ed25519 keypair and an operator, and foodblock_load_agent restores an agent from saved credentials after a restart. Agents can create drafts, while foodblock_approve_draft turns an approved draft into a confirmed version. foodblock_tombstone records a content-erasure action while retaining the target's hash, type, and references for chain continuity.

Setup and configuration

Run the standalone server with npx foodblock-mcp. The documented quick-start path requires no configuration, making it suitable for connecting from an MCP client without setting up a separate database or service. The server is intended for Claude, Cursor, Windsurf, Gemini CLI, and other MCP-compatible autonomous systems.

When creating an agent, save the returned credentials outside the running process. They are needed by foodblock_load_agent after a server restart and cannot be recovered after that restart. This matters whenever signed agent actions must continue across sessions.

Tools and capabilities

• Create, update, retrieve, search, and batch FoodBlocks.
• Inspect current heads, historical update chains, and recursive provenance trees.
• Convert plain-English food descriptions into structured blocks with foodblock_fb.
• Register agents, restore their credentials, and manage draft approval workflows.
• Validate blocks against declared or supplied schemas, including required fields, types, references, and instance identifiers.
• Mark blocks for content erasure through tombstone records.

Limitations and notes

FoodBlocks are append-only: changing a record creates another block rather than modifying the existing one. Updates replace the full state, so callers must provide every state property that should remain in the new version. Agent credentials require deliberate storage because a restart removes the ability to recover them from the server.

The protocol distinguishes duplicate batch entries from inserted and failed entries, so import code should inspect the returned counts. Validation returns an array of errors; an empty array indicates that the block passed the selected checks.