{
  "mcpServers": {
    "uk-business-intel": {
      "command": "npx",
      "args": ["-y", "uk-business-intelligence-mcp"],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "your-key",
        "COMPANIES_HOUSE_API_KEY": "your-key",
        "GOOGLE_PLACES_API_KEY": "your-key",
        "API_KEY_SALT": "your-random-32-char-string"
      }
    }
  }
}

# 1. Create an API key
curl -X POST https://your-domain.com/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

# 2. Enrich a business
curl -X POST https://your-domain.com/api/v1/enrich \
  -H "Content-Type: application/json" \
  -H "x-api-key: ukb_your_key_here" \
  -d '{"business_name": "Greggs", "location": "Newcastle"}'

{
  "email": "developer@example.com",
  "plan": "free"
}

{
  "success": true,
  "data": {
    "api_key": "ukb_a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5",
    "key_prefix": "ukb_a3f8b2c1...",
    "plan": "free",
    "message": "Store this API key securely. It will not be shown again."
  }
}

{
  "business_name": "Greggs",
  "location": "Newcastle",
  "company_number": "00502851",
  "domain": "greggs.co.uk"
}

{
  "success": true,
  "data": {
    "query": {
      "business_name": "Greggs",
      "location": "Newcastle",
      "company_number": null,
      "domain": null
    },
    "companies_house": {
      "company_number": "00502851",
      "company_name": "GREGGS PLC",
      "company_status": "active",
      "incorporation_date": "1951-09-22",
      "company_type": "plc",
      "sic_codes": ["10710", "47240"],
      "registered_address": {
        "address_line_1": "Greggs House",
        "address_line_2": "Quorum Business Park",
        "locality": "Newcastle Upon Tyne",
        "region": "Tyne and Wear",
        "postal_code": "NE12 8BU",
        "country": "England"
      },
      "directors": [
        {
          "name": "SHERWOOD, Roisin",
          "role": "director",
          "appointed_on": "2019-05-01",
          "resigned_on": null
        }
      ]
    },
    "google_places": {
      "place_id": "ChIJx9k5WQ1yfkgRnx-XPkd9DGw",
      "display_name": "Greggs",
      "formatted_address": "Northumberland St, Newcastle upon Tyne NE1 7DE",
      "rating": 4.1,
      "review_count": 1847,
      "phone": "0191 232 7749",
      "website": "https://www.greggs.co.uk",
      "google_maps_url": "https://maps.google.com/?cid=7771234567890"
    },
    "website": {
      "domain": "greggs.co.uk",
      "is_live": true,
      "http_status": 200,
      "ssl_valid": true,
      "ssl_expiry": "2027-01-15T00:00:00Z"
    },
    "social": {
      "facebook": "https://facebook.com/GreggsFans",
      "instagram": null,
      "linkedin": "https://linkedin.com/company/greggs",
      "twitter": "https://twitter.com/GreggsOfficial"
    },
    "meta": {
      "sources_successful": ["companies_house", "google_places", "dns", "scrape"],
      "sources_failed": [],
      "sources_skipped": [],
      "cached_sources": [],
      "enriched_at": "2026-03-21T14:30:00.000Z",
      "duration_ms": 1247
    }
  }
}

{
  "success": true,
  "data": {
    "plan": "free",
    "month": "2026-03",
    "lookups_used": 47,
    "lookups_limit": 100,
    "lookups_remaining": 53,
    "overage_count": 0,
    "rate_limit_per_minute": 10
  }
}

{ "success": false, "error": "Description of the error" }

git clone https://github.com/Fluke-Studio/uk-business-intelligence-mcp.git
cd uk-business-intelligence-mcp
npm install
cp .env.example .env.local
# Fill in your API keys in .env.local

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
SUPABASE_ANON_KEY=your-anon-key
COMPANIES_HOUSE_API_KEY=your-ch-api-key
GOOGLE_PLACES_API_KEY=your-google-api-key
API_KEY_SALT=random-32-character-string

npm run dev          # Start Next.js dev server (http://localhost:3000)
npm run build        # Production build (Next.js)
npm run build:mcp    # Build MCP server to dist/
npm start            # Production server

# Update package.json with your GitHub username in repository/bugs/homepage URLs
npm run build:mcp    # Builds to dist/
npm publish          # Publishes to npm (prepublishOnly auto-runs build:mcp)

npx uk-business-intelligence-mcp

POST /api/v1/enrich
  → Validate body (Zod)
  → Authenticate (x-api-key → SHA-256 hash → DB lookup)
  → Rate limit (fixed-window, DB-backed)
  → Quota check (monthly counter)
  → Enrichment orchestrator
      Round 1 (parallel): Companies House + Google Places
      Round 2 (parallel, if domain found): DNS/SSL Check + Social Scraper
  → Return merged JSON profile

MCP Server (stdio)
  → Receives enrich_uk_business tool call
  → Calls enrichment orchestrator directly (no HTTP)
  → Returns JSON profile to MCP client