com.murphys-laws/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 <PID>     # 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