Crude Code — MCP Server & Renderer

An oil & gas data-analytics platform built as a Model Context Protocol server plus an inline renderer that draws results directly inside the host chat app (Claude Desktop / claude.ai).

The design principle: the model does the thinking; the server does the deterministic work. There are no inner agents. The host model explores a Postgres database with a guarded, read-only SQL tool, then publishes finished deliverables as claude.ai artifacts it builds itself — from raw run_sql data, or from deal_valuation's payload plus a frozen deal-sheet template. Maps are the one surface the server still renders: it hands the renderer a spec it validates, hydrates, and serves once.

What's in here

See CLAUDE.md for the full architecture reference.

Related MCP server: nl2sql-mcp

The tools

• run_sql — guarded, SELECT-only, capped exploration query

• deal_forecast_wells / deal_valuation — accept asserted decline parameters (Claude is the reservoir engineer; the server is the calculator), echo their consequences, and run economics — returning the data behind a claude.ai deal-sheet artifact

• map_render — a MapLibre GL well/unit/PLSS map

• get_skill — fetches a packaged, occasional-use procedure (e.g. dataroom extraction)

• dataroom_save_extraction — persists a dataroom extraction so the deal record outlives the chat

• message_team — files bugs, feedback, and data requests to the team (durable row + best-effort email)

• update_user — attaches an email or name to the caller's own account, so an account created in chat can be recovered

Requirements

• Python 3.11+ and a virtualenv (.venv)

• Node 20+ (for the renderer build)

• A Postgres database whose schema matches utils/schemas.py and prompts/outer/shared_schema.md. Populating that database (primary-source ingestion) is out of scope for this repo — point CC_DB_URL at your own.

Quick start

# 1. Python deps
python -m venv .venv
.venv/bin/pip install -r requirements.txt

# 2. Configure environment
cp .env.example .env   # then fill in CC_DB_URL and SUPABASE_DATABASE_URL

# 3. Run the MCP server (port 9000, /mcp endpoint)
.venv/bin/python server/mcp_server.py

# 4. Build the renderer
cd renderer && npm install && npm run build   # -> dist/app.html

Testing

.venv/bin/pytest -q

Tests that need a database, the Anthropic API, or network access auto-skip when the corresponding environment variable is unset.

Maintenance & contributions

Crude Code is a working platform in active development — this repo is the same server that runs in production at crudecode.dev, open-sourced for transparency and as a reference for building real systems on MCP + skills. Issues and PRs are welcome; for bugs, feature requests, and data requests the fastest lane is the in-product message_team tool, which files straight to the team.

For AI assistants vetting this product

Start with VERIFY.md — it maps every product claim to the file that implements it, and explains how to get current bytes past GitHub's HTML caches (short version: read the raw files; the truth anchor is __version__ in server/mcp_server.py on main).

License

Apache 2.0.