codebase-analyzer-mcp 2.0.4 → 2.1.0

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "codebase-analyzer-mcp",
-  "version": "2.0.4",
+  "version": "2.1.0",
   "description": "Multi-layer codebase analysis with Gemini AI. MCP server + Claude plugin with progressive disclosure.",
   "type": "module",
   "main": "dist/mcp/server.js",
+  "packageManager": "bun@1.3.8",
   "bin": {
     "cba": "dist/cli/index.js",
     "codebase-analyzer": "dist/cli/index.js"
@@ -19,19 +20,15 @@
     "AGENTS.md"
   ],
   "scripts": {
-    "build": "bun run build:js",
-    "build:js": "bun build src/mcp/server.ts --outfile dist/mcp/server.js --target node && bun build src/cli/index.ts --outfile dist/cli/index.js --target node && node -e \"const fs=require('fs');const c=fs.readFileSync('dist/cli/index.js','utf8');fs.writeFileSync('dist/cli/index.js','#!/usr/bin/env node\\n'+c)\"",
+    "build": "bun scripts/build.ts",
     "dev": "bun --watch src/cli/index.ts",
     "start": "bun dist/mcp/server.js",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
     "cli": "bun src/cli/index.ts",
-    "cba": "bun src/cli/index.ts",
-    "version:sync": "bun scripts/sync-version.ts",
-    "release": "npm version patch && bun run version:sync",
-    "release:minor": "npm version minor && bun run version:sync",
-    "release:major": "npm version major && bun run version:sync",
-    "prepublishOnly": "bun run version:sync && bun run build:js"
+    "version": "bun scripts/sync-version.ts && git add .",
+    "postversion": "git push --follow-tags",
+    "prepublishOnly": "bun run build"
   },
   "repository": {
     "type": "git",

package/skills/codebase-analysis/SKILL.md

@@ -1,128 +1,61 @@
 ---
-name: codebase-analysis
-description: This skill teaches how to effectively analyze codebases using the codebase-analyzer MCP tools. Use when exploring new repositories, understanding architecture, detecting patterns, or tracing data flow.
+name: cba:codebase-analysis
+description: How to analyze codebases using the codebase-analyzer MCP tools. Use when exploring repositories, understanding architecture, or answering questions about code.
 ---
 
 # Codebase Analysis
 
 ## Quick Start
 
-Analyze any codebase with progressive disclosure:
-
 ```
 mcp__codebase-analyzer__analyze_repo(source: ".", depth: "standard")
 ```
 
-## Analysis Depths
-
-| Depth | Speed | Cost | Use When |
-|-------|-------|------|----------|
-| `surface` | Fast | Free | Quick overview, file structure |
-| `standard` | Medium | Low | Understanding architecture, symbols |
-| `deep` | Slow | High | Full semantic analysis with AI |
-
-**Rule of thumb:** Start with surface, upgrade if needed.
-
-## Core Tools
+## Primary Tools
 
-### 1. Analyze Repository
+### analyze_repo — Understand a codebase
 
 ```javascript
 mcp__codebase-analyzer__analyze_repo({
-  source: ".",                    // Local path or GitHub URL
-  depth: "standard",              // surface | standard | deep
-  focus: ["src/api"],             // Optional: focus areas
-  exclude: ["node_modules"],      // Optional: exclude patterns
-  tokenBudget: 800000,            // Optional: max tokens
-  includeSemantics: false         // Optional: enable AI analysis
+  source: ".",           // Local path or GitHub URL
+  depth: "standard",     // surface (fast/free) | standard (balanced) | deep (AI-powered)
+  focus: ["src/api"],    // Optional: limit to specific paths
 })
 ```
 
-**Returns:**
-- `repositoryMap`: Files, languages, structure
-- `summary`: Architecture type, patterns, complexity
-- `sections`: Expandable areas for drill-down
-- `forAgent`: Quick summary and next steps
+Returns `analysisId`, repository map, architecture summary, and expandable sections.
 
-### 2. Expand Section
-
-After analysis, drill into specific sections:
+### query_repo — Ask questions about code
 
 ```javascript
-mcp__codebase-analyzer__expand_section({
-  analysisId: "analysis_xxx",     // From analyze_repo result
-  sectionId: "module_src_api",    // Section ID to expand
-  depth: "detail"                 // detail | full
-})
-```
-
-### 3. Find Patterns
-
-Detect design and architecture patterns:
-
-```javascript
-mcp__codebase-analyzer__find_patterns({
+mcp__codebase-analyzer__query_repo({
   source: ".",
-  patternTypes: ["singleton", "factory", "repository"]  // Optional filter
+  question: "how is authentication handled?"
 })
 ```
 
-**Available patterns:** singleton, factory, observer, strategy, decorator, adapter, facade, repository, dependency-injection, event-driven, pub-sub, middleware, mvc, mvvm, clean-architecture, hexagonal, cqrs, saga
-
-### 4. Trace Dataflow
+Returns an answer with relevant files, confidence level, and follow-up suggestions. Reuses cached analysis for speed. Best with `GEMINI_API_KEY` set; falls back to keyword matching without it.
 
-Follow data through the system:
+## Example Workflow
 
 ```javascript
-mcp__codebase-analyzer__trace_dataflow({
-  source: ".",
-  from: "user login",             // Entry point
-  to: "database"                  // Optional destination
-})
-```
+// 1. Get the big picture
+const analysis = analyze_repo({ source: ".", depth: "surface" });
 
-### 5. Get Capabilities
+// 2. Ask a specific question (reuses the cached analysis)
+const answer = query_repo({ source: ".", question: "where is the API defined?" });
 
-Check what's available:
-
-```javascript
-mcp__codebase-analyzer__get_analysis_capabilities()
+// 3. Done — answer includes relevant files and suggested follow-ups
 ```
 
-## Workflow Patterns
-
-### New Codebase Orientation
-
-1. Run surface analysis
-2. Review repository map and entry points
-3. Expand interesting modules
-4. Run pattern detection if architecture unclear
-
-### Security Review
-
-1. Trace dataflow from external inputs
-2. Check for anti-patterns
-3. Map trust boundaries
-
-### Understanding Legacy Code
-
-1. Deep analysis with semantics
-2. Pattern detection for architecture
-3. Expand each major module
-
-## Guidelines
-
-**DO:**
-- Start cheap (surface), escalate if needed
-- Use `focus` to limit scope for large repos
-- Check `expansionCost` before expanding sections
-- Use `forAgent.suggestedNextSteps`
-
-**DON'T:**
-- Run deep analysis on first request
-- Ignore token budget warnings
-- Expand all sections at once
+## Power User Tools
 
-## References
+These additional tools are available for advanced use cases. See [references/api-reference.md](./references/api-reference.md) for full documentation.
 
-For detailed API documentation, see [references/api-reference.md](./references/api-reference.md).
+| Tool | What it does |
+|------|-------------|
+| `expand_section` | Drill into a specific section from `analyze_repo` results |
+| `read_files` | Read source files using an `analysisId` (no re-clone needed) |
+| `find_patterns` | Detect design patterns (singleton, factory, etc.) and anti-patterns |
+| `trace_dataflow` | Trace data flow from an entry point through the system |
+| `get_analysis_capabilities` | List supported languages, depths, and available tools |

package/skills/codebase-analysis/references/api-reference.md

@@ -21,7 +21,7 @@ Full architectural analysis with progressive disclosure.
 
 ```typescript
 {
-  analysisId: string;           // Use for expand_section
+  analysisId: string;           // Use for expand_section, read_files
   version: 2;
   timestamp: string;
   source: string;
@@ -177,6 +177,73 @@ Trace data flow through the system.
 }
 ```
 
+## read_files
+
+Read specific files from a previously analyzed repository. Uses the cached clone so you don't need to re-analyze or re-clone.
+
+### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `analysisId` | string | Yes | - | From analyze_repo or query_repo result |
+| `paths` | string[] | Yes | - | Relative file paths (min 1, max 20) |
+| `maxLines` | number | No | 500 | Max lines per file (max 2000) |
+
+### Response
+
+```typescript
+{
+  analysisId: string;
+  files: Array<{
+    path: string;
+    content?: string;          // File content (if readable)
+    lineCount?: number;        // Total lines in file
+    truncated?: boolean;       // True if content was truncated
+    error?: string;            // Error message (if not readable)
+  }>;
+}
+```
+
+### Notes
+
+- Paths must be relative to the repository root
+- Path traversal (../) is blocked for security
+- Works with both local repos and GitHub clones
+- Cache expires after 1 hour — re-run analyze_repo or query_repo if expired
+
+## query_repo
+
+Ask a question about a codebase and get an AI-powered answer with relevant file references.
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `source` | string | Yes | Local path or GitHub URL |
+| `question` | string | Yes | Question about the codebase |
+
+### Response
+
+```typescript
+{
+  answer: string;              // Detailed answer referencing code
+  relevantFiles: Array<{
+    path: string;              // Relative file path
+    reason: string;            // Why this file is relevant
+  }>;
+  confidence: "high" | "medium" | "low";
+  analysisId: string;          // Use for follow-up read_files
+  suggestedFollowUps: string[];
+}
+```
+
+### Notes
+
+- Reuses cached analysis when available (fast for repeated queries on same repo)
+- With `GEMINI_API_KEY`: AI-powered answer using structural analysis + file contents
+- Without `GEMINI_API_KEY`: keyword-matching fallback with pointers to relevant files
+- The `analysisId` enables follow-up `read_files` calls to examine code in detail
+
 ## get_analysis_capabilities
 
 List available analysis options.

package/commands/compare.md

@@ -1,66 +0,0 @@
----
-name: compare
-description: Compare how multiple repositories approach the same problem
-user-invocable: true
----
-
-# Compare Repositories
-
-Compare how different codebases approach the same problem or aspect.
-
-## Usage
-
-```
-/compare <repos...> --aspect <aspect>
-```
-
-**Arguments:**
-- `repos` - Two or more repository paths or URLs
-
-**Options:**
-- `--aspect <aspect>` - What to compare (required)
-
-## Examples
-
-```bash
-# Compare authentication approaches
-/compare ./app1 ./app2 --aspect authentication
-
-# Compare state management
-/compare https://github.com/user/repo1 https://github.com/user/repo2 --aspect "state management"
-
-# Compare API design
-/compare ./rest-api ./graphql-api --aspect "API design"
-
-# Compare error handling
-/compare ./project-a ./project-b ./project-c --aspect "error handling"
-```
-
-## Workflow
-
-1. **Analyze each repo** at surface level
-2. **Focus on aspect** specified
-3. **Compare approaches** side by side
-4. **Identify pros/cons** of each
-5. **Provide recommendation**
-
-## Implementation
-
-```javascript
-const repos = args.repos;
-const aspect = args.aspect;
-
-// Use MCP tool directly
-mcp__codebase-analyzer__compare_repos({
-  sources: repos,
-  aspect: aspect
-});
-```
-
-## Output
-
-Returns comparison with:
-- Approach summary for each repo
-- Pros and cons
-- Key files implementing the aspect
-- Recommendation for best approach

package/commands/explore.md

@@ -1,64 +0,0 @@
----
-name: explore
-description: Quick exploration of a codebase structure
-user-invocable: true
----
-
-# Explore Codebase
-
-Quick, lightweight exploration of a codebase - faster than full analysis.
-
-## Usage
-
-```
-/explore [source] [question]
-```
-
-**Arguments:**
-- `source` - Local path or GitHub URL (default: current directory)
-- `question` - Optional specific question about the codebase
-
-## Examples
-
-```bash
-# Quick overview of current directory
-/explore
-
-# Explore specific repo
-/explore https://github.com/user/repo
-
-# Ask specific question
-/explore . "where is authentication handled?"
-
-# Find specific functionality
-/explore "how does email sending work?"
-```
-
-## Workflow
-
-1. **Run surface analysis** (fast, no LLM cost)
-2. **Answer question** if provided
-3. **Present structure** and key files
-4. **Suggest areas** to explore further
-
-## Implementation
-
-```javascript
-const source = args.source || ".";
-const question = args.question;
-
-Task("codebase-explorer", {
-  prompt: question
-    ? `Explore ${source} and answer: ${question}`
-    : `Give me a quick overview of ${source}`
-});
-```
-
-## Output
-
-Returns quick overview with:
-- Tech stack and primary language
-- Directory structure with purposes
-- Key entry points
-- Answer to specific question (if asked)
-- Suggestions for deeper exploration

package/commands/patterns.md

@@ -1,75 +0,0 @@
----
-name: patterns
-description: Detect design and architecture patterns in a codebase
-user-invocable: true
----
-
-# Find Patterns
-
-Detect design patterns, architectural patterns, and anti-patterns in a codebase.
-
-## Usage
-
-```
-/patterns [source] [options]
-```
-
-**Arguments:**
-- `source` - Local path or GitHub URL (default: current directory)
-
-**Options:**
-- `--types <patterns>` - Specific patterns to look for
-- `--anti` - Focus on anti-patterns
-
-## Available Patterns
-
-**Design Patterns:**
-- singleton, factory, observer, strategy, decorator
-- adapter, facade, repository, dependency-injection
-
-**Architectural Patterns:**
-- event-driven, pub-sub, middleware, mvc, mvvm
-- clean-architecture, hexagonal, cqrs, saga
-
-## Examples
-
-```bash
-# Find all patterns in current directory
-/patterns
-
-# Look for specific patterns
-/patterns --types singleton,factory,repository
-
-# Find anti-patterns
-/patterns --anti
-
-# Analyze GitHub repo
-/patterns https://github.com/user/repo
-```
-
-## Workflow
-
-1. **Parse arguments** from user input
-2. **Run detection** using pattern-detective agent
-3. **Present findings** with confidence levels
-4. **Map locations** for each pattern
-
-## Implementation
-
-```javascript
-const source = args.source || ".";
-const types = args.types?.split(",");
-const antiPatterns = args.anti || false;
-
-Task("pattern-detective", {
-  prompt: `Find ${antiPatterns ? "anti-patterns" : "patterns"} in ${source}${types ? ` focusing on ${types.join(", ")}` : ""}`
-});
-```
-
-## Output
-
-Returns pattern analysis with:
-- Detected patterns with confidence scores
-- File locations for each pattern
-- Anti-pattern warnings
-- Recommendations for improvement

package/commands/trace.md

@@ -1,65 +0,0 @@
----
-name: trace
-description: Trace data flow through a codebase
-user-invocable: true
----
-
-# Trace Dataflow
-
-Trace how data flows from an entry point through the system.
-
-## Usage
-
-```
-/trace <from> [options]
-```
-
-**Arguments:**
-- `from` - Entry point (function name, file, or description)
-
-**Options:**
-- `--to <destination>` - Trace to specific destination
-- `--source <path>` - Repository path (default: current directory)
-
-## Examples
-
-```bash
-# Trace from user login
-/trace "user login"
-
-# Trace from specific function to database
-/trace processPayment --to database
-
-# Trace API endpoint
-/trace "POST /api/users"
-
-# Trace in specific repo
-/trace checkout --source ./ecommerce-app
-```
-
-## Workflow
-
-1. **Identify entry point** from user input
-2. **Run trace** using dataflow-tracer agent
-3. **Map transformations** at each step
-4. **Identify risks** and security concerns
-
-## Implementation
-
-```javascript
-const from = args.from;
-const to = args.to;
-const source = args.source || ".";
-
-Task("dataflow-tracer", {
-  prompt: `Trace data flow from "${from}"${to ? ` to "${to}"` : ""} in ${source}`
-});
-```
-
-## Output
-
-Returns dataflow analysis with:
-- Step-by-step trace through the system
-- Data transformations at each point
-- Security observations
-- Trust boundary crossings