Metadata-Version: 2.4
Name: onboardai
Version: 0.1.13
Summary: An AI-powered onboarding intelligence layer on top of Graphify for MCP
Author-email: ROHIT ANISH <rohit.anish2025@vitstudent.ac.in>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn>=0.20.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: networkx>=3.0
Requires-Dist: pydantic>=2.0
Requires-Dist: graphifyy>=0.8.0

# OnboardAI: AI-Powered Onboarding Intelligence Layer

![OnboardAI Use Case & Features](./website/assets/onboard_ai_infographic.webp)

OnboardAI is a developer onboarding intelligence system that integrates with Claude Code and other MCP-compatible clients. It is designed to dramatically reduce the time it takes a new developer, intern, or employee to understand a codebase by converting raw repository data and Graphify knowledge graphs into interactive, onboarding-oriented insights.

---

## 1. Vision & Architecture

Rather than generating raw repository diagrams or acting as another codebase crawler, OnboardAI acts as a **structured guidance layer** on top of Graphify. It parses Graphify’s extraction data, maps relationships with NetworkX, groups code modules by directory structure, and answers questions relative to what tasks a developer has been assigned.

### Core Architecture Flow

```mermaid
flowchart TD
    subgraph Client Layer
        ClaudeCode[Claude Code / MCP Client]
    end

    subgraph OnboardAI MCP Server
        Server[FastMCP Server]
        Scanner[Project Scanner & Tech Detector]
        Adapter[Graphify Adapter]
        Roadmap[Roadmap Generator]
        QA[Q&A & Context Engine]
        Dependency[Dependency Analyzer]
        Viz[Mermaid Visualizer]
    end

    subgraph Intelligence Engine
        Graphify[Graphify extraction]
        NX[NetworkX Directed Graph]
    end

    ClaudeCode <-->|JSON-RPC via Stdio/SSE| Server
    Server <--> Scanner
    Server <--> Adapter
    Adapter <-->|Reads graphify-out/| Graphify
    Adapter <-->|Builds| NX
    Roadmap <--> Adapter
    QA <--> Adapter
    Dependency <--> Adapter
    Viz <--> Adapter
```

---

## 2. Directory Layout & Components

Here is the file structure of the OnboardAI project:

```text
OnboardAI/
├── .graphifyignore        # Ignore rules to bypass LLM extraction for non-code files
├── requirements.txt       # Project dependencies
├── pyproject.toml         # Packaging metadata, lists graphifyy package as dependency
├── main.py                # Launcher: starts MCP server in stdio or sse mode
├── test_integration.py    # Offline self-check verification test script
├── test_client.py         # Standard python MCP client session simulation script
├── scanner/
│   ├── __init__.py
│   ├── project_scanner.py     # Counts files and crawls folders
│   └── architecture_detector.py # Detects tech stacks (FastAPI, React, etc.)
├── knowledge/
│   ├── __init__.py
│   ├── graphify_adapter.py    # Integrates Graphify output, builds graphs, handles executable discovery
│   ├── dependency_analyzer.py # Traverses graph for upstream/downstream impact and risk analysis
│   ├── onboarding_plan.py     # Generates day-by-day study paths
│   ├── repository_inventory.py# Structured module/class/function catalogs
│   └── qa_assistant.py        # Performs graph-based Q&A and task instructions
└── graph/
    ├── __init__.py
    └── graph_generator.py     # Generates Mermaid mindmaps, dependencies, and call-flows
```

---

## 3. The 4 Core Product Features

### Feature 1: Repository Intelligence Summary
* **MCP Tool**: `get_repository_summary(repo_path: str)`
* **Description**: Combines scanner statistics, directory structure trees, technology detection, config files list, module inventory, and critical abstractions (high-degree centrality components) into a structured high-level overview.
* **Output**: Project type, architecture style, technologies, core modules, entry points, major dependencies, and high-level system flow.

### Feature 2: Task-Aware Onboarding
* **MCP Tool**: `get_task_onboarding_guide(repo_path, task_description, role, team, target_module, question)`
* **Description**: Generates a tailored learning progression plan. If `task_description` is provided, it extracts relevant files, suggested study order, prerequisites, and estimated ramp-up time. Also answers repository Q&A queries.
* **Roadmap Structure**:
  - **Day 1**: Environment setup, tech summary, configs.
  - **Day 2**: Foundational modules (utilities, schemas, database clients).
  - **Day 3**: Mid-level business logic.
  - **Day 4**: API controllers, routers, and entry points.
  - **Day 5**: Automated tests and first contribution.

### Feature 3: Dependency Impact Analyzer
* **MCP Tool**: `analyze_dependency_impact(repo_path, target_component)`
* **Description**: Analyzes the consequences of modifying a target component or code file. Traces upstream (incoming) and downstream (outgoing) relationships, determines a Risk Level (High/Medium/Low), and suggests recommended tests.

### Feature 4: Graphify Visual Knowledge Graph
* **MCP Tool**: `get_visual_knowledge_graph(repo_path, visualization_type)`
* **Description**: Translates the NetworkX graph nodes into beautiful Mermaid syntax for direct rendering:
  - `mindmap`: Folder layout and core modules.
  - `callflow`: Functional method-to-method call flow chart.
  - `dependency`: High-level module import connections.

---

## 4. MCP Server & Protocols

The MCP Server is implemented in `mcp_server/server.py` using the **FastMCP SDK**.

It exposes exactly **4 consolidated tools** to any connected client:
1. `get_repository_summary(repo_path)`: Overall tech stack, folders, stats, flow.
2. `get_task_onboarding_guide(repo_path, task_description, role, team, target_module, question)`: Customized roadmap, task analysis, and codebase Q&A.
3. `analyze_dependency_impact(repo_path, target_component)`: Upstream/downstream impact analysis, risk level, test recommendations.
4. `get_visual_knowledge_graph(repo_path, visualization_type)`: Generates Mermaid mindmap, dependency, or callflow diagrams.

---

## 5. Setup & Integration Guide

### Installation
OnboardAI depends on the PyPI package **`graphifyy`** (with two 'y's). Installing `onboardai` automatically resolves and installs it:
```bash
pip install onboardai
```

### Local Verification
Verify the server runs successfully on your machine by running the test client session simulation:
```powershell
python test_client.py
```
This script acts as a local client session, connects to the server, retrieves the tools list, and invokes them locally.

### Integrating with Claude Code
To register the server with the **Claude Code CLI**, run:
```powershell
claude mcp add onboard-ai python -m mcp_server.server
# OR if calling main.py launcher
claude mcp add onboard-ai python "<path-to-onboardai-repo>\main.py"
```

Once registered, launch Claude Code:
```powershell
claude
```

---

## 6. How to Ask Questions

Once integrated into Claude, the model will automatically pick the right tool based on your natural language prompt. Here are some examples:

| Question you ask Claude | Tool Claude calls under the hood |
| :--- | :--- |
| **"Summarise this project"** | `get_repository_summary` |
| **"Explain the module GraphifyAdapter"** | `get_task_onboarding_guide(target_module='GraphifyAdapter')` |
| **"How should I build the visualizer? What files are relevant?"** | `get_task_onboarding_guide(task_description='visualizer')` |
| **"Show me the dependency mindmap"** | `get_visual_knowledge_graph(visualization_type='mindmap')` |
| **"If I modify GraphifyAdapter, what will break?"** | `analyze_dependency_impact(target_component='GraphifyAdapter')` |
