# FoodXDevelopment/foodblock-mcp [Health: Active]

**Category:** 🛠️ Other Tools and Integrations  
**Repository:** https://github.com/FoodXDevelopment/foodblock  
**GitHub Stars:** 1  
**npm Downloads (last month):** 137  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/foodxdevelopment-foodblock-mcp

## Description
17 MCP tools for the food industry. Describe food in plain English and get structured, content-addressed data blocks back. Covers actors, places, ingredients, products, transforms, transfers, and observations. Works standalone with zero config via npx foodblock-mcp.

## Tools
Capabilities this server exposes over MCP:

- **foodblock_create** — Create a new FoodBlock. A FoodBlock is the universal data primitive for the food system. It has three fields: type (what it is), state (its properties), refs (what it references). Base types: actor (person/org), place (location), substance (ingredient/product), transform (cooking/processing), transfer (sale/delivery), observe (review/certification). Use dot notation for subtypes: actor.producer, substance.product, observe.review, etc.
- **foodblock_update** — Create a new version of an existing FoodBlock. FoodBlocks are append-only — this creates a new block that references the previous one via refs.updates. Note: state is a FULL REPLACEMENT, not a merge.
- **foodblock_get** — Fetch a specific FoodBlock by its SHA-256 hash.
- **foodblock_query** — Search for FoodBlocks by type, ref, or heads. Returns matching blocks.
- **foodblock_chain** — Follow the update chain of a FoodBlock backwards through its versions. Shows the full version history: current → previous → original.
- **foodblock_tree** — Build the full provenance tree for a FoodBlock by following ALL refs recursively. Shows the complete story: bread ← baking ← flour ← wheat ← farm.
- **foodblock_heads** — List all head blocks (latest version of each entity/item). Optionally filter by type.
- **foodblock_info** — Get an overview of the FoodBlock system: server info, block count, and protocol summary. Call this first to understand what data is available.
- **foodblock_create_agent** — Register a new AI agent in the FoodBlock system. The agent gets its own identity, Ed25519 keypair, and can sign blocks. Every agent must have an operator — the human or business it acts for. IMPORTANT: Save the returned credentials — they cannot be recovered after server restart.
- **foodblock_load_agent** — Load a previously created agent using saved credentials. Required after MCP server restart to restore signing ability.
- **foodblock_agent_draft** — Create a draft FoodBlock on behalf of an agent. Draft blocks have state.draft=true. The human operator can approve or reject with foodblock_approve_draft.
- **foodblock_approve_draft** — Approve a draft block created by an agent. Creates a confirmed version with draft removed.
- **foodblock_list_agents** — List all AI agents in the FoodBlock system.
- **foodblock_tombstone** — Mark a FoodBlock for content erasure (GDPR compliance). Creates an observe.tombstone block that references the target. The target block's state is replaced with {tombstoned: true}. The hash, type, and refs are preserved for chain integrity.
- **foodblock_validate** — Validate a FoodBlock against its declared schema or a provided schema. Returns an array of error messages (empty means valid). Checks required fields, types, expected refs, and instance_id requirements.
- **foodblock_batch** — Create multiple FoodBlocks in a single request. Blocks are sorted in dependency order automatically. Useful for syncing offline-created blocks or bulk imports. Returns counts of inserted, skipped (duplicates), and failed blocks.
- **foodblock_fb** — The single natural language entry point to FoodBlock. Describe food in plain English and get structured FoodBlocks back. No need to know types, fields, or hashes. Examples: 'Sourdough bread, $4.50, organic, contains gluten', 'Amazing pizza at Luigi\'s, 5 stars', 'Green Acres Farm, 200 acres, organic wheat in Oregon', 'Walk-in cooler temperature 4 celsius', 'Ordered 50kg flour from Stone Mill'.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "foodblock-mcp": {
    "command": "npx",
    "args": ["-y","foodblock-mcp"]
  }
}
```

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/foodxdevelopment-foodblock-mcp/readme_