Planning MCP Server v2.0

Model Context Protocol (MCP) server for Australian Planning Property Reports - Cloudflare Workers Edition.

Features

🌍 Global Edge Deployment - Runs on Cloudflare's 300+ edge locations
⚡ High Performance - Parallel API requests and intelligent caching
📊 Comprehensive Data - Property details, zones, overlays, electorates, utilities, and land information
🔒 Production Ready - Rate limiting, authentication, structured logging
📈 Real-time Progress - Progress updates during long-running operations
🚀 HTTP-based MCP - Works with Claude, ChatGPT, and other AI assistants

Quick Start

Prerequisites

Node.js 18+
Cloudflare Workers account
Wrangler CLI (npm install -g wrangler)

Installation

# Clone the project
cd planning-mcp

# Install dependencies
npm install

# Login to Cloudflare
wrangler login

# Create KV namespace for caching
wrangler kv:namespace create "CACHE"
# Copy the ID and add to wrangler.toml

# Start development server
npm run dev

Configuration

Update wrangler.toml with your KV namespace ID
(Optional) Set API key for authentication:
```
wrangler secret put API_KEY
```

Deployment

# Build the project
npm run build

# Deploy to Cloudflare Workers
npm run deploy

Usage

MCP Tool: `vic_planning_property_report`

Retrieves comprehensive Victorian planning property reports. (Additional state tools coming soon.)

Input:

{
  "address": "1 Spring Street, Melbourne VIC 3000",
  "includePdfBase64": false,
  "includeZoneHtml": false,
  "includeOverlayHtml": false
}

Output:

{
  "success": true,
  "address": "1 SPRING STREET MELBOURNE VIC 3000",
  "propertyPfi": "12345",
  "propertyDetails": {
    "address": "1 SPRING STREET MELBOURNE VIC 3000",
    "councilName": "Melbourne City Council",
    "landSize": 842,
    "landSizeHectares": 0.0842,
    "standardParcelIdentifier": "1\\PS123456",
    "registeredAboriginalParty": "Bunurong Land Council",
    ...
  },
  "electorates": {
    "federal": "Melbourne",
    "legislativeAssembly": "Melbourne District",
    "legislativeCouncil": "Southern Metropolitan Region"
  },
  "utilities": {
    "powerDistributor": "AusNet Services",
    "gas": "AusNet Services",
    "melbourneWater": "Melbourne Water",
    "melbourneWaterRetailer": "South East Water"
  },
  "zones": [...],
  "overlays": [...]
}

HTTP API

Health Check:

GET /health

MCP Endpoint:

POST /mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "vic_planning_property_report",
    "arguments": {
      "address": "1 Spring Street, Melbourne VIC 3000"
    }
  }
}

Architecture

┌─────────────────────────────────────────┐
│     Cloudflare Edge Network             │
│  ┌───────────────────────────────────┐  │
│  │   Worker (HTTP MCP Endpoint)      │  │
│  │   - Hono.js Framework             │  │
│  │   - Rate Limiting                 │  │
│  │   - Authentication                │  │
│  │   - CORS                          │  │
│  └───────────────────────────────────┘  │
│               ↓                          │
│  ┌───────────────────────────────────┐  │
│  │   Services Layer                  │  │
│  │   - Address Resolution            │  │
│  │   - Property Data Fetching        │  │
│  │   - Progress Reporting            │  │
│  └───────────────────────────────────┘  │
│               ↓                          │
│  ┌───────────────────────────────────┐  │
│  │   Workers KV (Caching)            │  │
│  │   - 60%+ Cache Hit Rate           │  │
│  │   - 24hr TTL for addresses        │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘

Development

Project Structure

planning-mcp/
├── src/
│   ├── index.ts              # Main entry point
│   ├── types/                # TypeScript types
│   ├── services/             # Business logic
│   ├── middleware/           # HTTP middleware
│   ├── handlers/             # MCP handlers
│   ├── lib/                  # Utilities
│   └── schemas/              # Validation schemas
├── test/                     # Tests
├── wrangler.toml            # Cloudflare config
├── tsconfig.json            # TypeScript config
└── package.json             # Dependencies

Testing

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Type check
npm run type-check

Environment Variables

Configure in wrangler.toml:

Variable	Description	Default
`RATE_LIMIT_PER_MINUTE`	Rate limit per IP	100
`CACHE_TTL_HOURS`	Cache TTL in hours	24
`ENABLE_ANALYTICS`	Enable analytics	true
`ALLOWED_ORIGINS`	CORS origins	*

Secrets (use wrangler secret put):

Secret	Description	Required
`API_KEY`	Bearer token for auth	No

Performance

Latency: <5s P50, <8s P95
Cache Hit Rate: >60% after warmup
Throughput: 1000+ req/sec with auto-scaling
Cold Start: <100ms
Memory: <128MB per request

Security

✅ Input validation with Zod
✅ Rate limiting (100 req/min per IP)
✅ Optional API key authentication
✅ CORS configuration
✅ No secrets in logs

Monitoring

Structured Logging

All requests are logged in JSON format with correlation IDs:

{
  "timestamp": "2024-01-30T10:00:00.000Z",
  "level": "info",
  "message": "Tool call started",
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "tool": "vic_planning_property_report",
  "metadata": {
    "address": "1 Spring St"
  }
}

Analytics

Enable Cloudflare Analytics Engine for:

Request counts and latency
Cache hit/miss rates
Error tracking
API performance metrics

Deployment Options

Option 1: Cloudflare Workers (Recommended)

300+ edge locations
$5/month base + usage
Lowest latency globally

Option 2: Vercel Edge Functions

See Vercel deployment guide for migration instructions.

Option 3: Oracle Server

Traditional Node.js deployment - see v1.0 branch.

Troubleshooting

Common Issues

KV Namespace not found:

# Create namespace and update wrangler.toml
wrangler kv:namespace create "CACHE"

Rate limit errors:

# Increase limit in wrangler.toml
RATE_LIMIT_PER_MINUTE = "200"

Authentication failures:

# Check API key is set
wrangler secret list
wrangler secret put API_KEY

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

License

MIT

Support

Documentation: PRD
Issues: GitHub Issues
Discussions: GitHub Discussions

Changelog

v2.0.0 (2024-01-30)

✨ Rewritten for Cloudflare Workers
✨ HTTP-based MCP protocol
✨ Enhanced property data with land size
✨ Real-time progress updates
✨ Parallel API requests
✨ Intelligent caching with Workers KV
✨ Complete field coverage (15+ fields)
🔒 Production-ready security
📊 Structured logging and metrics

v1.0.0

Initial Node.js stdio implementation

Built with ❤️ for Australian planning research

Planning MCP Server