verytis 0.1.1

package/LICENSE

@@ -0,0 +1,12 @@
+Copyright (c) 2026 Verytis. All rights reserved.
+
+This software and associated documentation files (the "Software") are proprietary and confidential to Verytis.
+
+You are granted a non-exclusive, non-transferable limited right to install and execute the binary package for its intended use as a client and Model Context Protocol (MCP) server for Verytis.
+
+You are NOT permitted to:
+1. Modify, reverse engineer, decompile, or disassemble the Software.
+2. Sublicense, rent, lease, or redistribute copies of the Software (or modified versions thereof) to third parties.
+3. Remove, alter, or obscure any copyright, trademark, or other proprietary notices from the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+
+## Getting Started
+
+First, run the development server:
+
+```bash
+npm run dev
+# or
+yarn dev
+# or
+pnpm dev
+# or
+bun dev
+```
+
+Open [https://www.verytis.com](https://www.verytis.com) with your browser to see the result.
+
+## CLI event storage
+
+To store events from another local project, generate a CLI key from Verytis Settings, then set:
+
+```bash
+export VERYTIS_API_URL="https://www.verytis.com"
+export VERYTIS_API_KEY="vt_live_xxxxx"
+verytis run "node fichier-inexistant.js"
+```
+
+The CLI also reads `VERYTIS_API_KEY` and `VERYTIS_API_URL` from the current project's `.env.local`.
+The key is sent as `Authorization: Bearer <vt_key>` and is not printed in CLI logs.
+
+You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+
+This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+
+## Learn More
+
+To learn more about Next.js, take a look at the following resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+
+You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+
+## Deploy on Vercel
+
+The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+
+Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "verytis",
+  "version": "0.1.1",
+  "license": "UNLICENSED",
+  "files": [
+    "packages"
+  ],
+  "bin": {
+    "verytis": "packages/cli/bin/verytis.mjs"
+  },
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint",
+    "test": "vitest run",
+    "mcp:verytis": "tsx packages/mcp/server.ts"
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.4.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@supabase/ssr": "^0.10.3",
+    "@supabase/supabase-js": "^2.105.4",
+    "@vercel/analytics": "^2.0.1",
+    "@vercel/speed-insights": "^2.0.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "date-fns": "^4.1.0",
+    "dotenv": "^16.4.7",
+    "lucide-react": "^1.14.0",
+    "next": "16.2.6",
+    "openai": "^6.37.0",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "react-markdown": "^10.1.0",
+    "rehype-highlight": "^7.0.2",
+    "shadcn": "^4.7.0",
+    "tailwind-merge": "^3.6.0",
+    "tsx": "^4.22.0",
+    "tw-animate-css": "^1.4.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "16.2.6",
+    "tailwindcss": "^4",
+    "typescript": "^5",
+    "vitest": "^4.1.6"
+  }
+}

package/packages/cli/bin/verytis.mjs

