codebase-analyzer-mcp 1.0.0

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "codebase-analyzer-mcp",
+  "version": "1.0.0",
+  "description": "Multi-layer codebase analysis with Gemini AI. MCP server + Claude plugin with progressive disclosure.",
+  "type": "module",
+  "main": "dist/mcp/server.js",
+  "bin": {
+    "cba": "dist/cli/index.js",
+    "codebase-analyzer": "dist/cli/index.js"
+  },
+  "files": [
+    "dist/cli",
+    "dist/mcp",
+    "agents",
+    "commands",
+    "skills",
+    ".claude-plugin",
+    "CLAUDE.md",
+    "AGENTS.md"
+  ],
+  "scripts": {
+    "build": "bun run build:js && bun run build:bin",
+    "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 && echo '#!/usr/bin/env node' | cat - dist/cli/index.js > /tmp/cba.js && mv /tmp/cba.js dist/cli/index.js",
+    "build:bin": "bun build src/cli/index.ts --compile --outfile dist/cba",
+    "build:bin:all": "bun run build:bin:macos && bun run build:bin:linux && bun run build:bin:windows",
+    "build:bin:macos": "bun build src/cli/index.ts --compile --target=bun-darwin-arm64 --outfile dist/cba-macos-arm64 && bun build src/cli/index.ts --compile --target=bun-darwin-x64 --outfile dist/cba-macos-x64",
+    "build:bin:linux": "bun build src/cli/index.ts --compile --target=bun-linux-x64 --outfile dist/cba-linux-x64 && bun build src/cli/index.ts --compile --target=bun-linux-arm64 --outfile dist/cba-linux-arm64",
+    "build:bin:windows": "bun build src/cli/index.ts --compile --target=bun-windows-x64 --outfile dist/cba-windows-x64.exe",
+    "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",
+    "prepublishOnly": "bun run build:js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jkcorrea/codebase-analyzer-mcp.git"
+  },
+  "homepage": "https://github.com/jkcorrea/codebase-analyzer-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/jkcorrea/codebase-analyzer-mcp/issues"
+  },
+  "author": "jkcorrea",
+  "keywords": [
+    "mcp",
+    "gemini",
+    "codebase",
+    "analyzer",
+    "architecture",
+    "patterns",
+    "claude",
+    "ai",
+    "progressive-disclosure",
+    "tree-sitter"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@google/genai": "^1.38.0",
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "commander": "^14.0.2",
+    "glob": "^13.0.0",
+    "web-tree-sitter": "^0.26.3",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^25.1.0",
+    "typescript": "^5.9.3"
+  }
+}

