@reinteractive/rails-insight 1.0.1

package/src/tools/handlers/get-overview.js

@@ -0,0 +1,153 @@
+import { noIndex, respond } from './helpers.js'
+import { MAX_KEY_ENTITIES } from '../../core/constants.js'
+
+/**
+ * Register the get_overview tool.
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {Object} state - Mutable state with { index, provider, verbose }
+ */
+export function register(server, state) {
+  server.tool(
+    'get_overview',
+    'Project summary: Rails/Ruby versions, database, auth strategy, key models and controllers, frontend stack, file counts. Call this first.',
+    {},
+    async () => {
+      const index = state.index
+      if (!index) return noIndex()
+      const v = index.versions || {}
+      const config = index.extractions?.config || {}
+      const auth = index.extractions?.auth || {}
+      const authorization = index.extractions?.authorization || {}
+      const caching = index.extractions?.caching || {}
+      const models = index.extractions?.models || {}
+      const controllers = index.extractions?.controllers || {}
+      const tier2 = index.extractions?.tier2 || {}
+      const tier3 = index.extractions?.tier3 || {}
+
+      // Auth summary
+      const authSummary = {
+        strategy: auth.primary_strategy || auth.strategy || 'none',
+        models: [],
+        features: [],
+      }
+      if (auth.native_auth) {
+        authSummary.models = ['User', 'Session', 'Current'].filter(
+          (m) => models[m],
+        )
+        if (auth.has_secure_password)
+          authSummary.features.push('has_secure_password')
+        if (models['Session']) authSummary.features.push('database_sessions')
+        if (auth.native_auth.password_reset)
+          authSummary.features.push('password_reset')
+      } else if (auth.devise) {
+        authSummary.models = Object.keys(auth.devise.models || {})
+        authSummary.features = Object.values(auth.devise.models || {}).flatMap(
+          (m) => m.modules || [],
+        )
+      }
+
+      // Authorization summary
+      const authzSummary = {
+        strategy:
+          authorization.strategy || authorization.primary_strategy || 'none',
+        library:
+          authorization.library !== undefined ? authorization.library : null,
+        roles: [],
+        enforcement: null,
+        admin_boundary: null,
+      }
+      if (authorization.role_definition?.roles) {
+        authzSummary.roles = Object.keys(authorization.role_definition.roles)
+      } else {
+        const userModel = models['User']
+        if (userModel?.enums?.role) {
+          const roleEnum = userModel.enums.role
+          authzSummary.roles = Array.isArray(roleEnum.values)
+            ? roleEnum.values
+            : Object.keys(roleEnum.values || {})
+        }
+      }
+      if (authorization.concern?.guard_methods) {
+        const guardCount = Object.keys(
+          authorization.concern.guard_methods,
+        ).length
+        authzSummary.enforcement = `before_action guard methods in Authorization concern (${guardCount} guards)`
+      }
+      const adminNs = authorization.controller_enforcement_map?.admin_namespace
+      if (adminNs?.base_guard) {
+        authzSummary.admin_boundary = adminNs.base_guard
+      }
+
+      // Key models
+      const keyModels = Object.entries(models)
+        .filter(([n, m]) => m.type !== 'concern' && !m.abstract)
+        .sort(
+          (a, b) =>
+            (b[1].associations?.length || 0) - (a[1].associations?.length || 0),
+        )
+        .slice(0, MAX_KEY_ENTITIES)
+        .map(([n]) => n)
+
+      // Key controllers
+      const keyControllers = Object.entries(controllers)
+        .sort(
+          (a, b) => (b[1].actions?.length || 0) - (a[1].actions?.length || 0),
+        )
+        .slice(0, MAX_KEY_ENTITIES)
+        .map(([n]) => n)
+
+      // Custom pattern counts
+      const customPatterns = {
+        services: tier2.services?.length || tier2.service_objects?.length || 0,
+        concerns: Object.values(models).filter((m) => m.type === 'concern')
+          .length,
+        form_objects: tier2.form_objects?.length || 0,
+        presenters: tier2.presenters?.length || 0,
+        policies: tier3.policies?.count || 0,
+      }
+
+      const overview = {
+        rails_version: v.rails || 'unknown',
+        ruby_version: v.ruby || 'unknown',
+        database: config.database || v.database || 'unknown',
+        asset_pipeline: v.asset_pipeline || 'unknown',
+        frontend_stack: v.frontend || [],
+        authentication: authSummary,
+        authorization: authzSummary,
+        job_adapter: config.queue_adapter || 'unknown',
+        cache_store: caching.store || 'unknown',
+        test_framework: v.test_framework || 'unknown',
+        key_models: keyModels,
+        key_controllers: keyControllers,
+        custom_patterns: customPatterns,
+        file_counts: index.statistics || {},
+        workers: {
+          sidekiq_native_count: Object.keys(index.extractions?.workers || {})
+            .length,
+          queues: [
+            ...new Set(
+              Object.values(index.extractions?.workers || {}).map(
+                (w) => w.queue,
+              ),
+            ),
+          ],
+        },
+        helpers: {
+          count: Object.keys(index.extractions?.helpers || {}).length,
+        },
+        uploaders: {
+          count: Object.keys(index.extractions?.uploaders?.uploaders || {})
+            .length,
+          mounted: (index.extractions?.uploaders?.mounted || []).length,
+        },
+        pwa: index.pwa || { detected: false },
+        extraction_errors: (index.extraction_errors || []).length,
+        ...(index.extraction_errors?.length > 0
+          ? { extraction_error_details: index.extraction_errors }
+          : {}),
+      }
+
+      return respond(overview)
+    },
+  )
+}

