@reinteractive/rails-insight 1.0.1

package/src/server.js

@@ -0,0 +1,71 @@
+import { createRequire } from 'node:module'
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { LocalFSProvider } from './providers/local-fs.js'
+import { buildIndex } from './core/indexer.js'
+import { registerTools } from './tools/index.js'
+
+const require = createRequire(import.meta.url)
+const { version: PKG_VERSION } = require('../package.json')
+
+/**
+ * Create an MCP server with tool registrations.
+ * @param {Object} options
+ * @param {Object} options.index - Pre-built index (null if not yet built)
+ * @param {string} options.tier - 'free' | 'pro' | 'team'
+ * @param {boolean} options.verbose - Enable verbose logging
+ * @param {import('./providers/interface.js').FileProvider} [options.provider] - File provider for re-indexing
+ * @returns {McpServer}
+ */
+export function createServer(options) {
+  const server = new McpServer({
+    name: 'railsinsight',
+    version: PKG_VERSION,
+    capabilities: { tools: {} },
+  })
+
+  registerTools(server, options)
+
+  return server
+}
+
+/**
+ * Start the server in local mode with stdio transport.
+ * @param {string} projectRoot - Absolute path to Rails project
+ * @param {Object} options
+ */
+export async function startLocal(projectRoot, options = {}) {
+  const provider = new LocalFSProvider(projectRoot)
+  const verbose = options.verbose || false
+
+  if (verbose) {
+    process.stderr.write(`[railsinsight] Indexing ${projectRoot}...\n`)
+  }
+
+  const index = await buildIndex(provider, {
+    claudeMdPath: options.claudeMdPath,
+    verbose,
+  })
+
+  if (verbose) {
+    process.stderr.write(`[railsinsight] Index built. Starting MCP server...\n`)
+  }
+
+  const server = createServer({
+    index,
+    provider,
+    tier: options.tier || 'pro',
+    verbose,
+  })
+
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+}
+
+/**
+ * Start the server in remote mode with Streamable HTTP transport.
+ * @param {Object} options
+ */
+export async function startRemote(options = {}) {
+  throw new Error('Remote mode is not yet implemented. Use local mode.')
+}

package/src/tools/blast-radius-tools.js

@@ -0,0 +1,129 @@
+/**
+ * Blast Radius MCP Tools
+ * Registers get_blast_radius and get_review_context tools.
+ */
+
+import { z } from 'zod'
+import { computeBlastRadius, buildReviewContext } from '../core/blast-radius.js'
+import { detectChangedFiles } from '../git/diff-parser.js'
+import { noIndex, respond } from './handlers/helpers.js'
+import { DEFAULT_TOKEN_BUDGET } from '../core/constants.js'
+
+/**
+ * Register blast radius analysis tools on the MCP server.
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {Object} state - Mutable state object with { index, provider, verbose }
+ */
+export function registerBlastRadiusTools(server, state) {
+  server.tool(
+    'get_blast_radius',
+    'Analyse the impact of code changes. Accepts explicit file paths or auto-detects from git diff. Returns impacted entities classified by risk level (CRITICAL/HIGH/MEDIUM/LOW) with affected tests. Call this before making changes to understand what else might break, or after changes to identify what needs testing.',
+    {
+      files: z
+        .array(z.string())
+        .optional()
+        .describe('Explicit list of changed file paths'),
+      base_ref: z
+        .string()
+        .optional()
+        .describe('Git ref to diff against (default: HEAD)'),
+      staged: z
+        .boolean()
+        .optional()
+        .describe('Only staged changes (default: false)'),
+      max_depth: z
+        .number()
+        .optional()
+        .describe('BFS traversal depth limit (default: 3)'),
+    },
+    async (args) => {
+      if (!state.index) return noIndex()
+
+      const changedFiles = await resolveChangedFiles(args, state)
+      if (
+        changedFiles.error &&
+        changedFiles.files.length === 0 &&
+        !args.files?.length
+      ) {
+        return respond({ error: changedFiles.error })
+      }
+
+      const result = computeBlastRadius(state.index, changedFiles.files, {
+        maxDepth: args.max_depth || 3,
+      })
+      return respond(result)
+    },
+  )
+
+  server.tool(
+    'get_review_context',
+    'Get a token-budgeted structural summary of entities impacted by code changes. Returns compact Rails-aware descriptions of each impacted model, controller, and component — enough context for an AI agent to review the change safely. Call get_blast_radius first, or provide files directly.',
+    {
+      files: z
+        .array(z.string())
+        .optional()
+        .describe('Explicit list of changed file paths'),
+      base_ref: z
+        .string()
+        .optional()
+        .describe('Git ref to diff against (default: HEAD)'),
+      token_budget: z
+        .number()
+        .optional()
+        .describe('Maximum tokens for the response (default: 8000)'),
+      risk_filter: z
+        .string()
+        .optional()
+        .describe('Minimum risk level to include (default: LOW)'),
+    },
+    async (args) => {
+      if (!state.index) return noIndex()
+
+      const changedFiles = await resolveChangedFiles(args, state)
+      if (
+        changedFiles.error &&
+        changedFiles.files.length === 0 &&
+        !args.files?.length
+      ) {
+        return respond({ error: changedFiles.error })
+      }
+
+      const tokenBudget = args.token_budget || DEFAULT_TOKEN_BUDGET
+      const blastResult = computeBlastRadius(state.index, changedFiles.files)
+
+      if (args.risk_filter) {
+        const levels = ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW']
+        const minIdx = levels.indexOf(args.risk_filter)
+        if (minIdx >= 0) {
+          blastResult.impacted = blastResult.impacted.filter(
+            (e) => levels.indexOf(e.risk) <= minIdx,
+          )
+        }
+      }
+
+      const reviewContext = buildReviewContext(
+        state.index,
+        blastResult,
+        tokenBudget,
+      )
+      return respond(reviewContext)
+    },
+  )
+}
+
+async function resolveChangedFiles(args, state) {
+  if (args.files && args.files.length > 0) {
+    return {
+      files: args.files.map((path) => ({ path, status: 'modified' })),
+      error: null,
+    }
+  }
+
+  if (state.provider && typeof state.provider.execCommand === 'function') {
+    return detectChangedFiles(state.provider, args.base_ref || 'HEAD', {
+      staged: args.staged || false,
+    })
+  }
+
+  return { files: [], error: 'No files provided and git detection unavailable' }
+}