@@ -0,0 +1,517 @@
+#!/usr/bin/env node
+
+import { spawn, spawnSync } from "node:child_process"
+import { createHash } from "node:crypto"
+import { existsSync, readFileSync } from "node:fs"
+import path from "node:path"
+
+const MAX_LOG_CHARS = 50000
+
+function usage() {
+  console.log('Usage: verytis run "npm run build" [--api-key <vt_key>] [--error-id <id>] [--fix-id <id>] [--before-fingerprint <fingerprint>]')
+  console.log('       verytis mcp            (start the MCP stdio server)')
+  console.log("Auth: set VERYTIS_API_KEY=vt_... in your shell or project .env.local")
+  console.log("API URL: set VERYTIS_API_URL=https://www.verytis.com (or custom URL)")
+  console.log("       verytis --version")
+}
+
+function readCliVersion() {
+  try {
+    const packageJson = JSON.parse(readFileSync(new URL("../../../package.json", import.meta.url), "utf8"))
+    return packageJson.version || "0.0.0"
+  } catch {
+    return "0.0.0"
+  }
+}
+
+function parseArgs(argv) {
+  const [commandName, ...rest] = argv
+
+  if (commandName === "mcp") {
+    return { commandName, command: "mcp", options: {} }
+  }
+
+  if (commandName !== "run") {
+    return { commandName, command: "", options: {} }
+  }
+
+  const commandParts = []
+  const options = {}
+
+  for (let index = 0; index < rest.length; index += 1) {
+    const value = rest[index]
+
+    if (value === "--api-url") {
+      options.apiUrl = rest[index + 1]
+      index += 1
+    } else if (value === "--api-key") {
+      options.apiKey = rest[index + 1]
+      index += 1
+    } else if (value === "--error-id") {
+      options.errorId = rest[index + 1]
+      index += 1
+    } else if (value === "--fix-id") {
+      options.fixId = rest[index + 1]
+      index += 1
+    } else if (value === "--before-fingerprint") {
+      options.beforeFingerprint = rest[index + 1]
+      index += 1
+    } else {
+      commandParts.push(value)
+    }
+  }
+
+  return {
+    commandName,
+    command: commandParts.join(" ").trim(),
+    options,
+  }
+}
+
+function parseEnvFileValue(rawValue) {
+  const value = rawValue.trim()
+  const withoutComment = value
+    .replace(/\s+#.*$/, "")
+    .trim()
+
+  if (
+    (withoutComment.startsWith('"') && withoutComment.endsWith('"')) ||
+    (withoutComment.startsWith("'") && withoutComment.endsWith("'"))
+  ) {
+    return withoutComment.slice(1, -1)
+  }
+
+  return withoutComment
+}
+
+function readLocalCliEnv() {
+  const values = {}
+  const envFiles = [".env", ".env.local"]
+
+  for (const envFile of envFiles) {
+    const envPath = path.join(process.cwd(), envFile)
+
+    if (!existsSync(envPath)) {
+      continue
+    }
+
+    try {
+      const contents = readFileSync(envPath, "utf8")
+
+      for (const line of contents.split(/\r?\n/)) {
+        const match = line.match(/^\s*(?:export\s+)?(VERYTIS_API_KEY|VERYTIS_API_URL|FIXGRAPH_API_KEY|FIXGRAPH_API_URL)\s*=\s*(.*)\s*$/)
+
+        if (!match) {
+          continue
+        }
+
+        values[match[1]] = parseEnvFileValue(match[2])
+      }
+    } catch {
+      // Ignore unreadable local env files; explicit shell env and flags still work.
+    }
+  }
+
+  return values
+}
+
+function resolveCliConfig(options) {
+  const localEnv = readLocalCliEnv()
+
+  return {
+    apiKey: options.apiKey || process.env.VERYTIS_API_KEY || localEnv.VERYTIS_API_KEY || process.env.FIXGRAPH_API_KEY || localEnv.FIXGRAPH_API_KEY || null,
+    apiUrl:
+      options.apiUrl ||
+      process.env.VERYTIS_API_URL ||
+      localEnv.VERYTIS_API_URL ||
+      process.env.FIXGRAPH_API_URL ||
+      localEnv.FIXGRAPH_API_URL ||
+      "https://www.verytis.com",
+  }
+}
+
+function runGit(args) {
+  const result = spawnSync("git", args, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  })
+
+  if (result.status !== 0) {
+    return null
+  }
+
+  return result.stdout.trim()
+}
+
+function captureGitState() {
+  const insideTree = runGit(["rev-parse", "--is-inside-work-tree"])
+
+  if (insideTree !== "true") {
+    return {
+      available: false,
+      changedFiles: [],
+      diffStat: null,
+    }
+  }
+
+  const changedFiles = (runGit(["diff", "--name-only"]) ?? "")
+    .split("\n")
+    .map((filePath) => filePath.trim())
+    .filter(Boolean)
+  const diffStat = runGit(["diff", "--shortstat"]) || null
+
+  return {
+    available: true,
+    changedFiles,
+    diffStat,
+  }
+}
+
+function categorizeChangedFile(filePath) {
+  const normalized = filePath.replace(/\\/g, "/").toLowerCase()
+  const fileName = normalized.split("/").pop() || normalized
+
+  if (
+    fileName === "tsconfig.json" ||
+    fileName.startsWith("next.config") ||
+    fileName.startsWith("eslint") ||
+    fileName.startsWith(".eslintrc") ||
+    fileName.startsWith("tailwind.config") ||
+    fileName.startsWith("postcss.config") ||
+    fileName.startsWith("vercel.") ||
+    fileName === ".env.example" ||
+    fileName.endsWith(".env.example")
+  ) {
+    return "config"
+  }
+
+  if (
+    fileName === "package.json" ||
+    fileName === "package-lock.json" ||
+    fileName === "pnpm-lock.yaml" ||
+    fileName === "yarn.lock"
+  ) {
+    return "dependency"
+  }
+
+  if (
+    normalized.includes("supabase/migrations/") ||
+    normalized.includes("/prisma/") ||
+    normalized.startsWith("prisma/") ||
+    normalized.endsWith(".sql")
+  ) {
+    return "database"
+  }
+
+  if (normalized.includes("/app/api/") || normalized.startsWith("app/api/") || normalized.includes("/pages/api/")) {
+    return "api_route"
+  }
+
+  if (
+    normalized.includes("/lib/supabase/") ||
+    normalized.includes("/lib/stripe/") ||
+    normalized.includes("/lib/auth/") ||
+    normalized.includes("/lib/openai/") ||
+    normalized.startsWith("lib/supabase/") ||
+    normalized.startsWith("lib/stripe/") ||
+    normalized.startsWith("lib/auth/") ||
+    normalized.startsWith("lib/openai/")
+  ) {
+    return "integration"
+  }
+
+  if (
+    normalized.includes("__tests__/") ||
+    normalized.includes("/test/") ||
+    normalized.includes("/tests/") ||
+    normalized.includes(".test.") ||
+    normalized.includes(".spec.")
+  ) {
+    return "test"
+  }
+
+  if (
+    normalized.includes("/components/") ||
+    normalized.startsWith("components/") ||
+    normalized.includes("/app/") ||
+    normalized.startsWith("app/") ||
+    normalized.endsWith(".jsx") ||
+    normalized.endsWith(".tsx")
+  ) {
+    return "ui"
+  }
+
+  return "unknown"
+}
+
+function categorizeChangedFiles(filePaths) {
+  return Array.from(new Set(filePaths.map(categorizeChangedFile))).sort()
+}
+
+function redactSecrets(input) {
+  return input
+    .replace(/https?:\/\/[^/\s:@]+:[^/\s@]+@/gi, "https://[REDACTED]@")
+    .replace(/\bOPENAI_API_KEY\s*=\s*[^\s]+/gi, "OPENAI_API_KEY=[REDACTED]")
+    .replace(/\b(?:NEXT_PUBLIC_)?SUPABASE(?:_[A-Z]+)*_KEY\s*=\s*[^\s]+/gi, "SUPABASE_KEY=[REDACTED]")
+    .replace(/\bDATABASE_URL\s*=\s*[^\s]+/gi, "DATABASE_URL=[REDACTED]")
+    .replace(/\bJWT_SECRET\s*=\s*[^\s]+/gi, "JWT_SECRET=[REDACTED]")
+    .replace(/\b[A-Z0-9_]*(?:API_)?(?:KEY|TOKEN|SECRET|PASSWORD|PWD)\s*=\s*[^\s]+/gi, "[SECRET]=[REDACTED]")
+    .replace(/"[^"]*(?:key|token|secret|password|pwd)[^"]*"\s*:\s*"[^"]*"/gi, '"[SECRET]":"[REDACTED]"')
+    .replace(/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, "PRIVATE_KEY=[REDACTED]")
+    .replace(/\bPRIVATE_KEY\s*=\s*[^\n]+/gi, "PRIVATE_KEY=[REDACTED]")
+    .replace(/\bsk-[A-Za-z0-9_-]{16,}\b/g, "sk-[REDACTED]")
+    .replace(/\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{16,}\b/g, "github_[REDACTED]")
+    .replace(/\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, "github_pat_[REDACTED]")
+    .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]{16,}/gi, "Bearer [REDACTED]")
+    .replace(/\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi, "[EMAIL_REDACTED]")
+    .replace(/\b[A-Za-z]:\\Users\\[^\\\s:)'"`]+(?:\\[^\\\s:)'"`]+)*/g, "[path]")
+    .replace(/\b[A-Za-z]:\\[^\\\s:)'"`]+(?:\\[^\\\s:)'"`]+)*/g, "[path]")
+    .replace(/\/Users\/[^\s:)'"`]+/g, "[path]")
+    .replace(/\/home\/[^\s:)'"`]+/g, "[path]")
+    .replace(/\/private\/var\/[^\s:)'"`]+/g, "[path]")
+}
+
+function createErrorFingerprint(errorMessage) {
+  const normalized = errorMessage
+    .toLowerCase()
+    .replace(/\b(line|column|col)\s+\d+\b/g, "$1")
+    .replace(/:\d+:\d+/g, "")
+    .replace(/:\d+/g, "")
+    .replace(/(?:[A-Za-z]:)?(?:\/|\\)[\w./\\-]+/g, "[path]")
+    .replace(/\b[\w.-]+\.(ts|tsx|js|jsx|mjs|cjs|json|css|scss)\b/g, "[file]")
+    .replace(/\s+/g, " ")
+    .trim()
+
+  if (!normalized) {
+    return null
+  }
+
+  return createHash("sha256").update(normalized).digest("hex").slice(0, 16)
+}
+
+function extractFirstUsefulErrorBlock(output) {
+  const lines = output
+    .split(/\r?\n/)
+    .map((line) => line.trimEnd())
+    .filter((line) => line.trim().length > 0)
+  const startIndex = lines.findIndex((line) =>
+    /(error|failed|exception|module not found|type error|cannot find|permission denied)/i.test(line)
+  )
+
+  if (startIndex === -1) {
+    return lines.slice(0, 12).join("\n").slice(0, 4000)
+  }
+
+  return lines.slice(startIndex, startIndex + 10).join("\n").slice(0, 4000)
+}
+
+function readPackageContext() {
+  const packageJsonPath = path.join(process.cwd(), "package.json")
+
+  if (!existsSync(packageJsonPath)) {
+    return {}
+  }
+
+  try {
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"))
+    const dependencies = {
+      ...(packageJson.dependencies ?? {}),
+      ...(packageJson.devDependencies ?? {}),
+    }
+    const trackedPackages = [
+      "next",
+      "react",
+      "typescript",
+      "@supabase/supabase-js",
+      "@supabase/ssr",
+      "zod",
+      "openai",
+      "stripe",
+    ]
+    const packageVersions = Object.fromEntries(
+      trackedPackages
+        .filter((packageName) => dependencies[packageName])
+        .map((packageName) => [packageName, dependencies[packageName]])
+    )
+
+    return { packageVersions }
+  } catch {
+    return {}
+  }
+}
+
+function runCommand(command) {
+  return new Promise((resolve) => {
+    const startedAt = Date.now()
+    const child = spawn(command, {
+      shell: true,
+      stdio: ["inherit", "pipe", "pipe"],
+      env: process.env,
+    })
+    const stdoutChunks = []
+    const stderrChunks = []
+
+    child.stdout.on("data", (chunk) => {
+      process.stdout.write(chunk)
+      stdoutChunks.push(Buffer.from(chunk))
+    })
+
+    child.stderr.on("data", (chunk) => {
+      process.stderr.write(chunk)
+      stderrChunks.push(Buffer.from(chunk))
+    })
+
+    child.on("close", (code) => {
+      resolve({
+        exitCode: code,
+        status: code === 0 ? "passed" : "failed",
+        durationMs: Date.now() - startedAt,
+        stdout: Buffer.concat(stdoutChunks).toString("utf8").slice(0, MAX_LOG_CHARS),
+        stderr: Buffer.concat(stderrChunks).toString("utf8").slice(0, MAX_LOG_CHARS),
+      })
+    })
+  })
+}
+
+async function postCliEvent(apiUrl, payload, apiKey) {
+  const endpoint = `${apiUrl.replace(/\/$/, "")}/api/cli/events`
+  const headers = { "Content-Type": "application/json" }
+
+  if (!apiKey) {
+    throw new Error(
+      "Verytis could not store this event because the CLI is not authenticated. Set VERYTIS_API_KEY to a valid vt_ key, add it to project .env.local, or pass --api-key."
+    )
+  }
+
+  if (apiKey) {
+    headers.Authorization = `Bearer ${apiKey}`
+  }
+
+  const response = await fetch(endpoint, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(payload),
+  })
+
+  const data = await response.json().catch(() => null)
+
+  if (response.status === 401) {
+    throw new Error(
+      "Verytis could not store this event because the CLI is not authenticated. Set VERYTIS_API_KEY to a valid vt_ key, add it to project .env.local, or pass --api-key."
+    )
+  }
+
+  if (!response.ok) {
+    throw new Error(data?.error || `Verytis event failed with HTTP ${response.status}`)
+  }
+
+  return data
+}
+
+function printEventSummary(metadata, result) {
+  const categories = metadata.changeCategories.length > 0 ? metadata.changeCategories.join(", ") : "none"
+
+  console.log("")
+  console.log("Verytis event")
+  console.log(`- command status: ${metadata.status}`)
+  console.log(`- stored: ${result.stored ? "yes" : "no"}`)
+  console.log(`- changed files: ${metadata.changedFiles.length}`)
+  console.log(`- categories: ${categories}`)
+  console.log(`- diff stat: ${metadata.diffStat || "none"}`)
+  console.log(`- created new error: ${metadata.createdNewError ? "yes" : "no"}`)
+}
+
+async function main() {
+  const argv = process.argv.slice(2)
+
+  if (argv[0] === "--version" || argv[0] === "-v") {
+    console.log(readCliVersion())
+    process.exit(0)
+  }
+
+  if (argv[0] === "--help" || argv[0] === "-h") {
+    usage()
+    process.exit(0)
+  }
+
+  const { commandName, command, options } = parseArgs(argv)
+
+  if (commandName === "mcp") {
+    const serverPath = new URL("../../mcp/server.ts", import.meta.url).pathname
+    const child = spawn("npx", ["tsx", serverPath], {
+      stdio: "inherit",
+      env: process.env,
+    })
+    child.on("close", (code) => {
+      process.exit(code ?? 0)
+    })
+    return
+  }
+
+  if (commandName !== "run" || !command) {
+    usage()
+    process.exit(commandName === "run" ? 1 : 0)
+  }
+
+  const beforeGitState = captureGitState()
+  const commandResult = await runCommand(command)
+  const eventCommand = redactSecrets(command)
+  const afterGitState = captureGitState()
+  const combinedOutput = `${commandResult.stderr}\n${commandResult.stdout}`
+  const redactedStdout = redactSecrets(commandResult.stdout)
+  const redactedStderr = redactSecrets(commandResult.stderr)
+  const errorBlock =
+    commandResult.status === "failed" ? extractFirstUsefulErrorBlock(redactSecrets(combinedOutput)) : ""
+  const beforeErrorFingerprint =
+    options.beforeFingerprint || process.env.FIXGRAPH_ERROR_FINGERPRINT || null
+  const afterErrorFingerprint =
+    commandResult.status === "failed" ? createErrorFingerprint(errorBlock) : null
+  const errorFingerprint = beforeErrorFingerprint || afterErrorFingerprint
+  const changedFiles = afterGitState.available ? afterGitState.changedFiles : beforeGitState.changedFiles
+  const changeCategories = categorizeChangedFiles(changedFiles)
+  const metadata = {
+    command: eventCommand,
+    status: commandResult.status,
+    exitCode: commandResult.exitCode,
+    durationMs: commandResult.durationMs,
+    stdout: redactedStdout,
+    stderr: redactedStderr,
+    redacted:
+      eventCommand !== command ||
+      redactedStdout !== commandResult.stdout ||
+      redactedStderr !== commandResult.stderr,
+    sourceCodeCollected: false,
+    packageContext: readPackageContext(),
+    changedFiles,
+    changeCategories,
+    diffStat: afterGitState.diffStat,
+    errorFingerprint,
+    createdNewError: Boolean(
+      beforeErrorFingerprint && afterErrorFingerprint && beforeErrorFingerprint !== afterErrorFingerprint
+    ),
+    afterErrorFingerprint,
+    source: "cli",
+  }
+  const cliConfig = resolveCliConfig(options)
+  const payload = {
+    errorId: options.errorId || process.env.FIXGRAPH_ERROR_ID || undefined,
+    fixId: options.fixId || process.env.FIXGRAPH_FIX_ID || undefined,
+    ...metadata,
+  }
+
+  try {
+    const result = await postCliEvent(cliConfig.apiUrl, payload, cliConfig.apiKey)
+    printEventSummary(result.metadata ?? metadata, result)
+  } catch (error) {
+    console.warn("")
+    console.warn(`Verytis event was not stored: ${error instanceof Error ? error.message : String(error)}`)
+    printEventSummary(metadata, { stored: false })
+  }
+
+  process.exit(commandResult.exitCode ?? 1)
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error)
+  process.exit(1)
+})

package/packages/mcp/retrieval.ts

@@ -0,0 +1,432 @@
+const SEARCH_CAUTION = "Similar cases are not guaranteed to have the same root cause."
+const VARIANT_CAUTION = "Worked in similar cases, not guaranteed for this case."
+const PRIVACY_NOTE = "This payload is anonymized and does not include raw user data."
+
+export type SimilarityLevel = "high" | "medium" | "low"
+
+// --- Sanitized types for FixGraph API responses (no raw events, no private fields) ---
+
+type ApiSearchError = {
+  id?: string
+  slug?: string
+  title?: string
+  errorMessage?: string
+  fingerprint?: string
+  stack?: string[]
+  probableCause?: string
+  relatedCasesCount?: number
+}
+
+type ApiSearchFix = {
+  summary?: string
+  steps?: string[] | null
+  validationCount?: number
+  buildPassedCount?: number
+  testPassedCount?: number
+  confidenceScore?: number
+}
+
+type ApiSearchResult = {
+  error?: ApiSearchError
+  bestFix?: ApiSearchFix
+}
+
+type ApiPatternVariant = {
+  title?: string
+  category?: string
+  similarity?: string
+  sharedSignals?: string[]
+  keyDifferences?: string[]
+  occurrenceCount?: number
+  commonEnvironment?: string | null
+  possibleFix?: string | null
+}
+
+type ApiPatternFix = {
+  summary?: string
+  steps?: string[] | null
+  similarity?: string
+  confirmationCount?: number
+  confidenceScore?: number
+}
+
+type ApiPattern = {
+  fingerprint?: string
+  title?: string
+  category?: string
+  explanation?: string
+  occurrenceCount?: number
+  commonEnvironments?: string[]
+  variants?: ApiPatternVariant[]
+  fixes?: ApiPatternFix[]
+}
+
+type ApiBundle = {
+  error?: ApiSearchError
+  fixes?: ApiSearchFix[]
+  bestFix?: ApiSearchFix
+}
+
+type ApiErrorResponse = {
+  pattern?: ApiPattern
+} & ApiBundle
+
+// --- HTTP helpers ---
+
+const FETCH_TIMEOUT_MS = 12_000
+
+function getApiBase(): string {
+  return (process.env.VERYTIS_API_URL ?? process.env.FIXGRAPH_API_URL ?? "https://www.verytis.com").replace(/\/$/, "")
+}
+
+function apiHeaders(): Record<string, string> {
+  const headers: Record<string, string> = { "Content-Type": "application/json" }
+  const key = process.env.VERYTIS_API_KEY ?? process.env.FIXGRAPH_API_KEY
+  // Never log the key itself
+  if (key) headers["Authorization"] = `Bearer ${key}`
+  return headers
+}
+
+function debugLog(message: string): void {
+  process.stderr.write(`[verytis-mcp] ${message}\n`)
+}
+
+async function apiGet(urlPath: string): Promise<{ data: unknown; status: number }> {
+  const url = `${getApiBase()}${urlPath}`
+  debugLog(`GET ${url}`)
+  const response = await fetch(url, {
+    headers: apiHeaders(),
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+  })
+  debugLog(`status ${response.status} for ${urlPath}`)
+  if (!response.ok) {
+    throw new Error(`Verytis API ${response.status}: ${response.statusText}`)
+  }
+  const data = await response.json()
+  return { data, status: response.status }
+}
+
+// --- Token similarity ---
+
+function tokenize(text: string): Set<string> {
+  const stopwords = new Set(["the", "and", "for", "not", "with", "this", "that"])
+  return new Set(
+    text
+      .toLowerCase()
+      .replace(/[^a-z0-9\s@.-]/g, " ")
+      .split(/\s+/)
+      .map((t) => t.trim())
+      .filter((t) => t.length >= 3 && !stopwords.has(t))
+  )
+}
+
+function jaccard(a: Set<string>, b: Set<string>): number {
+  if (a.size === 0 || b.size === 0) return 0
+  let intersection = 0
+  a.forEach((token) => {
+    if (b.has(token)) intersection++
+  })
+  return intersection / (a.size + b.size - intersection)
+}
+
+function computeSimilarity(query: string, title = "", errorMessage = ""): SimilarityLevel {
+  const queryTokens = tokenize(query)
+  const textTokens = tokenize(`${title} ${errorMessage}`)
+  const score = jaccard(queryTokens, textTokens)
+  if (score >= 0.3) return "high"
+  if (score >= 0.1) return "medium"
+  return "low"
+}
+
+function normalizeSimilarity(level: string | undefined): SimilarityLevel {
+  if (level?.toLowerCase() === "high") return "high"
+  if (level?.toLowerCase() === "low") return "low"
+  return "medium"
+}
+
+// --- Signal extraction ---
+
+const FRAMEWORK_TAGS = new Set([
+  "next", "nextjs", "react", "vue", "nuxt", "angular",
+  "svelte", "astro", "remix", "vite",
+])
+const RUNTIME_TAGS = new Set(["node", "nodejs", "deno", "bun", "browser"])
+
+function categorizeStack(stack: string[]): { frameworks: string[]; runtimes: string[] } {
+  const frameworks: string[] = []
+  const runtimes: string[] = []
+  for (const tag of stack) {
+    const lower = tag.toLowerCase()
+    if (FRAMEWORK_TAGS.has(lower)) frameworks.push(tag)
+    else if (RUNTIME_TAGS.has(lower)) runtimes.push(tag)
+  }
+  return { frameworks, runtimes }
+}
+
+function inferCategory(title: string): string | null {
+  const lower = title.toLowerCase()
+  if (/module|import|require|resolve/.test(lower)) return "Module resolution"
+  if (/export|no exported member/.test(lower)) return "Missing export"
+  if (/typescript|cannot find name|property.*does not exist/.test(lower)) return "TypeScript"
+  if (/permission|denied|access/.test(lower)) return "Permissions"
+  if (/connection|econnrefused|network/.test(lower)) return "Connection"
+  if (/syntax|unexpected token/.test(lower)) return "Syntax error"
+  return null
+}
+
+function extractSharedSignals(
+  query: string,
+  error: ApiSearchError,
+  fix: ApiSearchFix | undefined
+): string[] {
+  const signals: string[] = []
+  const queryTokens = tokenize(query)
+  const errorTokens = tokenize(`${error.title ?? ""} ${error.errorMessage ?? ""}`)
+  const matched = [...queryTokens].filter((t) => errorTokens.has(t)).slice(0, 4)
+  if (matched.length > 0) signals.push(`Matched terms: ${matched.join(", ")}`)
+
+  const { frameworks, runtimes } = categorizeStack(error.stack ?? [])
+  if (frameworks.length > 0) signals.push(`Framework: ${frameworks.join(", ")}`)
+  if (runtimes.length > 0) signals.push(`Runtime: ${runtimes.join(", ")}`)
+
+  const category = inferCategory(error.title ?? "")
+  if (category) signals.push(`Error category: ${category}`)
+
+  const validations = fix?.validationCount ?? 0
+  if (validations > 0) signals.push(`Validated fix available (${validations} validations)`)
+
+  return signals.slice(0, 6)
+}
+
+// --- Safe text helpers ---
+
+import { sanitizePublicText } from "@/lib/fixgraph/redact-secrets"
+
+function safeText(text: string | null | undefined, maxLength = 500): string {
+  if (!text) return ""
+  return sanitizePublicText(text, maxLength)
+}
+
+function safePossibleFixes(fix: ApiSearchFix | undefined): string[] {
+  if (!fix) return []
+  const parts: string[] = []
+  if (fix.summary) parts.push(safeText(fix.summary, 1000))
+  for (const step of (fix.steps ?? []).slice(0, 6)) {
+    const clean = safeText(step, 1000)
+    if (clean) parts.push(clean)
+  }
+  return parts.filter(Boolean).slice(0, 8)
+}
+
+// --- Result mapping ---
+
+export type McpSearchResult = {
+  pattern_id: string
+  title: string
+  category: string | null
+  similarity: SimilarityLevel
+  shared_signals: string[]
+  key_differences: string[]
+  occurrences: number
+  common_environment: string[]
+  possible_fixes: string[]
+  caution: string
+}
+
+export type McpSearchResponse = {
+  query: string
+  results: McpSearchResult[]
+}
+
+function apiResultsToMcp(
+  params: SearchParams,
+  raw: unknown
+): McpSearchResult[] {
+  const allResults: ApiSearchResult[] = Array.isArray(raw) ? raw : []
+  const limit = Math.min(params.limit ?? 10, 20)
+
+  // Client-side framework/runtime filter — fall back to all if filter empties the set
+  let filtered = allResults.filter((r) => {
+    if (!r.error) return false
+    const stack = (r.error.stack ?? []).map((s) => s.toLowerCase())
+    if (params.framework && !stack.some((s) => s.includes(params.framework!.toLowerCase()))) return false
+    if (params.runtime && !stack.some((s) => s.includes(params.runtime!.toLowerCase()))) return false
+    return true
+  })
+  if (filtered.length === 0) filtered = allResults.filter((r) => Boolean(r.error))
+
+  return filtered.slice(0, limit).map((r) => {
+    const error = r.error ?? {}
+    const fix = r.bestFix
+    return {
+      pattern_id: sanitizePublicText(error.fingerprint ?? error.slug ?? error.id ?? "unknown", 256),
+      title: safeText(error.title, 1000) || "Unknown error pattern",
+      category: safeText(inferCategory(error.title ?? "")),
+      similarity: computeSimilarity(params.query, error.title, error.errorMessage),
+      shared_signals: extractSharedSignals(params.query, error, fix).map((s) => safeText(s, 500)),
+      key_differences: [].map((d) => safeText(d, 500)),
+      occurrences: Number(error.relatedCasesCount ?? 0),
+      common_environment: (error.stack ?? []).slice(0, 4).map((e) => safeText(e, 200)),
+      possible_fixes: safePossibleFixes(fix),
+      caution: safeText(SEARCH_CAUTION),
+    } satisfies McpSearchResult
+  })
+}
+
+// --- Public search function (with MCP-endpoint primary + public fallback) ---
+
+export type SearchParams = {
+  query: string
+  framework?: string
+  runtime?: string
+  command?: string
+  limit?: number
+}
+
+async function tryMcpSearch(params: SearchParams): Promise<McpSearchResult[]> {
+  const encoded = encodeURIComponent(params.query)
+  const limit = Math.min(params.limit ?? 10, 20)
+  const { data } = await apiGet(`/api/mcp/search?q=${encoded}&limit=${limit}`)
+  const results = apiResultsToMcp(params, data)
+  debugLog(`mcp/search: ${results.length} results after scoring`)
+  return results
+}
+
+async function tryPublicSearch(params: SearchParams): Promise<McpSearchResult[]> {
+  const encoded = encodeURIComponent(params.query)
+  const { data } = await apiGet(`/api/search?q=${encoded}`)
+  const results = apiResultsToMcp(params, data)
+  debugLog(`api/search: ${results.length} results after scoring`)
+  return results
+}
+
+export async function searchVerytisErrors(params: SearchParams): Promise<McpSearchResponse> {
+  let results: McpSearchResult[] = []
+
+  // Primary: MCP-dedicated endpoint uses service client (bypasses RLS)
+  try {
+    results = await tryMcpSearch(params)
+  } catch (err) {
+    debugLog(`mcp/search failed: ${err instanceof Error ? err.message : String(err)}`)
+  }
+
+  // Fallback: public search endpoint (anon client, only reads public tables)
+  if (results.length === 0) {
+    debugLog(`mcp/search returned empty — trying public search fallback`)
+    try {
+      results = await tryPublicSearch(params)
+    } catch (err) {
+      debugLog(`api/search failed: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+
+  debugLog(`search complete: ${results.length} total results for query "${params.query.slice(0, 80)}"`)
+  return { query: params.query, results }
+}
+
+// --- Public context function ---
+
+export type McpSimilarCase = {
+  variant_title: string
+  similarity: SimilarityLevel
+  shared_signals: string[]
+  key_differences: string[]
+  observed_fixes: string[]
+  caution: string
+}
+
+export type McpContextResponse = {
+  pattern_id: string
+  title: string
+  summary: string
+  similar_cases: McpSimilarCase[]
+  common_causes: string[]
+  possible_fixes: string[]
+  privacy_note: string
+}
+
+function patternToContext(pattern: ApiPattern, patternId: string): McpContextResponse {
+  const fixes = pattern.fixes ?? []
+  const variants = pattern.variants ?? []
+
+  const possibleFixes: string[] = []
+  for (const fix of fixes.slice(0, 5)) {
+    if (fix.summary) possibleFixes.push(safeText(fix.summary, 1000))
+    for (const step of (fix.steps ?? []).slice(0, 4)) {
+      const clean = safeText(step, 1000)
+      if (clean) possibleFixes.push(clean)
+    }
+  }
+
+  const similarCases: McpSimilarCase[] = variants.slice(0, 8).map((v) => ({
+    variant_title: safeText(v.title, 1000) || "Comparable case",
+    similarity: normalizeSimilarity(v.similarity),
+    shared_signals: (v.sharedSignals ?? []).slice(0, 5).map((s) => safeText(s, 500)),
+    key_differences: (v.keyDifferences ?? []).slice(0, 4).map((d) => safeText(d, 500)),
+    observed_fixes: v.possibleFix ? [safeText(v.possibleFix, 1000)] : [],
+    caution: safeText(VARIANT_CAUTION),
+  }))
+
+  return {
+    pattern_id: sanitizePublicText(pattern.fingerprint ?? patternId, 256),
+    title: safeText(pattern.title, 1000) || "Unknown error pattern",
+    summary: safeText(pattern.explanation, 3000) || "",
+    similar_cases: similarCases,
+    common_causes: pattern.explanation ? [safeText(pattern.explanation, 3000)] : [],
+    possible_fixes: possibleFixes.filter(Boolean).slice(0, 10),
+    privacy_note: safeText(PRIVACY_NOTE),
+  }
+}
+
+function bundleToContext(bundle: ApiBundle, patternId: string): McpContextResponse {
+  const error = bundle.error ?? {}
+  const allFixes = bundle.fixes ?? []
+  const best = bundle.bestFix ?? allFixes[0]
+
+  const possibleFixes: string[] = []
+  if (best?.summary) possibleFixes.push(safeText(best.summary, 1000))
+  for (const step of (best?.steps ?? []).slice(0, 6)) {
+    const clean = safeText(step, 1000)
+    if (clean) possibleFixes.push(clean)
+  }
+
+  return {
+    pattern_id: sanitizePublicText(error.fingerprint ?? patternId, 256),
+    title: safeText(error.title, 1000) || "Unknown error pattern",
+    summary: safeText(error.probableCause, 3000) || "",
+    similar_cases: [],
+    common_causes: error.probableCause ? [safeText(error.probableCause, 3000)] : [],
+    possible_fixes: possibleFixes.filter(Boolean).slice(0, 10),
+    privacy_note: safeText(PRIVACY_NOTE),
+  }
+}
+
+export async function getVerytisContext(patternId: string): Promise<McpContextResponse> {
+  debugLog(`GET /api/errors/${patternId}`)
+  const { data } = await apiGet(`/api/errors/${encodeURIComponent(patternId)}`)
+  debugLog(`context response received for pattern: ${patternId}`)
+
+  if (!data || typeof data !== "object") {
+    throw new Error(`No context found for pattern: ${patternId}`)
+  }
+
+  const response = data as ApiErrorResponse
+
+  if ("pattern" in response && response.pattern) {
+    const ctx = patternToContext(response.pattern, patternId)
+    debugLog(
+      `context: ${ctx.similar_cases.length} similar cases, ${ctx.possible_fixes.length} possible fixes`
+    )
+    return ctx
+  }
+
+  if ("error" in response && response.error) {
+    const ctx = bundleToContext(response as ApiBundle, patternId)
+    debugLog(
+      `context (bundle): ${ctx.common_causes.length} causes, ${ctx.possible_fixes.length} possible fixes`
+    )
+    return ctx
+  }
+
+  throw new Error(`Unexpected API response for pattern: ${patternId}`)
+}

package/packages/mcp/server.ts

@@ -0,0 +1,84 @@
+import path from "node:path"
+import { config as dotenvConfig } from "dotenv"
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
+import { z } from "zod"
+
+import { searchVerytisErrors, getVerytisContext } from "./retrieval"
+
+// Load env vars from project root (.env.local takes precedence over .env)
+const projectRoot = path.resolve(process.cwd())
+dotenvConfig({ path: path.join(projectRoot, ".env.local"), override: false })
+dotenvConfig({ path: path.join(projectRoot, ".env"), override: false })
+
+const server = new McpServer({
+  name: "verytis",
+  version: "0.1.0",
+})
+
+server.tool(
+  "search_verytis_errors",
+  [
+    "Search Verytis for similar historical error patterns before attempting a fix.",
+    "Returns anonymized, agent-friendly context: similarity signals, observed environments, occurrence counts, and possible fix approaches.",
+    "Do not assume similar cases have the same root cause. Use results as investigation guidance only.",
+  ].join(" "),
+  {
+    query: z.string().min(1).max(5000).describe(
+      "Error message, stack trace summary, or description of the error"
+    ),
+    framework: z.string().max(100).optional().describe(
+      "Framework to filter by (e.g. 'next', 'react', 'vue', 'nuxt')"
+    ),
+    runtime: z.string().max(100).optional().describe(
+      "Runtime to filter by (e.g. 'node', 'bun', 'deno')"
+    ),
+    command: z.string().max(500).optional().describe(
+      "Command that failed (e.g. 'npm run build', 'npx tsc')"
+    ),
+    limit: z.number().int().min(1).max(20).optional().describe(
+      "Maximum results to return (default 10, max 20)"
+    ),
+  },
+  async (args) => {
+    const result = await searchVerytisErrors(args)
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    }
+  }
+)
+
+server.tool(
+  "get_verytis_context",
+  [
+    "Retrieve a full anonymized context bundle for a single error pattern.",
+    "Use the pattern_id value from search_verytis_errors results.",
+    "Returns similar historical cases, common causes, and observed fix approaches.",
+    "No raw source code, user data, or private paths are included.",
+  ].join(" "),
+  {
+    pattern_id: z.string().min(1).max(256).describe(
+      "Pattern ID (fingerprint or slug) from search_verytis_errors results"
+    ),
+  },
+  async (args) => {
+    const result = await getVerytisContext(args.pattern_id)
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    }
+  }
+)
+
+async function main() {
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+  process.stderr.write(
+    `[verytis-mcp] connected — API: ${process.env.VERYTIS_API_URL ?? process.env.FIXGRAPH_API_URL ?? "https://www.verytis.com (default)"}\n`
+  )
+}
+
+main().catch((error: unknown) => {
+  const message = error instanceof Error ? error.message : String(error)
+  process.stderr.write(`[verytis-mcp] fatal: ${message}\n`)
+  process.exit(1)
+})