Deadend MCP Server

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 (56+ entries across 20+ countries): visa rules, 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, emergency numbers, driving norms, 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?

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

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

cat ~/.claude/claude_desktop_config.json

1. 로컬 서버 직접 실행 테스트

cd /path/to/deadends.dev
python -m mcp.server

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

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

1. 마지막으로 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)

API Endpoints

Covered Domains (54)

Code error domains (51)

Country-scoped real-world domains (new, growing)

Data Quality

All metrics are publicly available on the Data Quality Dashboard:

• 2,204 canon entries across 54 domains and 39+ countries
• Benchmark: 90% Precision@1, 95% Precision@3, 0.935 MRR (on code scenarios)
• Error transition graph: 4,330+ edges connecting related errors
• Community feedback loop: report_outcome updates fix success rates from real usage
• Country canons: every entry cites primary gov/embassy/regulator sources, reviewed by humans (review_status: human_reviewed), no LLM bulk generation

Country coverage (39 countries as of v0.9)

kr · jp · us · de · uk · fr · it · es · cn · hk · tw · th · in · vn · id · sg · ph · my · pk · sa · ae · tr · il · ru · br · mx · ar · co · pe · au · nz · eg · ma · et · ng · ke · ca · pl · at

See /country/ hub or /api/v1/countries.json for the authoritative list with counts.

See docs/country-canon-guide.md for the authoring workflow, sourcing requirements, and confidence calibration.

Contributing

See CONTRIBUTING.md for full details.

• GitHub 자동 수집 운영안: docs/GITHUB_DATA_COLLECTION_STRATEGY.md

• 자동 수집 주기: 6시간마다(하루 4회), 기본 품질 필터: min_score=2

• 수집 데이터는 후보이며, 최종 반영은 maintainer 검수 후 진행

• Submit a new error

• Report a workaround result

• Use report_outcome via MCP after trying a workaround

Development

pip install -e ".[dev]"

python -m generator.pipeline          # Full pipeline
python -m generator.build_site        # Build static site
python -m generator.validate          # Validate data + site
python -m pytest tests/ -v            # Run tests
ruff check generator/ tests/          # Lint
python benchmarks/run_benchmark.py    # Run benchmarks

SEO 점검 가이드 (모든 페이지 공통)

아래 명령은 템플릿에 핵심 SEO 신호가 있는지 빠르게 점검합니다.

python - <<'PY'
from pathlib import Path
files=[
  'generator/templates/index.html',
  'generator/templates/domain.html',
  'generator/templates/error_summary.html',
  'generator/templates/page.html',
  'generator/templates/search.html',
  'generator/templates/dashboard.html',
]
required=[
  '<title',
  'meta name="description"',
  'meta name="robots"',
  'link rel="canonical"',
  'meta property="og:title"',
  'meta name="twitter:card"',
]
for f in files:
    txt=Path(f).read_text()
    missing=[r for r in required if r not in txt]
    print(f'✅ {f}' if not missing else f'❌ {f} missing: {", ".join(missing)}')
PY

실제 빌드 결과물까지 확인하려면:

python -m generator.build_site
python -m http.server -d public 8080

그 후 브라우저에서 아래를 점검:

• view-source:http://localhost:8080/search/
• view-source:http://localhost:8080/dashboard/
• canonical / og / twitter / JSON-LD 유효성

Changelog

v0.9.0 — Country pivot

• New axis: country-scoped real-world dead ends alongside code errors
• 56+ country canons across 20+ countries — visa, banking, legal red lines, cultural taboos, food safety, emergency numbers, driving norms
• 3 new domains: visa, banking, emergency (plus extended use of existing legal, culture, medical, communication, food-safety, safety domains with country env segment)
• Per-country landing pages at /country/{cc}/ (e.g. /country/jp/)
• generator.country_canon_template helper for authoring new country canons with validated env-segment + audience + jurisdiction metadata
• docs/country-canon-guide.md: sourcing standards (primary > embassy

  reputable media), confidence calibration, slug/regex conventions

• Schema unchanged (backward-compatible enum extensions); existing 2,089 code canons preserved

v0.8.0

• Benchmark suite: 20 error scenarios, Precision@1=90%, MRR=0.935
• Data quality dashboard at /dashboard/ — transparent metrics
• Outcome feedback loop: report_outcome → aggregated stats → fix_success_rate updates
• Usage analytics: anonymous tool usage tracking (domain/match only, no PII)
• Community contribution: GitHub Issue templates for new errors and workaround reports
• TF-IDF search: improved relevance with smoothed IDF scoring
• Error transition graph: materialized graph with 4,330+ edges, hub node analysis
• 9 MCP tools (added report_outcome)

v0.7.0

• Expanded to 2089 error entries across 51 domains (from 1028/20)
• Added 23 new domains
• Fixed 73 regex patterns that didn't match their own signatures

v0.5.0

• page_url field added to index.json, errors.ndjson, and all SDK/MCP responses
• SEO fixes for canonical summary URLs

v0.4.0

• Initial public release with 1028 error entries across 20 domains

License

MIT (code) · CC BY 4.0 (data)

Ops Docs

• SEO 운영 가이드: docs/SEO_OPERATIONS_GUIDE.md
• PyPI 릴리즈 매뉴얼: docs/PYPI_RELEASE_MANUAL.md