mcp-ptitchef

# mcp-ptitchef

[![CI](https://github.com/smeet666/mcp-ptitchef/actions/workflows/ci.yml/badge.svg)](https://github.com/smeet666/mcp-ptitchef/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/mcp-ptitchef)](https://www.npmjs.com/package/mcp-ptitchef)
[![licence MIT](https://img.shields.io/badge/licence-MIT-blue)](LICENSE)

An MCP server that reads recipes on [Ptitchef](https://www.ptitchef.com).
Read-only, no API key, no account.

_[Version française](#mcp-ptitchef-français)_

---

## Why it exists

Ptitchef browses its recipes by a tree of ingredient families, and it writes the
address of each category freely. The same kind of thing appears as `chou-kale`
on one line, as `recette-de-petits-pois` on the next and as `recettes-aux-feves`
on a third. There is no rule to derive one from an ingredient's name.

An address built by hand therefore misses, and the site answers a miss by
sending the reader to the root of the tree with HTTP 200 and the root's own
categories. A model that guessed a slug gets a full, confident answer about a
level it never asked for.

This server publishes the tree, so a category is opened by the name the site
gave it.

## The tools

### `list_categories`

Lists the categories recipes are browsed by. Called without arguments it returns
the families of ingredients; pass a family's slug back to list what it holds.

| Argument | Type              | Meaning                                                                            |
| -------- | ----------------- | ---------------------------------------------------------------------------------- |
| `family` | string, optional  | The slug of a family to open, from a previous call. Leave it out to read the root. |
| `limit`  | integer, optional | Entries to render, 50 by default, 200 at most.                                     |

```json
{
  "family": null,
  "family_title": "Recettes de cuisine sur Ptitchef",
  "categories": [
    {
      "slug": "legume",
      "title": "Légume",
      "url": "https://www.ptitchef.com/recettes/cat/legume",
      "description": null,
      "sample_children": [
        {
          "slug": "pois-mange-tout",
          "title": "Pois mange-tout",
          "url": "https://www.ptitchef.com/recettes/pois-mange-tout"
        }
      ],
      "is_family": true
    }
  ],
  "category_count": 15,
  "categories_published": 15,
  "url": "https://www.ptitchef.com/recettes",
  "source": "Ptitchef",
  "notes": ["…"]
}
```

### `search_recipes`

Searches by dish or ingredient. The site answers in one of two ways, and `kind`
says which.

| Argument | Type              | Meaning                                     |
| -------- | ----------------- | ------------------------------------------- |
| `query`  | string            | A dish or an ingredient, in French.         |
| `limit`  | integer, optional | Rows to render, 20 by default, 100 at most. |

Searching `puree de patate douce` comes back as `kind: "topic"` with
`topic_slug: "puree-de-patates-douces"`: the site holds a page for it, sent the
search there, and the total counts what that page holds. Searching
`soupe froide concombre menthe` comes back as `kind: "free_text"`: the site holds
no such page, answered on its own terms, and the total is the number of rows it
served.

### `browse_recipes`

Reads a category page by page, or one of the three lists the site keeps standing.

| Argument   | Type                                     | Meaning                                                    |
| ---------- | ---------------------------------------- | ---------------------------------------------------------- |
| `category` | string, optional                         | A slug from `list_categories`, or a search's `topic_slug`. |
| `listing`  | `latest` \| `top_rated` \| `most_viewed` | One of the site's standing lists.                          |
| `page`     | integer, optional                        | The page of a category to read.                            |
| `limit`    | integer, optional                        | Rows to render, 20 by default.                             |

### `search_by_ingredients`

Reads the site's own fridge search: one to five ingredients in, recipes holding
them out.

| Argument      | Type              | Meaning                             |
| ------------- | ----------------- | ----------------------------------- |
| `ingredients` | string[]          | One to five ingredients, in French. |
| `limit`       | integer, optional | Rows to render, 20 by default.      |

### `get_recipe`

Reads one recipe, and rescales its ingredients on request.

| Argument   | Type              | Meaning                                        |
| ---------- | ----------------- | ---------------------------------------------- |
| `id`       | string            | The `id` of a row from a search or a listing.  |
| `servings` | integer, optional | Rescale the ingredients to this many servings. |

Every line carries a `scaling` that says what the arithmetic did: `scaled` is
exact, `rounded` was moved to stay usable, `unscaled` carries nothing that could
be multiplied. Doubling `1 oeuf` gives `2 oeufs`; halving it gives `1 oeuf`
marked `rounded`, because half an egg is not an amount a kitchen measures out.

### `scale_ingredients`

The same arithmetic, offline, on any French ingredient list whatever its source.

| Argument                          | Type     | Meaning                              |
| --------------------------------- | -------- | ------------------------------------ |
| `ingredients`                     | string[] | The lines to rescale.                |
| `factor`                          | number   | The multiplier to apply.             |
| `from_servings` and `to_servings` | numbers  | Or the pair the factor is read from. |

### `get_recipe_translations`

Lists the other languages a recipe was published in. Ptitchef is the French
edition of a network of sites publishing the same recipes, and each page names
its counterparts. How many there are is the recipe's own business: a recent one
names more than twenty, an older one names none, and the answer states what the
page carries rather than a number fixed here.

## What the answers refuse to overstate

**A level the site substituted is not the level that was asked for.** An unknown
family is answered with HTTP 200 and the root of the tree, so the address the
answer came back from decides which level it is. A family that was not held is
reported as `not_found`, rather than rendered as the categories the site offered
instead.

**The entries beside a family are an excerpt.** The root shows three of them
followed by an ellipsis the site prints itself. They are returned under
`sample_children` and a note says what they are, because rendering them as the
family's contents would offer a family of ninety as a family of three.

**Two counts, because they answer two questions.** `categories_published` is what
the page listed and `category_count` is what the answer rendered. They differ
whenever a limit cut the list, and the note says by how much rather than letting
a capped listing read as a complete one.

**An entry with no address is set aside rather than rendered.** A heading the
site published without a link carries no slug to pass back, so it is dropped,
counted, and named in the notes.

**A blurb the page does not carry is `null`, never an empty string.** An empty
description would offer wording that was never published.

**A listing has two totals that count different things, and the answer says
which arrived.** A search the site sends to a category page reports that
category's total; a search it answers itself reports the number of rows it
served. Summing the two would add a catalogue to a page.

**A rating is the figure the site computed.** A row states
3.8 in its payload and draws four stars. The drawn figure is left alone.

**A page past the last one comes back as the page the site served.** The site
answers it with the first page, so reporting the number that was asked for would
send a caller round the same rows for ever.

**The fridge search counts far past what it serves.** It finds eighty-nine
recipes for three ingredients, offers twenty-four of them on one page, and links
no other. The answer states both figures and says the rest cannot be read.

**A guide is not a listing, and the answer says which arrived.** Some topics are
served as a guide the site wrote: recipes grouped under headings of its own,
with no total, and rows carrying only a name and an address. `kind` says `guide`
there, and `browse_recipes` on the same slug reads the topic's full listing with
its total: `épinards` comes back as a guide of 32, and its listing holds 736.

**Another recipe served in place of one is rendered as an absence.** The words
of a recipe's address are decorative and its number is not: asking for a number
the site does not hold brings back an unrelated recipe, in HTTP 200 and full
detail. The number that came back is compared with the number asked for.

**Nothing is multiplied blindly.** A countable thing lands on the smallest share
a cook takes out of one of it: a whole where half of one cannot be measured out,
an egg; a half where half of one pours or splits, a sachet. A mass moves to a
smaller unit before it is rounded, so a quantity under one never rounds to zero.
A pinch keeps its own vocabulary and has its count multiplied, because the size
of one is the cook's.

**A list handed back unrescaled says so once, rather than line by line.** With no
servings asked for there is no arithmetic, and marking every line `unscaled`
would claim that none of them carries anything to multiply.

**The cost the site estimates is repeated, never recomputed.** It is the site's
own figure, and readers of the site dispute it as too low; the answer says so
rather than quietly passing it on or silently dropping it.

## Install

```bash
npx mcp-ptitchef
```

### Claude Code

```bash
claude mcp add ptitchef --