Achiote

# Achiote

**TL;DR:** Achiote — food-memory and cultural taste research product. Best for researchers and builders exploring food memory and heritage taste. Keywords: food memory research, cultural taste, heritage cuisine AI.

Achiote is a **Model Context Protocol (MCP)** server for research-first food-and-drink memory reconstruction. It helps a host AI turn incomplete family food or drink memories into structured clues, research plans, cited/provenance-ready findings, sensory analysis, sourcing/substitution strategy, and a minimum viable nostalgia cue before any fuller recipe handoff.

> "The nostalgia lives in the maillard crust's interaction with the lactic tang — here's how to reproduce that."

## Super Quick Start

From this repo:

```bash
npm ci
npm run build
mkdir -p ~/.codex/skills/achiote
cp skill/SKILL.md ~/.codex/skills/achiote/SKILL.md
```

Claude Code can use the checked-in `.mcp.json` after the build step. For Codex, add the MCP server to `~/.codex/config.toml` with an absolute path to this repo's built `dist/index.js`:

```bash
pwd
# copy the printed path and append /dist/index.js
```

```toml
[mcp_servers.achiote]
command = "node"
args = ["/absolute/path/to/achiote/dist/index.js"]
enabled = true
startup_timeout_sec = 10
```

Restart the host AI session, then test with:

```text
Use the achiote skill.

My mom said my Puerto Rican grandma made something that sounded like pass-teh-lay. I don't speak Spanish. Maybe plantains or pork?
```

Expected behavior: the host AI should use the MCP tools to collect the memory, plan research, build a dossier, and present a minimum viable nostalgia cue first. Only after that should it ask whether the user wants something more complex, such as sourcing help or a full recipe handoff.

## Public Web Surfaces

The hosted/static product surface lives under [`docs/landing/`](docs/landing/). The core app and launch pages are dependency-free static assets served by the optional HTTP server:

- `/` -> [`docs/landing/index.html`](docs/landing/index.html), the public landing page.
- `/app` -> [`docs/landing/app.html`](docs/landing/app.html), the interactive food-memory detective.
- `/pricing`, `/about`, `/roadmap`, `/changelog`, `/status`, `/blog`, and `/receipt` -> standalone launch/trust/growth pages.
- `/ai-search`, `/llms.txt`, `/privacy`, `/terms`, `/safety`, `/support`, `/compare`, `/robots.txt`, and `/sitemap.xml` -> AI-search, legal, support, comparison, and crawler surfaces.

Open the HTML files directly in a browser for static review; the full route behavior is covered by `npm run package:smoke`.

## What It Does Today

Achiote is a research-first food-and-drink memory reconstruction server. It provides 18 MCP tools that let a host AI chat client run the workflow from a fragment to a minimum viable nostalgia cue, with optional sourcing/substitution and recipe handoff if the user wants more:

| Stage | Tool | Implemented behavior |
|------|------|----------------------|
| Workflow control | `plan_tool_workflow` | Deterministically plans the `/ask` tool sequence from the raw user message so provider models do not freestyle the workflow. |
| Memory intake | `collect_food_memory` | Structures raw fragments, sound-alikes, family context, remembered ingredients, sensory clues, missing information, and gentle next questions. |
| Research planning | `plan_dish_research` | Produces hypotheses, search queries, source preferences, facts to verify, and clarification questions for foods or drinks. It plans research instead of pretending sparse fragments are solved. |
| Optional search adapter | `search_web` | Uses configured host search (`SERPER_API_KEY`) when available, otherwise returns an explicit no-search note. Search remains optional and should not be treated as guaranteed runtime behavior. |
| Research provenance | `build_research_record` / `validate_research_record` / `extract_research_findings` | Converts host-researched source facts into typed provenance records, validates source metadata, and summarizes researched facts/inferences/unknowns for dossier handoff. |
| Evidence ledger | `build_reconstruction_dossier` | Builds a dossier that separates user-said, researched, inferred, and unknown claims, plus sensory priorities and adaptation strategy. |
| Receipt | `build_memory_receipt` | Builds a portable Memory Receipt from collected memory, research plan, and optional first tiny taste test so families can inspect and correct the evidence trail. |
| Family connection | `generate_family_followup_questions` | Generates gentle questions the user can ask relatives to deepen the memory and resolve uncertainty. |
| Name resolution | `resolve_dish_name` | Resolves names to broad families and ambiguity-aware candidates using bundled aliases, fuzzy matching, and transliterations. |
| Sensory analysis | `analyze_nostalgic_dish` | Returns sensory-dimension criteria and a bounded prompt for the host model to analyze nostalgia-critical elements. |
| Substitution | `find_sensory_substitutes` | Returns compound/group-matched substitutes from bundled ingredient data, plus regional hints when available. |
| Sourcing | `source_ingredients` | Returns static regional store/corridor hints and a host-model prompt for sourcing. It returns static sourcing guidance, not live inventory, and does not perform live price lookup. |
| Regional comparison | `discover_regional_similars` | Returns bundled dish-family context and a host-model prompt for neighboring/regional comparisons. |
| Minimum viable nostalgia cue | `generate_minimum_viable_nostalgia` | Produces the smallest practical aroma, bite, sip, condiment, or ritual to test the likely memory trigger before attempting a full recipe or drink. It prioritizes cheap, accessible, easy-to-find proxies and explains the substitute logic instead of defaulting to exact specialty ingredients. |
| Optional recipe handoff | `generate_recipe` | Returns an expected recipe schema and a bounded host-model prompt for recipe generation and self-critique. Use only after the minimum viable cue has been presented and the user wants something more complex. |
| Recipe validation | `validate_recipe_output` | Validates a host-synthesized final recipe object against the expected schema before treating it as structured output. |