package/src/tools/handlers/get-routes.js

@@ -0,0 +1,18 @@
+import { noIndex, respond } from './helpers.js'
+
+/**
+ * Register the get_routes tool.
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {Object} state - Mutable state with { index, provider, verbose }
+ */
+export function register(server, state) {
+  server.tool(
+    'get_routes',
+    'Complete route map with namespaces, nested resources, member/collection routes.',
+    {},
+    async () => {
+      if (!state.index) return noIndex()
+      return respond(state.index.extractions?.routes || {})
+    },
+  )
+}

package/src/tools/handlers/get-schema.js

@@ -0,0 +1,40 @@
+import { noIndex, respond, toTableName } from './helpers.js'
+
+/**
+ * Register the get_schema tool.
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {Object} state - Mutable state with { index, provider, verbose }
+ */
+export function register(server, state) {
+  server.tool(
+    'get_schema',
+    'Database schema with tables, columns, indexes, foreign keys, and model-to-table mapping.',
+    {},
+    async () => {
+      if (!state.index) return noIndex()
+      const schema = state.index.extractions?.schema || {}
+      const models = state.index.extractions?.models || {}
+
+      // Add model ↔ table mapping
+      const modelTableMap = {}
+      for (const [modelName, modelData] of Object.entries(models)) {
+        const tableName = modelData.table_name || toTableName(modelName)
+        modelTableMap[modelName] = tableName
+      }
+
+      // Add FK relationship arrows
+      const fkArrows = (schema.foreign_keys || []).map((fk) => {
+        const col =
+          fk.options?.match(/column:\s*['"]?(\w+)['"]?/)?.[1] ||
+          `${fk.to_table.replace(/s$/, '')}_id`
+        return `${fk.from_table}.${col} → ${fk.to_table}.id`
+      })
+
+      return respond({
+        ...schema,
+        model_table_map: modelTableMap,
+        fk_arrows: fkArrows,
+      })
+    },
+  )
+}

package/src/tools/handlers/get-subgraph.js

@@ -0,0 +1,82 @@
+import { z } from 'zod'
+import { noIndex, respond } from './helpers.js'
+
+/**
+ * Register the get_subgraph tool.
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {Object} state - Mutable state with { index, provider, verbose }
+ */
+export function register(server, state) {
+  server.tool(
+    'get_subgraph',
+    'Skill-scoped relationship subgraph with ranked files. Skills: authentication, database, frontend, api, jobs, email.',
+    {
+      skill: z
+        .string()
+        .describe(
+          'Skill domain (e.g. "authentication", "database", "frontend", "api")',
+        ),
+    },
+    async ({ skill }) => {
+      if (!state.index) return noIndex()
+
+      const skillDomains = {
+        authentication: [
+          'auth',
+          'devise',
+          'session',
+          'current',
+          'password',
+          'registration',
+          'confirmation',
+        ],
+        database: ['model', 'schema', 'migration', 'concern'],
+        frontend: ['component', 'stimulus', 'view', 'turbo', 'hotwire'],
+        api: ['api', 'serializer', 'blueprint', 'graphql'],
+        jobs: ['job', 'worker', 'sidekiq', 'queue'],
+        email: ['mailer', 'mail', 'mailbox'],
+      }
+
+      const domains = skillDomains[skill]
+      if (!domains) {
+        return respond({
+          error: `Unknown skill '${skill}'`,
+          available: Object.keys(skillDomains),
+        })
+      }
+
+      const allRels = state.index.relationships || []
+      const rankings = state.index.rankings || {}
+      const relevantEntities = new Set()
+      for (const rel of allRels) {
+        const fromMatch = domains.some((d) =>
+          rel.from.toLowerCase().includes(d),
+        )
+        const toMatch = domains.some((d) => rel.to.toLowerCase().includes(d))
+        if (fromMatch || toMatch) {
+          relevantEntities.add(rel.from)
+          relevantEntities.add(rel.to)
+        }
+      }
+      for (const key of Object.keys(rankings)) {
+        if (domains.some((d) => key.toLowerCase().includes(d)))
+          relevantEntities.add(key)
+      }
+
+      const subgraphRels = allRels.filter(
+        (r) => relevantEntities.has(r.from) || relevantEntities.has(r.to),
+      )
+      const rankedFiles = [...relevantEntities]
+        .map((e) => ({ entity: e, rank: rankings[e] || 0 }))
+        .sort((a, b) => b.rank - a.rank)
+
+      return respond({
+        skill,
+        entities: rankedFiles,
+        relationships: subgraphRels,
+        total_entities: rankedFiles.length,
+        total_relationships: subgraphRels.length,
+      })
+    },
+  )
+}

package/src/tools/handlers/get-test-conventions.js

@@ -0,0 +1,18 @@
+import { noIndex, respond } from './helpers.js'
+
+/**
+ * Register the get_test_conventions tool.
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {Object} state - Mutable state with { index, provider, verbose }
+ */
+export function register(server, state) {
+  server.tool(
+    'get_test_conventions',
+    'Returns detected test patterns and conventions: spec style (request vs controller), let style, auth helper, factories, shared examples, custom matchers, and pattern reference files.',
+    {},
+    async () => {
+      if (!state.index) return noIndex()
+      return respond(state.index.extractions?.test_conventions || {})
+    },
+  )
+}

package/src/tools/handlers/get-well-tested-examples.js

@@ -0,0 +1,51 @@
+import { z } from 'zod'
+import { noIndex, respond } from './helpers.js'
+import { MAX_EXAMPLE_CONTENT_LENGTH } from '../../core/constants.js'
+
+/**
+ * Register the get_well_tested_examples tool.
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {Object} state - Mutable state with { index, provider, verbose }
+ */
+export function register(server, state) {
+  server.tool(
+    'get_well_tested_examples',
+    'Returns high-quality existing spec files suitable as pattern references for test generation agents. Selected by structural complexity (most describe/context blocks) per spec category.',
+    {
+      category: z
+        .string()
+        .optional()
+        .describe(
+          'Filter by spec category (e.g. "model_specs", "request_specs")',
+        ),
+      limit: z
+        .number()
+        .optional()
+        .describe('Maximum results to return (default: 3)'),
+    },
+    async ({ category, limit = 3 }) => {
+      if (!state.index) return noIndex()
+      const conventions = state.index.extractions?.test_conventions || {}
+      let refs = conventions.pattern_reference_files || []
+
+      if (category) {
+        refs = refs.filter((r) => r.category === category)
+      }
+
+      const results = refs.slice(0, limit).map((ref) => {
+        const content = state.provider?.readFile(ref.path) || null
+        return {
+          ...ref,
+          content: content
+            ? content.slice(0, MAX_EXAMPLE_CONTENT_LENGTH)
+            : null,
+        }
+      })
+
+      return respond({
+        examples: results,
+        total_available: refs.length,
+      })
+    },
+  )
+}

package/src/tools/handlers/helpers.js

@@ -0,0 +1,115 @@
+/**
+ * Shared helpers and constants for tool handlers.
+ */
+
+import { tableize } from '../../utils/inflector.js'
+
+/**
+ * Convert a PascalCase model name to a snake_case plural table name.
+ * @param {string} name e.g. "UserProfile"
+ * @returns {string} e.g. "user_profiles"
+ */
+export function toTableName(name) {
+  return tableize(name)
+}
+
+/**
+ * Convert a file path to a Ruby-style class name.
+ * @param {string} path
+ * @returns {string}
+ */
+export function pathToClassName(path) {
+  const basename = path.split('/').pop().replace('.rb', '')
+  return basename
+    .split('_')
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join('')
+}
+
+/** MCP response when no index has been built yet. */
+export function noIndex() {
+  return respondError('Index not built. Call index_project first.')
+}
+
+/** Wrap data as an MCP text response. */
+export function respond(data) {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(data) }],
+  }
+}
+
+/**
+ * Wrap an error as an MCP error response.
+ * @param {string} message - Error message
+ * @param {Object} [details] - Additional details
+ * @returns {Object} MCP response with isError flag
+ */
+export function respondError(message, details = {}) {
+  return {
+    content: [
+      { type: 'text', text: JSON.stringify({ error: message, ...details }) },
+    ],
+    isError: true,
+  }
+}
+
+/** Architecturally significant gem categories (for slimmed dependencies output). */
+export const SIGNIFICANT_CATEGORIES = new Set([
+  'core',
+  'frontend',
+  'auth',
+  'authorization',
+  'background',
+  'caching',
+  'realtime',
+  'testing',
+  'deployment',
+  'search',
+  'admin',
+  'payments',
+  'monitoring',
+  'api',
+  'data',
+])
+
+/** Gems to always drop even if in significant categories. */
+export const DROP_GEMS = new Set([
+  'railties',
+  'activesupport',
+  'activerecord',
+  'actionpack',
+  'actionview',
+  'actionmailer',
+  'activejob',
+  'actioncable',
+  'activestorage',
+  'actiontext',
+  'actionmailbox',
+  'tzinfo-data',
+  'sprockets',
+  'sprockets-rails',
+])
+
+/** Well-known absent gems worth noting. */
+export const NOTABLE_ABSENT_CANDIDATES = [
+  'devise',
+  'pundit',
+  'cancancan',
+  'sidekiq',
+  'redis',
+  'activeadmin',
+  'administrate',
+  'jbuilder',
+  'grape',
+  'graphql',
+  'elasticsearch-rails',
+  'searchkick',
+  'meilisearch-rails',
+  'stripe',
+  'pay',
+  'sentry-rails',
+  'newrelic_rpm',
+  'rack-attack',
+  'paper_trail',
+  'audited',
+]

