ai-stack-radar 0.0.1

Repo-aware engineering change intelligence — detect your stack, monitor upstream releases, and get scored, actionable recommendations in your AI assistant.

AI Stack Radar

Repo-aware engineering change intelligence. AI Stack Radar detects the technologies your repository depends on, monitors upstream releases, classifies and scores each change for relevance to your codebase, and surfaces actionable recommendations — as a CLI, a local dashboard, or as an MCP tool inside Claude Code, Claude Desktop, Cursor, Windsurf, or any MCP-compatible AI assistant.

Instead of drowning in release notes, get answers like:

"There's a FastAPI 0.137 release with a security patch that affects your auth middleware. Pydantic v3 is in beta — monitor, don't adopt yet. httpx shipped a breaking change to AsyncClient.send() — you use it in 3 places."

What it does

1. Analyze — Parses pyproject.toml, uv.lock, requirements.txt, package.json, and Dockerfiles to build a StackProfile.
2. Ingest — Fetches GitHub Releases (and issues/changelogs where useful) for each detected technology, with rate-limit-aware caching.
3. Normalize — Classifies each event as security, breaking, deprecation, feature, or bugfix using regex heuristics plus optional LLM disambiguation.
4. Score — Computes deterministic relevance, urgency, risk, and confidence scores against your stack.
5. Recommend — Maps scored events to actions: ignore, monitor, test_in_staging, create_migration_task, apply_security_patch, adopt_when_ready.
6. Report — Emits a briefing as text, JSON, or Markdown; serves an interactive dashboard; and exposes the whole pipeline as MCP tools for your AI assistant.

Quickstart

Install

pip install ai-stack-radar

With optional extras:

# LLM-enhanced classification and recommendations (Gemini)
pip install "ai-stack-radar[llm]"

# MCP server for AI assistant integration
pip install "ai-stack-radar[mcp]"

# Everything
pip install "ai-stack-radar[llm,mcp]"

Run the pipeline (CLI)

From the root of any repo:

# 1. See what got detected
ai-stack-radar analyze

# 2. Fetch upstream events (set GITHUB_TOKEN to raise the 60 req/hour limit)
export GITHUB_TOKEN=ghp_...
ai-stack-radar ingest --since 2026-01-01

# 3. Normalize and classify
ai-stack-radar normalize

# 4. Score against your stack
ai-stack-radar score

# 5. Get a briefing
ai-stack-radar report --format markdown --min-relevance 0.3

Or launch the dashboard:

ai-stack-radar dashboard
# → http://127.0.0.1:8000

Use inside Claude Code

Add AI Stack Radar as an MCP server. Create (or edit) .mcp.json in your repo root:

{
  "mcpServers": {
    "ai-stack-radar": {
      "command": "ai-stack-radar-mcp"
    }
  }
}

Or, without a global install, run via uvx:

{
  "mcpServers": {
    "ai-stack-radar": {
      "command": "uvx",
      "args": ["--with", "ai-stack-radar[mcp]", "ai-stack-radar-mcp"]
    }
  }
}

Restart Claude Code. You can now ask:

• "What technologies does this repo use?"
• "Are there any updates I should know about?"
• "Show me only security updates in my stack."
• "Tell me more about that FastAPI event — why was it flagged?"
• "What would break if I upgraded httpx to the latest?"
• "Open the dashboard."

The assistant will invoke the right tool (analyze_stack, check_updates, get_briefing, get_event_detail, list_technologies, launch_dashboard) and summarize the result.

Use inside Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "ai-stack-radar": {
      "command": "ai-stack-radar-mcp"
    }
  }
}

Restart Claude Desktop.

MCP tools

Tool	What it does
analyze_stack	Scan dependency files and return the detected StackProfile.
check_updates	Run the full pipeline (analyze → ingest → normalize → score → briefing). The main power tool.
get_briefing	Re-filter cached scored events without re-running the pipeline.
get_event_detail	Full score breakdown, provenance, and recommendation for one event.
list_technologies	Quick stack overview — names, versions, sources.
launch_dashboard	Start the local web dashboard in a background thread and return the URL.

Configuration

• GITHUB_TOKEN — GitHub API token. Without one, ingestion is rate-limited to 60 req/hour.
• GEMINI_API_KEY — Enables LLM-enhanced classification and recommendations. Optional.
• Cache location — platform user-cache directory (see ai_stack_radar/config.py).

Development

git clone https://github.com/AndrewZhao86/AI-Stack-Radar.git
cd AI-Stack-Radar
uv sync --all-extras
uv run pytest

License

MIT