<p align="center"> <img src="assets/banner.png" alt="Athena — Local-First Git & AST Intelligence" width="100%" /> </p> <br />

Athena (athena-mcp) — v1.1.0

Local-First, Evidence-Backed Multi-Language Git & AST Release-Readiness and Change-Intelligence MCP Server

• Version: 1.1.0
• Owner & Maintainer: Aaryan Rawat (aaryan28rwt@gmail.com)

Athena is an open-source, local-first Model Context Protocol (MCP) server and developer CLI that delivers verifiable, ground-truth code-change intelligence. By combining deterministic Git diff analysis (100+ commit range inspection), Python Abstract Syntax Tree (ast) and multi-language structural signature comparison (TypeScript, JavaScript, Python, C++, C, Go, Rust, Java, Kotlin, Scala, C#, Ruby, PHP, Swift), downstream caller blast-radius tracing, and documentation-drift detection, Athena eliminates the hallucination and superficiality of conventional release-note generators.

<p align="center"> <img src="assets/athena-brag.gif" alt="Athena in Action — AST & Git Change Intelligence Showcase" width="100%" /> </p>

---

Key Differentiators (v1.1.0)

1. Deterministic-First Core (100% LLM-Independent): Athena works out-of-the-box completely offline without Ollama, without an external API, and without any network connection. All Git inspections, AST symbol deltas, caller blast-radius graphs, doc-drift warnings, and release notes execute deterministically with 0ms LLM wait time.
2. Multi-Language Structural & AST Diffing (New in v1.1.0): Full Python ast contract and recursion analysis plus structural symbol & signature comparison across TypeScript, JavaScript, C++, C, Go, Rust, Java, Kotlin, Scala, C#, Ruby, PHP, and Swift — detecting removed public symbols, parameter additions/removals, visibility narrowing, and return-type mutations across 100+ commit histories.
3. Ground-Truth Evidence Citations: Every reported change story and potential breaking change is bound to verified EvidenceRecord items containing the 40-character commit SHA, commit subject, file path, exact base/target line spans, unified diff hunk header/excerpt, and confidence rating.
4. AST Contract Differencing & Recursive Function Defect Analysis: Athena ignores misleading Conventional Commit prefixes (e.g. fix: commit messages that actually introduce new public methods or break signatures). It analyzes parameter defaults, positional-parameter index shifts (BUG-030), None-fallback body guards (griffe#469), return-type annotations, (str, Enum) <-> StrEnum migrations (griffe#501), Enum members, public constants, newly raised exceptions (griffe#498), and recursive function bugs (broken recursive self-call arity, unconditional infinite recursion without a base case, unqualified class-method self-recursion NameErrors, and self-recursive caller blast radius).
5. Public API Exposure Differentiation: Automatically distinguishes symbols exported via __all__, package __init__.py re-exports, TypeScript export declarations, Go exported identifiers, Rust pub items, and Java/C#/C++ public symbols (is_public_api_export=True) from internal/private helpers (is_public_api_export=False) so teams know when external package consumers are at risk even if internal callers look clean.
6. Unresolved Dynamic Dispatch Detection & Coverage Confidence Score: Scans repository ASTs for reflection and dynamic invocation patterns (getattr, hasattr, setattr, globals(), locals(), eval, exec, importlib.import_module, and TypeScript bracket dispatch obj[key]()) and emits an explicit AnalysisCoverageReport (static_parse_coverage_pct, unresolved_dynamic_calls_count, overall_blast_radius_confidence) so CI and PR reviewers never get a false sense of security.
7. Three Resilient Operating Modes (Supporting gemma:latest / Gemma 7B & qwen2.5-coder:7b):
   • Mode A (Deterministic-only, Default): High-speed, 100% offline rule-based engine.
   • Mode B (Optional Local Ollama Enhancement): When requested (--llm, use_llm=True, or ATHENA_ENABLE_LLM=1), local Ollama (gemma:latest / gemma:7b or qwen2.5-coder:7b) enhances narrative explanations while strictly verifying evidence citations against deterministic ground truth. Includes automatic VRAM swap eviction for 6 GB GPUs.
   • Mode C (Fault-Tolerant Fallback): If Ollama times out, returns malformed JSON, or is offline, Athena gracefully degrades to deterministic output with clear diagnostic warnings.
8. Drop-In GitHub Actions PR Audit Bot (.github/workflows/athena-audit.yml): Ships with a ready-to-use GitHub Actions workflow that runs the multi-Python test matrix and posts a structured Breaking-Change, Blast-Radius & Release Notes summary table directly to $GITHUB_STEP_SUMMARY on every Pull Request.
9. Private, Read-Only & Fully Annotated MCP Tools: Athena declares explicit MCP ToolAnnotations (readOnlyHint=True, destructiveHint=False, idempotentHint=True, openWorldHint=False) on all 7 registered tools, never modifies your repository, never pushes code, and runs 100% locally on consumer hardware (verified on an NVIDIA RTX 4050 Laptop GPU with 6 GB VRAM and 16 GB RAM).

---

Architecture

flowchart TD
    subgraph Client["MCP Clients & CLI"]
        CLI["Athena CLI v1.1.0\n(athena / python -m athena.cli)"]
        IDE["MCP Clients\n(Claude Desktop, Cursor, VS Code)"]
    end

    subgraph Server["Athena MCP Server (stdio)"]
        MCP["athena.mcp_server\n(7 Read-Only Annotated Tools & Schema Validation)"]
        SEC["Security & Redaction Gate\n- Path Jail & Symlink Defense\n- CLI Flag Injection Defense\n- Bearer / Key Redaction"]
    end

    subgraph Pipeline["Athena Deterministic Analysis Pipeline (Mode A)"]
        GIT["Git Inspector\n(100+ Commit Range, Partial Clone Batching, Diffs)"]
        AST["Multi-Language AST & Structural Analyzer\n- Python ast Contract & Recursion Differ\n- TS/JS/C++/C/Go/Rust/Java/C#/Ruby/PHP Scanner\n- Public API & None-Guard Analysis"]
        BLAST["Blast-Radius & Caller Engine\n(Self-Recursion, Static Import, Arity & Dynamic Call Tracing)"]
        DRIFT["Doc-Drift Scanner\n(Markdown Stale Symbol & Call-Arity Extraction)"]
        VERIFY["Evidence & Coverage Verifier\n(SHA, Line Span, Parse Coverage & Confidence)"]
    end

    subgraph OptionalAI["Optional Local LLM Enhancement (Mode B / Mode C)"]
        OLLAMA["Local Ollama Service\n(gemma:latest 7B / qwen2.5-coder:7b)"]
        FALLBACK["Graceful Degrader\n(Timeout / Malformed JSON / Offline)"]
    end

    subgraph Output["Evidence-Backed Results"]
        REPORT["Audience-Tailored Release Notes\n(Developers, Maintainers, Clients)"]
        BREAK["Potential Breaking Changes\n(Recursion Bugs, Public Exposure, Callers)"]
    end

    CLI --> SEC
    IDE --> MCP
    MCP --> SEC
    SEC --> GIT
    GIT --> AST
    AST --> BLAST
    BLAST --> DRIFT
    DRIFT --> VERIFY

    VERIFY -->|Default: Mode A| Output
    VERIFY -->|Optional --llm: Mode B| OLLAMA
    OLLAMA -->|Enhanced Output| Output
    OLLAMA -.->|Failure / Timeout| FALLBACK
    FALLBACK -->|Degraded Mode C| Output

---

Installation & Setup

Prerequisites

• Python: >= 3.12 (verified on Python 3.12, 3.13, and 3.14)
• Git: >= 2.30 (verified on git 2.53)
• (Optional) Ollama: Local Ollama server at http://127.0.0.1:11434 with gemma:latest (Gemma 7B, a72c7f4d0a15, ~5.0 GB) and/or qwen2.5-coder:7b (dae161e27b0e, ~4.7 GB) if Mode B is desired.

Portable Installation

Clone the repository and install Athena in a clean virtual environment:

# 1. Clone repository
git clone https://github.com/aaryanrwt/athena.git
cd athena

# 2. Create and activate virtual environment
python -m venv .venv

# On Linux / macOS:
source .venv/bin/activate

# On Windows (PowerShell):
.venv\Scripts\Activate.ps1

# 3. Install in editable development mode
pip install -e .

---

MCP Server Configuration

Athena communicates via standard JSON-RPC 2.0 over standard I/O (stdio).

Claude Desktop (claude_desktop_config.json)

Add Athena to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "athena": {
      "command": "athena",
      "args": ["mcp"],
      "env": {
        "ATHENA_ENABLE_LLM": "0"
      }
    }
  }
}

