onboarding-agent 0.1.0__tar.gz

onboarding_agent-0.1.0/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__onboarding-agent__build_knowledge_graph"
+    ]
+  }
+}

onboarding_agent-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+Claude.md
+.venv/
+.onboarding_agent/
+__pycache__/
+*.pyc
+dist/
+*.egg-info/
+./claude

onboarding_agent-0.1.0/.mcp.json

@@ -0,0 +1,8 @@
+{                                                                               
+    "mcpServers": {                                                                 
+      "onboarding-agent": {                                                         
+        "command": "uv",                                                            
+        "args": ["--directory", "/Users/abhirambanda/onboarding-agent", "run", "main.py"]                                                                        
+      }                                                                             
+    }                                                                               
+  }  

onboarding_agent-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

onboarding_agent-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: onboarding-agent
+Version: 0.1.0
+Summary: An MCP server that onboards you to any codebase — point it at a repo and ask questions like a senior engineer who knows the project inside out.
+License-Expression: MIT
+Keywords: codebase,developer-tools,knowledge-graph,mcp,onboarding
+Requires-Python: >=3.12
+Requires-Dist: gitpython>=3.1.50
+Requires-Dist: mcp>=1.27.2
+Description-Content-Type: text/markdown
+
+# onboarding-agent
+
+An MCP server that onboards you to any codebase. Point it at a repo, and it builds a knowledge graph of the project — files, functions, classes, imports, and their relationships. Then ask questions like you're talking to a senior engineer who knows the project inside out.
+
+## What it does
+
+- **Ingests any local repo** — crawls the file tree, detects languages and frameworks
+- **Builds a knowledge graph** — maps files, functions, classes, modules, and how they connect via imports
+- **Answers onboarding questions** — "where does auth happen?", "what does this file do?", "who should I ask about the database?"
+- **Analyzes git history** — finds the most-changed files (often the most important), recent activity, and contributors per file
+- **Works 100% locally** — no API keys, no cloud, no data leaves your machine
+
+## Install
+
+Requires Python 3.12+.
+
+```bash
+# With uv (recommended)
+uv pip install git+https://github.com/abab754/onboarding-agent.git
+
+# Or clone and install locally
+git clone https://github.com/abab754/onboarding-agent.git
+cd onboarding-agent
+uv sync
+```
+
+## Connect to an MCP client
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "onboarding-agent": {
+      "command": "uv",
+      "args": ["--directory", "/path/to/onboarding-agent", "run", "main.py"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add a `.mcp.json` file to your project root (or the repo you want to onboard to):
+
+```json
+{
+  "mcpServers": {
+    "onboarding-agent": {
+      "command": "uv",
+      "args": ["--directory", "/path/to/onboarding-agent", "run", "main.py"]
+    }
+  }
+}
+```
+
+Then restart Claude Code.
+
+### Any MCP-compatible client
+
+The server uses stdio transport. Run it with:
+
+```bash
+uv run main.py
+```
+
+Any MCP client can connect via stdin/stdout.
+
+## Usage examples
+
+Once connected, just talk to your AI assistant naturally:
+
+**Full onboarding:**
+> "Onboard me to the repo at /Users/me/projects/my-app"
+
+**Understand a file:**
+> "Explain what /Users/me/projects/my-app/src/auth.py does"
+
+**Find relevant code:**
+> "Where does database configuration happen in /Users/me/projects/my-app?"
+
+**Check project activity:**
+> "Who are the main contributors to /Users/me/projects/my-app and what files change the most?"
+
+**Freeform questions:**
+> "How is error handling done in this project?"
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `ingest_repo` | Crawl a repo and return the file tree |
+| `read_file` | Read a file's contents with metadata |
+| `get_overview` | High-level summary: languages, frameworks, entry points |
+| `explain_file` | File contents + imports, functions, classes |
+| `explain_module` | Directory overview with per-file symbols |
+| `build_knowledge_graph` | Index the repo into a queryable knowledge graph |
+| `query_entities` | Search the graph for files, functions, classes, modules |
+| `query_relationships` | Find how entities connect (imports, contains) |
+| `find_relevant_code` | Search by topic and get ranked results |
+| `get_architecture` | Import graph, module structure, coupling analysis |
+| `ask` | Freeform Q&A — gathers context automatically |
+| `get_git_history` | Recent commits and contributor summary |
+| `get_hot_files` | Most frequently changed files |
+| `get_file_contributors` | Who has worked on a specific file |
+
+## Resources
+
+| URI | Description |
+|---|---|
+| `repo://overview` | Project summary (after a repo is loaded) |
+| `repo://structure` | File tree |
+| `repo://dependencies` | Import/dependency graph |
+
+## Prompts
+
+| Prompt | Description |
+|---|---|
+| `onboard` | Full onboarding walkthrough |
+| `explain_this_file` | Deep dive into a specific file |
+| `find_code_for` | Find code related to a topic |
+| `ask_question` | Freeform question answering |
+
+## How it works
+
+1. You point the server at a repo path
+2. It crawls the file tree, skipping noise directories (`.git`, `node_modules`, etc.)
+3. For Python files, it extracts functions, classes, and import statements
+4. Everything gets stored in a knowledge graph (saved to `.onboarding_agent/graph.json` in the repo)
+5. When you ask a question, it searches the graph, reads relevant files, and bundles the context for the LLM to answer
+
+The knowledge graph persists between sessions, so re-analysis is only needed when the code changes.
+
+## Development
+
+```bash
+git clone https://github.com/YOUR_USERNAME/onboarding-agent.git
+cd onboarding-agent
+uv sync
+
+# Run the server
+uv run main.py
+
+# Test with MCP Inspector
+npx @modelcontextprotocol/inspector uv run main.py
+```
+
+## Project structure
+
+```
+onboarding_agent/
+├── server.py              # FastMCP instance and global state
+├── constants.py           # Language maps, config signals, skip dirs
+├── helpers.py             # File tree building, Python symbol extraction
+├── knowledge_graph.py     # KnowledgeGraph class with JSON persistence
+├── resources.py           # MCP resources (repo://overview, etc.)
+├── prompts.py             # MCP prompt templates
+└── tools/
+    ├── ingest.py          # ingest_repo, read_file
+    ├── analysis.py        # get_overview, explain_file, explain_module
+    ├── graph.py           # build_knowledge_graph, query_entities, query_relationships
+    ├── search.py          # find_relevant_code, get_architecture, ask
+    └── git_history.py     # get_git_history, get_hot_files, get_file_contributors
+```
+
+## License
+
+MIT

onboarding_agent-0.1.0/README.md

@@ -0,0 +1,170 @@
+# onboarding-agent
+
+An MCP server that onboards you to any codebase. Point it at a repo, and it builds a knowledge graph of the project — files, functions, classes, imports, and their relationships. Then ask questions like you're talking to a senior engineer who knows the project inside out.
+
+## What it does
+
+- **Ingests any local repo** — crawls the file tree, detects languages and frameworks
+- **Builds a knowledge graph** — maps files, functions, classes, modules, and how they connect via imports
+- **Answers onboarding questions** — "where does auth happen?", "what does this file do?", "who should I ask about the database?"
+- **Analyzes git history** — finds the most-changed files (often the most important), recent activity, and contributors per file
+- **Works 100% locally** — no API keys, no cloud, no data leaves your machine
+
+## Install
+
+Requires Python 3.12+.
+
+```bash
+# With uv (recommended)
+uv pip install git+https://github.com/abab754/onboarding-agent.git
+
+# Or clone and install locally
+git clone https://github.com/abab754/onboarding-agent.git
+cd onboarding-agent
+uv sync
+```
+
+## Connect to an MCP client
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "onboarding-agent": {
+      "command": "uv",
+      "args": ["--directory", "/path/to/onboarding-agent", "run", "main.py"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add a `.mcp.json` file to your project root (or the repo you want to onboard to):
+
+```json
+{
+  "mcpServers": {
+    "onboarding-agent": {
+      "command": "uv",
+      "args": ["--directory", "/path/to/onboarding-agent", "run", "main.py"]
+    }
+  }
+}
+```
+
+Then restart Claude Code.
+
+### Any MCP-compatible client
+
+The server uses stdio transport. Run it with:
+
+```bash
+uv run main.py
+```
+
+Any MCP client can connect via stdin/stdout.
+
+## Usage examples
+
+Once connected, just talk to your AI assistant naturally:
+
+**Full onboarding:**
+> "Onboard me to the repo at /Users/me/projects/my-app"
+
+**Understand a file:**
+> "Explain what /Users/me/projects/my-app/src/auth.py does"
+
+**Find relevant code:**
+> "Where does database configuration happen in /Users/me/projects/my-app?"
+
+**Check project activity:**
+> "Who are the main contributors to /Users/me/projects/my-app and what files change the most?"
+
+**Freeform questions:**
+> "How is error handling done in this project?"
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `ingest_repo` | Crawl a repo and return the file tree |
+| `read_file` | Read a file's contents with metadata |
+| `get_overview` | High-level summary: languages, frameworks, entry points |
+| `explain_file` | File contents + imports, functions, classes |
+| `explain_module` | Directory overview with per-file symbols |
+| `build_knowledge_graph` | Index the repo into a queryable knowledge graph |
+| `query_entities` | Search the graph for files, functions, classes, modules |
+| `query_relationships` | Find how entities connect (imports, contains) |
+| `find_relevant_code` | Search by topic and get ranked results |
+| `get_architecture` | Import graph, module structure, coupling analysis |
+| `ask` | Freeform Q&A — gathers context automatically |
+| `get_git_history` | Recent commits and contributor summary |
+| `get_hot_files` | Most frequently changed files |
+| `get_file_contributors` | Who has worked on a specific file |
+
+## Resources
+
+| URI | Description |
+|---|---|
+| `repo://overview` | Project summary (after a repo is loaded) |
+| `repo://structure` | File tree |
+| `repo://dependencies` | Import/dependency graph |
+
+## Prompts
+
+| Prompt | Description |
+|---|---|
+| `onboard` | Full onboarding walkthrough |
+| `explain_this_file` | Deep dive into a specific file |
+| `find_code_for` | Find code related to a topic |
+| `ask_question` | Freeform question answering |
+
+## How it works
+
+1. You point the server at a repo path
+2. It crawls the file tree, skipping noise directories (`.git`, `node_modules`, etc.)
+3. For Python files, it extracts functions, classes, and import statements
+4. Everything gets stored in a knowledge graph (saved to `.onboarding_agent/graph.json` in the repo)
+5. When you ask a question, it searches the graph, reads relevant files, and bundles the context for the LLM to answer
+
+The knowledge graph persists between sessions, so re-analysis is only needed when the code changes.
+
+## Development
+
+```bash
+git clone https://github.com/YOUR_USERNAME/onboarding-agent.git
+cd onboarding-agent
+uv sync
+
+# Run the server
+uv run main.py
+
+# Test with MCP Inspector
+npx @modelcontextprotocol/inspector uv run main.py
+```
+
+## Project structure
+
+```
+onboarding_agent/
+├── server.py              # FastMCP instance and global state
+├── constants.py           # Language maps, config signals, skip dirs
+├── helpers.py             # File tree building, Python symbol extraction
+├── knowledge_graph.py     # KnowledgeGraph class with JSON persistence
+├── resources.py           # MCP resources (repo://overview, etc.)
+├── prompts.py             # MCP prompt templates
+└── tools/
+    ├── ingest.py          # ingest_repo, read_file
+    ├── analysis.py        # get_overview, explain_file, explain_module
+    ├── graph.py           # build_knowledge_graph, query_entities, query_relationships
+    ├── search.py          # find_relevant_code, get_architecture, ask
+    └── git_history.py     # get_git_history, get_hot_files, get_file_contributors
+```
+
+## License
+
+MIT

onboarding_agent-0.1.0/main.py

@@ -0,0 +1,15 @@
+"""Entry point for the onboarding-agent MCP server."""
+
+from onboarding_agent.server import mcp
+
+# Import all tool/resource/prompt modules so they register with the mcp instance.
+import onboarding_agent.tools.ingest  # noqa: F401
+import onboarding_agent.tools.analysis  # noqa: F401
+import onboarding_agent.tools.graph  # noqa: F401
+import onboarding_agent.tools.search  # noqa: F401
+import onboarding_agent.tools.git_history  # noqa: F401
+import onboarding_agent.resources  # noqa: F401
+import onboarding_agent.prompts  # noqa: F401
+
+if __name__ == "__main__":
+    mcp.run()

onboarding_agent-0.1.0/onboarding_agent/constants.py

@@ -0,0 +1,30 @@
+# Directories we never want to crawl — these are noise, not project structure.
+SKIP_DIRS = {".git", ".venv", "venv", "node_modules", "__pycache__", ".tox", ".mypy_cache"}
+
+# Maps file extensions to language names.
+EXTENSION_TO_LANGUAGE = {
+    ".py": "Python", ".js": "JavaScript", ".ts": "TypeScript",
+    ".jsx": "JavaScript (React)", ".tsx": "TypeScript (React)",
+    ".java": "Java", ".go": "Go", ".rs": "Rust", ".rb": "Ruby",
+    ".cpp": "C++", ".c": "C", ".cs": "C#", ".swift": "Swift",
+    ".kt": "Kotlin", ".scala": "Scala", ".php": "PHP",
+    ".html": "HTML", ".css": "CSS", ".scss": "SCSS",
+    ".sh": "Shell", ".sql": "SQL", ".r": "R",
+}
+
+# Config files that reveal which frameworks/tools the project uses.
+CONFIG_SIGNALS = {
+    "pyproject.toml": "Python (uv/pip)", "setup.py": "Python (setuptools)",
+    "requirements.txt": "Python (pip)", "Pipfile": "Python (pipenv)",
+    "package.json": "Node.js", "tsconfig.json": "TypeScript",
+    "Cargo.toml": "Rust", "go.mod": "Go", "pom.xml": "Java (Maven)",
+    "build.gradle": "Java (Gradle)", "Gemfile": "Ruby",
+    "Makefile": "Make", "Dockerfile": "Docker",
+    "docker-compose.yml": "Docker Compose", "docker-compose.yaml": "Docker Compose",
+    ".eslintrc.json": "ESLint", ".prettierrc": "Prettier",
+}
+
+ENTRY_POINT_NAMES = {
+    "main.py", "app.py", "manage.py", "server.py", "cli.py",
+    "index.js", "index.ts", "main.go", "main.rs", "App.java",
+}

onboarding_agent-0.1.0/onboarding_agent/helpers.py

@@ -0,0 +1,101 @@
+"""Shared helper functions used across multiple tools."""
+
+from pathlib import Path
+
+from onboarding_agent.constants import SKIP_DIRS, EXTENSION_TO_LANGUAGE, CONFIG_SIGNALS, ENTRY_POINT_NAMES
+
+
+def build_file_tree(root: Path, max_depth: int = 5) -> dict:
+    """Recursively walk a directory and return a nested dict representing the file tree.
+
+    Each directory is a dict with "type": "directory" and "children": {...}.
+    Each file is a dict with "type": "file" and "size": <bytes>.
+    """
+    tree: dict = {}
+
+    try:
+        entries = sorted(root.iterdir(), key=lambda e: (e.is_file(), e.name))
+    except PermissionError:
+        return {"error": "permission denied"}
+
+    for entry in entries:
+        if entry.name in SKIP_DIRS:
+            continue
+
+        if entry.is_dir():
+            if max_depth <= 0:
+                tree[entry.name] = {"type": "directory", "children": "...truncated"}
+            else:
+                tree[entry.name] = {
+                    "type": "directory",
+                    "children": build_file_tree(entry, max_depth - 1),
+                }
+        elif entry.is_file():
+            tree[entry.name] = {
+                "type": "file",
+                "size": entry.stat().st_size,
+            }
+
+    return tree
+
+
+def extract_python_symbols(content: str) -> dict:
+    """Extract imports, function names, and class names from Python source code.
+
+    Uses simple line-based parsing rather than AST — faster, works on files
+    with syntax errors, and good enough for an overview.
+    """
+    imports: list[str] = []
+    functions: list[str] = []
+    classes: list[str] = []
+
+    for line in content.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("import ") or stripped.startswith("from "):
+            imports.append(stripped)
+        elif stripped.startswith("def "):
+            name = stripped[4:].split("(")[0].strip()
+            functions.append(name)
+        elif stripped.startswith("class "):
+            name = stripped[6:].split("(")[0].split(":")[0].strip()
+            classes.append(name)
+
+    return {"imports": imports, "functions": functions, "classes": classes}
+
+
+def collect_extensions(tree: dict) -> dict[str, int]:
+    """Walk the file tree and count occurrences of each file extension."""
+    counts: dict[str, int] = {}
+    for name, info in tree.items():
+        if not isinstance(info, dict):
+            continue
+        if info.get("type") == "file":
+            ext = Path(name).suffix.lower()
+            if ext:
+                counts[ext] = counts.get(ext, 0) + 1
+        elif info.get("type") == "directory":
+            children = info.get("children")
+            if isinstance(children, dict):
+                for ext, n in collect_extensions(children).items():
+                    counts[ext] = counts.get(ext, 0) + n
+    return counts
+
+
+def find_config_files(tree: dict) -> list[str]:
+    """Return names of known config/framework files found at the repo root."""
+    return [name for name in tree if name in CONFIG_SIGNALS]
+
+
+def find_entry_points(tree: dict, root_path: str) -> list[str]:
+    """Find likely entry point files in the tree (searches recursively)."""
+    found: list[str] = []
+    for name, info in tree.items():
+        if not isinstance(info, dict):
+            continue
+        if info.get("type") == "file" and name in ENTRY_POINT_NAMES:
+            found.append(f"{root_path}/{name}")
+        elif info.get("type") == "directory":
+            children = info.get("children")
+            if isinstance(children, dict):
+                found.extend(find_entry_points(children, f"{root_path}/{name}"))
+    return found

onboarding_agent-0.1.0/onboarding_agent/knowledge_graph.py

@@ -0,0 +1,139 @@
+"""A simple file-backed knowledge graph for storing codebase entities and relationships.
+
+Entities are things like files, functions, classes, and modules.
+Relationships connect them: "file contains function", "file imports module", etc.
+
+The graph persists to a JSON file so it survives server restarts.
+"""
+
+import json
+from pathlib import Path
+
+
+class KnowledgeGraph:
+    """In-memory knowledge graph with JSON file persistence.
+
+    Each entity has:
+        - id: unique identifier (e.g., file path or "filepath::function_name")
+        - type: "file", "function", "class", "module"
+        - name: human-readable name
+        - metadata: dict of extra info (language, size, etc.)
+
+    Each relationship has:
+        - source: entity id
+        - target: entity id
+        - type: "contains", "imports", "calls", etc.
+    """
+
+    def __init__(self, storage_path: str | None = None):
+        self.entities: dict[str, dict] = {}
+        self.relationships: list[dict] = []
+        self.storage_path = Path(storage_path) if storage_path else None
+
+        if self.storage_path and self.storage_path.exists():
+            self._load()
+
+    def add_entity(self, entity_id: str, entity_type: str, name: str, metadata: dict | None = None) -> None:
+        """Add or update an entity in the graph."""
+        self.entities[entity_id] = {
+            "id": entity_id,
+            "type": entity_type,
+            "name": name,
+            "metadata": metadata or {},
+        }
+
+    def add_relationship(self, source: str, target: str, rel_type: str) -> None:
+        """Add a relationship between two entities. Skips duplicates."""
+        rel = {"source": source, "target": target, "type": rel_type}
+        if rel not in self.relationships:
+            self.relationships.append(rel)
+
+    def get_entity(self, entity_id: str) -> dict | None:
+        """Look up a single entity by id."""
+        return self.entities.get(entity_id)
+
+    def find_entities(self, entity_type: str | None = None, name_contains: str | None = None) -> list[dict]:
+        """Search entities by type and/or name substring."""
+        results = list(self.entities.values())
+        if entity_type:
+            results = [e for e in results if e["type"] == entity_type]
+        if name_contains:
+            query = name_contains.lower()
+            results = [e for e in results if query in e["name"].lower()]
+        return results
+
+    def find_relationships(
+        self,
+        source: str | None = None,
+        target: str | None = None,
+        rel_type: str | None = None,
+    ) -> list[dict]:
+        """Search relationships by source, target, and/or type."""
+        results = self.relationships
+        if source:
+            results = [r for r in results if r["source"] == source]
+        if target:
+            results = [r for r in results if r["target"] == target]
+        if rel_type:
+            results = [r for r in results if r["type"] == rel_type]
+        return results
+
+    def get_neighbors(self, entity_id: str) -> dict:
+        """Find all entities directly connected to the given entity."""
+        outgoing = self.find_relationships(source=entity_id)
+        incoming = self.find_relationships(target=entity_id)
+
+        connected_ids = set()
+        for r in outgoing:
+            connected_ids.add(r["target"])
+        for r in incoming:
+            connected_ids.add(r["source"])
+
+        return {
+            "entity": self.get_entity(entity_id),
+            "outgoing": outgoing,
+            "incoming": incoming,
+            "neighbors": [self.entities[eid] for eid in connected_ids if eid in self.entities],
+        }
+
+    def clear(self) -> None:
+        """Wipe the graph."""
+        self.entities.clear()
+        self.relationships.clear()
+
+    def save(self) -> None:
+        """Persist the graph to disk as JSON."""
+        if not self.storage_path:
+            return
+        self.storage_path.parent.mkdir(parents=True, exist_ok=True)
+        data = {"entities": self.entities, "relationships": self.relationships}
+        self.storage_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+    def _load(self) -> None:
+        """Load graph from disk."""
+        try:
+            data = json.loads(self.storage_path.read_text(encoding="utf-8"))
+            self.entities = data.get("entities", {})
+            self.relationships = data.get("relationships", [])
+        except (json.JSONDecodeError, KeyError):
+            self.entities = {}
+            self.relationships = []
+
+    def stats(self) -> dict:
+        """Return summary stats about the graph."""
+        type_counts: dict[str, int] = {}
+        for e in self.entities.values():
+            t = e["type"]
+            type_counts[t] = type_counts.get(t, 0) + 1
+
+        rel_type_counts: dict[str, int] = {}
+        for r in self.relationships:
+            t = r["type"]
+            rel_type_counts[t] = rel_type_counts.get(t, 0) + 1
+
+        return {
+            "total_entities": len(self.entities),
+            "total_relationships": len(self.relationships),
+            "entities_by_type": type_counts,
+            "relationships_by_type": rel_type_counts,
+        }