package/src/tools/free-tools.js

@@ -0,0 +1,44 @@
+/**
+ * Primary MCP tools — always registered regardless of tier.
+ * Each tool handler lives in its own file under ./handlers/.
+ * This barrel imports all handlers and wires them up.
+ */
+
+import { register as indexProject } from './handlers/index-project.js'
+import { register as getOverview } from './handlers/get-overview.js'
+import { register as getFullIndex } from './handlers/get-full-index.js'
+import { register as getModel } from './handlers/get-model.js'
+import { register as getController } from './handlers/get-controller.js'
+import { register as getRoutes } from './handlers/get-routes.js'
+import { register as getSchema } from './handlers/get-schema.js'
+import { register as getSubgraph } from './handlers/get-subgraph.js'
+import { register as searchPatterns } from './handlers/search-patterns.js'
+import { register as getDeepAnalysis } from './handlers/get-deep-analysis.js'
+import { register as getCoverageGaps } from './handlers/get-coverage-gaps.js'
+import { register as getTestConventions } from './handlers/get-test-conventions.js'
+import { register as getDomainClusters } from './handlers/get-domain-clusters.js'
+import { register as getFactoryRegistry } from './handlers/get-factory-registry.js'
+import { register as getWellTestedExamples } from './handlers/get-well-tested-examples.js'
+
+/**
+ * Register all primary tools on the MCP server.
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {Object} state - Mutable state object with { index, provider, verbose }
+ */
+export function registerFreeTools(server, state) {
+  indexProject(server, state)
+  getOverview(server, state)
+  getFullIndex(server, state)
+  getModel(server, state)
+  getController(server, state)
+  getRoutes(server, state)
+  getSchema(server, state)
+  getSubgraph(server, state)
+  searchPatterns(server, state)
+  getDeepAnalysis(server, state)
+  getCoverageGaps(server, state)
+  getTestConventions(server, state)
+  getDomainClusters(server, state)
+  getFactoryRegistry(server, state)
+  getWellTestedExamples(server, state)
+}

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

