Murphy's Laws

A comprehensive collection of Murphy's Laws - humorous observations about life's tendency for things to go wrong.

Available on Web, iOS, and Android.

Platforms

• Web: https://murphys-laws.com (PWA - installable, works offline)
• iOS: Coming Soon
• Android: Coming Soon

AI & Developer Integration

Four official ways to integrate Murphy's Laws. No API key for reads.

Package	npm	Purpose
murphys-laws-sdk		Typed TypeScript client, zero deps
murphys-laws-cli		Command-line interface (npx murphys-laws-cli)
murphys-laws-mcp		Model Context Protocol server for AI agents
REST API	-	Public HTTP API at https://murphys-laws.com/api/v1/

Full details and examples on the developer landing page.

REST API

Public API at https://murphys-laws.com/api/v1/, no auth required for reads.

• API Documentation
• OpenAPI spec
• llms.txt | llms-full.txt

TypeScript SDK

murphys-laws-sdk on npm is a tiny typed client over the REST API with zero runtime dependencies.

import { MurphysLawsClient } from 'murphys-laws-sdk';
const law = await new MurphysLawsClient().getRandomLaw();

Command-line interface

murphys-laws-cli on npm wraps the API for scripts and terminal use.

npx murphys-laws-cli random
npx murphys-laws-cli search "computer" --limit 3

MCP Server (Model Context Protocol)

An MCP server lets AI agents (Claude Desktop, Cursor, VS Code Copilot) query Murphy's Laws directly.

Quick start, no clone needed:

{
  "mcpServers": {
    "murphys-laws": {
      "command": "npx",
      "args": ["-y", "murphys-laws-mcp"]
    }
  }
}

7 tools: search_laws, get_random_law, get_law_of_the_day, get_law, list_categories, get_laws_by_category, submit_law.

See mcp/README.md or npm, or the developer landing page for the full picture.

Repository Structure

This is a monorepo containing:

murphys-laws/
├── backend/        # Node.js API server (TypeScript runtime via tsx)
├── web/            # Web application (TypeScript + Vite)
├── mcp/            # MCP server for AI agent integration (npm: murphys-laws-mcp)
├── sdk/            # TypeScript SDK over the public REST API (npm: murphys-laws-sdk)
├── cli/            # Command-line interface (npm: murphys-laws-cli)
├── ios/            # iOS app (Swift + SwiftUI)
├── android/        # Android app (Kotlin + Jetpack Compose)
└── shared/         # Shared resources and documentation

Quick Start

Backend (API Server)

cd backend
npm install
npm run build:db # Build SQLite database
npm run dev # Start API server
npm start # Run API from src/server/api-server.ts via tsx

Web Application

cd web
npm install
npm run dev # Start dev server

iOS App

cd ios
open MurphysLaws.xcodeproj
# Press ⌘R to run

Android App

cd android
./gradlew assembleDebug
# Or open in Android Studio

Documentation

• Architecture: Mobile Architecture Guide
• MCP Server: MCP README
• API: API Documentation
• iOS: iOS PRD
• Android: Android PRD
• Deployment: Deployment Guide
• Repository Structure: Repository Structure Guide

Testing

# Run all tests (backend unit, web unit, web E2E)
npm test

# Test a subset only
npm run test:backend   # Backend Vitest suite
npm run test:web       # Web Vitest suite only (no E2E)
npm run test:web:e2e   # Web E2E (Playwright) only

Development

Prerequisites

• Node.js 22+
• For iOS: macOS, Xcode 15+
• For Android: Android Studio Hedgehog+, JDK 17+

Install Dependencies

# Install all dependencies (root + workspaces)
npm run install:all

# Or install individually
cd backend && npm install
cd web && npm install

Run Development Servers

# Run backend + web concurrently
npm run dev

# Or run individually
npm run dev:backend
npm run dev:web

Note: The predev script automatically cleans up any orphaned processes using ports 8787 and 5175 before starting.

Troubleshooting Port Issues

If you encounter EADDRINUSE errors (port already in use):

# Check which processes are using development ports
npm run cleanup-ports

# Automatically kill processes using development ports
npm run cleanup-ports --kill

# Or manually check and kill
lsof -i :8787  # Check API port
lsof -i :5175  # Check frontend port
kill <PID>     # Kill the process

Building

# Build everything
npm run build

# Build specific platform
npm run build:web
npm run build:backend:db

TypeScript Runtime Architecture

• Backend runs TypeScript source directly with tsx (no JS build step required for startup).
• Canonical backend runtime entrypoint: backend/src/server/api-server.ts.
• PM2 runtime uses Node loader: node --import tsx.
• Shared runtime templates are TypeScript in shared/modules/*.ts.

Deployment

See Deployment Guide for detailed instructions.

# Deploy web app (builds and syncs to production)
npm run deploy

Keyboard Shortcuts (Web)

Press ? anywhere on the site to see all available shortcuts:

Search Autocomplete: When typing in the search field, suggestions appear automatically. Use arrow keys to navigate, Enter to select, or Escape to close.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under CC0 1.0 Universal (Public Domain).

Acknowledgments

Thanks to all contributors who have submitted Murphy's Laws over the years!

Made with for anyone who's ever experienced Murphy's Law in action