codebase-analyzer-mcp 2.1.1 → 2.2.0

package/README.md

@@ -3,36 +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.
 
-## Quick Start
+## Install
 
-### Claude Code Plugin
-
-```bash
-claude /plugin install https://github.com/jaykaycodes/codebase-analyzer-mcp
-```
-
-Then use `/cba:analyze` to analyze a codebase, or just ask questions naturally.
-
-### MCP Server
-
-Add to `~/.mcp.json` (create if it doesn't exist):
-
-```json
-{
-  "mcpServers": {
-    "codebase-analyzer": {
-      "command": "npx",
-      "args": ["-y", "codebase-analyzer-mcp"]
-    }
-  }
-}
-```
-
-Restart Claude Code, then use the `analyze_repo` or `query_repo` tools.
-
-**Optional:** For semantic analysis with Gemini AI, get an API key at https://aistudio.google.com/apikey and add it:
+Add to your MCP config (`~/.mcp.json` for Claude Code):
 
 ```json
 {
@@ -41,25 +16,30 @@ Restart Claude Code, then use the `analyze_repo` or `query_repo` tools.
       "command": "npx",
       "args": ["-y", "codebase-analyzer-mcp"],
       "env": {
-        "GEMINI_API_KEY": "your_api_key"
+        "GEMINI_API_KEY": "your_key_here"
       }
     }
   }
 }
 ```
 
-### CLI
+Restart Claude Code. The tools will be available immediately.
 
-```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
-```
+**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
+
+## 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 |
 |-------|------|--------------|
@@ -67,48 +47,17 @@ 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.
+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
-
-### Command
-
-```
-/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 — just ask naturally.
-
----
-
-## Alternative Installation
-
-### Global Install
+## CLI
 
 ```bash
-npm install -g codebase-analyzer-mcp
-# Then use: cba analyze .
+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
 ```
 
 ## Development
@@ -117,9 +66,20 @@ npm install -g codebase-analyzer-mcp
 git clone https://github.com/jaykaycodes/codebase-analyzer-mcp.git
 cd codebase-analyzer-mcp
 bun install
-bun run dev           # Watch mode
-bun run build         # Build
-bun run cba analyze . # Test CLI
+bun run build
+```
+
+For local MCP testing, create `.mcp.json` at repo root:
+
+```json
+{
+  "mcpServers": {
+    "codebase-analyzer": {
+      "command": "node",
+      "args": ["dist/mcp/server.js"]
+    }
+  }
+}
 ```
 
 ## License

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.1",
-    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.1",
-  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.1",
-  "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.1"
-  },
-  "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.1",
-      "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,30 +0,0 @@
-{
-  "name": "codebase-analyzer",
-  "version": "2.1.1",
-  "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": "npx",
-      "args": [
-        "-y",
-        "codebase-analyzer-mcp"
-      ]
-    }
-  }
-}

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.