claudex-setup 1.10.0 → 1.10.2

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [1.10.2] - 2026-04-02
+
+### Fixed
+- MCP recommendations are now less speculative: `postgres-mcp` requires explicit Postgres signals, `figma-mcp` only appears for design-system repos, and `mcp-security` is no longer auto-added just because multiple packs were suggested
+- `sentry-mcp` now requires real observability signals or stricter operational domains instead of appearing for every frontend/backend repo
+- design-system detection now respects `.storybook/` directories directly, improving frontend pack accuracy
+
+### Added
+- MCP preflight warnings for `setup`, `plan`, and `apply` when selected packs require missing environment variables
+- user-facing docs now reflect the actual 22 detected stacks
+
 ## [1.10.0] - 2026-04-01
 
 ### Added

package/README.md

@@ -204,16 +204,16 @@ The exact applicable count can be lower on a given repo because stack-specific c
 
 ## Stack Detection
 
-Auto-detects and tailors output for 18 stacks:
+Auto-detects and tailors output for 22 stacks:
 
 | | |
 |--|--|
 | **Frontend** | React, Vue, Angular, Next.js, Svelte |
 | **Backend** | Node.js, Python, Django, FastAPI |
 | **Mobile** | Flutter, Swift, Kotlin |
-| **Systems** | Rust, Go, Java, Ruby |
+| **Systems** | Rust, Go, Java, Ruby, C++, Bazel |
 | **Language** | TypeScript |
-| **Infra** | Docker |
+| **Infra** | Docker, Terraform, Kubernetes |
 
 ## GitHub Action
 