Note: To enable optional local Ollama enhancement (gemma:latest or qwen2.5-coder:7b), set "ATHENA_ENABLE_LLM": "1".

Cursor / VS Code / Other MCP Clients

For generic MCP clients using executable commands:

{
  "athena": {
    "command": "python",
    "args": ["-m", "athena.cli", "mcp"]
  }
}

---

Registered MCP Tools

Athena exposes 7 read-only, schema-validated MCP tools, each annotated with explicit MCP ToolAnnotations (readOnlyHint=True, destructiveHint=False, idempotentHint=True, openWorldHint=False):

| MCP Tool Name | Primary Parameters | Description | | :--- | :--- | :--- | | inspect_repository | repo_path (str), max_recent_commits (int, default 10) | Safely inspects branch status, tags, HEAD commit, clean status, and recent commits. | | analyze_git_history | repo_path (str), base_ref (str, default "AUTO"), target_ref (str, default "HEAD"), max_commits (int, default 100, up to 500), use_llm (bool, default False) | Extracts bounded revision range (100+ commits), commit history, unified diffs, and multi-language AST/structural symbol deltas into grounded change stories. | | detect_potential_breaking_changes | repo_path (str), base_ref (str, default "AUTO"), target_ref (str, default "HEAD"), include_low_confidence (bool, default False), use_llm (bool, default False) | Detects signature mutations, removed symbols, newly raised exceptions, base class changes, affected downstream callers, and documentation drift. | | generate_release_notes | repo_path (str), base_ref (str, default "AUTO"), target_ref (str, default "HEAD"), release_version (str, default "Unreleased"), audience (str: end_users | developers | maintainers | clients), output_file (str, optional), overwrite (bool, default False), use_llm (bool, default False) | Synthesizes audience-tailored Markdown release notes with evidence citations, upgrade considerations, and potential breaking changes. | | analyze_change_graph | repo_path (str), base_ref (str), head_ref (str, default "HEAD"), max_commits (int, default 100) | Inspects deterministic symbol delta graph, caller blast radius, and commit history across base_ref..head_ref. | | verify_breaking_and_doc_drift | repo_path (str), base_ref (str), head_ref (str, default "HEAD"), include_low_confidence (bool, default False) | Verifies breaking changes, documentation drift, and caller impact across base_ref..head_ref. | | generate_verified_release_brief | repo_path (str), base_ref (str), head_ref (str, default "HEAD"), release_version (str), audience (str) | Generates structured Markdown + JSON release brief backed by verified commit and diff evidence. |

---

CLI Usage & Verified Execution Output

The Athena CLI provides instant, zero-LLM deterministic analysis directly from your terminal. All examples below are executed directly against examples/demo_repo, a realistic Git repository with tags v0.1.0 and v0.2.0 (generated via python examples/create_demo_repo.py).

To run from source:

# 1. Generate the local demo Git repository (for testing):
python examples/create_demo_repo.py

# 2. Run Athena CLI (if installed via pip / editable):
athena <subcommand> [options]

# Or directly with Python:
pyt