deadends.dev

<!-- mcp-name: dev.deadends/deadends-dev -->

Stop AI agents from repeating known failures - in code AND in the real world.

AI assistants reliably fumble two kinds of problems: known-failed code fixes, and
country-specific real-world rules they've never been exposed to in training.
deadends.dev now covers both:

- Code errors (2,089 entries, 51 domains): what NOT to try when an agent
hits ModuleNotFoundError, CUDA OOM, CrashLoopBackOff, etc.
- Country-scoped dead ends (250+ entries across 52 countries): visa rules
(ETA/eVisitor, NZeTA, e-visas, arrival cards), banking requirements, legal red
lines (lèse-majesté, §86a, Article 301), cultural taboos (chopsticks in rice,
clock gifts in China, red-ink names in Korea), food safety (tap-water safety by
country), emergency numbers, driving norms (left-hand traffic), housing
contracts - all the friction where a plausible-sounding global answer is wrong
locally.

> Why the expansion? Coding dead ends are largely solved by a good LLM.
> Country-specific friction - Japanese hanko requirements, Schengen 90/180
> math, Ramadan business hours, Saudi alcohol ban, Indian beef taboos - is
> where generic AI advice breaks hardest. The codebase and schema are
> identical; the env segment just carries a country code.

> 90% Precision@1 · 0.935 MRR · Data Quality Dashboard

> Website: deadends.dev · MCP Server: Smithery · PyPI: deadends-dev · API: /api/v1/index.json
> Repository: https://github.com/dbwls99706/deadends.dev

Why Use This?

| Without deadends.dev | With deadends.dev |
|---------------------|-------------------|
| Agent tries sudo pip install → breaks system Python → wastes 3 retries | Agent sees "dead end: sudo pip - fails 70%" → skips it immediately |
| Agent tells user to tip 15% at a Tokyo restaurant | Agent knows tipping is refused in Japan (culture/tipping-refused/jp) |
| Agent drafts a Thai social post referencing King Rama X | Agent stops: Article 112 lèse-majesté risk (legal/lese-majeste-article-112/th) |
| Agent fixes error A, gets confused by error B | Agent knows "A leads to B 78% of the time" → handles both |
| Agent tells unmarried couple to kiss publicly in Dubai | Agent flags UAE public decency law (legal/unmarried-public-affection/ae) |

What makes this different from asking an LLM?
- Deterministic: Same query → same answer, every time. No hallucination.
- Country-scoped: ID format {domain}/{slug}/{env} - env holds the country
code (kr, jp, us, de...) so the same taboo can be answered
differently for different jurisdictions.
- Primary-sourced: Every country canon cites government sites, embassies,
or verifiable reporting. No "based on general knowledge" answers.
- Community-validated: Fix success rates updated from real outcome reports.
- Sub-millisecond: Local regex matching, no API roundtrip.

현실적인 한계 (운영 관점)

- 모든 에러를 다 커버하지는 못합니다. 없는 케이스는 이슈/PR/report_outcome로 빠르게 보완합니다.
- 설명의 깊이보다 실전 해결 우선(dead end/workaround 중심)으로 설계되어 있습니다.
- 신뢰성은 도메인/케이스마다 다를 수 있으므로, 고위험 변경은 공식 문서/벤더 가이드와 교차 검증을 권장합니다.

Quick Start (30 seconds)

pip install deadends-dev
deadends "CUDA error: out of memory"

MCP Server (Claude Desktop / Cursor)

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "deadend": {
      "command": "python",
      "args": ["-m", "mcp.server"],
      "cwd": "/path/to/deadends.dev"
    }
  }
}

Or install via Smithery (no local setup):

npx -y @smithery/cli@latest install deadend/deadends-dev --client claude

MCP Unauthorized 빠른 해결 가이드 (사람용)

deadend: calling "initialize": sending "initialize": Unauthorized 에러가 보이면 아래를 순서대로 그대로 실행/확인하세요.

1) 로컬 서버 모드인지, 원격(Smithery) 모드인지 하나만 사용

# 로컬 서버 확인 (정상 시 툴 목록이 출력됨)

python -m mcp.server --help

2) Claude Desktop 설정 파일 점검 (cwd는 실제 경로여야 함)

cat ~/.claude/claude_desktop_config.json

3) 로컬 서버 직접 실행 테스트

cd /path/to/deadends.dev

python -m mcp.server

4) Smithery 모드라면 재설치(토큰/설정 꼬임 복구)

npx -y @smithery/cli@latest uninstall deadend/deadends-dev --client claude

npx -y @smithery/cli@latest install deadend/deadends-dev --client claude

5) 마지막으로 Claude Desktop 완전 재시작

# macOS 예시

osascript -e 'quit app "Claude"'

open -a Claude

> 팁: Unauthorized는 보통 잘못된 cwd, 중복 서버 설정(로컬+원격 동시), 또는 만료된 인증 상태에서 발생합니다.

Antigravity (Google AI IDE)

Add as a remote MCP server - no authentication required:

{
  "mcpServers": {
    "deadend": {
      "serverUrl": "https://deadends.dev/mcp",
      "type": "http"
    }
  }
}

> Note: Antigravity uses serverUrl (not url). If you get Unauthorized, remove any existing deadend entries from the MCP Store and re-add manually using the config above. See the Antigravity MCP auth guide for general troubleshooting.

Python SDK

from generator.lookup import lookup, batch_lookup, search
Single error lookup
result = lookup("ModuleNotFoundError: No module named 'torch'")
What NOT to try (saves tokens and time)
for d in result["dead_ends"]:
    print(f"AVOID: {d['action']} - fails {int(d['fail_rate']100)}%")
What actually works
for w in result["workarounds"]:
    print(f"TRY: {w['action']} - works {int(w['success_rate']100)}%")
Batch lookup (multiple errors at once)
results = batch_lookup(["error1", "error2", "error3"])

Example Response

## ModuleNotFoundError: No module named 'X' (Python 3.11+)
Resolvable: true | Fix rate: 0.88
Dead Ends (DO NOT TRY):
- pip install X with system Python (fails 70%): venv not activated
Workarounds (TRY THESE):
- Create venv, activate, then pip install (works 95%)
- Use python -m pip install instead of bare pip (works 90%)

MCP Tools (11)

| Tool | Description |
|------|-------------|
| lookup_error | Match an error message against 2000+ known patterns |
| get_error_detail | Full canon by ID |
| list_error_domains | All 54 domains with counts |
| search_errors | TF-IDF keyword search across all domains |
| list_errors_by_domain | All errors in a domain |
| list_errors_by_country | All country-scoped dead ends for an ISO alpha-2 code |
| get_country_summary | Country-level summary (entries, fix rate, domain mix) |
| batch_lookup | Look up multiple errors at once (max 10) |
| get_domain_stats | Domain quality metrics and confidence levels |
| get_error_chain | Traverse the error transition graph |
| report_outcome | Report whether a workaround worked (feeds back into success rates) |

API Endpoints

…