{
  "markdown": "# PocketLantern\n\n[![npm version](https://img.shields.io/npm/v/pocketlantern)](https://www.npmjs.com/package/pocketlantern)\n[![npm downloads](https://img.shields.io/npm/dm/pocketlantern)](https://www.npmjs.com/package/pocketlantern)\n[![CI](https://github.com/pocketlantern/pocketlantern/actions/workflows/ci.yml/badge.svg)](https://github.com/pocketlantern/pocketlantern/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n**Your AI agent sounds confident. It missed the blockers.**\n\nPrices shift, versions break, licenses change. PocketLantern is a blocker-aware decision layer for AI coding agents, grounded in source-linked, time-sensitive facts.\n\n## Try these queries\n\nAsk your AI agent after installing PocketLantern:\n\n**\"Which auth provider — Clerk, Auth0, or Cognito?\"**\n\n```\n⚠️ Cognito password hashes are permanently non-exportable\n⚠️ Auth0 password export requires support ticket — Free tier excluded\n⚠️ Auth0 Rules/Hooks EOL 2026-11-18 — Actions not portable\n✅ Clerk has the most flexible migration path\n```\n\n**\"Should I upgrade to Next.js 16?\"**\n\n```\n⚠️ Sync API access fully removed — all dynamic calls must be awaited\n⚠️ Custom webpack config breaks next build\n⚠️ next lint removed — switch to Biome or ESLint CLI\n⚠️ Requires Node.js 20.9.0+, TypeScript 5.1.0+, React 19.0+\n✅ Plan phased migration — codemod doesn't cover webpack or middleware\n```\n\n**\"Can I use the OpenAI Realtime API?\"**\n\n```\n⚠️ gpt-4o-realtime-preview removed 2026-05-07\n⚠️ Beta interface (realtime=v1 header) removed same date\n⚠️ GA event schema incompatible — 4 event renames\n✅ Start on GA from day one — or plan dual-stack migration\n```\n\nThree questions. Three blocker types. Same AI, different facts.\n\n![PocketLantern demo — Node.js 20→24 upgrade blockers surfaced in seconds](demo.gif)\n\n## Quick start\n\n**Prerequisites**: Node.js >= 22, an MCP client ([Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://cursor.com), etc.)\n\n```bash\nnpm install -g pocketlantern\n```\n\n### Claude Code\n\nIn your project directory:\n\n```bash\ncd your-project\npocketlantern init\n```\n\n`init` registers the MCP server in `~/.claude.json` and adds a one-line rule to your project's `CLAUDE.md`. Restart Claude Code (`Ctrl+C`, then run `claude` again), then ask your first query.\n\n### Cursor / Windsurf / other MCP clients\n\nAdd to your MCP config (Cursor: `~/.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"pocketlantern\": {\n      \"command\": \"pocketlantern-mcp\"\n    }\n  }\n}\n```\n\nThen add this line to your project rules (`.cursorrules`, Kiro steering file, etc.):\n\n```\nFor technology decisions, upgrades, migrations, or licensing questions: before finalizing your answer, check the PocketLantern MCP server's search_cards tool for blockers in these bundled decision cards — your training data may be stale.\n```\n\nReload MCP servers: Cursor — `Cmd+Shift+P` -> \"MCP: Restart Servers\". Windsurf — restart the editor.\n\n### More queries to try\n\n4. **\"How did Vercel pricing change with Fluid Compute?\"**\n   Billing split to Active CPU + Memory, shared-process concurrency breaks isolation\n\n5. **\"Prisma or Drizzle for Edge/serverless?\"**\n   Prisma v7 ESM + driver adapter breaking, Edge preview-only; Drizzle 0.30-1.0 also breaking\n\n### Verify installation\n\n```bash\npocketlantern doctor               # check installation status\npocketlantern search \"auth pricing\" # search cards from CLI\n```\n\n## How it works\n\nPocketLantern is an MCP server. Your AI agent calls `search_cards` — and gets source-linked decision cards **plus source-linked blocker warnings** where available.\n\n```\nAgent asks question\n  -> search_cards(\"clerk vs auth0 authentication\")\n  -> 3 cards + 5 blocker warnings (lock-in, EOL, export restrictions)\n  -> Agent answers with source-linked constraints\n```\n\nLocal cardset. Instant lookup. No vector database. No embeddings. Keyword search, card links, and source-linked blocker warnings where available. The value is in **source-linked decision cards**, not clever retrieval alone.\n\n```\nsearch_cards(\"auth\", constraints:[\"serverless\"]) -> cards + blockers\nget_card(\"auth/clerk-vs-auth0-vs-cognito-2026\")  -> full card with facts\nget_related_cards(...)                           -> connected topics\n```\n\n## What's included\n\nBlocker-aware decision cards across 27 categories — plus source-linked blocker warnings from the bundled graph index. Ships with the npm package, works immediately, no network, no account:\n\n| Category   | What it covers                                           |\n| ---------- | -------------------------------------------------------- |\n| auth       | Vendor lock-in, migration pain, SSO, RBAC, passkeys      |\n| frontend   | Next.js, React, Svelte, Vite, Angular upgrade blockers   |\n| database   | Prisma, Drizzle, Postgres, Aurora, Neon, Supabase        |\n| ai         | OpenAI API migrations, model pricing, batch vs streaming |\n| serverless | Vercel, Cloudflare Workers, Lambda cost and runtime      |\n| infra      | Hosting platforms, Terraform, Node.js LTS, Python EOL    |\n| backend    | Supabase vs Firebase, Express, job queues, realtime sync |\n| + 18 more  | deployment, devtools, testing, security, compliance, ... |\n\n### What a card looks like\n\nEach card is a structured YAML file with source-linked facts and official reference links:\n\n```yaml\nid: auth/clerk-vs-auth0-vs-cognito-2026\ntitle: Clerk vs Auth0 vs Cognito Under Current Pricing and Feature Changes\nproblem: Select an auth vendor given recent pricing shifts, MAU economics, ...\nconstraints: [cost-sensitive, low-ops, enterprise, compliance, serverless]\ncandidates:\n  - name: Clerk\n    summary: \"Pro starts at $20/mo, includes 50,000 MRUs per app...\"\n    when_to_use: \"Choose for small-team + low-ops + cost-sensitive SaaS...\"\n    tradeoffs: \"Best DX and fastest implementation...\"\n    cautions: \"Be precise about org-member limits...\"\n    links:\n      - https://clerk.com/pricing\n      - https://clerk.com/docs/guides/organizations/configure\n  - name: Auth0\n    # ...\n  - name: Amazon Cognito\n    # ...\ntags: [auth, clerk, auth0, pricing, passkeys, b2b, compliance]\nrelated_cards: [auth/sso-for-b2b-saas, auth/rbac-vs-abac-vs-rebac]\nupdated: 2026-03-14\n```\n\nSee [packages/schema/src/card.ts](packages/schema/src/card.ts) for the full schema definition.\n\n## Project structure\n\n```\npocketlantern/\n  packages/schema/       <- Card schema (zod + TypeScript types)\n  apps/mcp-server/       <- MCP server (search, retrieval, tool handlers)\n  apps/cli/              <- CLI (validate, search, init, doctor)\n  packages/knowledge/    <- Decision cards + graph index (data package)\n  docs/                  <- User guides & roadmap\n```\n\n**Monorepo**: pnpm workspace. Build order: `schema -> knowledge (no build) -> mcp-server -> cli`.\n\n## Development\n\n```bash\npnpm build              # Build all packages\npnpm test               # Run tests (299 tests)\npnpm test:coverage      # Run with coverage report\npnpm lint               # ESLint\npnpm format:check       # Prettier check\n```\n\nMissing a topic? Request coverage in [Card Requests](https://github.com/pocketlantern/pocketlantern/discussions/categories/card-requests).\n\n## Contributing\n\nContributions to the tool (schema, MCP server, CLI, search) are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 7343,
  "sha": "708f4f2a6e42049aa27c092598bf5934dce2a8b8abf576171752133aeaa6c73f",
  "repo_slug": "pocketlantern/pocketlantern",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_pocketlantern_pocketlantern_a93901fd/readme"
}