Murphys Laws

Murphy's Laws

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

Available on the Web, with iOS and Android releases forthcoming.

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.

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, web, SDK, CLI, and MCP)

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 and 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 # Kill the process

Building

# Generate OpenAPI and build the web app

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

Policies and Support

• Security: Private vulnerability reporting and supported versions.
• Privacy: Data-handling policy.
• Support: Help and troubleshooting.
• Agent Guide: Canonical instructions for AI coding agents.
• Design System: Token and component-contract guidance.

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 love for anyone who's ever experienced Murphy's Law in action