{
  "markdown": "# Murphy's Laws\n\nA comprehensive collection of Murphy's Laws - humorous observations about life's tendency for things to go wrong.\n\nAvailable on **Web**, **iOS**, and **Android**.\n\n## Platforms\n\n- **Web**: <https://murphys-laws.com> (PWA - installable, works offline)\n- **iOS**: Coming Soon\n- **Android**: Coming Soon\n\n## AI & Developer Integration\n\nFour official ways to integrate Murphy's Laws. No API key for reads.\n\n| Package | npm | Purpose |\n|---------|-----|---------|\n| [`murphys-laws-sdk`](sdk/) | [![npm](https://img.shields.io/npm/v/murphys-laws-sdk.svg?label=)](https://www.npmjs.com/package/murphys-laws-sdk) | Typed TypeScript client, zero deps |\n| [`murphys-laws-cli`](cli/) | [![npm](https://img.shields.io/npm/v/murphys-laws-cli.svg?label=)](https://www.npmjs.com/package/murphys-laws-cli) | Command-line interface (`npx murphys-laws-cli`) |\n| [`murphys-laws-mcp`](mcp/) | [![npm](https://img.shields.io/npm/v/murphys-laws-mcp.svg?label=)](https://www.npmjs.com/package/murphys-laws-mcp) | Model Context Protocol server for AI agents |\n| [REST API](shared/docs/API.md) | - | Public HTTP API at `https://murphys-laws.com/api/v1/` |\n\nFull details and examples on the [developer landing page](https://murphys-laws.com/developers).\n\n### REST API\n\nPublic API at `https://murphys-laws.com/api/v1/`, no auth required for reads.\n\n- [API Documentation](shared/docs/API.md)\n- [OpenAPI spec](https://murphys-laws.com/openapi.json)\n- [llms.txt](https://murphys-laws.com/llms.txt) | [llms-full.txt](https://murphys-laws.com/llms-full.txt)\n\n### TypeScript SDK\n\n[`murphys-laws-sdk`](sdk/) on [npm](https://www.npmjs.com/package/murphys-laws-sdk) is a tiny typed client over the REST API with zero runtime dependencies.\n\n```ts\nimport { MurphysLawsClient } from 'murphys-laws-sdk';\nconst law = await new MurphysLawsClient().getRandomLaw();\n```\n\n### Command-line interface\n\n[`murphys-laws-cli`](cli/) on [npm](https://www.npmjs.com/package/murphys-laws-cli) wraps the API for scripts and terminal use.\n\n```bash\nnpx murphys-laws-cli random\nnpx murphys-laws-cli search \"computer\" --limit 3\n```\n\n### MCP Server (Model Context Protocol)\n\nAn [MCP server](mcp/) lets AI agents (Claude Desktop, Cursor, VS Code Copilot) query Murphy's Laws directly.\n\nQuick start, no clone needed:\n\n```json\n{\n  \"mcpServers\": {\n    \"murphys-laws\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"murphys-laws-mcp\"]\n    }\n  }\n}\n```\n\n7 tools: `search_laws`, `get_random_law`, `get_law_of_the_day`, `get_law`, `list_categories`, `get_laws_by_category`, `submit_law`.\n\nSee [mcp/README.md](mcp/README.md) or [npm](https://www.npmjs.com/package/murphys-laws-mcp), or the [developer landing page](https://murphys-laws.com/developers) for the full picture.\n\n## Repository Structure\n\nThis is a monorepo containing:\n\n```\nmurphys-laws/\n├── backend/        # Node.js API server (TypeScript runtime via tsx)\n├── web/            # Web application (TypeScript + Vite)\n├── mcp/            # MCP server for AI agent integration (npm: murphys-laws-mcp)\n├── sdk/            # TypeScript SDK over the public REST API (npm: murphys-laws-sdk)\n├── cli/            # Command-line interface (npm: murphys-laws-cli)\n├── ios/            # iOS app (Swift + SwiftUI)\n├── android/        # Android app (Kotlin + Jetpack Compose)\n└── shared/         # Shared resources and documentation\n```\n\n## Quick Start\n\n### Backend (API Server)\n\n```bash\ncd backend\nnpm install\nnpm run build:db # Build SQLite database\nnpm run dev # Start API server\nnpm start # Run API from src/server/api-server.ts via tsx\n```\n\n### Web Application\n\n```bash\ncd web\nnpm install\nnpm run dev # Start dev server\n```\n\n### iOS App\n\n```bash\ncd ios\nopen MurphysLaws.xcodeproj\n# Press ⌘R to run\n```\n\n### Android App\n\n```bash\ncd android\n./gradlew assembleDebug\n# Or open in Android Studio\n```\n\n## Documentation\n\n- **Architecture**: [Mobile Architecture Guide](shared/docs/MOBILE-ARCHITECTURE.md)\n- **MCP Server**: [MCP README](mcp/README.md)\n- **API**: [API Documentation](shared/docs/API.md)\n- **iOS**: [iOS PRD](shared/docs/MOBILE-IOS-PRD.md)\n- **Android**: [Android PRD](shared/docs/MOBILE-ANDROID-PRD.md)\n- **Deployment**: [Deployment Guide](shared/docs/DEPLOYMENT.md)\n- **Repository Structure**: [Repository Structure Guide](shared/docs/MOBILE-REPOSITORY-STRUCTURE.md)\n\n## Testing\n\n```bash\n# Run all tests (backend unit, web unit, web E2E)\nnpm test\n\n# Test a subset only\nnpm run test:backend   # Backend Vitest suite\nnpm run test:web       # Web Vitest suite only (no E2E)\nnpm run test:web:e2e   # Web E2E (Playwright) only\n```\n\n## Development\n\n### Prerequisites\n\n- Node.js 22+\n- For iOS: macOS, Xcode 15+\n- For Android: Android Studio Hedgehog+, JDK 17+\n\n### Install Dependencies\n\n```bash\n# Install all dependencies (root + workspaces)\nnpm run install:all\n\n# Or install individually\ncd backend && npm install\ncd web && npm install\n```\n\n### Run Development Servers\n\n```bash\n# Run backend + web concurrently\nnpm run dev\n\n# Or run individually\nnpm run dev:backend\nnpm run dev:web\n```\n\n**Note**: The `predev` script automatically cleans up any orphaned processes using ports 8787 and 5175 before starting.\n\n### Troubleshooting Port Issues\n\nIf you encounter `EADDRINUSE` errors (port already in use):\n\n```bash\n# Check which processes are using development ports\nnpm run cleanup-ports\n\n# Automatically kill processes using development ports\nnpm run cleanup-ports --kill\n\n# Or manually check and kill\nlsof -i :8787  # Check API port\nlsof -i :5175  # Check frontend port\nkill <PID>     # Kill the process\n```\n\n## Building\n\n```bash\n# Build everything\nnpm run build\n\n# Build specific platform\nnpm run build:web\nnpm run build:backend:db\n```\n\n## TypeScript Runtime Architecture\n\n- Backend runs TypeScript source directly with `tsx` (no JS build step required for startup).\n- Canonical backend runtime entrypoint: `backend/src/server/api-server.ts`.\n- PM2 runtime uses Node loader: `node --import tsx`.\n- Shared runtime templates are TypeScript in `shared/modules/*.ts`.\n\n## Deployment\n\nSee [Deployment Guide](shared/docs/DEPLOYMENT.md) for detailed instructions.\n\n```bash\n# Deploy web app (builds and syncs to production)\nnpm run deploy\n```\n\n## Keyboard Shortcuts (Web)\n\nPress `?` anywhere on the site to see all available shortcuts:\n\n| Shortcut | Action |\n|----------|--------|\n| `/` | Focus search |\n| `↑` / `↓` | Navigate search suggestions (when autocomplete is open) |\n| `Enter` | Select search suggestion (when autocomplete is open) |\n| `Escape` | Close search suggestions / modal / popover |\n| `j` | Next law card |\n| `k` | Previous law card |\n| `?` | Show shortcuts help |\n| `Enter` / `Space` | Activate focused card |\n\n**Search Autocomplete:** When typing in the search field, suggestions appear automatically. Use arrow keys to navigate, Enter to select, or Escape to close.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under CC0 1.0 Universal (Public Domain).\n\n## Acknowledgments\n\nThanks to all contributors who have submitted Murphy's Laws over the years!\n\n---\n\n**Made with for anyone who's ever experienced Murphy's Law in action**\n",
  "bytes": 7300,
  "sha": "dcf06c238542b39b30c8b0597900b98072dd5d8a6593baf227b7db42bf99f672",
  "repo_slug": "ravidorr/murphys-laws",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_murphys_laws_murphys_laws_ae0983bb/readme"
}