Environment & Configuration

This page covers all configuration files, environment variables, storage keys, install paths, and dependencies used by the AI Legal Assistant.

MCP Server Configuration (`.mcp.json`)

The root .mcp.json file registers three MCP servers that provide live legal data to skills:

json

{
  "mcpServers": {
    "uk-legislation": {
      "command": "npx",
      "args": ["tsx", "mcp-servers/uk-legislation/src/index.ts"]
    },
    "caselaw": {
      "command": "npx",
      "args": ["tsx", "mcp-servers/caselaw/src/index.ts"]
    },
    "lex": {
      "type": "http",
      "url": "https://lex.lab.i.ai.gov.uk/mcp"
    }
  }
}

Server	Type	Description	Tools Provided
`uk-legislation`	Local (stdio)	Runs locally via `npx tsx`. Queries the legislation.gov.uk XML API	`search_legislation`, `lookup_statute`, `lookup_section`, `check_in_force`, `check_amendments`, `get_extent`
`caselaw`	Local (stdio)	Runs locally via `npx tsx`. Queries the National Archives' Find Case Law service	`search_caselaw`, `get_recent_judgments`, `search_by_party`, `search_by_judge`, `lookup_judgment`, `get_judgments_for_section`, `download_judgment_pdf`, `extract_judgment_text`, `summarise_judgment`
`lex`	Remote (HTTP)	Connects to the LAI Government lex server	63,000+ court cases, semantic legal search

TIP

The local uk-legislation server requires no configuration beyond having the project cloned and npm install run in mcp-servers/uk-legislation/. It queries the public legislation.gov.uk API directly with no API key required (Open Government Licence v3.0).

Dashboard Environment Variables

The dashboard runs with zero required environment variables in demo mode. For hosted trial, live analysis, OCR, and audio features, the following server-side environment variables apply.

Hosted Trial Configuration

Variable	Alias	Description	Default
`AI_LEGAL_UK_HOSTED_ANTHROPIC_API_KEY`	--	Server-side Anthropic key for signed-in hosted analysis requests	--
`AI_LEGAL_UK_HOSTED_OPENAI_API_KEY`	--	Server-side OpenAI key for signed-in hosted analysis and OCR requests	--
`AI_LEGAL_UK_HOSTED_GEMINI_TTS_API_KEY`	--	Preferred server-side Gemini key for hosted caselaw audio	--
`AI_LEGAL_UK_HOSTED_ENABLED`	--	Set to `false` to pause hosted trial requests globally	`true`
`AI_LEGAL_UK_HOSTED_MONTHLY_LIMIT`	--	Global monthly hosted request cap	app default
`AI_LEGAL_UK_HOSTED_MONTHLY_LIMIT_USD`	--	Global monthly estimated-spend cap	app default
`ANALYSIS_MODEL`	--	Anthropic model override for analysis routes	app default
`OPENAI_ANALYSIS_MODEL`	--	OpenAI model override for analysis routes	app default

Signed-in hosted users are still subject to per-user, per-device/network, monthly, and company-scope quota checks. Companies can be given higher pilot limits from the /ops quota controls. Users who need heavier usage can add their own Anthropic or OpenAI key in Settings; browser keys are stored only in that browser's local storage and are not persisted by the server.

OCR Configuration

Variable	Alias	Description	Default
`OCR_PROVIDER`	`AI_LEGAL_UK_OCR_PROVIDER`	OCR provider for scanned PDF processing	--
`AI_LEGAL_UK_HOSTED_OPENAI_API_KEY`	--	Preferred OpenAI key for hosted OCR and hosted analysis	--
`OPENAI_API_KEY`	--	Legacy OpenAI OCR fallback when a hosted key is not configured	--
`OCR_OPENAI_MODEL`	--	OpenAI model to use for OCR requests	`gpt-4o`

Only OpenAI OCR is Implemented

The OCR system recognises five provider values but only openai has a working implementation. The other four are recognised but will fail at runtime.

Supported OCR Providers

Provider Value	Status	Requirements
`openai`	Implemented	`AI_LEGAL_UK_HOSTED_OPENAI_API_KEY` or `OPENAI_API_KEY` must be set. Uses OpenAI vision API for scanned PDF text extraction
`google`	Stub only	Recognised but not implemented; will fail at runtime
`aws`	Stub only	Recognised but not implemented; will fail at runtime
`azure`	Stub only	Recognised but not implemented; will fail at runtime
`tesseract`	Stub only	Recognised but not implemented; will fail at runtime

Next.js Standard Variables

Variable	Default	Description
`PORT`	`3000`	Port for the development server
`NODE_ENV`	`development`	Node environment (`development`, `production`, `test`)

Example: Setting OCR Variables

bash

