construct-purupuru-codex

Canonical knowledge base for the Purupuru universe — a world of honey-rooted magic, sentient Puruhani beings, and the Wuxing elemental cycles that bind them.

Built as a construct-format codex following the patterns established by construct-mibera-codex. Serves canonical lore over HTTP and MCP via HyperJS, wiring into the freeside API ecosystem.

What's in the codex

Category	Count	Path
KIZUNA Characters	5	`characters/`
Puruhani	5	`puruhani/`
Locations	19	`locations/`
Jani Variants	15	`jani/`
Cards	15	`cards/`
Wuxing Elements	5	`core-lore/wuxing.yaml`
Total Entities	59

The HENLO System

Letter	Element	Character	Trait	Puruhani
H	Wood	Kaori	Hopeful	Happy
E	Earth	Nemu	Empty	Exhausted
N	Fire	Akane	Naughty	Nefarious
L	Metal	Eun	Loyal	Loving
O	Water	Ruan	Overstimulated	Overwhelmed

HTTP API

RESTful API served via HyperJS with OpenAPI 3.1 spec and Swagger UI.

bun install
bun run dev    # starts on http://localhost:3000

Endpoints

Route	Method	Description
`/v1/characters/:slug`	GET	Look up a KIZUNA character
`/v1/puruhani/:identifier`	GET	Look up a Puruhani by element or name
`/v1/locations/:slug`	GET	Look up a location
`/v1/jani/:variant`	GET	Look up a Jani variant
`/v1/cards/:slug`	GET	Look up a canonical card
`/v1/elements/:name`	GET	Wuxing element with cycle relationships
`/v1/search?q=&limit=`	GET	Fuzzy search across all entities
`/v1/entities?type=`	GET	List all entities of a type
`/v1/validate`	POST	Validate a claim against canonical data
`/health`	GET	Service status with entity counts
`/openapi.json`	GET	OpenAPI 3.1 spec
`/docs`	GET	Swagger UI

All entity responses include world: "purupuru" for cross-service identification.

MCP

The same 9 tools are available over MCP via JSON-RPC 2.0 at POST /mcp, or via stdio for agent constructs:

node dist/server.js   # stdio transport (for Claude Desktop, etc.)

9 Tools

Tool	Description
`lookupCharacter`	Look up a KIZUNA character by name or slug
`lookupPuruhani`	Look up a Puruhani by element or name
`lookupLocation`	Look up a location by slug
`lookupJani`	Look up a Jani variant
`lookupCard`	Look up a canonical card
`lookupElement`	Wuxing element with Sheng/Ke cycle relationships
`validateWorldElement`	Anti-hallucination — validate claims against canonical data
`search`	Fuzzy search across all entities
`listEntities`	List all entities of a given type

Add to Claude Desktop

{
  "mcpServers": {
    "purupuru-codex": {
      "command": "node",
      "args": ["/path/to/construct-purupuru-codex/dist/server.js"]
    }
  }
}

Browse

Navigate entities by dimension:

browse/by-element/ — Wood, Earth, Fire, Metal, Water
browse/by-generation/ — Kizuna
browse/by-type/ — Character, Puruhani, Location, Jani
browse/by-district/ — Horai Surface, Old Horai, Tsuheji
browse/by-canon-tier/ — Canonical, Established, Exploratory, Speculative

Data Exports

Machine-readable exports in _codex/data/:

File	Format	Content
`characters.jsonl`	JSONL	5 character records
`puruhani.jsonl`	JSONL	5 puruhani records
`locations.jsonl`	JSONL	19 location records
`jani.jsonl`	JSONL	15 jani records
`cards.jsonl`	JSONL	15 card records
`wuxing.json`	JSON	Element system with Sheng/Ke cycles
`graph.json`	JSON	Knowledge graph (44 nodes, 67 edges)
`scope.json`	JSON	Entity counts and version

Skills

Three construct skills for agent-driven exploration:

browse-codex — Navigate by dimension
query-entity — Deterministic lookup with fuzzy fallback
cross-reference — Traverse entity relationships

Canon Authority

Content follows a four-tier authority model:

Tier	Meaning
Canonical	Binding truth from lore-bible
Established	Committed decisions from design cycles
Exploratory	Validated but not locked
Speculative	Not yet validated

Source material: world-purupuru

Development

bun install               # Install deps
bun run dev               # HTTP API server (port 3000)
bun run dev:mcp           # MCP stdio server (watch mode)
bun run test              # Run tests (69 specs)
bun run test:api          # Run API tests only
bun run lint              # Lint
bun run build             # Build MCP stdio server
bun run validate:schema   # Validate all entity frontmatter
bun run generate:exports  # Regenerate JSONL/JSON exports
bun run generate:indices  # Regenerate browse indices

License

MIT