package/skills/add-mcp-tool/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: add-mcp-tool
+description: This skill guides adding new MCP tools to the codebase-analyzer server. Use when extending the analyzer with new capabilities like new analysis types, query tools, or integrations.
+---
+
+# Adding MCP Tools
+
+## Quick Start
+
+To add a new MCP tool:
+
+1. Create `src/mcp/tools/your-tool.ts`
+2. Export from `src/mcp/tools/index.ts`
+3. Register in `src/mcp/server.ts`
+4. Add CLI command (optional)
+5. Run `pnpm build`
+
+## Step 1: Create Tool File
+
+Create `src/mcp/tools/your-tool.ts`:
+
+```typescript
+import { z } from "zod";
+import { resolveSource } from "../../core/repo-loader.js";
+
+// Schema for MCP tool parameters
+export const yourToolSchema = {
+  source: z
+    .string()
+    .describe("Local path or GitHub URL to the repository"),
+  yourParam: z
+    .string()
+    .optional()
+    .describe("Description of parameter"),
+};
+
+export type YourToolInput = {
+  source: string;
+  yourParam?: string;
+};
+
+// Execute function
+export async function executeYourTool(input: YourToolInput): Promise<object> {
+  const { source, yourParam } = input;
+
+  // Resolve source (handles GitHub URLs)
+  const { repoPath, cleanup } = await resolveSource(source);
+
+  try {
+    // Your implementation here
+    const result = {
+      // Your result structure
+    };
+
+    return result;
+  } finally {
+    // Clean up temp directory if GitHub clone
+    if (cleanup) await cleanup();
+  }
+}
+```
+
+## Step 2: Export from Index
+
+Add to `src/mcp/tools/index.ts`:
+
+```typescript
+export {
+  yourToolSchema,
+  executeYourTool,
+  type YourToolInput,
+} from "./your-tool.js";
+```
+
+## Step 3: Register in Server
+
+Add to `src/mcp/server.ts`:
+
+```typescript
+import {
+  yourToolSchema,
+  executeYourTool,
+} from "./tools/index.js";
+
+server.tool(
+  "your_tool_name",
+  "Description of what the tool does",
+  {
+    source: yourToolSchema.source,
+    yourParam: yourToolSchema.yourParam,
+  },
+  async ({ source, yourParam }) => {
+    try {
+      const result = await executeYourTool({ source, yourParam });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(result, null, 2),
+        }],
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        content: [{
+          type: "text" as const,
+          text: `Error: ${message}`,
+        }],
+        isError: true,
+      };
+    }
+  }
+);
+```
+
+## Step 4: Add CLI Command (Optional)
+
+Add to `src/cli/index.ts`:
+
+```typescript
+program
+  .command("your-command")
+  .description("What this command does")
+  .argument("<source>", "Local path or GitHub URL")
+  .option("-p, --param <value>", "Your parameter")
+  .action(async (source: string, options) => {
+    try {
+      const { executeYourTool } = await import("../mcp/tools/your-tool.js");
+      const result = await executeYourTool({
+        source,
+        yourParam: options.param,
+      });
+      console.log(JSON.stringify(result, null, 2));
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+  });
+```
+
+## Step 5: Add Types (If Needed)
+
+Add to `src/types.ts`:
+
+```typescript
+export interface YourToolResult {
+  // Define your result structure
+}
+```
+
+## Patterns to Follow
+
+### Use Existing Layers
+
+If your tool does analysis, consider using existing layers:
+
+```typescript
+import { surfaceAnalysis } from "../../core/layers/index.js";
+
+const surface = await surfaceAnalysis(repoPath, { exclude });
+```
+
+### Handle Partial Failures
+
+Don't throw on every error - capture and continue:
+
+```typescript
+const warnings: string[] = [];
+const failures: { area: string; error: string }[] = [];
+
+try {
+  // risky operation
+} catch (error) {
+  failures.push({
+    area: "operation-name",
+    error: error.message
+  });
+}
+
+return { result, warnings, failures };
+```
+
+### Respect Token Budget
+
+Check budget before expensive operations:
+
+```typescript
+if (estimatedTokens > tokenBudget) {
+  warnings.push(`Estimated tokens (${estimatedTokens}) exceeds budget`);
+}
+```
+
+## Testing
+
+After adding:
+
+```bash
+pnpm build
+pnpm cba your-command ./test-repo
+```
+
+## Checklist
+
+- [ ] Tool file created with schema and execute function
+- [ ] Exported from index.ts
+- [ ] Registered in server.ts
+- [ ] CLI command added (if applicable)
+- [ ] Types added to types.ts (if needed)
+- [ ] `pnpm build` passes
+- [ ] Tool works via MCP and CLI

package/skills/codebase-analysis/SKILL.md

@@ -0,0 +1,128 @@
+---
+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.
+---
+
+# 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
+
+### 1. Analyze Repository
+
+```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
+})
+```
+
+**Returns:**
+- `repositoryMap`: Files, languages, structure
+- `summary`: Architecture type, patterns, complexity
+- `sections`: Expandable areas for drill-down
+- `forAgent`: Quick summary and next steps
+
+### 2. Expand Section
+
+After analysis, drill into specific sections:
+
+```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({
+  source: ".",
+  patternTypes: ["singleton", "factory", "repository"]  // Optional filter
+})
+```
+
+**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
+
+Follow data through the system:
+
+```javascript
+mcp__codebase-analyzer__trace_dataflow({
+  source: ".",
+  from: "user login",             // Entry point
+  to: "database"                  // Optional destination
+})
+```
+
+### 5. Get Capabilities
+
+Check what's available:
+
+```javascript
+mcp__codebase-analyzer__get_analysis_capabilities()
+```
+
+## 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
+
+## References
+
+For detailed API documentation, see [references/api-reference.md](./references/api-reference.md).

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

