second-opinion-mcp 0.1.0

package/dist/tools/review.js

@@ -0,0 +1,199 @@
+import * as fs from "fs";
+import * as path from "path";
+import { z } from "zod";
+import { loadConfig, loadReviewInstructions } from "../config.js";
+import { bundleContext, formatBundleAsMarkdown, } from "../context/index.js";
+import { isWithinProject } from "../context/imports.js";
+import { createProvider } from "../providers/index.js";
+import { writeReview, writeEgressManifest, deriveSessionName, } from "../output/writer.js";
+/**
+ * Validate that a project path is safe to use
+ */
+function validateProjectPath(projectPath) {
+    // Must be absolute
+    if (!path.isAbsolute(projectPath)) {
+        throw new Error(`projectPath must be absolute, got: ${projectPath}`);
+    }
+    // Normalize and check for traversal
+    const normalized = path.normalize(projectPath);
+    if (normalized !== projectPath && projectPath.includes("..")) {
+        throw new Error(`projectPath contains path traversal: ${projectPath}`);
+    }
+    // Must exist
+    if (!fs.existsSync(normalized)) {
+        throw new Error(`projectPath does not exist: ${normalized}`);
+    }
+    // Must be a directory
+    const stat = fs.statSync(normalized);
+    if (!stat.isDirectory()) {
+        throw new Error(`projectPath is not a directory: ${normalized}`);
+    }
+}
+export const SecondOpinionInputSchema = z.object({
+    // Required
+    provider: z.enum(["gemini", "openai"]).describe("Which LLM to use for the review"),
+    projectPath: z.string().describe("Absolute path to the project being reviewed"),
+    // Task specification
+    task: z
+        .string()
+        .optional()
+        .describe("The task or prompt for the LLM to accomplish. When omitted, defaults to code review."),
+    // Context options
+    sessionId: z
+        .string()
+        .optional()
+        .describe("Claude Code session ID (defaults to most recent)"),
+    includeFiles: z
+        .array(z.string())
+        .optional()
+        .describe("Additional files or folders to include (supports ~ and relative paths)"),
+    allowExternalFiles: z
+        .boolean()
+        .default(false)
+        .describe("Allow including files outside the project directory. Required when includeFiles contains paths outside the project. Use with caution as these files will be sent to the external LLM."),
+    includeConversation: z
+        .boolean()
+        .default(true)
+        .describe("Include conversation context from Claude session"),
+    // Smart context options
+    includeDependencies: z
+        .boolean()
+        .default(true)
+        .describe("Include files imported by modified files"),
+    includeDependents: z
+        .boolean()
+        .default(true)
+        .describe("Include files that import modified files"),
+    includeTests: z
+        .boolean()
+        .default(true)
+        .describe("Include corresponding test files"),
+    includeTypes: z
+        .boolean()
+        .default(true)
+        .describe("Include referenced type definitions"),
+    maxTokens: z
+        .number()
+        .default(100000)
+        .describe("Maximum tokens for context"),
+    // Output options
+    sessionName: z
+        .string()
+        .optional()
+        .describe("Name for this output (used in filename)"),
+    customPrompt: z
+        .string()
+        .optional()
+        .describe("Additional instructions (deprecated: use task instead)"),
+    focusAreas: z
+        .array(z.string())
+        .optional()
+        .describe("Specific areas to focus on (for code reviews)"),
+    dryRun: z
+        .boolean()
+        .default(false)
+        .describe("If true, return a preview of what would be sent without calling the external API. Use this for confirmation before sending files to external providers."),
+});
+/**
+ * Build egress summary from bundle, categorizing files as project vs external
+ */
+function buildEgressSummary(bundle, projectPath, provider) {
+    const projectFilePaths = [];
+    const externalFilePaths = [];
+    for (const file of bundle.files) {
+        if (isWithinProject(file.path, projectPath)) {
+            projectFilePaths.push(file.path);
+        }
+        else {
+            externalFilePaths.push(file.path);
+        }
+    }
+    // Get unique parent directories of external files
+    const externalLocations = [
+        ...new Set(externalFilePaths.map((p) => path.dirname(p))),
+    ];
+    return {
+        projectFilesSent: projectFilePaths.length,
+        projectFilePaths,
+        externalFilesSent: externalFilePaths.length,
+        externalFilePaths,
+        externalLocations,
+        blockedFiles: bundle.omittedFiles.map((f) => ({
+            path: f.path,
+            reason: f.reason,
+        })),
+        provider,
+    };
+}
+export async function executeReview(input) {
+    // Validate project path before proceeding
+    validateProjectPath(input.projectPath);
+    const config = loadConfig();
+    // 1. Bundle the context
+    const bundle = await bundleContext({
+        projectPath: input.projectPath,
+        sessionId: input.sessionId,
+        includeFiles: input.includeFiles,
+        allowExternalFiles: input.allowExternalFiles,
+        includeConversation: input.includeConversation,
+        includeDependencies: input.includeDependencies,
+        includeDependents: input.includeDependents,
+        includeTests: input.includeTests,
+        includeTypes: input.includeTypes,
+        maxTokens: input.maxTokens,
+    });
+    // Build egress summary (used for both dry run and actual execution)
+    const summary = buildEgressSummary(bundle, input.projectPath, input.provider);
+    // 2. If dry run, return preview without calling external API
+    if (input.dryRun) {
+        return {
+            dryRun: true,
+            provider: input.provider,
+            summary,
+            totalTokens: bundle.totalTokens,
+        };
+    }
+    // 3. Format as markdown
+    const contextMarkdown = formatBundleAsMarkdown(bundle, input.projectPath);
+    // 4. Load review instructions
+    const instructions = loadReviewInstructions(input.projectPath);
+    // 5. Create provider and execute task
+    const provider = createProvider(input.provider, config);
+    const response = await provider.review({
+        instructions,
+        context: contextMarkdown,
+        task: input.task,
+        focusAreas: input.focusAreas,
+        customPrompt: input.customPrompt,
+    });
+    // 6. Derive session name if not provided
+    const sessionName = input.sessionName ||
+        deriveSessionName(bundle.conversationContext, "code-review");
+    // 7. Write the output files
+    const timestamp = new Date().toISOString();
+    const metadata = {
+        sessionName,
+        provider: input.provider,
+        model: response.model,
+        timestamp,
+        filesReviewed: bundle.files.map((f) => f.path),
+        tokensUsed: response.tokensUsed,
+        task: input.task,
+    };
+    const reviewFile = writeReview(input.projectPath, config.reviewsDir, metadata, response.review);
+    // 8. Write egress manifest for audit trail
+    const egressManifestFile = writeEgressManifest(input.projectPath, config.reviewsDir, metadata, summary);
+    return {
+        dryRun: false,
+        review: response.review,
+        reviewFile,
+        egressManifestFile,
+        provider: input.provider,
+        model: response.model,
+        tokensUsed: response.tokensUsed,
+        timestamp,
+        filesReviewed: bundle.files.length,
+        contextTokens: bundle.totalTokens,
+        summary,
+    };
+}

