feat: add git-based versioning with DEV badge

- Pass GIT_COMMIT, GIT_REF, BUILD_TIME as Docker build args
- Generate version.json at build time with git info
- Update version.ts to read from version.json in production
- Add getDisplayVersion() showing version + commit hash
- Add isDevBuild() to detect development builds
- Add DEV badge (coral color) on landing page for dev builds
- Production builds (tags starting with 'v') show clean version

Examples:
- Dev: "v1.0.0-rc.1 (e5f1b19)" with DEV badge
- Prod: "v1.0.0" without badge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: ConalMullan

.github/workflows/deploy-dev.yml

@@ -80,6 +80,10 @@ jobs:
           tags: |
             ${{ secrets.DOCKER_REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}
             ${{ secrets.DOCKER_REGISTRY }}/${{ env.IMAGE_NAME }}:latest
+          build-args: |
+            GIT_COMMIT=${{ github.sha }}
+            GIT_REF=${{ github.ref_name }}
+            BUILD_TIME=${{ github.event.head_commit.timestamp }}
           cache-from: type=gha
           cache-to: type=gha,mode=max
 

.github/workflows/deploy-prod.yml

@@ -94,6 +94,10 @@ jobs:
             ${{ secrets.DOCKER_REGISTRY }}/${{ env.IMAGE_NAME }}:${{ steps.version.outputs.version }}
             ${{ secrets.DOCKER_REGISTRY }}/${{ env.IMAGE_NAME }}:latest
             ${{ secrets.DOCKER_REGISTRY }}/${{ env.IMAGE_NAME }}:production
+          build-args: |
+            GIT_COMMIT=${{ github.sha }}
+            GIT_REF=${{ github.ref_name }}
+            BUILD_TIME=${{ github.event.head_commit.timestamp }}
           cache-from: type=gha
           cache-to: type=gha,mode=max
 

Dockerfile

@@ -11,6 +11,11 @@
 
 FROM node:20-alpine AS builder
 
+# Build arguments for version info
+ARG GIT_COMMIT=unknown
+ARG GIT_REF=unknown
+ARG BUILD_TIME=unknown
+
 WORKDIR /app
 
 # Copy package files
@@ -22,6 +27,9 @@ RUN npm ci
 # Copy source
 COPY . .
 
+# Generate version info file
+RUN echo "{\"commit\":\"${GIT_COMMIT}\",\"ref\":\"${GIT_REF}\",\"buildTime\":\"${BUILD_TIME}\"}" > version.json
+
 # Build TypeScript
 RUN npm run build
 
@@ -36,9 +44,10 @@ COPY package*.json ./
 # Install production dependencies only
 RUN npm ci --omit=dev && npm cache clean --force
 
-# Copy built files
+# Copy built files and version info
 COPY --from=builder /app/dist ./dist
 COPY --from=builder /app/bin ./bin
+COPY --from=builder /app/version.json ./version.json
 
 # Set environment variables
 ENV NODE_ENV=production

src/server.ts

@@ -90,7 +90,14 @@ import {
   executeExportTool,
 } from "./tools/export-tools/index.js";
 
-import { VERSION, VERSION_INFO } from "./version.js";
+import {
+  VERSION,
+  VERSION_INFO,
+  GIT_COMMIT,
+  GIT_REF,
+  getDisplayVersion,
+  isDevBuild,
+} from "./version.js";
 
 // API client instance cache - keyed by apiKey:apiUrl to support different URLs per session
 let apiClientCache: Map<string, DigitalSambaApiClient> = new Map();
@@ -382,4 +389,11 @@ export function createServer(config: ServerConfig = {}): Server {
   return server;
 }
 
-export { VERSION, VERSION_INFO };
+export {
+  VERSION,
+  VERSION_INFO,
+  GIT_COMMIT,
+  GIT_REF,
+  getDisplayVersion,
+  isDevBuild,
+};

src/transports/http.ts

@@ -10,7 +10,13 @@ import { randomUUID } from "node:crypto";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 
-import { createServer, VERSION, VERSION_INFO } from "../server.js";
+import {
+  createServer,
+  VERSION,
+  VERSION_INFO,
+  getDisplayVersion,
+  isDevBuild,
+} from "../server.js";
 import logger from "../logger.js";
 import apiKeyContext from "../auth.js";
 import {
@@ -954,6 +960,19 @@ export async function startHttpServer(config: HttpTransportConfig = {}): Promise
       padding: 4px 10px;
       border-radius: 6px;
       margin-left: auto;
+      display: flex;
+      align-items: center;
+      gap: 6px;
+    }
+    .dev-badge {
+      background: var(--ds-coral);
+      color: white;
+      font-size: 10px;
+      font-weight: 600;
+      padding: 2px 6px;
+      border-radius: 4px;
+      text-transform: uppercase;
+      letter-spacing: 0.5px;
     }
   </style>
 </head>
@@ -978,7 +997,7 @@ export async function startHttpServer(config: HttpTransportConfig = {}): Promise
       <div class="card-header">
         <div class="card-icon">⚡</div>
         <h2>Quick Connect</h2>
-        <span class="version-tag">v${VERSION}</span>
+        <span class="version-tag">${isDevBuild() ? '<span class="dev-badge">Dev</span>' : ""}v${getDisplayVersion()}</span>
       </div>
       <div class="card-body">
         <div class="url-box">

src/version.ts

@@ -1,26 +1,62 @@
 /**
  * Version information module
- * In development, this reads directly from package.json
- * In production, this is replaced by the build script
+ *
+ * In development: reads from package.json
+ * In production: reads from version.json (generated at build time)
+ *
+ * version.json contains git info:
+ * - commit: short SHA
+ * - ref: branch name or tag
+ * - buildTime: ISO timestamp
  */
 
-// Try to read package.json in development
-let versionInfo: any;
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+interface VersionInfo {
+  version: string;
+  name: string;
+  commit: string;
+  ref: string;
+  buildTime: string;
+  nodeVersion: string;
+}
+
+let versionInfo: VersionInfo;
+
 try {
-  // Development path - this will fail in production build
-  // eslint-disable-next-line @typescript-eslint/no-var-requires
-  const packageJson = require("../package.json");
+  // Get the directory of this file
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+
+  // Try to read package.json
+  const packageJsonPath = join(__dirname, "..", "..", "package.json");
+  const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+
+  // Try to read version.json (production builds)
+  let gitInfo = { commit: "dev", ref: "local", buildTime: "development" };
+  try {
+    const versionJsonPath = join(__dirname, "..", "..", "version.json");
+    gitInfo = JSON.parse(readFileSync(versionJsonPath, "utf-8"));
+  } catch {
+    // version.json doesn't exist in development - that's fine
+  }
+
   versionInfo = {
     version: packageJson.version,
     name: packageJson.name,
-    buildTime: "development",
+    commit: gitInfo.commit,
+    ref: gitInfo.ref,
+    buildTime: gitInfo.buildTime,
     nodeVersion: process.version,
   };
 } catch {
-  // Production build - use injected values
+  // Fallback if nothing works
   versionInfo = {
     version: "unknown",
     name: "@digitalsamba/embedded-api-mcp-server",
+    commit: "unknown",
+    ref: "unknown",
     buildTime: "unknown",
     nodeVersion: process.version,
   };
@@ -30,3 +66,35 @@ export const VERSION_INFO = versionInfo;
 export const VERSION = versionInfo.version;
 export const PACKAGE_NAME = versionInfo.name;
 export const BUILD_TIME = versionInfo.buildTime;
+export const GIT_COMMIT = versionInfo.commit;
+export const GIT_REF = versionInfo.ref;
+
+/**
+ * Get a formatted version string for display
+ * Examples:
+ * - Production (on tag): "1.0.0"
+ * - Development: "1.0.0-rc.1 (e5f1b19)"
+ */
+export function getDisplayVersion(): string {
+  // If commit is a tag ref or matches version, just show version
+  if (
+    versionInfo.ref.startsWith("v") ||
+    versionInfo.commit === "dev" ||
+    versionInfo.commit === "unknown"
+  ) {
+    return versionInfo.version;
+  }
+  // Otherwise show version with commit
+  return `${versionInfo.version} (${versionInfo.commit})`;
+}
+
+/**
+ * Check if this is a development build
+ */
+export function isDevBuild(): boolean {
+  return (
+    versionInfo.buildTime === "development" ||
+    versionInfo.ref === "develop" ||
+    versionInfo.ref.includes("dev")
+  );
+}