codebase-analyzer-mcp 2.1.2 → 2.2.0

package/README.md

@@ -3,30 +3,11 @@
 [![npm](https://img.shields.io/npm/v/codebase-analyzer-mcp)](https://www.npmjs.com/package/codebase-analyzer-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Analyze any codebase with Gemini AI. Progressive disclosure keeps costs low - start with free structural analysis, drill into semantic details only when needed.
+MCP server for codebase analysis with Gemini AI. Progressive disclosure keeps costs low — start with free structural analysis, drill into semantic details only when needed.
 
 ## Install
 
-### Option 1: Claude Code Plugin (recommended)
-
-```bash
-claude /plugin install jaykaycodes/codebase-analyzer-mcp
-```
-
-This gives you MCP tools + agents + the `/cba:analyze` command. Just ask questions naturally.
-
-**Gemini API key (optional):** Enables semantic analysis, pattern detection, and dataflow tracing. Without it, you still get structural analysis.
-
-```bash
-mkdir -p ~/.config/codebase-analyzer
-echo '{"geminiApiKey":"YOUR_KEY"}' > ~/.config/codebase-analyzer/config.json
-```
-
-Get a free key at https://aistudio.google.com/apikey
-
-### Option 2: Standalone MCP Server
-
-Add to `~/.mcp.json`:
+Add to your MCP config (`~/.mcp.json` for Claude Code):
 
 ```json
 {
@@ -42,20 +23,23 @@ Add to `~/.mcp.json`:
 }
 ```
 
-Restart Claude Code, then use `analyze_repo`, `query_repo`, etc.
+Restart Claude Code. The tools will be available immediately.
 
-### Option 3: CLI
+**Gemini API key** is optional — enables semantic analysis, pattern detection, and dataflow tracing. Without it, you still get structural analysis. Get a free key at https://aistudio.google.com/apikey
 
-```bash
-npx codebase-analyzer-mcp analyze .                              # Standard analysis
-npx codebase-analyzer-mcp analyze . -d surface                   # Fast, free overview
-npx codebase-analyzer-mcp analyze . -d deep -s                   # Full semantic analysis
-npx codebase-analyzer-mcp query . "how is auth handled?"         # Ask a question
-npx codebase-analyzer-mcp patterns .                             # Find design patterns
-npx codebase-analyzer-mcp dataflow . "user login"                # Trace data flow
-```
+## Tools
+
+| Tool | Description | Requires Gemini |
+|------|-------------|:---:|
+| `analyze_repo` | Full analysis with progressive disclosure | No |
+| `query_repo` | Ask questions about a codebase | Optional |
+| `expand_section` | Drill into specific analysis sections | No |
+| `read_files` | Read source files from a cached analysis | No |
+| `find_patterns` | Detect design/architecture patterns | Yes |
+| `trace_dataflow` | Trace data flow through the system | Yes |
+| `get_analysis_capabilities` | List supported languages and options | No |
 
-## What It Does
+## Analysis Layers
 
 | Layer | Cost | What You Get |
 |-------|------|--------------|
@@ -63,38 +47,18 @@ npx codebase-analyzer-mcp dataflow . "user login"                # Trace data fl
 | **Structural** | Free | Symbols, imports, complexity (via tree-sitter) |
 | **Semantic** | Gemini | Architecture insights, pattern detection |
 
-Analysis results include expandable sections - you only pay for what you drill into.
-
-## MCP Tools
-
-| Tool | Description |
-|------|-------------|
-| `analyze_repo` | Full analysis with progressive disclosure |
-| `query_repo` | Ask questions about a codebase |
-| `expand_section` | Drill into specific sections |
-| `read_files` | Read source files from a cached analysis |
-| `find_patterns` | Detect design/architecture patterns |
-| `trace_dataflow` | Trace data flow through the system |
-| `get_analysis_capabilities` | List supported languages and analysis options |
-
-## Plugin Components
+Results include expandable sections — you only pay for what you drill into.
 
-### Command
+## CLI
 
+```bash
+npx codebase-analyzer-mcp analyze .                      # Standard analysis
+npx codebase-analyzer-mcp analyze . -d surface            # Fast, free overview
+npx codebase-analyzer-mcp analyze . -d deep -s            # Full semantic analysis
+npx codebase-analyzer-mcp query . "how is auth handled?"  # Ask a question
+npx codebase-analyzer-mcp patterns .                      # Find design patterns
+npx codebase-analyzer-mcp dataflow . "user login"         # Trace data flow
 ```
-/cba:analyze [source] [--depth surface|standard|deep] [--focus <paths>]
-```
-
-### Agents
-
-| Agent | Purpose |
-|-------|---------|
-| `architecture-analyzer` | Full codebase architecture analysis |
-| `pattern-detective` | Design/anti-pattern detection |
-| `dataflow-tracer` | Data flow tracing through systems |
-| `codebase-explorer` | Quick exploration and Q&A |
-
-Agents are routed automatically based on your question.
 
 ## Development
 
@@ -102,8 +66,7 @@ Agents are routed automatically based on your question.
 git clone https://github.com/jaykaycodes/codebase-analyzer-mcp.git
 cd codebase-analyzer-mcp
 bun install
-bun run build         # Build dist/
-bun run dev           # Watch mode
+bun run build
 ```
 
 For local MCP testing, create `.mcp.json` at repo root:

package/dist/cli/index.js

@@ -44251,8 +44251,8 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "codebase-analyzer-mcp",
-    version: "2.1.2",
-    description: "Multi-layer codebase analysis with Gemini AI. MCP server + Claude plugin with progressive disclosure.",
+    version: "2.2.0",
+    description: "Multi-layer codebase analysis MCP server with Gemini AI and progressive disclosure.",
     type: "module",
     main: "dist/mcp/server.js",
     packageManager: "bun@1.3.8",
@@ -44262,13 +44262,7 @@ var init_package = __esm(() => {
     },
     files: [
       "dist/cli",
-      "dist/mcp",
-      "agents",
-      "commands",
-      "skills",
-      ".claude-plugin",
-      "CLAUDE.md",
-      "AGENTS.md"
+      "dist/mcp"
     ],
     scripts: {
       build: "bun scripts/build.ts",
@@ -44277,7 +44271,7 @@ var init_package = __esm(() => {
       typecheck: "tsc --noEmit",
       test: "bun test",
       cli: "bun src/cli/index.ts",
-      version: "bun scripts/sync-version.ts && git add .",
+      version: "git add .",
       postversion: "git push --follow-tags",
       prepublishOnly: "bun run build"
     },

package/dist/mcp/server.js

@@ -71136,8 +71136,8 @@ function buildFallbackAnswer(question, analysisId, cached2, scored, fileContents
 // package.json
 var package_default = {
   name: "codebase-analyzer-mcp",
-  version: "2.1.2",
-  description: "Multi-layer codebase analysis with Gemini AI. MCP server + Claude plugin with progressive disclosure.",
+  version: "2.2.0",
+  description: "Multi-layer codebase analysis MCP server with Gemini AI and progressive disclosure.",
   type: "module",
   main: "dist/mcp/server.js",
   packageManager: "bun@1.3.8",
@@ -71147,13 +71147,7 @@ var package_default = {
   },
   files: [
     "dist/cli",
-    "dist/mcp",
-    "agents",
-    "commands",
-    "skills",
-    ".claude-plugin",
-    "CLAUDE.md",
-    "AGENTS.md"
+    "dist/mcp"
   ],
   scripts: {
     build: "bun scripts/build.ts",
@@ -71162,7 +71156,7 @@ var package_default = {
     typecheck: "tsc --noEmit",
     test: "bun test",
     cli: "bun src/cli/index.ts",
-    version: "bun scripts/sync-version.ts && git add .",
+    version: "git add .",
     postversion: "git push --follow-tags",
     prepublishOnly: "bun run build"
   },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "codebase-analyzer-mcp",
-  "version": "2.1.2",
-  "description": "Multi-layer codebase analysis with Gemini AI. MCP server + Claude plugin with progressive disclosure.",
+  "version": "2.2.0",
+  "description": "Multi-layer codebase analysis MCP server with Gemini AI and progressive disclosure.",
   "type": "module",
   "main": "dist/mcp/server.js",
   "packageManager": "bun@1.3.8",
@@ -11,13 +11,7 @@
   },
   "files": [
     "dist/cli",
-    "dist/mcp",
-    "agents",
-    "commands",
-    "skills",
-    ".claude-plugin",
-    "CLAUDE.md",
-    "AGENTS.md"
+    "dist/mcp"
   ],
   "scripts": {
     "build": "bun scripts/build.ts",
@@ -26,7 +20,7 @@
     "typecheck": "tsc --noEmit",
     "test": "bun test",
     "cli": "bun src/cli/index.ts",
-    "version": "bun scripts/sync-version.ts && git add .",
+    "version": "git add .",
     "postversion": "git push --follow-tags",
     "prepublishOnly": "bun run build"
   },

package/.claude-plugin/marketplace.json

@@ -1,34 +0,0 @@
-{
-  "name": "codebase-analyzer",
-  "owner": {
-    "name": "Jake Correa",
-    "url": "https://github.com/jaykaycodes"
-  },
-  "metadata": {
-    "description": "Multi-layer codebase analysis tools",
-    "version": "2.1.2"
-  },
-  "plugins": [
-    {
-      "name": "codebase-analyzer",
-      "description": "Multi-layer codebase analysis with Gemini AI. 4 agents, 1 command, 1 skill for architecture analysis, pattern detection, and dataflow tracing.",
-      "version": "2.1.2",
-      "author": {
-        "name": "Jake Correa",
-        "url": "https://github.com/jaykaycodes"
-      },
-      "homepage": "https://github.com/jaykaycodes/codebase-analyzer-mcp",
-      "tags": [
-        "codebase-analysis",
-        "architecture",
-        "patterns",
-        "gemini",
-        "mcp"
-      ],
-      "source": {
-        "source": "github",
-        "repo": "jaykaycodes/codebase-analyzer-mcp"
-      }
-    }
-  ]
-}

package/.claude-plugin/plugin.json

@@ -1,32 +0,0 @@
-{
-  "name": "codebase-analyzer",
-  "version": "2.1.2",
-  "description": "Multi-layer codebase analysis with Gemini AI. 4 agents, 1 command, 1 skill for architecture analysis, pattern detection, and dataflow tracing.",
-  "author": {
-    "name": "Jake Correa",
-    "url": "https://github.com/jaykaycodes"
-  },
-  "homepage": "https://github.com/jaykaycodes/codebase-analyzer-mcp",
-  "license": "MIT",
-  "keywords": [
-    "codebase-analysis",
-    "architecture",
-    "patterns",
-    "gemini",
-    "mcp",
-    "progressive-disclosure",
-    "tree-sitter"
-  ],
-  "mcpServers": {
-    "codebase-analyzer": {
-      "type": "stdio",
-      "command": "node",
-      "args": [
-        "${CLAUDE_PLUGIN_ROOT}/dist/mcp/server.js"
-      ],
-      "env": {
-        "GEMINI_API_KEY": "${GEMINI_API_KEY}"
-      }
-    }
-  }
-}

package/AGENTS.md

@@ -1,112 +0,0 @@
-# Agent Instructions
-
-This repository is both an MCP server and a Claude plugin for multi-layer codebase analysis.
-
-## Working Agreement
-
-- **Branching:** Feature branches for non-trivial changes
-- **Safety:** No destructive git commands, no deleting user data
-- **Testing:** Run `pnpm build` after changes - TypeScript errors break everything
-- **Architecture:** Respect layer separation (surface → structural → semantic)
-- **Counts:** When adding agents/commands/skills, update plugin.json description
-
-## Repository Structure
-
-```
-codebase-analyzer-mcp/
-├── .claude-plugin/
-│   └── plugin.json           # Plugin metadata
-├── agents/
-│   ├── analysis/             # Analysis agents
-│   └── research/             # Research agents
-├── commands/                 # Slash commands
-├── skills/                   # Context-loaded skills
-├── src/
-│   ├── mcp/                  # MCP server + tools
-│   ├── cli/                  # CLI interface
-│   └── core/                 # Analysis engine
-│       └── layers/           # Surface, structural, semantic
-└── docs/                     # Documentation
-```
-
-## Key Decisions
-
-| Decision | Rationale |
-|----------|-----------|
-| Gemini for semantic | Keep Claude context clean |
-| Tree-sitter for parsing | Fast AST without LLM |
-| Progressive disclosure | Minimize initial context cost |
-| Plugin + MCP | Both distribution paths |
-
-## Layer Responsibilities
-
-**Surface Layer** (`src/core/layers/surface.ts`)
-- File enumeration, language detection
-- Entry points, module identification
-- NO LLM calls
-
-**Structural Layer** (`src/core/layers/structural.ts`)
-- Tree-sitter parsing
-- Symbol extraction
-- Import/export mapping
-- NO LLM calls
-
-**Semantic Layer** (`src/core/layers/semantic.ts`)
-- Gemini API calls
-- Architecture detection
-- Pattern recognition
-- EXPENSIVE - opt-in only
-
-## Code Patterns
-
-**Partial failures:** Capture in `warnings[]` or `partialFailures[]`, don't throw
-
-**Token budget:** Check before expensive operations, warn if exceeded
-
-**Logging:** Use `logger` from `src/core/logger.ts`
-
-## Plugin Component Guidelines
-
-### Agents
-
-- Place in `agents/[category]/` by purpose
-- YAML frontmatter: `name`, `description` with examples
-- Description explains when to use the agent
-- Use haiku model for efficiency
-
-### Commands
-
-- Place in `commands/`
-- Set `user-invocable: true`
-- Document usage, options, examples
-- Show workflow and implementation
-
-### Skills
-
-- Directory in `skills/[name]/`
-- SKILL.md is entry point (<500 lines)
-- references/ for detailed docs
-- Description in third person
-
-## Updating Plugin Counts
-
-After adding/removing components:
-
-```bash
-# Count components
-ls agents/**/*.md | wc -l    # agents
-ls commands/*.md | wc -l      # commands
-ls -d skills/*/ | wc -l       # skills
-
-# Update description in .claude-plugin/plugin.json
-```
-
-Format: `"X agents, Y commands, Z skills"`
-
-## Testing Checklist
-
-- [ ] `pnpm build` succeeds
-- [ ] `pnpm cba capabilities` returns JSON
-- [ ] `pnpm cba analyze . -d surface -q` works
-- [ ] New agent/command/skill follows patterns
-- [ ] plugin.json counts match actual files

package/CLAUDE.md

@@ -1,160 +0,0 @@
-# Codebase Analyzer MCP
-
-Multi-layer codebase analysis with Gemini AI. Both an MCP server and a Claude plugin.
-
-## Philosophy
-
-**Progressive Disclosure**: Start cheap (surface), reveal more on demand. Don't analyze everything upfront.
-
-**Budget Awareness**: Track tokens. Surface is free, structural is cheap, semantic is expensive.
-
-**Graceful Degradation**: Partial failures don't break analysis. Capture warnings, continue.
-
-**Agent-First Design**: Output structured for AI agents - expandable sections, cost estimates, next steps.
-
-## Quick Start
-
-```bash
-pnpm install && pnpm build
-```
-
-## Plugin Components
-
-| Component | Count | Purpose |
-|-----------|-------|---------|
-| Agents | 4 | Specialized analysis tasks |
-| Commands | 1 | User-invocable actions |
-| Skills | 1 | Context-loaded guidance |
-| MCP Server | 1 | Tool interface for Claude |
-
-### Agents
-
-| Agent | Purpose |
-|-------|---------|
-| `architecture-analyzer` | Full codebase architecture analysis |
-| `pattern-detective` | Design/anti-pattern detection |
-| `dataflow-tracer` | Data flow tracing through systems |
-| `codebase-explorer` | Quick exploration and Q&A |
-
-### Commands
-
-| Command | Usage |
-|---------|-------|
-| `/cba:analyze` | Analyze a codebase |
-
-### Skills
-
-| Skill | Purpose |
-|-------|---------|
-| `cba:codebase-analysis` | How to use the MCP tools |
-
-## Architecture
-
-See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for system design.
-
-## Key Paths
-
-| Path | Purpose |
-|------|---------|
-| `.claude-plugin/plugin.json` | Plugin metadata |
-| `agents/` | Agent definitions |
-| `commands/` | Slash commands |
-| `skills/` | Context-loaded skills |
-| `src/mcp/server.ts` | MCP server entry |
-| `src/mcp/tools/` | MCP tool definitions |
-| `src/cli/index.ts` | CLI interface |
-| `src/core/orchestrator.ts` | Analysis coordination |
-| `src/core/layers/` | Analysis layers |
-
-## MCP Tools
-
-| Tool | Purpose | Cost |
-|------|---------|------|
-| `analyze_repo` | Full analysis with expandable sections | Varies |
-| `query_repo` | Ask questions about a codebase | Medium |
-| `expand_section` | Drill into specific sections | Low |
-| `read_files` | Read source files from cached analysis | None |
-| `find_patterns` | Pattern detection | Medium |
-| `trace_dataflow` | Data flow tracing | Medium |
-| `get_analysis_capabilities` | List capabilities | None |
-
-## Analysis Depth
-
-| Depth | What It Does | LLM Cost |
-|-------|--------------|----------|
-| `surface` | File enumeration, languages, entry points | ~0 |
-| `standard` | + structural analysis with Tree-sitter | Low |
-| `deep` | + semantic analysis with Gemini | High |
-
-## Adding Components
-
-### Adding a New MCP Tool
-
-1. Create `src/mcp/tools/your-tool.ts` (schema + execute)
-2. Export from `src/mcp/tools/index.ts`
-3. Register in `src/mcp/server.ts`
-4. Add CLI command in `src/cli/index.ts` (optional)
-5. `pnpm build`
-
-### Adding an Agent
-
-1. Create `agents/[category]/your-agent.md`
-2. Use YAML frontmatter: name, description
-3. Include examples in description
-4. Update plugin.json description count
-
-### Adding a Command
-
-1. Create `commands/your-command.md`
-2. Set `user-invocable: true` in frontmatter
-3. Document usage, examples, workflow
-4. Update plugin.json description count
-
-### Adding a Skill
-
-1. Create `skills/your-skill/SKILL.md`
-2. Add references/ for detailed docs
-3. Keep SKILL.md under 500 lines
-4. Update plugin.json description count
-
-## Environment
-
-```bash
-GEMINI_API_KEY=...  # Required for semantic analysis
-```
-
-## Releasing
-
-Uses npm trusted publishing (OIDC) - no NPM_TOKEN secret needed.
-
-1. Bump version: `npm version patch` (or minor/major)
-2. Sync version to plugin.json: `bun run version:sync`
-3. Push with tags: `git push && git push --tags`
-
-CI automatically publishes to npm when version changes on main.
-
-**Trusted publisher config:** npm package must be linked to `jaykaycodes/codebase-analyzer-mcp` in npm settings (Settings → Publishing access → Add GitHub Actions as publisher).
-
-**Requirements:** npm >= 11.5.1 (CI updates npm automatically). See [npm trusted publishing docs](https://docs.npmjs.com/trusted-publishers/).
-
-## Key Learnings
-
-_This section captures learnings as we work on this repository._
-
-### 2026-01-28: Source name extraction for GitHub URLs
-
-When analyzing GitHub repos, temp clone directory name (cba-XXXXX) was shown instead of repo name. Fixed by extracting owner/repo from GitHub URLs before resolving to local path and passing `sourceName` through analysis chain.
-
-**Pattern:** Preserve user-facing identifiers separately from internal paths.
-
-### 2026-01-28: Property name consistency between types and usage
-
-Multiple bugs from accessing wrong property names (l.name vs l.language, totalFiles vs fileCount).
-
-**Pattern:** When adding new types, grep for all usages of old patterns and update together.
-
-### 2026-01-28: Plugin architecture for agentic development
-
-Adopted compound-engineering patterns: agents for specialized tasks, commands for user actions, skills for context-loaded guidance. Makes the repo self-documenting for Claude.
-
-**Pattern:** Structure repos as plugins even for MCP servers - the documentation patterns apply.

package/agents/analysis/architecture-analyzer.md

@@ -1,115 +0,0 @@
----
-name: cba:architecture-analyzer
-description: "Use this agent when you need to understand a codebase's architecture, identify patterns, and get a high-level overview. This agent uses the codebase-analyzer MCP to perform multi-layer analysis with progressive disclosure - starting cheap and drilling down as needed.\n\n<example>Context: User wants to understand a new codebase.\nuser: \"Help me understand the architecture of this repo\"\nassistant: \"I'll use the architecture-analyzer agent to analyze the codebase structure and patterns.\"\n<commentary>Since the user wants architectural understanding, use architecture-analyzer to run progressive analysis.</commentary></example>\n\n<example>Context: User is evaluating a library.\nuser: \"What patterns does this library use?\"\nassistant: \"Let me use the architecture-analyzer agent to detect patterns in this codebase.\"\n<commentary>Pattern detection is a core capability of architecture-analyzer.</commentary></example>"
-model: haiku
----
-
-You are an expert software architect specializing in codebase analysis. Your mission is to help users understand codebases quickly and thoroughly using the codebase-analyzer MCP tools.
-
-## Analysis Strategy
-
-### Step 1: Surface Analysis (Always Start Here)
-
-Run a surface-level analysis first - it's fast and free:
-
-```
-mcp__codebase-analyzer__analyze_repo(source: "<path>", depth: "surface")
-```
-
-This gives you:
-- Repository map (files, languages, structure)
-- Entry points
-- Module identification
-- Complexity score
-
-### Step 2: Evaluate Complexity
-
-Based on surface analysis:
-- **Low complexity (<30)**: Surface may be enough
-- **Medium complexity (30-60)**: Standard depth recommended
-- **High complexity (>60)**: Consider deep analysis with semantics
-
-### Step 3: Standard Analysis (If Needed)
-
-For structural understanding:
-
-```
-mcp__codebase-analyzer__analyze_repo(source: "<path>", depth: "standard")
-```
-
-Adds:
-- Symbol extraction (functions, classes, types)
-- Import/export relationships
-- Complexity metrics per module
-
-### Step 4: Expand Sections (On Demand)
-
-Don't expand everything. Ask the user what they want to explore:
-
-```
-mcp__codebase-analyzer__expand_section(analysisId: "<id>", sectionId: "<section>", depth: "detail")
-```
-
-### Step 5: Pattern Detection (If Relevant)
-
-For specific pattern questions:
-
-```
-mcp__codebase-analyzer__find_patterns(source: "<path>", patternTypes: ["singleton", "factory", "repository"])
-```
-
-### Step 6: Deep Semantic Analysis (Expensive - Ask First)
-
-Only use with explicit permission:
-
-```
-mcp__codebase-analyzer__analyze_repo(source: "<path>", depth: "deep", includeSemantics: true)
-```
-
-This uses Gemini API and costs tokens.
-
-## Output Format
-
-Structure your findings as:
-
-```markdown
-## Architecture Overview
-
-**Type:** [monolith/microservices/serverless/etc]
-**Complexity:** [low/medium/high] (score: X)
-**Primary Language:** [language] (X%)
-
-## Key Patterns
-
-1. **[Pattern Name]** - [where it's used]
-2. ...
-
-## Module Structure
-
-- `[module]` - [purpose]
-- ...
-
-## Entry Points
-
-- `[file]` - [what it does]
-
-## Recommendations
-
-- [What to explore next]
-- [Potential concerns]
-```
-
-## Guidelines
-
-**DO:**
-- Start with surface analysis (free)
-- Let complexity guide depth decisions
-- Ask before running expensive operations
-- Present expandable sections for user choice
-- Focus on what the user asked about
-
-**DON'T:**
-- Run deep analysis without asking
-- Expand all sections upfront
-- Dump raw JSON to user
-- Ignore the token budget