@@ -0,0 +1,201 @@
+# API Reference
+
+Complete reference for codebase-analyzer MCP tools.
+
+## analyze_repo
+
+Full architectural analysis with progressive disclosure.
+
+### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `source` | string | Yes | - | Local path or GitHub URL |
+| `depth` | enum | No | "standard" | surface, standard, deep |
+| `focus` | string[] | No | - | Paths to focus on |
+| `exclude` | string[] | No | - | Glob patterns to exclude |
+| `tokenBudget` | number | No | 800000 | Max tokens for analysis |
+| `includeSemantics` | boolean | No | false | Enable LLM analysis |
+
+### Response
+
+```typescript
+{
+  analysisId: string;           // Use for expand_section
+  version: 2;
+  timestamp: string;
+  source: string;
+  depth: "surface" | "standard" | "deep";
+  tokenCost: number;
+  durationMs: number;
+
+  repositoryMap: {
+    name: string;
+    languages: Array<{
+      language: string;
+      fileCount: number;
+      percentage: number;
+      extensions: string[];
+    }>;
+    fileCount: number;
+    totalSize: number;
+    estimatedTokens: number;
+    entryPoints: string[];
+    structure: DirectoryNode;
+    readme?: string;
+  };
+
+  summary: {
+    architectureType: string;
+    primaryPatterns: string[];
+    techStack: string[];
+    complexity: "low" | "medium" | "high";
+  };
+
+  sections: Array<{
+    id: string;
+    title: string;
+    type: "module" | "pattern" | "datamodel" | "api" | "custom";
+    summary: string;
+    canExpand: boolean;
+    expansionCost: {
+      detail: number;
+      full: number;
+    };
+  }>;
+
+  forAgent: {
+    quickSummary: string;
+    keyInsights: string[];
+    suggestedNextSteps: string[];
+  };
+
+  warnings?: string[];
+  partialFailures?: Array<{
+    layer: string;
+    error: string;
+  }>;
+}
+```
+
+## expand_section
+
+Expand a section from previous analysis.
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `analysisId` | string | Yes | From analyze_repo result |
+| `sectionId` | string | Yes | Section ID to expand |
+| `depth` | enum | No | "detail" or "full" (default: detail) |
+
+### Response
+
+```typescript
+{
+  section: ExpandableSection | null;
+  error?: string;
+}
+```
+
+## find_patterns
+
+Detect patterns in codebase.
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `source` | string | Yes | Local path or GitHub URL |
+| `patternTypes` | string[] | No | Filter to specific patterns |
+
+### Available Pattern Types
+
+**Design Patterns:**
+- `singleton` - Single instance pattern
+- `factory` - Object creation abstraction
+- `observer` - Event subscription pattern
+- `strategy` - Interchangeable algorithms
+- `decorator` - Dynamic behavior extension
+- `adapter` - Interface compatibility
+- `facade` - Simplified interface
+- `repository` - Data access abstraction
+- `dependency-injection` - Inversion of control
+
+**Architectural Patterns:**
+- `event-driven` - Event-based architecture
+- `pub-sub` - Publish-subscribe messaging
+- `middleware` - Request processing chain
+- `mvc` - Model-View-Controller
+- `mvvm` - Model-View-ViewModel
+- `clean-architecture` - Dependency rule layers
+- `hexagonal` - Ports and adapters
+- `cqrs` - Command Query Responsibility Segregation
+- `saga` - Distributed transaction pattern
+
+### Response
+
+```typescript
+{
+  patterns: Array<{
+    name: string;
+    type: "architectural" | "design" | "anti-pattern";
+    confidence: number;        // 0-1
+    locations: string[];       // File paths
+    description: string;
+  }>;
+  summary: string;
+}
+```
+
+## trace_dataflow
+
+Trace data flow through the system.
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `source` | string | Yes | Local path or GitHub URL |
+| `from` | string | Yes | Entry point (function, file, or description) |
+| `to` | string | No | Destination to trace to |
+
+### Response
+
+```typescript
+{
+  entryPoint: string;
+  destination?: string;
+  steps: Array<{
+    location: string;
+    operation: string;
+    dataShape?: string;
+  }>;
+  securityObservations: string[];
+  recommendations: string[];
+}
+```
+
+## get_analysis_capabilities
+
+List available analysis options.
+
+### Parameters
+
+None.
+
+### Response
+
+```typescript
+{
+  layers: string[];
+  depths: string[];
+  supportedLanguages: string[];
+  tools: Array<{
+    name: string;
+    description: string;
+    parameters: string[];
+  }>;
+}
+```