@@ -0,0 +1,93 @@
+import { z } from 'zod'
+import { noIndex, respond } from './helpers.js'
+
+/**
+ * Register the get_controller 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_controller',
+    'Deep extraction for a specific controller: actions with routes, filters, rate limiting, strong params, rescue handlers.',
+    {
+      name: z
+        .string()
+        .describe('Controller class name (e.g. "SessionsController")'),
+    },
+    async ({ name }) => {
+      if (!state.index) return noIndex()
+      const controllers = state.index.extractions?.controllers || {}
+      const ctrl = controllers[name]
+      if (!ctrl) {
+        return respond({
+          error: `Controller '${name}' not found`,
+          available: Object.keys(controllers),
+        })
+      }
+
+      // Enrich with route mapping
+      const routes = state.index.extractions?.routes || {}
+      const allRoutes = routes.routes || []
+      const ctrlBase = name
+        .replace(/Controller$/, '')
+        .toLowerCase()
+        .replace(/::/g, '/')
+
+      const actionRoutes = {}
+      for (const action of ctrl.actions || []) {
+        const match = allRoutes.find(
+          (r) =>
+            r.controller &&
+            r.action &&
+            (r.controller.toLowerCase() === ctrlBase ||
+              r.controller.toLowerCase().endsWith(`/${ctrlBase}`) ||
+              r.controller.toLowerCase() ===
+                name.replace('Controller', '').toLowerCase()) &&
+            r.action === action,
+        )
+        if (match) {
+          actionRoutes[action] = {
+            method: match.method || match.verb,
+            path: match.path || match.pattern,
+          }
+        }
+      }
+
+      // Resolve inherited authorization from superclass
+      let inherited_authorization = null
+      if (ctrl.superclass && ctrl.superclass !== 'ApplicationController') {
+        const parentCtrl = controllers[ctrl.superclass]
+        if (parentCtrl) {
+          const parentGuards = (parentCtrl.filters || []).filter(
+            (f) => f.authorization_guard,
+          )
+          if (parentGuards.length > 0) {
+            const authzData = state.index.extractions?.authorization || {}
+            const guardMethods = authzData.concern?.guard_methods || {}
+            const guardInfo = guardMethods[parentGuards[0].method]
+            inherited_authorization = {
+              from: ctrl.superclass,
+              guard: parentGuards[0].method,
+              requirement: guardInfo?.requirement || null,
+            }
+          }
+        }
+      }
+
+      return respond({
+        ...ctrl,
+        ...(inherited_authorization ? { inherited_authorization } : {}),
+        action_routes:
+          Object.keys(actionRoutes).length > 0 ? actionRoutes : null,
+        actions_detail: (ctrl.actions || []).reduce((acc, action) => {
+          acc[action] = {
+            ...(actionRoutes[action] || {}),
+            key_logic: ctrl.action_summaries?.[action] || null,
+          }
+          return acc
+        }, {}),
+      })
+    },
+  )
+}

package/src/tools/handlers/get-coverage-gaps.js

@@ -0,0 +1,100 @@
+import { z } from 'zod'
+import { noIndex, respond } from './helpers.js'
+
+/**
+ * Register the get_coverage_gaps 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_coverage_gaps',
+    'Returns prioritised list of files needing test coverage, with structural context from RailsInsight and per-method coverage data from SimpleCov.',
+    {
+      category: z
+        .string()
+        .optional()
+        .describe(
+          'Filter by spec category (e.g. "model_specs", "request_specs")',
+        ),
+      min_gap: z
+        .number()
+        .optional()
+        .describe('Minimum coverage gap percentage to include (default: 0)'),
+      limit: z
+        .number()
+        .optional()
+        .describe('Maximum results to return (default: 20)'),
+    },
+    async ({ category, min_gap = 0, limit = 20 }) => {
+      if (!state.index) return noIndex()
+      const extractions = state.index.extractions || {}
+      const coverageSnapshot = extractions.coverage_snapshot || {}
+      const models = extractions.models || {}
+      const controllers = extractions.controllers || {}
+      const manifest = state.index.manifest || {}
+
+      const gaps = []
+      const entries = manifest.entries || []
+
+      for (const [name, model] of Object.entries(models)) {
+        if (!model.file) continue
+        const fileCov = coverageSnapshot.per_file?.[model.file]
+        const coverage = fileCov ? fileCov.line_coverage : 0
+        const gap = 100 - (coverage || 0)
+
+        if (gap < min_gap) continue
+        if (category && category !== 'model_specs') continue
+
+        gaps.push({
+          file: model.file,
+          entity: name,
+          entity_type: 'model',
+          coverage: coverage || 0,
+          gap,
+          public_methods: model.public_methods?.length || 0,
+          associations: model.associations?.length || 0,
+          uncovered_methods: (coverageSnapshot.uncovered_methods || [])
+            .filter((m) => m.entity === name)
+            .map((m) => ({ method: m.method, coverage: m.coverage })),
+        })
+      }
+
+      for (const [name, ctrl] of Object.entries(controllers)) {
+        if (!ctrl.file) continue
+        const fileCov = coverageSnapshot.per_file?.[ctrl.file]
+        const coverage = fileCov ? fileCov.line_coverage : 0
+        const gap = 100 - (coverage || 0)
+
+        if (gap < min_gap) continue
+        if (
+          category &&
+          category !== 'request_specs' &&
+          category !== 'controller_specs'
+        )
+          continue
+
+        gaps.push({
+          file: ctrl.file,
+          entity: name,
+          entity_type: 'controller',
+          coverage: coverage || 0,
+          gap,
+          actions: ctrl.actions?.length || 0,
+          uncovered_methods: (coverageSnapshot.uncovered_methods || [])
+            .filter((m) => m.entity === name)
+            .map((m) => ({ method: m.method, coverage: m.coverage })),
+        })
+      }
+
+      gaps.sort((a, b) => b.gap - a.gap)
+
+      return respond({
+        coverage_available: coverageSnapshot.available || false,
+        overall: coverageSnapshot.overall || null,
+        gaps: gaps.slice(0, limit),
+        total_gaps: gaps.length,
+      })
+    },
+  )
+}