package/dist/utils/index.d.ts

@@ -0,0 +1 @@
+export { estimateTokens, BUDGET_ALLOCATION, type BudgetCategory } from "./tokens.js";

package/dist/utils/index.js

@@ -0,0 +1 @@
+export { estimateTokens, BUDGET_ALLOCATION } from "./tokens.js";

package/dist/utils/tokens.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Token estimation utilities for context budgeting
+ */
+/**
+ * Rough token estimation (4 chars per token is a reasonable approximation for code)
+ *
+ * This is intentionally simple - for budget estimation we don't need tiktoken's
+ * precision, just a ballpark to avoid sending too much context.
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Budget allocation by category (explicit files get priority, then session, etc.)
+ *
+ * These percentages determine how the token budget is divided when multiple
+ * categories of files compete for space.
+ */
+export declare const BUDGET_ALLOCATION: {
+    readonly explicit: 0.15;
+    readonly session: 0.3;
+    readonly git: 0.1;
+    readonly dependency: 0.15;
+    readonly dependent: 0.15;
+    readonly test: 0.1;
+    readonly type: 0.05;
+};
+export type BudgetCategory = keyof typeof BUDGET_ALLOCATION;

package/dist/utils/tokens.js

@@ -0,0 +1,27 @@
+/**
+ * Token estimation utilities for context budgeting
+ */
+/**
+ * Rough token estimation (4 chars per token is a reasonable approximation for code)
+ *
+ * This is intentionally simple - for budget estimation we don't need tiktoken's
+ * precision, just a ballpark to avoid sending too much context.
+ */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Budget allocation by category (explicit files get priority, then session, etc.)
+ *
+ * These percentages determine how the token budget is divided when multiple
+ * categories of files compete for space.
+ */
+export const BUDGET_ALLOCATION = {
+    explicit: 0.15,
+    session: 0.3,
+    git: 0.1,
+    dependency: 0.15,
+    dependent: 0.15,
+    test: 0.1,
+    type: 0.05,
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "second-opinion-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for getting code reviews from Gemini/GPT in Claude Code",
+  "keywords": [
+    "mcp",
+    "claude",
+    "claude-code",
+    "code-review",
+    "gemini",
+    "openai",
+    "gpt"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/noelweichbrodt/second-opinion.git"
+  },
+  "homepage": "https://github.com/noelweichbrodt/second-opinion#readme",
+  "bugs": {
+    "url": "https://github.com/noelweichbrodt/second-opinion/issues"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "second-opinion-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "scripts",
+    "second-opinion.skill.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build",
+    "postinstall": "node scripts/install-config.js",
+    "install-config": "node scripts/install-config.js"
+  },
+  "dependencies": {
+    "@google/generative-ai": "^0.21.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "glob": "^11.0.0",
+    "openai": "^4.77.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "@vitest/coverage-v8": "^4.0.18",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^4.0.18"
+  }
+}