# For development with OCR support
export OCR_PROVIDER=openai
export AI_LEGAL_UK_HOSTED_OPENAI_API_KEY=sk-your-openai-key-here
export OCR_OPENAI_MODEL=gpt-4o

# Then start the dashboard
cd dashboard && npm run dev

API Key Handling

Security Model

The dashboard has two live paths. Hosted trial requests use server-side AI_LEGAL_UK_HOSTED_* keys only after authentication and quota checks. User-supplied provider keys remain browser-local: the browser stores them in localStorage, sends them with the request that needs them, and the server does not persist them.

How API Keys Flow

Hosted trial  -->  Clerk session  -->  quota gate  -->  hosted env key  -->  Provider adapter
Own key       -->  localStorage   -->  request body  ------------------>  Provider adapter

Hosted trial requests are logged to usage_events for quota and budget protection; document text and browser API keys are not stored there. When a user adds their own key in Settings, it is stored under ai-legal-uk-api-key in that browser only and sent in the JSON request body for the relevant call.

API Key Validation

Settings accepts Anthropic keys beginning sk-ant- and OpenAI keys beginning sk-. Google AI Studio keys beginning AIza are stored separately for Gemini audio and are not accepted for legal analysis. The legacy /api/anthropic/validate route still performs an Anthropic-only provider ping; new hosted-trial routes rely on provider-prefix detection plus server-side provider errors.

Validation Constants

Defined in dashboard/lib/api-route-utils.ts:

Constant	Value	Description
`MAX_LIVE_DOCUMENT_CHARS`	`50,000`	Maximum character count for uploaded documents
`ANTHROPIC_VALIDATE_URL`	`https://api.anthropic.com/v1/messages`	Endpoint for API key validation
`ANTHROPIC_VALIDATE_MODEL`	Default `claude-sonnet-4-20250514` (override with `ANALYSIS_MODEL` env var)	Model used for Anthropic key validation and live analysis

Browser localStorage Keys

The dashboard stores all client-side state in the browser's localStorage:

Key	Type	Description	Example Value
`ai-legal-uk-mode`	`string`	Current operating mode	`"demo"` or `"live"`
`ai-legal-uk-reviews`	`JSON array`	Array of saved review result objects (full analysis data)	`[{ id: "...", type: "contract", score: 72, ... }]`
`ai-legal-uk-api-key`	`string`	User's provider API key (for live mode only)	`"sk-..."`

Demo Mode

In demo mode (ai-legal-uk-mode = "demo"), no API key is needed. The dashboard uses fixture data from dashboard/lib/demo-data/ to simulate analysis results with zero API cost.

localStorage Data Lifecycle

Mode (ai-legal-uk-mode): Set when the user toggles between demo and live mode via the UI. Defaults to "demo" if not set.

Reviews (ai-legal-uk-reviews): Updated after each completed analysis. Contains the full review data including scores, clauses, recommendations, and metadata. Reviews persist across browser sessions until manually cleared from the History page.

API Key (ai-legal-uk-api-key): Set when the user enters their provider API key in Settings. Sent with each live-mode API request in the request body. Never transmitted to any server other than the selected provider API. Clearing browser storage removes the key.

Installation Paths

When ./install.sh is run, files are copied to these locations under the user's home directory:

Source Directory	Destination	Contents
`legal/SKILL.md`	`~/.claude/skills/legal/SKILL.md`	Main orchestrator / router (command menu + routing table)
`skills/legal-*/SKILL.md`	configured agent-host skills directory	All 38 individual skill files (3 orchestrators + 35 single-agent / utility)
`agents/legal-*.md`	configured agent-host agents directory	All 12 agent files
`scripts/generate_legal_pdf.py`	`~/.claude/skills/legal/scripts/generate_legal_pdf.py`	PDF report generator
`templates/`	`~/.claude/skills/legal/templates/`	Report templates

Directory Structure After Installation

~/.claude/
  skills/
    legal/
      SKILL.md                    # Main router (35 commands)
      scripts/
        generate_legal_pdf.py     # PDF report generator
      templates/
        ...                       # Report templates
    legal-review/
      SKILL.md                    # Flagship contract review (5-agent orchestrator)
    legal-employment/
      SKILL.md                    # Employment review (4-agent orchestrator)
    legal-corporate/
      SKILL.md                    # Corporate review (3-agent orchestrator)
    legal-risks/
      SKILL.md
    legal-compare/
      SKILL.md
    ... (38 skill directories total)
  agents/
    legal-clauses.md              # Contract review: clause analysis (20%)
    legal-risks.md                # Contract review: risk assessment (25%)
    legal-compliance.md           # Contract review: compliance check (20%)
    legal-terms.md                # Contract review: terms & obligations (15%)
    legal-recommendations.md      # Contract review: recommendations (20%)
    legal-employment-contract.md  # Employment: contract terms (25%)
    legal-employment-rights.md    # Employment: statutory rights (25%)
    legal-employment-discrimination.md  # Employment: Equality Act (25%)
    legal-employment-obligations.md     # Employment: obligations (25%)
    legal-corporate-compliance.md # Corporate: CA 2006 / ECCTA (35%)
    legal-corporate-documents.md  # Corporate: document review (35%)
    legal-corporate-risk.md       # Corporate: risk assessment (30%)

