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 two MCP servers that provide live legal data to skills:

json

{
  "mcpServers": {
    "uk-legislation": {
      "command": "npx",
      "args": ["tsx", "mcp-servers/uk-legislation/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`
`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 live analysis and OCR features, the following server-side environment variables apply.

OCR Configuration

Variable	Alias	Description	Default
`OCR_PROVIDER`	`AI_LEGAL_UK_OCR_PROVIDER`	OCR provider for scanned PDF processing	--
`OPENAI_API_KEY`	--	OpenAI API key (used for OCR only, not for analysis)	--
`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	`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 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 server does not hold or store provider API keys. The user provides their own supported provider key via the browser UI. The key is stored in browser localStorage and sent in the request body of each API call. Route handlers pass it directly to the selected provider adapter without persisting it.

How API Keys Flow

Browser (localStorage)  -->  Request Body  -->  Route Handler  -->  Provider adapter
                                                    |
                                             (never stored,
                                              never logged)

User enters their provider API key in the browser UI
Key is stored in localStorage under ai-legal-uk-api-key
Each API request includes the key in the JSON request body ({ apiKey: "sk-..." })
Server-side route handler extracts the key and passes it to the selected provider adapter
Key is never logged, stored on disk, or cached server-side

API Key Validation

The dashboard validates API keys by making a minimal test request:

POST https://api.anthropic.com/v1/messages
Model: ANALYSIS_MODEL (default `claude-sonnet-4-20250514`, override via env)
Max tokens: 16
Message: "Reply with only: OK"

Keys must:

Be a non-empty string
Start with sk-
Pass the validation request above

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 ​

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

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