All tools return MCP `structuredContent`. Most tools also display JSON text; intake tools may display a short human-readable summary so Claude Code output stays readable while structured data remains available to the host.

## End-to-end flow

```text
food memory fragment
  -> collect_food_memory
  -> plan_dish_research
  -> optional host research / family clarification
  -> build_research_record / validate_research_record / extract_research_findings
  -> build_reconstruction_dossier
  -> generate_family_followup_questions
  -> generate_minimum_viable_nostalgia   # first concrete food output
  -> optional analyze_nostalgic_dish / find_sensory_substitutes / source_ingredients
  -> optional generate_recipe            # only if the user wants more
```

This executes through the full MCP workflow and is covered by `tests/reconstruction-flow-e2e.test.ts`. The preferred stopping point is the **minimum viable nostalgia cue**: the smallest, most accessible, easiest-to-find aroma, bite, sip, condiment, or ritual that tests whether the memory is on the right track. If the user asks for more, the MCP server can then provide sourcing/substitution context and a recipe-generation **handoff**. The host AI writes final recipe prose because live research, family confirmation, and adaptation judgment should not be faked by bundled data.

## Requirements

- Node.js `>=22.0.0`
- npm

`better-sqlite3` is a native dependency, so unsupported Node/platform combinations may need a compiler toolchain or a supported prebuild.

## Installation

Achiote is published to npm.

```bash
npm install achiote
```

The published package ships the built `dist/` output, so no build step is needed. To run from a source checkout instead:

```bash
npm ci
npm run build
```

## Using with Claude Code or another MCP client

After building, add the stdio server to your MCP settings:

```json
{
  "mcpServers": {
    "achiote": {
      "command": "node",
      "args": ["/path/to/achiote/dist/index.js"]
    }
  }
}
```

If installed as a package, the CLI binary is `achiote`.

## HTTP server

An optional HTTP server provides a web UI and AI agent endpoint:

```bash
node dist/http-server.js
# Listening on http://localhost:3000
```

| Endpoint | Description |
|----------|-------------|
| `GET /` | Public landing page (`index.html`) |
| `GET /app` | Web UI (`app.html`) |
| `GET /about` | Trust/company page (`about.html`) |
| `GET /pricing` | Standalone pricing page (`pricing.html`) |
| `GET /roadmap` | Public roadmap page (`roadmap.html`) |
| `GET /changelog` | Public changelog page (`changelog.html`) |
| `GET /status` | Public service status page (`status.html`) |
| `GET /blog` | Launch blog index (`blog.html`) |
| `GET /receipt` | Shareable Memory Receipt renderer (`receipt.html`) |
| `GET /ai-search`, `/llms.txt`, `/privacy`, `/terms`, `/safety`, `/support`, `/compare` | Public AI-search, legal, support, safety, and comparison surfaces |
| `GET /health` | JSON status with memory/uptime metrics |
| `GET /voice/status` | Local OSS speech readiness for optional voice input/read-aloud |
| `POST /voice/transcribe` | Local speech-to-text through a configured OSS engine |
| `POST /voice/synthesize` | Local text-to-speech through a configured OSS engine |
| `POST /ask` | SSE streaming AI agent (auth + rate limited) |
| `POST /mcp` | Streamable HTTP MCP transport |

Authentication is enabled by default for the HTTP server. Configure `ACHIOTE_API_KEYS` for `/ask`, `/mcp`, and voice upload endpoints. Setting `ACHIOTE_AUTH_ENABLED=false` does not by itself expose anonymous `/ask` or voice processing; set `ACHIOTE_ALLOW_ANON_ASK=true` only for local demos. Generate a self-hosted key with `npm run keygen