# io.github.FoodXDevelopment/foodblock-mcp (npm · foodblock-mcp)

Food data tools for any AI agent. Describe food in English, get structured data back.

- Trust score: 70/100 (medium)
- Change this week: −10
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `foodblock-mcp`: 70/100 (this document), [markdown](https://verifymcp.io/servers/foodxdevelopment-foodblock-mcp/foodblock-mcp.md), [page](https://verifymcp.io/servers/foodxdevelopment-foodblock-mcp/foodblock-mcp)

## Channel facts

- Registry: `npm`
- Package: `foodblock-mcp`
- Version: `0.5.1`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 87/100
  - No malware found by supply-chain analysis.
  - Only part of the dependency tree could be resolved (96 of 100), so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (96 of 100), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 166 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 77/100
  - AI-judged instruction clarity (excellent).
  - Tool/resource definitions use about 1486 tokens (~87/item across 17 items; 17 tools + 0 resources), lean.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 27/100
  - Stability observed for 8 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add foodxdevelopment-foodblock-mcp -- npx -y foodblock-mcp
```

### Codex

```bash
codex mcp add foodxdevelopment-foodblock-mcp -- npx -y foodblock-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "foodxdevelopment-foodblock-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "foodblock-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add foodxdevelopment-foodblock-mcp --command npx --arg -y --arg foodblock-mcp
```

### Hermes

```yaml
mcp_servers:
  foodxdevelopment-foodblock-mcp:
    command: "npx"
    args: ["-y", "foodblock-mcp"]
```

### Other

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

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-03 (score 70, +50)

- [security regression] Provenance: unverified → fail
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Install scripts: unverified → pass
- [functional improvement] MCP protocol: unverified → pass
- [functional improvement] Stability: unverified → 0.27
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] License: unverified → pass
- [functional improvement] Tool coverage: unverified → 100
- [functional] Licence: MIT

### 2026-08-02 (score 20, −16)

- [security improvement] Malware scan: unverified → pass
- [security] Stability: Stability not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.
- [functional regression] Tool coverage: 100 → unverified
- [functional regression] Capabilities: pass → unverified

### 2026-08-01 (score 36, +31)

- [security] Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window).
- [functional improvement] Tool coverage: unverified → 100
- [functional improvement] MCP protocol: unverified → pass

### 2026-07-31 (score 5, −57)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-30 (score 62, −18)

- [security regression] Malware scan: pass → unverified

### 2026-07-27 (score 80, +37)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-26 (score 43)

First indexed and scored.

## MCP tools (17)

### `foodblock_create` (~205 tokens)

Create FoodBlock

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.

Input parameters:

- `refs` (object): References to other blocks by hash. Example: { seller: 'abc123...' }
- `state` (object): The block's properties as a JSON object. Example: { name: 'Sourdough', price: 4.50 }
- `type` (string, required): Block type. Base types: actor, place, substance, transform, transfer, observe. Use dot notation for subtypes, e.g. actor.producer, substance.product, transfer.order

### `foodblock_update` (~121 tokens)

Update FoodBlock

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.

Input parameters:

- `previous_hash` (string, required): The hash of the block to update (64-character hex string)
- `refs` (object): Additional refs (updates ref is added automatically)
- `state` (object): The new state (full replacement, not a merge)
- `type` (string, required): The block type (must match the original)

### `foodblock_get` (~39 tokens)

Get FoodBlock

Fetch a specific FoodBlock by its SHA-256 hash.

Input parameters:

- `hash` (string, required): The 64-character hex hash of the block to retrieve

### `foodblock_query` (~129 tokens)

Query FoodBlocks

Search for FoodBlocks by type, ref, or heads. Returns matching blocks.

Input parameters:

- `heads_only` (boolean): If true, only return head blocks (latest version in each chain)
- `limit` (number): Maximum results to return (default 20)
- `ref_role` (string): Filter by ref role name. Use with ref_value. Example: 'seller'
- `ref_value` (string): Filter by ref value (a block hash). Use with ref_role.
- `type` (string): Filter by type (exact or prefix). Examples: 'actor', 'substance.product'

### `foodblock_chain` (~67 tokens)

Trace Provenance Chain

Follow the update chain of a FoodBlock backwards through its versions. Shows the full version history: current → previous → original.

Input parameters:

- `hash` (string, required): The hash of the block to trace backwards from
- `max_depth` (number): Maximum chain depth to traverse (default 50)

### `foodblock_tree` (~72 tokens)

Trace Provenance Tree

Build the full provenance tree for a FoodBlock by following ALL refs recursively. Shows the complete story: bread ← baking ← flour ← wheat ← farm.

Input parameters:

- `hash` (string, required): The hash of the block to build the provenance tree from
- `max_depth` (number): Maximum tree depth (default 10)

### `foodblock_heads` (~45 tokens)

List Head Blocks

List all head blocks (latest version of each entity/item). Optionally filter by type.

Input parameters:

- `type` (string): Optional type filter (e.g. 'substance.product')

### `foodblock_info` (~38 tokens)

FoodBlock System 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` (~131 tokens)

Create AI 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.

Input parameters:

- `capabilities` (array): Agent capabilities
- `model` (string): AI model, e.g. 'claude-sonnet'
- `name` (string, required): Name for the agent, e.g. 'Bakery Assistant'
- `operator_hash` (string, required): Hash of the actor this agent works for

### `foodblock_load_agent` (~88 tokens)

Load Agent

Load a previously created agent using saved credentials. Required after MCP server restart to restore signing ability.

Input parameters:

- `agent_hash` (string, required): The agent's block hash (from foodblock_create_agent)
- `private_key` (string, required): The agent's private key hex (from foodblock_create_agent credentials)
- `public_key` (string): The agent's public key hex (optional, for verification)

### `foodblock_agent_draft` (~94 tokens)

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

Input parameters:

- `agent_hash` (string, required): Hash of the agent creating this draft
- `refs` (object): Block refs
- `state` (object): Block state
- `type` (string, required): Block type, e.g. 'transfer.order'

### `foodblock_approve_draft` (~45 tokens)

Approve Agent Draft

Approve a draft block created by an agent. Creates a confirmed version with draft removed.

Input parameters:

- `draft_hash` (string, required): Hash of the draft block to approve

### `foodblock_list_agents` (~20 tokens)

List Agents

List all AI agents in the FoodBlock system.

### `foodblock_tombstone` (~124 tokens)

Tombstone FoodBlock

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.

Input parameters:

- `reason` (string): Reason for erasure (e.g. 'gdpr_erasure', 'user_request')
- `requested_by` (string, required): Hash of the actor requesting erasure
- `target_hash` (string, required): Hash of the block to tombstone (64-character hex string)

### `foodblock_validate` (~80 tokens)

Validate FoodBlock

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.

Input parameters:

- `refs` (object): Block refs to validate
- `state` (object): Block state to validate
- `type` (string, required): Block type to validate

### `foodblock_batch` (~69 tokens)

Batch Create FoodBlocks

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.

Input parameters:

- `blocks` (array, required): Array of blocks to create, each with type, state, refs

### `foodblock_fb` (~119 tokens)

Natural Language FoodBlock

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

Input parameters:

- `text` (string, required): Any food-related natural language text

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/foodxdevelopment-foodblock-mcp/foodblock-mcp#diagnostics

## Score history

- 2026-08-03: 70
- 2026-08-02: 20
- 2026-08-01: 36
- 2026-07-31: 5
- 2026-07-30: 62
- 2026-07-28: 80
- 2026-07-27: 80
- 2026-07-26: 43

## Links

- npm package: https://www.npmjs.com/package/foodblock-mcp
- Socket report: https://socket.dev/npm/package/foodblock-mcp
- Repository: https://github.com/FoodXDevelopment/foodblock
- Changelog RSS feed: https://verifymcp.io/servers/foodxdevelopment-foodblock-mcp/foodblock-mcp/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/foodxdevelopment-foodblock-mcp/foodblock-mcp/changelog.json
- HTML version of this page: https://verifymcp.io/servers/foodxdevelopment-foodblock-mcp/foodblock-mcp