package/src/tools/handlers/index-project.js

@@ -0,0 +1,36 @@
+import { z } from 'zod'
+import { buildIndex } from '../../core/indexer.js'
+import { respond } from './helpers.js'
+
+/**
+ * Register the index_project tool.
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {Object} state - Mutable state with { index, provider, verbose }
+ */
+export function register(server, state) {
+  server.tool(
+    'index_project',
+    'Re-index the Rails project. In local mode, re-scans the project root. Returns statistics and duration.',
+    {
+      force: z
+        .boolean()
+        .optional()
+        .describe('Force full re-index even if cached'),
+    },
+    async ({ force }) => {
+      if (!state.provider) {
+        return respond({
+          error: 'No project root configured. Start with --project-root.',
+        })
+      }
+      const start = Date.now()
+      state.index = await buildIndex(state.provider, { verbose: state.verbose })
+      const duration_ms = Date.now() - start
+      return respond({
+        status: 'success',
+        statistics: state.index.statistics,
+        duration_ms,
+      })
+    },
+  )
+}

package/src/tools/handlers/search-patterns.js

@@ -0,0 +1,104 @@
+import { z } from 'zod'
+import { noIndex, respond } from './helpers.js'
+
+/**
+ * Register the search_patterns tool.
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {Object} state - Mutable state with { index, provider, verbose }
+ */
+export function register(server, state) {
+  server.tool(
+    'search_patterns',
+    'Search across all extractions for a specific Rails pattern type (e.g. "has_many_through", "before_action", "turbo_broadcast").',
+    {
+      pattern: z
+        .string()
+        .describe(
+          'Pattern type to search for (e.g. "has_many_through", "devise_confirmable")',
+        ),
+    },
+    async ({ pattern }) => {
+      if (!state.index) return noIndex()
+
+      const results = []
+      const extractions = state.index.extractions || {}
+      const lowerPattern = pattern.toLowerCase()
+
+      for (const [name, model] of Object.entries(extractions.models || {})) {
+        const matches = []
+        if (model.associations) {
+          for (const assoc of model.associations) {
+            const assocType = assoc.type?.replace(':', '') || ''
+            if (
+              assocType.includes(lowerPattern) ||
+              `${assocType}_${assoc.through || ''}`.includes(lowerPattern)
+            ) {
+              matches.push({ type: 'association', detail: assoc })
+            }
+            if (
+              lowerPattern === 'has_many_through' &&
+              assocType === 'has_many' &&
+              assoc.through
+            ) {
+              matches.push({ type: 'has_many_through', detail: assoc })
+            }
+          }
+        }
+        if (model.callbacks) {
+          for (const cb of model.callbacks) {
+            if (
+              cb.type?.toLowerCase().includes(lowerPattern) ||
+              cb.method?.toLowerCase().includes(lowerPattern)
+            ) {
+              matches.push({ type: 'callback', detail: cb })
+            }
+          }
+        }
+        if (model.concerns) {
+          for (const concern of model.concerns) {
+            if (concern.toLowerCase().includes(lowerPattern))
+              matches.push({ type: 'concern', detail: concern })
+          }
+        }
+        if (lowerPattern.startsWith('devise') && model.devise_modules) {
+          const moduleName = lowerPattern.replace('devise_', '')
+          if (model.devise_modules.includes(moduleName))
+            matches.push({ type: 'devise_module', detail: moduleName })
+        }
+        if (model.enums && lowerPattern.includes('enum')) {
+          for (const [enumName, enumData] of Object.entries(model.enums)) {
+            matches.push({
+              type: 'enum',
+              detail: { name: enumName, ...enumData },
+            })
+          }
+        }
+        if (lowerPattern.includes('broadcast') && model.broadcasts) {
+          matches.push({ type: 'broadcast', detail: model.broadcasts })
+        }
+        if (matches.length > 0)
+          results.push({ entity: name, entity_type: 'model', matches })
+      }
+
+      for (const [name, ctrl] of Object.entries(
+        extractions.controllers || {},
+      )) {
+        const matches = []
+        const filters = ctrl.filters || []
+        for (const f of filters) {
+          const filterStr = typeof f === 'string' ? f : f.name || f.method || ''
+          if (filterStr.toLowerCase().includes(lowerPattern))
+            matches.push({ type: 'filter', detail: f })
+        }
+        if (matches.length > 0)
+          results.push({ entity: name, entity_type: 'controller', matches })
+      }
+
+      return respond({
+        pattern,
+        results,
+        total_matches: results.reduce((sum, r) => sum + r.matches.length, 0),
+      })
+    },
+  )
+}