@@ -227,7 +227,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: DnaFin/claudex-setup@v1.10.0
+      - uses: DnaFin/claudex-setup@v1.10.2
         with:
           threshold: 50
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudex-setup",
-  "version": "1.10.0",
+  "version": "1.10.2",
   "description": "Audit and improve Claude Code readiness with discover, plan, apply, governance, and benchmark workflows.",
   "main": "src/index.js",
   "bin": {

package/src/analyze.js

@@ -318,7 +318,7 @@ async function analyzeProject(options) {
   const maturity = detectMaturity(assets);
   const mainDirs = detectMainDirs(ctx);
   const recommendedDomainPacks = detectDomainPacks(ctx, stacks, assets);
-  const recommendedMcpPacks = recommendMcpPacks(stacks, recommendedDomainPacks);
+  const recommendedMcpPacks = recommendMcpPacks(stacks, recommendedDomainPacks, { ctx, assets });
 
   const report = {
     mode,

package/src/domain-packs.js

@@ -243,14 +243,14 @@ function detectDomainPacks(ctx, stacks, assets = null) {
   }
 
   // Regulated-lite detection
-  const isRegulated = ctx.files.includes('SECURITY.md') ||
-    ctx.files.includes('COMPLIANCE.md') || ctx.hasDir('compliance') ||
+  const hasSecurityPolicy = ctx.files.includes('SECURITY.md');
+  const isRegulated = ctx.files.includes('COMPLIANCE.md') || ctx.hasDir('compliance') ||
     ctx.hasDir('audit') || ctx.hasDir('policies') ||
     (pkg.keywords && pkg.keywords.some(k => ['hipaa', 'fintech', 'compliance', 'regulated', 'sox', 'pci'].includes(k)));
   if (isRegulated && !isEnterpriseGoverned) {
     addMatch('regulated-lite', [
       'Detected compliance or regulatory signals without full enterprise governance.',
-      ctx.files.includes('SECURITY.md') ? 'SECURITY.md present.' : null,
+      ctx.files.includes('COMPLIANCE.md') ? 'COMPLIANCE.md present.' : null,
       ctx.hasDir('compliance') ? 'Compliance directory detected.' : null,
     ]);
   }
@@ -293,7 +293,7 @@ function detectDomainPacks(ctx, stacks, assets = null) {
   // Design system detection
   const isDesignSystem = deps.storybook || deps['@storybook/react'] || deps['@storybook/vue3'] ||
     ctx.hasDir('tokens') || ctx.hasDir('design-tokens') ||
-    (ctx.hasDir('components') && ctx.files.includes('.storybook'));
+    (ctx.hasDir('components') && ctx.hasDir('.storybook'));
   if (isDesignSystem) {
     addMatch('design-system', [
       'Detected design system or component library signals.',
@@ -315,7 +315,7 @@ function detectDomainPacks(ctx, stacks, assets = null) {
   }
 
   // Security-focused detection
-  const isSecurityFocused = ctx.files.includes('SECURITY.md') &&
+  const isSecurityFocused = hasSecurityPolicy &&
     (hasBackend || deps.bcrypt || deps.jsonwebtoken || deps.passport || deps['next-auth']);
   if (isSecurityFocused && !isRegulated) {
     addMatch('security-focused', [

package/src/index.js

@@ -5,7 +5,7 @@ const { buildProposalBundle, applyProposalBundle } = require('./plans');
 const { getGovernanceSummary } = require('./governance');
 const { runBenchmark } = require('./benchmark');
 const { DOMAIN_PACKS, detectDomainPacks } = require('./domain-packs');
-const { MCP_PACKS, getMcpPack, mergeMcpServers, recommendMcpPacks } = require('./mcp-packs');
+const { MCP_PACKS, getMcpPack, mergeMcpServers, getMcpPackPreflight, recommendMcpPacks } = require('./mcp-packs');
 
 module.exports = {
   audit,
@@ -20,5 +20,6 @@ module.exports = {
   MCP_PACKS,
   getMcpPack,
   mergeMcpServers,
+  getMcpPackPreflight,
   recommendMcpPacks,
 };

package/src/mcp-packs.js

@@ -81,7 +81,7 @@ const MCP_PACKS = [
     servers: {
       docker: {
         command: 'npx',
-        args: ['-y', '@modelcontextprotocol/server-docker'],
+        args: ['-y', '@hypnosis/docker-mcp-server'],
       },
     },
   },
@@ -106,7 +106,7 @@ const MCP_PACKS = [
     servers: {
       linear: {
         command: 'npx',
-        args: ['-y', '@linear/mcp-server'],
+        args: ['-y', '@mseep/linear-mcp'],
         env: { LINEAR_API_KEY: '${LINEAR_API_KEY}' },
       },
     },
@@ -132,7 +132,7 @@ const MCP_PACKS = [
     servers: {
       slack: {
         command: 'npx',
-        args: ['-y', '@anthropic/slack-mcp-server'],
+        args: ['-y', 'slack-mcp-server'],
         env: { SLACK_BOT_TOKEN: '${SLACK_BOT_TOKEN}' },
       },
     },
@@ -145,7 +145,7 @@ const MCP_PACKS = [
     servers: {
       stripe: {
         command: 'npx',
-        args: ['-y', '@stripe/mcp-server'],
+        args: ['-y', '@stripe/mcp'],
         env: { STRIPE_API_KEY: '${STRIPE_API_KEY}' },
       },
     },
@@ -158,7 +158,7 @@ const MCP_PACKS = [
     servers: {
       figma: {
         command: 'npx',
-        args: ['-y', '@anthropic/figma-mcp-server'],
+        args: ['-y', 'claude-talk-to-figma-mcp'],
         env: { FIGMA_ACCESS_TOKEN: '${FIGMA_ACCESS_TOKEN}' },
       },
     },
@@ -183,7 +183,7 @@ const MCP_PACKS = [
     servers: {
       composio: {
         command: 'npx',
-        args: ['-y', 'composio-mcp@latest'],
+        args: ['-y', '@composio/mcp'],
         env: { COMPOSIO_API_KEY: '${COMPOSIO_API_KEY}' },
       },
     },
@@ -208,7 +208,7 @@ const MCP_PACKS = [
     servers: {
       jira: {
         command: 'npx',
-        args: ['-y', '@anthropic/jira-mcp-server'],
+        args: ['-y', 'jira-mcp'],
         env: { ATLASSIAN_API_TOKEN: '${ATLASSIAN_API_TOKEN}', ATLASSIAN_EMAIL: '${ATLASSIAN_EMAIL}' },
       },
     },
@@ -221,7 +221,7 @@ const MCP_PACKS = [
     servers: {
       ga4: {
         command: 'npx',
-        args: ['-y', '@anthropic/ga4-mcp-server'],
+        args: ['-y', 'mcp-server-ga4'],
         env: { GA4_PROPERTY_ID: '${GA4_PROPERTY_ID}' },
       },
     },
@@ -260,7 +260,7 @@ const MCP_PACKS = [
     servers: {
       zendesk: {
         command: 'npx',
-        args: ['-y', 'zendesk-mcp-server@latest'],
+        args: ['-y', 'zendesk-mcp'],
         env: { ZENDESK_API_TOKEN: '${ZENDESK_API_TOKEN}', ZENDESK_SUBDOMAIN: '${ZENDESK_SUBDOMAIN}' },
       },
     },
@@ -273,7 +273,7 @@ const MCP_PACKS = [
     servers: {
       infisical: {
         command: 'npx',
-        args: ['-y', '@infisical/mcp-server'],
+        args: ['-y', '@infisical/mcp'],
         env: { INFISICAL_TOKEN: '${INFISICAL_TOKEN}' },
       },
     },
@@ -286,7 +286,7 @@ const MCP_PACKS = [
     servers: {
       shopify: {
         command: 'npx',
-        args: ['-y', '@shopify/dev-mcp-server'],
+        args: ['-y', 'shopify-mcp'],
         env: { SHOPIFY_ACCESS_TOKEN: '${SHOPIFY_ACCESS_TOKEN}' },
       },
     },
@@ -299,7 +299,7 @@ const MCP_PACKS = [
     servers: {
       huggingface: {
         command: 'npx',
-        args: ['-y', '@huggingface/mcp-server'],
+        args: ['-y', 'huggingface-mcp-server'],
         env: { HF_TOKEN: '${HF_TOKEN}' },
       },
     },
@@ -312,7 +312,7 @@ const MCP_PACKS = [
     servers: {
       blender: {
         command: 'npx',
-        args: ['-y', 'blender-mcp@latest'],
+        args: ['-y', '@glutamateapp/blender-mcp-ts'],
       },
     },
   },
@@ -335,6 +335,71 @@ function clone(value) {
   return JSON.parse(JSON.stringify(value));
 }
 
+function hasDependency(deps, name) {
+  return Object.prototype.hasOwnProperty.call(deps || {}, name);
+}
+
+function hasFileContentMatch(ctx, filePath, pattern) {
+  if (!ctx) return false;
+  const content = ctx.fileContent(filePath);
+  return !!(content && pattern.test(content));
+}
+
+function getProjectDependencies(ctx) {
+  if (!ctx) return {};
+  const pkg = ctx.jsonFile('package.json') || {};
+  return {
+    ...(pkg.dependencies || {}),
+    ...(pkg.devDependencies || {}),
+  };
+}
+
+function hasPostgresSignals(ctx, deps = {}) {
+  if (
+    hasDependency(deps, 'pg') ||
+    hasDependency(deps, 'postgres') ||
+    hasDependency(deps, 'pg-promise') ||
+    hasDependency(deps, 'postgres.js') ||
+    hasDependency(deps, 'slonik') ||
+    hasDependency(deps, '@neondatabase/serverless') ||
+    hasDependency(deps, '@vercel/postgres')
+  ) {
+    return true;
+  }
+
+  return (
+    hasFileContentMatch(ctx, 'prisma/schema.prisma', /provider\s*=\s*["']postgresql["']/i) ||
+    hasFileContentMatch(ctx, 'docker-compose.yml', /\bpostgres\b/i) ||
+    hasFileContentMatch(ctx, 'docker-compose.yaml', /\bpostgres\b/i) ||
+    hasFileContentMatch(ctx, 'compose.yml', /\bpostgres\b/i) ||
+    hasFileContentMatch(ctx, 'compose.yaml', /\bpostgres\b/i) ||
+    hasFileContentMatch(ctx, '.env', /postgres(?:ql)?:\/\//i) ||
+    hasFileContentMatch(ctx, '.env.local', /postgres(?:ql)?:\/\//i) ||
+    hasFileContentMatch(ctx, '.env.example', /postgres(?:ql)?:\/\//i)
+  );
+}
+
+function hasObservabilitySignals(ctx, deps = {}) {
+  if (
+    hasDependency(deps, '@sentry/nextjs') ||
+    hasDependency(deps, '@sentry/node') ||
+    hasDependency(deps, '@sentry/react') ||
+    hasDependency(deps, '@sentry/vue') ||
+    hasDependency(deps, '@sentry/browser')
+  ) {
+    return true;
+  }
+
+  return (
+    hasFileContentMatch(ctx, 'sentry.client.config.js', /\S/) ||
+    hasFileContentMatch(ctx, 'sentry.client.config.ts', /\S/) ||
+    hasFileContentMatch(ctx, 'sentry.server.config.js', /\S/) ||
+    hasFileContentMatch(ctx, 'sentry.server.config.ts', /\S/) ||
+    hasFileContentMatch(ctx, 'instrumentation.ts', /sentry/i) ||
+    hasFileContentMatch(ctx, 'instrumentation.js', /sentry/i)
+  );
+}
+
 function getMcpPack(key) {
   return MCP_PACKS.find(pack => pack.key === key) || null;
 }
@@ -360,9 +425,46 @@ function mergeMcpServers(existing = {}, packKeys = []) {
   return merged;
 }
 
-function recommendMcpPacks(stacks = [], domainPacks = []) {
+function getRequiredEnvVars(packKeys = []) {
+  const required = new Set();
+  for (const key of normalizeMcpPackKeys(packKeys)) {
+    const pack = getMcpPack(key);
+    if (!pack) continue;
+    for (const serverConfig of Object.values(pack.servers || {})) {
+      for (const envKey of Object.keys(serverConfig.env || {})) {
+        required.add(envKey);
+      }
+    }
+  }
+  return [...required].sort();
+}
+
+function getMcpPackPreflight(packKeys = [], env = process.env) {
+  return normalizeMcpPackKeys(packKeys)
+    .map((key) => {
+      const pack = getMcpPack(key);
+      if (!pack) return null;
+      const requiredEnvVars = getRequiredEnvVars([key]);
+      if (requiredEnvVars.length === 0) return null;
+      const missingEnvVars = requiredEnvVars.filter((envKey) => {
+        const value = env && Object.prototype.hasOwnProperty.call(env, envKey) ? env[envKey] : '';
+        return !`${value || ''}`.trim();
+      });
+      return {
+        key,
+        label: pack.label,
+        requiredEnvVars,
+        missingEnvVars,
+      };
+    })
+    .filter(Boolean);
+}
+
+function recommendMcpPacks(stacks = [], domainPacks = [], options = {}) {
   const recommended = new Set();
   const stackKeys = new Set(stacks.map(stack => stack.key));
+  const ctx = options.ctx || null;
+  const deps = getProjectDependencies(ctx);
 
   for (const pack of domainPacks) {
     for (const key of pack.recommendedMcpPacks || []) {
@@ -384,8 +486,8 @@ function recommendMcpPacks(stacks = [], domainPacks = []) {
     recommended.add('github-mcp');
   }
 
-  // Postgres MCP for data-heavy repos
-  if (domainKeys.has('data-pipeline') || domainKeys.has('backend-api')) {
+  // Postgres MCP only when there are explicit Postgres signals
+  if ((domainKeys.has('data-pipeline') || domainKeys.has('backend-api')) && hasPostgresSignals(ctx, deps)) {
     recommended.add('postgres-mcp');
   }
 
@@ -404,13 +506,21 @@ function recommendMcpPacks(stacks = [], domainPacks = []) {
     recommended.add('docker-mcp');
   }
 
-  // Sentry for production backend/frontend
-  if (domainKeys.has('backend-api') || domainKeys.has('frontend-ui')) {
+  // Sentry when the repo already shows observability signals or has stricter operational needs
+  if (
+    (domainKeys.has('backend-api') || domainKeys.has('frontend-ui')) &&
+    (
+      hasObservabilitySignals(ctx, deps) ||
+      domainKeys.has('enterprise-governed') ||
+      domainKeys.has('security-focused') ||
+      domainKeys.has('ecommerce')
+    )
+  ) {
     recommended.add('sentry-mcp');
   }
 
-  // Figma for frontend-ui with design systems
-  if (domainKeys.has('frontend-ui')) {
+  // Figma only when design-system signals are present
+  if (domainKeys.has('design-system')) {
     recommended.add('figma-mcp');
   }
 
@@ -450,11 +560,6 @@ function recommendMcpPacks(stacks = [], domainPacks = []) {
     recommended.add('infisical-secrets');
   }
 
-  // Security scanner when 2+ MCP servers recommended
-  if (recommended.size >= 2) {
-    recommended.add('mcp-security');
-  }
-
   return MCP_PACKS
     .filter(pack => recommended.has(pack.key))
     .map(pack => clone(pack));
@@ -465,5 +570,7 @@ module.exports = {
   getMcpPack,
   normalizeMcpPackKeys,
   mergeMcpServers,
+  getRequiredEnvVars,
+  getMcpPackPreflight,
   recommendMcpPacks,
 };

package/src/plans.js

@@ -7,6 +7,7 @@ const { ProjectContext } = require('./context');
 const { TECHNIQUES, STACKS } = require('./techniques');
 const { TEMPLATES } = require('./setup');
 const { buildSettingsForProfile } = require('./governance');
+const { getMcpPackPreflight } = require('./mcp-packs');
 const { writeActivityArtifact, writeRollbackArtifact } = require('./activity');
 
 const TEMPLATE_DIR_MAP = {
@@ -374,6 +375,8 @@ async function buildProposalBundle(options) {
   const ctx = new ProjectContext(options.dir);
   const stacks = ctx.detectStacks(STACKS);
   const report = await analyzeProject({ ...options, mode: 'augment' });
+  const mcpPreflightWarnings = getMcpPackPreflight(options.mcpPacks || [])
+    .filter(item => item.missingEnvVars.length > 0);
   const groups = getFailedTemplateGroups(ctx, options.only || []);
   const proposals = [];
 
@@ -406,6 +409,7 @@ async function buildProposalBundle(options) {
     strengthsPreserved: report.strengthsPreserved,
     topNextActions: report.topNextActions,
     riskNotes: report.riskNotes,
+    mcpPreflightWarnings,
     proposals,
   };
 }
@@ -422,6 +426,14 @@ function printProposalBundle(bundle, options = {}) {
   console.log(`  ${bundle.projectSummary.name} | maturity=${bundle.projectSummary.maturity} | score=${bundle.projectSummary.score}/100`);
   console.log('');
 
+  if (bundle.mcpPreflightWarnings && bundle.mcpPreflightWarnings.length > 0) {
+    console.log('  MCP Preflight Warnings');
+    for (const warning of bundle.mcpPreflightWarnings) {
+      console.log(`  - ${warning.label}: missing ${warning.missingEnvVars.join(', ')}`);
+    }
+    console.log('');
+  }
+
   if (bundle.proposals.length === 0) {
     console.log('  No templated proposals are needed right now.');
     console.log('');
@@ -523,6 +535,8 @@ function resolvePlan(bundle, options) {
 async function applyProposalBundle(options) {
   const liveBundle = options.planFile ? null : await buildProposalBundle(options);
   const bundle = resolvePlan(liveBundle, options);
+  const mcpPreflightWarnings = getMcpPackPreflight(options.mcpPacks || [])
+    .filter(item => item.missingEnvVars.length > 0);
   const selectedIds = options.only && options.only.length > 0
     ? new Set(options.only)
     : null;
@@ -589,6 +603,7 @@ async function applyProposalBundle(options) {
     dryRun: options.dryRun === true,
     rollbackArtifact: rollback ? rollback.relativePath : null,
     activityArtifact: activity ? activity.relativePath : null,
+    mcpPreflightWarnings,
   };
 }
 
@@ -607,6 +622,12 @@ function printApplyResult(result, options = {}) {
   console.log(`  Applied proposal bundles: ${result.appliedProposalIds.join(', ') || 'none'}`);
   console.log(`  Created files: ${result.createdFiles.join(', ') || 'none'}`);
   console.log(`  Patched files: ${result.patchedFiles.join(', ') || 'none'}`);
+  if (result.mcpPreflightWarnings && result.mcpPreflightWarnings.length > 0) {
+    console.log('  MCP preflight warnings:');
+    for (const warning of result.mcpPreflightWarnings) {
+      console.log(`  - ${warning.label}: missing ${warning.missingEnvVars.join(', ')}`);
+    }
+  }
   if (result.rollbackArtifact) {
     console.log(`  Rollback: ${result.rollbackArtifact}`);
   }

package/src/setup.js

@@ -9,6 +9,7 @@ const { TECHNIQUES, STACKS } = require('./techniques');
 const { ProjectContext } = require('./context');
 const { audit } = require('./audit');
 const { buildSettingsForProfile } = require('./governance');
+const { getMcpPackPreflight } = require('./mcp-packs');
 
 // ============================================================
 // Helper: detect project scripts from package.json
@@ -1117,6 +1118,8 @@ async function setup(options) {
   const silent = options.silent === true;
   const writtenFiles = [];
   const preservedFiles = [];
+  const mcpPreflightWarnings = getMcpPackPreflight(options.mcpPacks || [])
+    .filter(item => item.missingEnvVars.length > 0);
 
   function log(message = '') {
     if (!silent) {
@@ -1243,6 +1246,15 @@ async function setup(options) {
   }
 
   log('');
+  if (mcpPreflightWarnings.length > 0) {
+    log('\x1b[33m  MCP Preflight Warnings\x1b[0m');
+    for (const warning of mcpPreflightWarnings) {
+      log(`  - ${warning.label}: missing ${warning.missingEnvVars.join(', ')}`);
+      log('  \x1b[2m  Settings were generated with placeholders, but this MCP server will not start until those env vars are set.\x1b[0m');
+    }
+    log('');
+  }
+
   log('  Run \x1b[1mnpx claudex-setup audit\x1b[0m to check your score.');
   log('');
 
@@ -1252,6 +1264,7 @@ async function setup(options) {
     writtenFiles,
     preservedFiles,
     stacks,
+    mcpPreflightWarnings,
   };
 }
 

package/src/techniques.js

@@ -696,8 +696,12 @@ const TECHNIQUES = {
     id: 1801,
     name: '2+ MCP servers for rich tooling',
     check: (ctx) => {
+      let count = 0;
       const settings = ctx.jsonFile('.claude/settings.local.json') || ctx.jsonFile('.claude/settings.json');
-      return !!(settings && settings.mcpServers && Object.keys(settings.mcpServers).length >= 2);
+      if (settings && settings.mcpServers) count += Object.keys(settings.mcpServers).length;
+      const mcpJson = ctx.jsonFile('.mcp.json');
+      if (mcpJson && mcpJson.mcpServers) count += Object.keys(mcpJson.mcpServers).length;
+      return count >= 2;
     },
     impact: 'medium',
     rating: 4,