Project Source Paths

Path	Contents
`skills/legal-*/SKILL.md`	Source skill files (38 skills)
`agents/legal-*.md`	Source agent files (12 agents)
`legal/SKILL.md`	Source orchestrator / router
`dashboard/`	Web application source
`mcp-servers/uk-legislation/`	MCP server source
`scripts/`	Utility scripts (PDF generator, etc.)
`samples/`	Sample legal documents
`templates/`	Report templates

Installation Commands

bash

# Install from local clone
./install.sh

# Install via curl (clones from GitHub automatically)
curl -fsSL https://raw.githubusercontent.com/davendra/ai-legal-uk/main/install.sh | bash

# Uninstall (removes all installed files from ~/.claude/)
./uninstall.sh

Python Dependencies

The PDF report generator (/legal report-pdf) requires Python 3.8+ and the reportlab library:

bash

pip3 install reportlab

Dependency	Minimum Version	Purpose
Python	3.8+	Runtime for `generate_legal_pdf.py`
`reportlab`	Any recent	PDF generation with A4 layout, score gauges, risk charts, colour-coded tables, prioritised action checklists

INFO

reportlab is only required for the /legal report-pdf command. The remaining command skills are pure Markdown and have no Python dependencies.

Dashboard Dependencies

The dashboard's Node.js dependencies are managed via package.json in the dashboard/ directory:

bash

cd dashboard
npm install

Key Packages

Package	Purpose
`next`	Next.js 14 App Router framework
`react`, `react-dom`	React 18 UI library
`@anthropic-ai/sdk`	Anthropic API client for live analysis
`@radix-ui/*`	Accessible headless UI primitives
`tailwindcss`	Utility-first CSS framework
`typescript`	Type checking and compilation
`fast-xml-parser`	XML parsing for legislation API responses
`lucide-react`	Icon library
`next-themes`	Dark/light theme support
`tailwind-merge`, `clsx`	CSS utility for conditional class merging

MCP Server Dependencies

The MCP server has its own package.json in mcp-servers/uk-legislation/:

bash

cd mcp-servers/uk-legislation
npm install

Package	Purpose
`@modelcontextprotocol/sdk`	MCP server framework
`fast-xml-parser`	Parsing legislation.gov.uk XML responses
`zod`	Input validation schemas for tool parameters
`tsx`	TypeScript execution in development mode
`typescript`	Compilation for production build

MCP Server Internal Constants

Defined in mcp-servers/uk-legislation/src/index.ts:

Constant	Value	Description
`BASE_URL`	`https://www.legislation.gov.uk`	legislation.gov.uk API base URL
`CACHE_TTL_MS`	`86,400,000` (24 hours)	In-memory cache time-to-live
`CACHE_MAX_ENTRIES`	`500`	Maximum cache entries before LRU eviction
`FETCH_TIMEOUT_MS`	`30,000` (30 seconds)	HTTP fetch timeout with AbortController

INFO

The MCP server has no external API key requirements -- it queries the public legislation.gov.uk XML API directly under the Open Government Licence v3.0.

Environment & Configuration ​

MCP Server Configuration (.mcp.json) ​

Dashboard Environment Variables ​

Hosted Trial Configuration ​

OCR Configuration ​

Supported OCR Providers ​

Next.js Standard Variables ​

Example: Setting OCR Variables ​

API Key Handling ​

How API Keys Flow ​

API Key Validation ​

Validation Constants ​

Browser localStorage Keys ​

Installation Paths ​

Directory Structure After Installation ​

Project Source Paths ​

Installation Commands ​

Python Dependencies ​

Dashboard Dependencies ​

Key Packages ​

MCP Server Dependencies ​

MCP Server Internal Constants ​

Environment & Configuration

MCP Server Configuration (`.mcp.json`)

Dashboard Environment Variables

Hosted Trial Configuration

OCR Configuration

Supported OCR Providers

Next.js Standard Variables

Example: Setting OCR Variables

API Key Handling

How API Keys Flow

API Key Validation

Validation Constants

Browser localStorage Keys

Installation Paths

Directory Structure After Installation

Project Source Paths

Installation Commands

Python Dependencies

Dashboard Dependencies

Key Packages

MCP Server Dependencies

MCP Server Internal Constants