@klitchevo/code-council 0.0.1 → 0.0.3

package/dist/index.js

@@ -1,79 +1,649 @@
 #!/usr/bin/env node
-/**
- * Code Council MCP Server
- * Multi-model AI code review server using OpenRouter API
- */
+
+// src/index.ts
 import "dotenv/config";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { BACKEND_REVIEW_MODELS, CODE_REVIEW_MODELS, FRONTEND_REVIEW_MODELS, PLAN_REVIEW_MODELS, } from "./config";
-import { logger } from "./logger";
-import { ReviewClient } from "./review-client";
-import { createReviewTool } from "./tools/factory";
-import { handleListConfig } from "./tools/list-config";
-import { backendReviewSchema, handleBackendReview, } from "./tools/review-backend";
-import { codeReviewSchema, handleCodeReview } from "./tools/review-code";
-import { frontendReviewSchema, handleFrontendReview, } from "./tools/review-frontend";
-import { handlePlanReview, planReviewSchema } from "./tools/review-plan";
-// Validate API key
-const OPENROUTER_API_KEY = process.env.OPENROUTER_API_KEY;
+
+// src/constants.ts
+var LLM_CONFIG = {
+  /** Default temperature for model responses (can override with TEMPERATURE env var) */
+  DEFAULT_TEMPERATURE: Number(process.env.TEMPERATURE) || 0.3,
+  /** Default max tokens for responses (can override with MAX_TOKENS env var) */
+  DEFAULT_MAX_TOKENS: Number(process.env.MAX_TOKENS) || 16384
+};
+var DEFAULT_MODELS = [
+  "minimax/minimax-m2.1",
+  "x-ai/grok-code-fast-1"
+];
+
+// src/config.ts
+function parseModels(envVar, defaults) {
+  if (envVar === void 0 || envVar === null) {
+    return defaults;
+  }
+  if (Array.isArray(envVar)) {
+    const filtered = envVar.filter((m) => m && m.trim().length > 0);
+    return filtered.length > 0 ? filtered : defaults;
+  }
+  throw new Error(
+    `Model configuration must be an array of strings, got: ${typeof envVar}. Example: ["anthropic/claude-sonnet-4.5", "openai/gpt-4o"]`
+  );
+}
+var CODE_REVIEW_MODELS = parseModels(
+  process.env.CODE_REVIEW_MODELS,
+  DEFAULT_MODELS
+);
+var FRONTEND_REVIEW_MODELS = parseModels(
+  process.env.FRONTEND_REVIEW_MODELS,
+  DEFAULT_MODELS
+);
+var BACKEND_REVIEW_MODELS = parseModels(
+  process.env.BACKEND_REVIEW_MODELS,
+  DEFAULT_MODELS
+);
+var PLAN_REVIEW_MODELS = parseModels(
+  process.env.PLAN_REVIEW_MODELS,
+  DEFAULT_MODELS
+);
+
+// src/logger.ts
+var Logger = class {
+  isDevelopment = process.env.NODE_ENV === "development";
+  debugEnabled = process.env.DEBUG === "true";
+  log(level, message, context) {
+    const logEntry = {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      level,
+      message,
+      ...context
+    };
+    if (this.isDevelopment) {
+      const emoji = {
+        debug: "\u{1F50D}",
+        info: "\u2139\uFE0F",
+        warn: "\u26A0\uFE0F",
+        error: "\u274C"
+      }[level];
+      console.error(
+        `${emoji} [${level.toUpperCase()}] ${message}`,
+        context ? JSON.stringify(context, null, 2) : ""
+      );
+    } else {
+      console.error(JSON.stringify(logEntry));
+    }
+  }
+  debug(message, context) {
+    if (this.debugEnabled) {
+      this.log("debug", message, context);
+    }
+  }
+  info(message, context) {
+    this.log("info", message, context);
+  }
+  warn(message, context) {
+    this.log("warn", message, context);
+  }
+  error(message, error, context) {
+    const errorContext = {
+      ...context
+    };
+    if (error instanceof Error) {
+      errorContext.error = {
+        name: error.name,
+        message: error.message,
+        stack: error.stack
+      };
+    } else if (error) {
+      errorContext.error = error;
+    }
+    this.log("error", message, errorContext);
+  }
+};
+var logger = new Logger();
+
+// src/review-client.ts
+import { OpenRouter } from "@openrouter/sdk";
+
+// src/errors.ts
+var AppError = class extends Error {
+  constructor(message, code, userMessage) {
+    super(message);
+    this.code = code;
+    this.userMessage = userMessage;
+    this.name = this.constructor.name;
+    Error.captureStackTrace(this, this.constructor);
+  }
+};
+var OpenRouterError = class extends AppError {
+  constructor(message, statusCode, retryable = false) {
+    super(
+      message,
+      "OPENROUTER_ERROR",
+      retryable ? "The AI service is temporarily unavailable. Please try again in a moment." : "Unable to complete the review. Please check your API key and try again."
+    );
+    this.statusCode = statusCode;
+    this.retryable = retryable;
+  }
+};
+function formatErrorMessage(error) {
+  if (error instanceof AppError) {
+    return error.userMessage || error.message;
+  }
+  if (error instanceof Error) {
+    const sanitized = error.message.replace(/sk-or-v1-[a-zA-Z0-9]+/g, "[REDACTED]").replace(/Bearer [a-zA-Z0-9-_]+/g, "Bearer [REDACTED]");
+    if (sanitized.includes("401") || sanitized.includes("Unauthorized")) {
+      return "API authentication failed. Please check your OPENROUTER_API_KEY environment variable.";
+    }
+    if (sanitized.includes("429") || sanitized.includes("rate limit")) {
+      return "Rate limit exceeded. Please wait a moment and try again.";
+    }
+    if (sanitized.includes("timeout") || sanitized.includes("ETIMEDOUT")) {
+      return "Request timed out. The AI service may be slow. Please try again.";
+    }
+    return sanitized;
+  }
+  return "An unexpected error occurred. Please try again.";
+}
+function formatError(error) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: `Error: ${formatErrorMessage(error)}`
+      }
+    ],
+    isError: true
+  };
+}
+
+// src/prompts/backend-review.ts
+var SYSTEM_PROMPT = `You are an expert backend developer and security specialist. Review backend code for security, performance, and architecture.`;
+function buildUserMessage(code, reviewType = "full", language, context) {
+  const focusArea = getFocusArea(reviewType);
+  const languageContext = language ? `Language/Framework: ${language}
+` : "";
+  const additionalContext = context ? `${context}
+` : "";
+  return `${languageContext}${additionalContext}${focusArea}
+
+Code to review:
+\`\`\`
+${code}
+\`\`\``;
+}
+function getFocusArea(reviewType) {
+  switch (reviewType) {
+    case "security":
+      return "Focus specifically on security (authentication, authorization, input validation, SQL injection, XSS, CSRF, secrets management).";
+    case "performance":
+      return "Focus specifically on backend performance (database queries, caching, async operations, resource usage, scalability).";
+    case "architecture":
+      return "Focus specifically on architecture (design patterns, separation of concerns, modularity, maintainability, scalability).";
+    default:
+      return "Provide a comprehensive backend review covering security, performance, and architecture.";
+  }
+}
+
+// src/prompts/code-review.ts
+var SYSTEM_PROMPT2 = `You are an expert code reviewer. Analyze the code for:
+- Code quality and best practices
+- Potential bugs and edge cases
+- Performance issues
+- Security vulnerabilities
+- Maintainability concerns
+
+Provide specific, actionable feedback.`;
+function buildUserMessage2(code, context) {
+  if (context) {
+    return `${context}
+
+Code to review:
+\`\`\`
+${code}
+\`\`\``;
+  }
+  return `Code to review:
+\`\`\`
+${code}
+\`\`\``;
+}
+
+// src/prompts/frontend-review.ts
+var SYSTEM_PROMPT3 = `You are an expert frontend developer and UX specialist. Review frontend code for best practices.`;
+function buildUserMessage3(code, reviewType = "full", framework, context) {
+  const focusArea = getFocusArea2(reviewType);
+  const frameworkContext = framework ? `Framework: ${framework}
+` : "";
+  const additionalContext = context ? `${context}
+` : "";
+  return `${frameworkContext}${additionalContext}${focusArea}
+
+Code to review:
+\`\`\`
+${code}
+\`\`\``;
+}
+function getFocusArea2(reviewType) {
+  switch (reviewType) {
+    case "accessibility":
+      return "Focus specifically on accessibility (WCAG compliance, ARIA labels, keyboard navigation, screen reader support).";
+    case "performance":
+      return "Focus specifically on frontend performance (bundle size, render optimization, lazy loading, Core Web Vitals).";
+    case "ux":
+      return "Focus specifically on user experience (intuitive design, error handling, loading states, responsive design).";
+    default:
+      return "Provide a comprehensive frontend review covering accessibility, performance, and user experience.";
+  }
+}
+
+// src/prompts/plan-review.ts
+var SYSTEM_PROMPT4 = `You are an expert software architect and project planner. Review implementation plans before code is written to catch issues early.`;
+function buildUserMessage4(plan, reviewType = "full", context) {
+  const focusArea = getFocusArea3(reviewType);
+  const additionalContext = context ? `${context}
+` : "";
+  return `${additionalContext}${focusArea}
+
+Implementation plan to review:
+\`\`\`
+${plan}
+\`\`\``;
+}
+function getFocusArea3(reviewType) {
+  switch (reviewType) {
+    case "feasibility":
+      return "Focus specifically on feasibility (technical complexity, resource requirements, potential blockers, dependencies).";
+    case "completeness":
+      return "Focus specifically on completeness (missing requirements, edge cases, error handling, testing strategy).";
+    case "risks":
+      return "Focus specifically on risks (technical risks, security concerns, scalability issues, maintenance burden).";
+    case "timeline":
+      return "Focus specifically on timeline (realistic estimates, task breakdown, critical path, potential delays).";
+    default:
+      return "Provide a comprehensive plan review covering feasibility, completeness, risks, and timeline.";
+  }
+}
+
+// src/utils/parallel-executor.ts
+async function executeInParallel(models, reviewFn) {
+  const promises = models.map(async (model) => {
+    try {
+      const review = await reviewFn(model);
+      return { model, review };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error";
+      return { model, review: "", error: errorMessage };
+    }
+  });
+  return Promise.all(promises);
+}
+
+// src/review-client.ts
+var ReviewClient = class {
+  client;
+  constructor(apiKey) {
+    this.client = new OpenRouter({
+      apiKey
+    });
+  }
+  /**
+   * Send a chat request to OpenRouter API
+   * @param model - Model identifier (e.g., "anthropic/claude-3.5-sonnet")
+   * @param systemPrompt - System prompt for the model
+   * @param userMessage - User message/question
+   * @returns The model's response content
+   * @throws {OpenRouterError} If the API call fails
+   */
+  async chat(model, systemPrompt, userMessage) {
+    try {
+      logger.debug("Sending chat request", {
+        model,
+        messageLength: userMessage.length
+      });
+      const response = await this.client.chat.send({
+        model,
+        messages: [
+          { role: "system", content: systemPrompt },
+          { role: "user", content: userMessage }
+        ],
+        temperature: LLM_CONFIG.DEFAULT_TEMPERATURE,
+        maxTokens: LLM_CONFIG.DEFAULT_MAX_TOKENS
+      });
+      const content = response.choices?.[0]?.message?.content;
+      if (typeof content === "string") {
+        logger.debug("Received response", { model, length: content.length });
+        return content;
+      }
+      if (Array.isArray(content)) {
+        const text = content.filter((item) => item.type === "text").map((item) => item.text).join("\n");
+        logger.debug("Received array response", { model, length: text.length });
+        return text;
+      }
+      throw new OpenRouterError("No response content from model", 500);
+    } catch (error) {
+      if (error instanceof OpenRouterError) {
+        throw error;
+      }
+      const message = error instanceof Error ? error.message : "Unknown error";
+      logger.error("Chat request failed", error, { model });
+      const isRetryable = message.includes("429") || message.includes("rate limit");
+      throw new OpenRouterError(message, void 0, isRetryable);
+    }
+  }
+  /**
+   * Review code for quality, bugs, performance, and security
+   * @param code - Code to review
+   * @param models - Array of model identifiers to use
+   * @param context - Optional context (language, description, etc.)
+   * @returns Array of review results from each model
+   */
+  async reviewCode(code, models, context) {
+    const userMessage = buildUserMessage2(code, context);
+    return executeInParallel(
+      models,
+      (model) => this.chat(model, SYSTEM_PROMPT2, userMessage)
+    );
+  }
+  /**
+   * Review frontend code for accessibility, performance, and UX
+   */
+  async reviewFrontend(code, models, options) {
+    const userMessage = buildUserMessage3(
+      code,
+      options?.reviewType || "full",
+      options?.framework,
+      options?.context
+    );
+    return executeInParallel(
+      models,
+      (model) => this.chat(model, SYSTEM_PROMPT3, userMessage)
+    );
+  }
+  /**
+   * Review backend code for security, performance, and architecture
+   */
+  async reviewBackend(code, models, options) {
+    const userMessage = buildUserMessage(
+      code,
+      options?.reviewType || "full",
+      options?.language,
+      options?.context
+    );
+    return executeInParallel(
+      models,
+      (model) => this.chat(model, SYSTEM_PROMPT, userMessage)
+    );
+  }
+  /**
+   * Review implementation plans before code is written
+   */
+  async reviewPlan(plan, models, options) {
+    const userMessage = buildUserMessage4(
+      plan,
+      options?.reviewType || "full",
+      options?.context
+    );
+    return executeInParallel(
+      models,
+      (model) => this.chat(model, SYSTEM_PROMPT4, userMessage)
+    );
+  }
+};
+
+// src/tools/factory.ts
+function formatResults(results) {
+  return results.map((r) => {
+    if (r.error) {
+      return `## Review from \`${r.model}\`
+
+**Error:** ${r.error}`;
+    }
+    return `## Review from \`${r.model}\`
+
+${r.review}`;
+  }).join("\n\n---\n\n");
+}
+function createReviewTool(server2, config) {
+  server2.registerTool(
+    config.name,
+    {
+      description: config.description,
+      inputSchema: config.inputSchema
+    },
+    async (input) => {
+      try {
+        logger.debug(`Starting ${config.name}`, {
+          inputKeys: Object.keys(input)
+        });
+        const { results, models, reviewType } = await config.handler(input);
+        logger.info(`Completed ${config.name}`, {
+          modelCount: models.length,
+          successCount: results.filter((r) => !r.error).length,
+          errorCount: results.filter((r) => r.error).length
+        });
+        const title = reviewType ? `# ${config.name.replace("review_", "").replace("_", " ")} Review - ${reviewType} (${models.length} models)` : `# ${config.name.replace("review_", "").replace("_", " ")} Review Results (${models.length} models)`;
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${title}
+
+${formatResults(results)}`
+            }
+          ]
+        };
+      } catch (error) {
+        logger.error(
+          `Error in ${config.name}`,
+          error instanceof Error ? error : new Error(String(error))
+        );
+        return formatError(error);
+      }
+    }
+  );
+}
+
+// src/tools/list-config.ts
+async function handleListConfig() {
+  const text = `## Current Configuration
+
+**Code Review Models:**
+${CODE_REVIEW_MODELS.map((m) => `- \`${m}\``).join("\n")}
+
+**Frontend Review Models:**
+${FRONTEND_REVIEW_MODELS.map((m) => `- \`${m}\``).join("\n")}
+
+**Backend Review Models:**
+${BACKEND_REVIEW_MODELS.map((m) => `- \`${m}\``).join("\n")}
+
+**Plan Review Models:**
+${PLAN_REVIEW_MODELS.map((m) => `- \`${m}\``).join("\n")}
+
+To customize models, set environment variables in your MCP config:
+- CODE_REVIEW_MODELS
+- FRONTEND_REVIEW_MODELS
+- BACKEND_REVIEW_MODELS
+- PLAN_REVIEW_MODELS`;
+  return {
+    results: [],
+    models: [],
+    text
+  };
+}
+
+// src/tools/review-backend.ts
+import { z } from "zod";
+var backendReviewSchema = {
+  code: z.string().describe("The backend code to review"),
+  language: z.string().optional().describe("Programming language/framework (e.g., node, python, go, rust)"),
+  review_type: z.enum(["security", "performance", "architecture", "full"]).optional().describe("Type of review to perform (default: full)"),
+  context: z.string().optional().describe("Additional context")
+};
+async function handleBackendReview(client2, input) {
+  const { code, language, review_type, context } = input;
+  logger.info("Running backend review", {
+    modelCount: BACKEND_REVIEW_MODELS.length,
+    models: BACKEND_REVIEW_MODELS,
+    language,
+    reviewType: review_type || "full"
+  });
+  const results = await client2.reviewBackend(code, BACKEND_REVIEW_MODELS, {
+    language,
+    reviewType: review_type,
+    context
+  });
+  return {
+    results,
+    models: BACKEND_REVIEW_MODELS,
+    reviewType: review_type || "full"
+  };
+}
+
+// src/tools/review-code.ts
+import { z as z2 } from "zod";
+var codeReviewSchema = {
+  code: z2.string().describe("The code to review"),
+  language: z2.string().optional().describe("Programming language of the code"),
+  context: z2.string().optional().describe("Additional context about the code")
+};
+async function handleCodeReview(client2, input) {
+  const { code, language, context } = input;
+  const fullContext = language ? `Language: ${language}${context ? `
+${context}` : ""}` : context;
+  logger.info("Running code review", {
+    modelCount: CODE_REVIEW_MODELS.length,
+    models: CODE_REVIEW_MODELS,
+    hasLanguage: !!language,
+    hasContext: !!context
+  });
+  const results = await client2.reviewCode(
+    code,
+    CODE_REVIEW_MODELS,
+    fullContext
+  );
+  return {
+    results,
+    models: CODE_REVIEW_MODELS
+  };
+}
+
+// src/tools/review-frontend.ts
+import { z as z3 } from "zod";
+var frontendReviewSchema = {
+  code: z3.string().describe("The frontend code to review"),
+  framework: z3.string().optional().describe("Frontend framework (e.g., react, vue, svelte)"),
+  review_type: z3.enum(["accessibility", "performance", "ux", "full"]).optional().describe("Type of review to perform (default: full)"),
+  context: z3.string().optional().describe("Additional context")
+};
+async function handleFrontendReview(client2, input) {
+  const { code, framework, review_type, context } = input;
+  logger.info("Running frontend review", {
+    modelCount: FRONTEND_REVIEW_MODELS.length,
+    models: FRONTEND_REVIEW_MODELS,
+    framework,
+    reviewType: review_type || "full"
+  });
+  const results = await client2.reviewFrontend(code, FRONTEND_REVIEW_MODELS, {
+    framework,
+    reviewType: review_type,
+    context
+  });
+  return {
+    results,
+    models: FRONTEND_REVIEW_MODELS,
+    reviewType: review_type || "full"
+  };
+}
+
+// src/tools/review-plan.ts
+import { z as z4 } from "zod";
+var planReviewSchema = {
+  plan: z4.string().describe("The implementation plan to review"),
+  review_type: z4.enum(["feasibility", "completeness", "risks", "timeline", "full"]).optional().describe("Type of review to perform (default: full)"),
+  context: z4.string().optional().describe("Additional context about the project or constraints")
+};
+async function handlePlanReview(client2, input) {
+  const { plan, review_type, context } = input;
+  logger.info("Running plan review", {
+    modelCount: PLAN_REVIEW_MODELS.length,
+    models: PLAN_REVIEW_MODELS,
+    reviewType: review_type || "full"
+  });
+  const results = await client2.reviewPlan(plan, PLAN_REVIEW_MODELS, {
+    reviewType: review_type,
+    context
+  });
+  return {
+    results,
+    models: PLAN_REVIEW_MODELS,
+    reviewType: review_type || "full"
+  };
+}
+
+// src/index.ts
+var OPENROUTER_API_KEY = process.env.OPENROUTER_API_KEY;
 if (!OPENROUTER_API_KEY) {
-    console.error("Error: OPENROUTER_API_KEY environment variable is required");
-    console.error("For MCP clients, add it to the 'env' section of your server config.");
-    console.error("For local development, create a .env file with: OPENROUTER_API_KEY=your-key");
-    process.exit(1);
-}
-// Initialize client and server
-const client = new ReviewClient(OPENROUTER_API_KEY);
-const server = new McpServer({
-    name: "code-council",
-    version: "1.0.0",
+  console.error("Error: OPENROUTER_API_KEY environment variable is required");
+  console.error(
+    "For MCP clients, add it to the 'env' section of your server config."
+  );
+  console.error(
+    "For local development, create a .env file with: OPENROUTER_API_KEY=your-key"
+  );
+  process.exit(1);
+}
+var client = new ReviewClient(OPENROUTER_API_KEY);
+var server = new McpServer({
+  name: "code-council",
+  version: "1.0.0"
 });
-// Register review tools
 createReviewTool(server, {
-    name: "review_code",
-    description: "Review code for quality, bugs, performance, and security issues using multiple AI models in parallel",
-    inputSchema: codeReviewSchema,
-    handler: (input) => handleCodeReview(client, input),
+  name: "review_code",
+  description: "Review code for quality, bugs, performance, and security issues using multiple AI models in parallel",
+  inputSchema: codeReviewSchema,
+  handler: (input) => handleCodeReview(client, input)
 });
 createReviewTool(server, {
-    name: "review_frontend",
-    description: "Review frontend code for accessibility, performance, UX, and best practices using multiple AI models in parallel",
-    inputSchema: frontendReviewSchema,
-    handler: (input) => handleFrontendReview(client, input),
+  name: "review_frontend",
+  description: "Review frontend code for accessibility, performance, UX, and best practices using multiple AI models in parallel",
+  inputSchema: frontendReviewSchema,
+  handler: (input) => handleFrontendReview(client, input)
 });
 createReviewTool(server, {
-    name: "review_backend",
-    description: "Review backend code for security, performance, architecture, and best practices using multiple AI models in parallel",
-    inputSchema: backendReviewSchema,
-    handler: (input) => handleBackendReview(client, input),
+  name: "review_backend",
+  description: "Review backend code for security, performance, architecture, and best practices using multiple AI models in parallel",
+  inputSchema: backendReviewSchema,
+  handler: (input) => handleBackendReview(client, input)
 });
 createReviewTool(server, {
-    name: "review_plan",
-    description: "Review implementation plans BEFORE coding to catch issues early using multiple AI models in parallel",
-    inputSchema: planReviewSchema,
-    handler: (input) => handlePlanReview(client, input),
+  name: "review_plan",
+  description: "Review implementation plans BEFORE coding to catch issues early using multiple AI models in parallel",
+  inputSchema: planReviewSchema,
+  handler: (input) => handlePlanReview(client, input)
 });
-// Register config tool
-server.registerTool("list_review_config", { description: "Show current model configuration" }, async () => {
+server.registerTool(
+  "list_review_config",
+  { description: "Show current model configuration" },
+  async () => {
     const { text } = await handleListConfig();
     return {
-        content: [{ type: "text", text }],
+      content: [{ type: "text", text }]
     };
-});
-// Start server
+  }
+);
 async function main() {
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    logger.info("Code Council MCP server started", {
-        codeReviewModels: CODE_REVIEW_MODELS,
-        frontendReviewModels: FRONTEND_REVIEW_MODELS,
-        backendReviewModels: BACKEND_REVIEW_MODELS,
-        planReviewModels: PLAN_REVIEW_MODELS,
-    });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  logger.info("Code Council MCP server started", {
+    codeReviewModels: CODE_REVIEW_MODELS,
+    frontendReviewModels: FRONTEND_REVIEW_MODELS,
+    backendReviewModels: BACKEND_REVIEW_MODELS,
+    planReviewModels: PLAN_REVIEW_MODELS
+  });
 }
 main().catch((error) => {
-    logger.error("Fatal error during server startup", error);
-    process.exit(1);
+  logger.error("Fatal error during server startup", error);
+  process.exit(1);
 });
 //# sourceMappingURL=index.js.map