package/src/tools/index.js

@@ -0,0 +1,34 @@
+/**
+ * Central tool registration with tier gating.
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {Object} options
+ * @param {Object} [options.index] - Pre-built index
+ * @param {import('../providers/interface.js').FileProvider} [options.provider] - File provider
+ * @param {string} [options.tier] - 'free' | 'pro' | 'team'
+ * @param {boolean} [options.verbose] - Verbose logging
+ */
+import { registerFreeTools } from './free-tools.js'
+import { registerProTools } from './pro-tools.js'
+import { registerBlastRadiusTools } from './blast-radius-tools.js'
+
+export function registerTools(server, options) {
+  const tier = options.tier || 'free'
+
+  // Mutable state shared between tools
+  const state = {
+    index: options.index || null,
+    provider: options.provider || null,
+    verbose: options.verbose || false,
+  }
+
+  // Always register all primary tools (they are all in free-tools now)
+  registerFreeTools(server, state)
+
+  // Blast radius analysis tools
+  registerBlastRadiusTools(server, state)
+
+  // registerProTools is now a no-op stub kept for compatibility
+  if (tier === 'pro' || tier === 'team') {
+    registerProTools(server, state)
+  }
+}

package/src/tools/pro-tools.js

@@ -0,0 +1,13 @@
+/**
+ * Pro tier tools — kept for compatibility.
+ * All tools have been consolidated into registerFreeTools in free-tools.js.
+ */
+
+/**
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {Object} state
+ */
+export function registerProTools(server, state) {
+  // All tools are now registered via registerFreeTools in free-tools.js.
+  // This function is kept for backward compatibility.
+}

package/src/utils/file-reader.js

@@ -0,0 +1,20 @@
+/**
+ * Safe file reading utility.
+ * Wraps FileProvider readFile with encoding handling.
+ */
+
+/**
+ * Safely read file content, stripping BOM if present.
+ * @param {import('../providers/interface.js').FileProvider} provider
+ * @param {string} relativePath
+ * @returns {string|null}
+ */
+export function safeReadFile(provider, relativePath) {
+  const content = provider.readFile(relativePath)
+  if (content === null) return null
+  // Strip UTF-8 BOM
+  if (content.charCodeAt(0) === 0xfeff) {
+    return content.slice(1)
+  }
+  return content
+}