codebase-analyzer-mcp 2.0.4 → 2.1.0

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

@@ -1,209 +0,0 @@
----
-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/debugging-analysis/SKILL.md

@@ -1,213 +0,0 @@
----
-name: debugging-analysis
-description: This skill helps troubleshoot issues with codebase analysis - failed analyses, incorrect results, performance problems, and Gemini API errors. Use when analysis isn't working as expected.
----
-
-# Debugging Analysis Issues
-
-## Common Issues
-
-### 1. Analysis Fails Immediately
-
-**Symptom:** Error on startup, no analysis runs
-
-**Check:**
-```bash
-# Verify build
-pnpm build
-
-# Check for TypeScript errors
-pnpm tsc --noEmit
-
-# Test CLI works
-pnpm cba capabilities
-```
-
-**Common causes:**
-- TypeScript compilation errors
-- Missing dependencies (`pnpm install`)
-- Syntax error in recent changes
-
-### 2. Gemini API Errors
-
-**Symptom:** Semantic analysis fails with API error
-
-**Check:**
-```bash
-# Verify API key is set
-echo $GEMINI_API_KEY
-
-# Test with explicit key
-GEMINI_API_KEY=your-key pnpm cba analyze . -d deep -s
-```
-
-**Common causes:**
-- Missing `GEMINI_API_KEY` environment variable
-- Invalid or expired API key
-- Rate limiting (wait and retry)
-- Network issues
-
-**Fix:** Set API key:
-```bash
-export GEMINI_API_KEY=your-key-here
-```
-
-### 3. Analysis Returns Empty Results
-
-**Symptom:** Analysis completes but sections are empty
-
-**Check:**
-```bash
-# Run with verbose output
-pnpm cba analyze . -v
-
-# Check surface analysis
-pnpm cba analyze . -d surface
-```
-
-**Common causes:**
-- All files excluded by patterns
-- Repository is empty or only has ignored files
-- Focus filter matches nothing
-
-**Debug:**
-```typescript
-// In orchestrator.ts, check modulesToAnalyze
-console.log("Modules to analyze:", modulesToAnalyze);
-```
-
-### 4. Wrong Repository Name
-
-**Symptom:** Shows temp directory name instead of repo name
-
-**Check:** Ensure `sourceName` is passed through:
-1. `extractSourceName()` in analyze.ts or cli/index.ts
-2. Passed to `orchestrateAnalysis()` options
-3. Passed to `surfaceAnalysis()` options
-4. Used in `buildRepositoryMap()`
-
-### 5. Structural Analysis Slow
-
-**Symptom:** Takes too long on large repos
-
-**Check:**
-```bash
-# See batch progress
-pnpm cba analyze . -v
-```
-
-**Tune:**
-- Reduce `MAX_PARALLEL_STRUCTURAL` in orchestrator.ts
-- Use `--focus` to limit modules
-- Increase `--exclude` patterns
-
-### 6. Property Access Errors
-
-**Symptom:** `Cannot read properties of undefined`
-
-**Debug:**
-```typescript
-// Add defensive checks
-const value = result?.property?.nested ?? defaultValue;
-```
-
-**Common pattern:** Type definition doesn't match actual usage
-- Check `src/types.ts` for correct property names
-- Grep for usages of old property names
-
-## Debug Mode
-
-Enable verbose logging:
-
-```bash
-# CLI
-pnpm cba analyze . -v
-
-# Programmatic
-logger.setVerbose(true);
-```
-
-This shows:
-- Surface analysis progress
-- Structural batch progress
-- Semantic analysis calls
-- Timing information
-
-## Log Categories
-
-The logger uses categories for filtering:
-
-```typescript
-logger.surface("message");     // Surface layer
-logger.structural("message");  // Structural layer
-logger.semantic("message");    // Semantic layer
-logger.orchestrator("message"); // Orchestration
-logger.error("category", "message"); // Errors
-```
-
-## Testing Individual Layers
-
-### Surface Only
-```bash
-pnpm cba analyze . -d surface
-```
-
-### Structural Without Semantic
-```bash
-pnpm cba analyze . -d standard
-```
-
-### With Semantic
-```bash
-pnpm cba analyze . -d deep -s
-```
-
-## Inspecting Cache
-
-Analysis results are cached for `expand_section`:
-
-```typescript
-// In orchestrator.ts
-import { analysisCache } from "./cache.js";
-
-// Check cache
-const cached = analysisCache.getByAnalysisId(analysisId);
-console.log("Cached result:", cached);
-```
-
-## Gemini Retry Logic
-
-The Gemini client in `src/core/gemini.ts` has retry logic:
-
-```typescript
-// Check retry configuration
-const MAX_RETRIES = 3;
-const RETRY_DELAY = 1000;
-```
-
-If retries fail, check:
-- API quotas
-- Request payload size
-- Network connectivity
-
-## Performance Profiling
-
-For slow analyses:
-
-```bash
-# Time the analysis
-time pnpm cba analyze . -d standard -q
-
-# Profile with Node
-node --prof dist/cli/index.js analyze .
-```
-
-## Checklist for Issues
-
-- [ ] `pnpm build` succeeds
-- [ ] `pnpm cba capabilities` returns JSON
-- [ ] Surface analysis works (`-d surface`)
-- [ ] Standard analysis works (`-d standard`)
-- [ ] Semantic analysis works (if API key set)
-- [ ] Verbose mode shows progress (`-v`)
-- [ ] No TypeScript errors (`pnpm tsc --noEmit`)