package/scripts/install-config.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const projectRoot = path.join(__dirname, "..");
+
+// Paths for review instructions template
+const configDir = path.join(os.homedir(), ".config", "second-opinion");
+const templatePath = path.join(projectRoot, "templates", "second-opinion.md");
+const targetPath = path.join(configDir, "second-opinion.md");
+
+// Paths for slash command
+const claudeCommandsDir = path.join(os.homedir(), ".claude", "commands");
+const skillPath = path.join(projectRoot, "second-opinion.skill.md");
+const commandTargetPath = path.join(claudeCommandsDir, "second-opinion.md");
+
+// Create config directory if it doesn't exist
+if (!fs.existsSync(configDir)) {
+  fs.mkdirSync(configDir, { recursive: true });
+  console.log(`Created config directory: ${configDir}`);
+}
+
+// Copy template if target doesn't exist
+if (!fs.existsSync(targetPath)) {
+  fs.copyFileSync(templatePath, targetPath);
+  console.log(`Installed default review instructions to: ${targetPath}`);
+} else {
+  console.log(`Review instructions already exist at: ${targetPath}`);
+  console.log("Skipping to preserve your customizations.");
+}
+
+// Install slash command to ~/.claude/commands/
+if (!fs.existsSync(claudeCommandsDir)) {
+  fs.mkdirSync(claudeCommandsDir, { recursive: true });
+  console.log(`Created Claude commands directory: ${claudeCommandsDir}`);
+}
+
+if (fs.existsSync(skillPath)) {
+  fs.copyFileSync(skillPath, commandTargetPath);
+  console.log(`Installed /second-opinion command to: ${commandTargetPath}`);
+} else {
+  console.log(`Warning: Skill file not found at ${skillPath}`);
+}
+
+console.log("\nSetup complete! Make sure to set your API keys:");
+console.log("  export GEMINI_API_KEY=your-key    # For Gemini");
+console.log("  export OPENAI_API_KEY=your-key    # For GPT");

package/second-opinion.skill.md

@@ -0,0 +1,34 @@
+---
+name: second-opinion
+description: Get feedback from Gemini or GPT on your current work
+user-invocable: true
+---
+
+# Second Opinion Skill
+
+Get a code review or custom feedback from an external LLM (Gemini or GPT).
+
+## Usage
+
+- `/second-opinion` - Default code review from Gemini
+- `/second-opinion [task]` - Custom task for Gemini
+- `/second-opinion openai [task]` - Use GPT instead
+- `/second-opinion gemini [task]` - Explicitly use Gemini
+
+## Instructions
+
+When invoked, parse the arguments:
+
+1. Check if first word is a provider (`gemini` or `openai`). If not, default to `gemini`.
+2. Remaining text becomes the custom task (if any).
+3. Derive a session name from the work done in this conversation (e.g., "add-auth-flow", "fix-login-bug").
+
+Call the `mcp__second-opinion__second_opinion` tool with:
+- `provider`: "gemini" or "openai"
+- `projectPath`: The current working directory (absolute path)
+- `sessionName`: Descriptive name based on the work done
+- `customPrompt`: The user's task text (if provided)
+
+After the review completes, report:
+- Path to the output file
+- Brief summary of key findings

package/templates/second-opinion.md

@@ -0,0 +1,54 @@
+# Code Review Instructions
+
+You are a code reviewer providing a second opinion on code changes made during a Claude Code session.
+
+## Your Role
+
+- Review the code changes objectively and thoroughly
+- Identify potential issues, bugs, security vulnerabilities, or improvements
+- Be constructive and specific in your feedback
+- Consider the conversation context to understand what was requested
+
+## Review Focus
+
+1. **Correctness**: Does the code do what it's supposed to do?
+2. **Security**: Are there any security vulnerabilities (injection, XSS, auth issues, etc.)?
+3. **Performance**: Are there obvious performance issues or inefficiencies?
+4. **Maintainability**: Is the code clear, well-organized, and easy to understand?
+5. **Error Handling**: Are errors handled appropriately?
+6. **Edge Cases**: Are edge cases considered?
+
+## Output Format
+
+Structure your review as follows:
+
+### Summary
+2-3 sentences summarizing the changes and your overall assessment.
+
+### Critical Issues
+Issues that should be fixed before merging (if any):
+- Issue description
+- Why it matters
+- Suggested fix
+
+### Suggestions
+Improvements that would be nice to have:
+- What could be improved
+- Why it would help
+
+### Questions
+Things that are unclear or might need clarification:
+- Question about intent or implementation
+
+### What's Done Well
+Positive aspects of the implementation:
+- Good practices observed
+- Clever solutions
+
+## Guidelines
+
+- Be specific: Reference file names and line numbers when possible
+- Be constructive: Don't just point out problems, suggest solutions
+- Be proportionate: Don't nitpick minor style issues if there are bigger concerns
+- Consider context: The conversation shows what was asked for - review against those requirements
+- Be honest: If the code looks good, say so