codebase-analyzer-mcp 1.0.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,31 @@
+{
+  "name": "jkcorrea-plugins",
+  "owner": {
+    "name": "jkcorrea",
+    "url": "https://github.com/jkcorrea"
+  },
+  "metadata": {
+    "description": "AI-powered development tools by jkcorrea",
+    "version": "1.0.0"
+  },
+  "plugins": [
+    {
+      "name": "codebase-analyzer",
+      "description": "Multi-layer codebase analysis with Gemini AI. 4 agents, 5 commands, 3 skills for architecture analysis, pattern detection, and dataflow tracing.",
+      "version": "1.0.0",
+      "author": {
+        "name": "jkcorrea",
+        "url": "https://github.com/jkcorrea"
+      },
+      "homepage": "https://github.com/jkcorrea/codebase-analyzer-mcp",
+      "tags": [
+        "codebase-analysis",
+        "architecture",
+        "patterns",
+        "gemini",
+        "mcp"
+      ],
+      "source": "."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,29 @@
+{
+  "name": "codebase-analyzer",
+  "version": "1.0.0",
+  "description": "Multi-layer codebase analysis with Gemini AI. 4 agents, 5 commands, 3 skills for architecture analysis, pattern detection, and dataflow tracing.",
+  "author": {
+    "name": "jkcorrea",
+    "url": "https://github.com/jkcorrea"
+  },
+  "homepage": "https://github.com/jkcorrea/codebase-analyzer-mcp",
+  "license": "MIT",
+  "keywords": [
+    "codebase-analysis",
+    "architecture",
+    "patterns",
+    "gemini",
+    "mcp",
+    "progressive-disclosure",
+    "tree-sitter"
+  ],
+  "mcpServers": {
+    "codebase-analyzer": {
+      "command": "node",
+      "args": [
+        "dist/mcp/server.js"
+      ],
+      "cwd": "."
+    }
+  }
+}

package/AGENTS.md

@@ -0,0 +1,112 @@
+# 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

@@ -0,0 +1,150 @@
+# 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 | 5 | User-invocable actions |
+| Skills | 3 | 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 |
+|---------|-------|
+| `/analyze` | Analyze a codebase |
+| `/patterns` | Find design patterns |
+| `/trace` | Trace data flow |
+| `/explore` | Quick exploration |
+| `/compare` | Compare repositories |
+
+### Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `codebase-analysis` | How to use the MCP tools |
+| `add-mcp-tool` | Guide for adding new tools |
+| `debugging-analysis` | Troubleshooting analysis issues |
+
+## 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 |
+| `expand_section` | Drill into specific sections | Low |
+| `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
+```
+
+## 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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jkcorrea
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,252 @@
+# Codebase Analyzer MCP
+
+[![Claude Plugin](https://img.shields.io/badge/Claude-Plugin-blueviolet)](https://github.com/jkcorrea/codebase-analyzer-mcp)
+[![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)
+
+Multi-layer codebase analysis with Gemini AI. Both an MCP server for Claude and a standalone CLI.
+
+**Features:**
+- Progressive disclosure - start cheap, drill down as needed
+- Tree-sitter structural analysis (no LLM cost)
+- Gemini semantic analysis (opt-in)
+- Pattern detection, dataflow tracing
+- Agent-optimized output
+- **Standalone binary - no Node/Bun required**
+
+## Installation
+
+### Standalone Binary (Recommended)
+
+Download the binary for your platform from [Releases](https://github.com/jkcorrea/codebase-analyzer-mcp/releases):
+
+```bash
+# macOS (Apple Silicon)
+curl -L https://github.com/jkcorrea/codebase-analyzer-mcp/releases/latest/download/cba-macos-arm64 -o cba
+chmod +x cba
+sudo mv cba /usr/local/bin/
+
+# macOS (Intel)
+curl -L https://github.com/jkcorrea/codebase-analyzer-mcp/releases/latest/download/cba-macos-x64 -o cba
+chmod +x cba
+sudo mv cba /usr/local/bin/
+
+# Linux (x64)
+curl -L https://github.com/jkcorrea/codebase-analyzer-mcp/releases/latest/download/cba-linux-x64 -o cba
+chmod +x cba
+sudo mv cba /usr/local/bin/
+
+# Linux (ARM64)
+curl -L https://github.com/jkcorrea/codebase-analyzer-mcp/releases/latest/download/cba-linux-arm64 -o cba
+chmod +x cba
+sudo mv cba /usr/local/bin/
+```
+
+### npm
+
+```bash
+npm install -g codebase-analyzer-mcp
+```
+
+### From Source (with Bun)
+
+```bash
+git clone https://github.com/jkcorrea/codebase-analyzer-mcp.git
+cd codebase-analyzer-mcp
+bun install && bun run build
+```
+
+## Configuration
+
+Set your Gemini API key (required for semantic analysis):
+
+```bash
+export GEMINI_API_KEY=your_api_key_here
+```
+
+Get a key at https://aistudio.google.com/apikey
+
+## CLI Usage
+
+```bash
+# Quick overview (surface depth - fast, free)
+cba analyze . -d surface
+
+# Standard analysis (includes structural)
+cba analyze .
+
+# Deep analysis with semantics (uses Gemini)
+cba analyze . -d deep -s
+
+# Analyze GitHub repo
+cba analyze https://github.com/user/repo
+
+# Focus on specific areas
+cba analyze . --focus src/api
+
+# Pattern detection
+cba patterns .
+cba patterns . --types singleton,factory,repository
+
+# Data flow tracing
+cba dataflow . "user login"
+cba dataflow . "payment" --to database
+
+# Show capabilities
+cba capabilities
+```
+
+### Analysis Depths
+
+| Depth | Speed | LLM Cost | Includes |
+|-------|-------|----------|----------|
+| `surface` | Fast | ~0 | Files, languages, entry points, modules |
+| `standard` | Medium | Low | + symbols, imports, complexity metrics |
+| `deep` | Slow | High | + semantic analysis, architecture insights |
+
+## MCP Server Usage
+
+Add to Claude Code settings (`~/.claude/settings.json`):
+
+### Using standalone binary (recommended)
+
+```json
+{
+  "mcpServers": {
+    "codebase-analyzer": {
+      "command": "cba",
+      "args": ["--mcp"],
+      "env": {
+        "GEMINI_API_KEY": "your_api_key"
+      }
+    }
+  }
+}
+```
+
+### Using npx (no install)
+
+```json
+{
+  "mcpServers": {
+    "codebase-analyzer": {
+      "command": "npx",
+      "args": ["-y", "codebase-analyzer-mcp", "--mcp"],
+      "env": {
+        "GEMINI_API_KEY": "your_api_key"
+      }
+    }
+  }
+}
+```
+
+### Using global npm install
+
+```bash
+npm install -g codebase-analyzer-mcp
+```
+
+```json
+{
+  "mcpServers": {
+    "codebase-analyzer": {
+      "command": "cba",
+      "args": ["--mcp"],
+      "env": {
+        "GEMINI_API_KEY": "your_api_key"
+      }
+    }
+  }
+}
+```
+
+### MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `analyze_repo` | Full analysis with progressive disclosure |
+| `expand_section` | Drill into specific sections |
+| `find_patterns` | Detect design/architecture patterns |
+| `trace_dataflow` | Trace data flow through the system |
+| `get_analysis_capabilities` | List available options |
+
+## Output Structure
+
+```json
+{
+  "analysisId": "analysis_xxx",
+  "repositoryMap": {
+    "name": "repo-name",
+    "languages": [...],
+    "fileCount": 42,
+    "entryPoints": [...]
+  },
+  "summary": {
+    "architectureType": "serverless",
+    "primaryPatterns": ["repository", "factory"],
+    "complexity": "medium"
+  },
+  "sections": [
+    {
+      "id": "module_src_api",
+      "title": "API Module",
+      "summary": "...",
+      "canExpand": true,
+      "expansionCost": { "detail": 500, "full": 2000 }
+    }
+  ],
+  "forAgent": {
+    "quickSummary": "...",
+    "keyInsights": [...],
+    "suggestedNextSteps": [...]
+  }
+}
+```
+
+## Claude Plugin
+
+This package also works as a Claude Code plugin with agents, commands, and skills.
+
+### Install as Plugin
+
+```bash
+# Direct install
+claude /plugin install https://github.com/jkcorrea/codebase-analyzer-mcp
+
+# Or add as marketplace first (if you want to browse/manage multiple plugins)
+claude /plugin marketplace add https://github.com/jkcorrea/codebase-analyzer-mcp
+claude /plugin install codebase-analyzer
+```
+
+### Plugin Commands
+
+| Command | Description |
+|---------|-------------|
+| `/analyze` | Analyze a codebase |
+| `/patterns` | Find design patterns |
+| `/trace` | Trace data flow |
+| `/explore` | Quick exploration |
+| `/compare` | Compare repositories |
+
+### Plugin Agents
+
+| Agent | Purpose |
+|-------|---------|
+| `architecture-analyzer` | Full architecture analysis |
+| `pattern-detective` | Pattern detection |
+| `dataflow-tracer` | Data flow tracing |
+| `codebase-explorer` | Quick exploration |
+
+## Development
+
+```bash
+bun install
+bun run dev           # Watch mode
+bun run build         # Build TS + binary
+bun run build:bin:all # Build all platform binaries
+bun run cba ...       # Run CLI
+```
+
+## License
+
+MIT