Seshat Server

Ask counterfactual questions of the historical record. Seshat turns the Seshat Global History Databank into something you can interrogate — both programmatically through an MCP server and visually through a web app — and then project what might have happened if history had gone differently.

"What if the Roman Empire had developed gunpowder weapons in 200 BCE? How might its social complexity have evolved?"

This monorepo has two front doors:

• 🔌 MCP server — exposes 9 Seshat tools to Claude and other MCP-enabled assistants, so researchers can query 10,000 years of social-complexity data in natural language. See packages/mcp-server/README.md.
• 🌍 Echoes of History web app — a Next.js app for picking a civilisation, injecting a hypothetical change, and watching a forward-projected complexity trajectory with confidence bands.

Both are powered by the same estimation engine, which lives in the shared package.

About the Seshat Global History Databank

This project is built on top of Seshat — it does not generate historical data, it makes Seshat's data queryable and projectable.

Seshat (named after the ancient Egyptian goddess of wisdom and record-keeping) is a research databank founded in 2011 that systematically documents the social and political organisation of human societies across history. It calls itself "the most current and comprehensive body of knowledge about human history," structured so that the past can be studied with established scientific techniques. The databank is maintained by an international team of historians, social scientists, and data scientists, and underpins peer-reviewed research into the long-run evolution of social complexity.

Its scope is what makes counterfactual projection possible:

• 864 polities (political societies) across 47 regions grouped into 10 macro-regions spanning Africa, Europe, Asia, the Americas, and Oceania
• Coverage from roughly 3550 BCE to the modern era
• 77 social-complexity variables (territory, population, settlement hierarchies, infrastructure, information systems, money) — the basis for the PC1 composite complexity score
• 49 warfare variables (military technology, fortifications, conflict patterns)
• 26 general variables (capitals, languages, religions, degree of centralisation)

Learn more or explore the source data at seshat-db.com. See Data provenance below for the specific datasets and licensing this project relies on.

Repository structure

This is a pnpm workspace monorepo:

Package	What it is
packages/shared	TypeScript types, the forward-projection model, scenario catalogue, and BCE/CE year utilities. Built first — the other packages depend on it.
packages/mcp-server	MCP server exposing 9 Seshat tools. Independently publishable for researchers.
packages/web	The "Echoes of History" Next.js 16 web app.
data/etl	Python ETL pipeline that ingests Seshat data into Supabase (separate venv).
data/schemas	Supabase SQL migrations, indexes, and RPC functions.

Quickstart

git clone https://github.com/mosse/seshat-mcp
cd seshat-mcp
pnpm install

# The shared package MUST be built before anything else
pnpm --filter @seshat/shared build

You'll need a Supabase project loaded with Seshat data (run the migrations in data/schemas and the ETL in data/etl). Copy the .env.example files in packages/mcp-server/ and packages/web/ and fill in:

Variable	Used by	Notes
SUPABASE_URL	both	Supabase project URL
SUPABASE_SERVICE_KEY	both	Service-role key — server-side only
ANTHROPIC_API_KEY	web	Narrative generation

Run the MCP server

pnpm --filter @seshat/shared build
pnpm --filter @seshat/mcp-server build
pnpm --filter @seshat/mcp-server dev

Then point Claude Desktop at it — see the MCP server README for config.

Run the web app

pnpm --filter @seshat/shared build
pnpm --filter web dev

The 9 MCP tools

Tool	Purpose
search_polities	Find historical polities by name, region, or active year
get_polity_detail	Complexity scores and key variables for one polity
get_variables	Variable values for a polity over time
get_complexity_timeline	PC1 composite complexity trajectory across centuries
compare_polities	Side-by-side comparison of 2–5 polities
find_analogous_polities	Similar societies via cosine similarity on feature vectors
get_technology_diffusion	How a technology spread across regions over time
run_counterfactual_estimate	Project complexity under hypothetical changes with Monte Carlo confidence bands
get_region_snapshot	All polities active in a region during a given century

Full parameter tables are in the MCP server README. Worked examples — full calls with outputs, the discovery workflow, and a variable-code reference — are in docs/EXAMPLES.md.

Testing

# MCP server (vitest) — 56 tests
pnpm --filter @seshat/mcp-server test

# Web app end-to-end (Playwright) — 34 tests, Desktop Chrome + mobile
pnpm --filter web exec playwright test

# ETL (pytest) — 75 tests, requires venv
cd data/etl && source .venv/bin/activate && pytest tests/

How estimates work — and their limits

The counterfactual engine implements the dynamic regression model from Turchin et al. (2022), Disentangling the evolutionary drivers of social complexity (Science Advances), using the published coefficients recovered from the paper's replication deposit and independently validated — see docs/MODEL.md and the audit trail in docs/MODEL_AUDIT.md. Monte Carlo sampling at the published residual scale produces the confidence bands.

⚠️ The model is real; the input data is still illustrative. The engine runs the validated published equations, but the historical values feeding it remain placeholder-grade until real Seshat ingestion lands (tracked in IMPROVEMENT_PLAN.md). The bands use Gaussian noise as an approximation of the paper's bootstrap. Read projections as directional illustrations, not authoritative estimates.

A few things to keep in mind when reading any projection:

• Uncertainty is a feature. Every projection ships with confidence bands and an explicit confidence_limits section. The bands capture statistical noise within the model — not the full range of historical contingency. Treat the central line as one illustrative path, not a prediction.
• Eurasian validation. The regression model was validated on Eurasian data. Projections for the Americas and Oceania-Pacific carry a prominent caveat and should be read with extra caution.
• Year convention. BCE years are negative integers (year 0 = 1 BCE, astronomical). They're displayed as "500 BCE", never "-500".

Data provenance

• Equinox-2020 — Seshat Global History Databank (Turchin et al., 2015). CC BY-NC-SA 4.0. Zenodo
• Cliopatria — Seshat geospatial boundaries. CC BY 4.0. GitHub
• Counterfactual model — Turchin et al. (2022). Disentangling the evolutionary drivers of social complexity. Science Advances.

License

Code is MIT. The underlying Seshat data is CC BY-NC-SA 4.0 — any use of the data must be non-commercial and attributed.