@soulbatical/tetra-dev-toolkit 1.20.9 → 1.20.10

package/lib/checks/codeQuality/mcp-tool-docs.js

@@ -0,0 +1,193 @@
+/**
+ * Code Quality Check: MCP Tool Documentation
+ *
+ * Ensures all MCP tool definitions have proper descriptions.
+ * Scans backend-mcp/src/ for tool definitions and verifies:
+ *
+ * 1. Every tool has a non-empty `description` field
+ * 2. Descriptions are meaningful (>20 chars, not just the tool name)
+ * 3. Tool names follow naming convention (snake_case)
+ *
+ * Severity: high — tools without descriptions are unusable for AI clients
+ */
+
+import { readdir, readFile, stat } from 'node:fs/promises'
+import { join, relative, extname } from 'node:path'
+
+export const meta = {
+  id: 'mcp-tool-docs',
+  name: 'MCP Tool Documentation',
+  category: 'codeQuality',
+  severity: 'high',
+  description: 'Ensures all MCP tool definitions have meaningful descriptions and follow naming conventions'
+}
+
+// ── Patterns ──────────────────────────────────────────
+
+// Match tool definition objects: { name: "...", description: "..." }
+// Handles both inline and multi-line definitions
+const TOOL_NAME_RE = /name:\s*["'`]([^"'`]+)["'`]/g
+const TOOL_DESC_RE = /description:\s*["'`]([^"'`]*)["'`]/g
+
+// snake_case check
+const SNAKE_CASE_RE = /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/
+
+// ── Scanner ───────────────────────────────────────────
+
+async function collectFiles(dir) {
+  const files = []
+  try {
+    const entries = await readdir(dir, { withFileTypes: true })
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name)
+      if (entry.isDirectory() && entry.name !== 'node_modules' && entry.name !== 'dist') {
+        files.push(...await collectFiles(fullPath))
+      } else if (['.ts', '.tsx', '.js'].includes(extname(entry.name))) {
+        files.push(fullPath)
+      }
+    }
+  } catch {
+    // Directory doesn't exist
+  }
+  return files
+}
+
+function extractTools(content) {
+  const tools = []
+
+  // Strategy 1: Find name/description pairs in tool definition objects
+  // Look for patterns like: { name: "tool_name", description: "..." }
+  const nameMatches = [...content.matchAll(TOOL_NAME_RE)]
+
+  for (const nameMatch of nameMatches) {
+    const name = nameMatch[1]
+    const namePos = nameMatch.index
+
+    // Look for a description within 500 chars of the name
+    const searchWindow = content.slice(Math.max(0, namePos - 200), namePos + 500)
+    const descMatch = searchWindow.match(/description:\s*["'`]([^"'`]*)["'`]/)
+
+    tools.push({
+      name,
+      description: descMatch ? descMatch[1] : null,
+      line: content.slice(0, namePos).split('\n').length,
+    })
+  }
+
+  return tools
+}
+
+function validateTool(tool) {
+  const violations = []
+
+  // Check name is snake_case
+  if (!SNAKE_CASE_RE.test(tool.name)) {
+    violations.push({
+      rule: 'tool-naming',
+      severity: 'medium',
+      message: `Tool "${tool.name}" should use snake_case naming`,
+    })
+  }
+
+  // Check description exists
+  if (!tool.description) {
+    violations.push({
+      rule: 'missing-description',
+      severity: 'high',
+      message: `Tool "${tool.name}" has no description — AI clients won't know what it does`,
+    })
+    return violations
+  }
+
+  // Check description is meaningful
+  if (tool.description.length < 20) {
+    violations.push({
+      rule: 'short-description',
+      severity: 'high',
+      message: `Tool "${tool.name}" description is too short (${tool.description.length} chars, min 20) — "${tool.description}"`,
+    })
+  }
+
+  // Check description isn't just the tool name
+  if (tool.description.toLowerCase().replace(/[_\s-]/g, '') === tool.name.toLowerCase().replace(/[_\s-]/g, '')) {
+    violations.push({
+      rule: 'lazy-description',
+      severity: 'high',
+      message: `Tool "${tool.name}" description just repeats the name — write what it does`,
+    })
+  }
+
+  return violations
+}
+
+// ── Main check ────────────────────────────────────────
+
+export async function run(config, projectRoot) {
+  const result = {
+    passed: true,
+    findings: [],
+    summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 },
+    details: { files: {}, totalTools: 0, totalViolations: 0, toolsWithoutDesc: 0 }
+  }
+
+  // Find MCP tool directories
+  const mcpDirs = [
+    join(projectRoot, 'backend-mcp', 'src', 'tools'),
+    join(projectRoot, 'backend-mcp', 'src'),
+    join(projectRoot, 'mcp', 'src', 'tools'),
+    join(projectRoot, 'src', 'tools'),
+  ]
+
+  let allFiles = []
+  for (const dir of mcpDirs) {
+    try {
+      await stat(dir)
+      allFiles.push(...await collectFiles(dir))
+    } catch {
+      // Directory doesn't exist, skip
+    }
+  }
+
+  if (allFiles.length === 0) return result // Not an MCP project
+
+  for (const filePath of allFiles) {
+    const content = await readFile(filePath, 'utf8')
+    const tools = extractTools(content)
+
+    if (tools.length === 0) continue
+
+    result.details.totalTools += tools.length
+    const fileViolations = []
+
+    for (const tool of tools) {
+      const violations = validateTool(tool)
+      if (violations.length > 0) {
+        fileViolations.push(...violations.map(v => ({ ...v, tool: tool.name, line: tool.line })))
+        if (violations.some(v => v.rule === 'missing-description')) {
+          result.details.toolsWithoutDesc++
+        }
+      }
+    }
+
+    if (fileViolations.length > 0) {
+      const rel = relative(projectRoot, filePath)
+      result.details.files[rel] = fileViolations
+      result.details.totalViolations += fileViolations.length
+
+      for (const v of fileViolations) {
+        result.summary[v.severity] = (result.summary[v.severity] || 0) + 1
+        result.summary.total++
+      }
+
+      result.findings.push({
+        type: `MCP tool docs in ${rel}`,
+        severity: fileViolations.some(v => v.severity === 'high') ? 'high' : 'medium',
+        message: `${fileViolations.length} issue(s): ${[...new Set(fileViolations.map(v => v.rule))].join(', ')}`,
+        files: fileViolations.map(v => `L${v.line}: [${v.rule}] ${v.message}`)
+      })
+    }
+  }
+
+  result.passed = result.summary.high === 0 && result.summary.critical === 0
+  return result
+}

package/lib/checks/index.js

@@ -22,6 +22,7 @@ export * as rpcGeneratorOrigin from './supabase/rpc-generator-origin.js'
 export * as uiTheming from './codeQuality/ui-theming.js'
 export * as barrelImportDetector from './codeQuality/barrel-import-detector.js'
 export * as typescriptStrictness from './codeQuality/typescript-strictness.js'
+export * as mcpToolDocs from './codeQuality/mcp-tool-docs.js'
 
 // Health checks (project ecosystem)
 export * as health from './health/index.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulbatical/tetra-dev-toolkit",
-  "version": "1.20.9",
+  "version": "1.20.10",
   "publishConfig": {
     "access": "restricted"
   },