fix: proper error handling and --force flag for create commands

- Add global error handler: clean messages instead of stack traces
- Add --force flag to create server/secret/project: updates on 409 conflict
- Strip null values and template-only fields from --from-template payload
- Add tests: 409 handling, --force update, null-stripping from templates

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

deploy.sh

@@ -288,7 +288,7 @@ update_stack() {
             "env": $env,
             "stackFileContent": $stackFileContent,
             "prune": true,
-            "pullImage": false
+            "pullImage": true
         }')
 
     local response

src/cli/src/commands/apply.ts

@@ -4,6 +4,14 @@ import yaml from 'js-yaml';
 import { z } from 'zod';
 import type { ApiClient } from '../api-client.js';
 
+const HealthCheckSchema = z.object({
+  tool: z.string().min(1),
+  arguments: z.record(z.unknown()).default({}),
+  intervalSeconds: z.number().int().min(5).max(3600).default(60),
+  timeoutSeconds: z.number().int().min(1).max(120).default(10),
+  failureThreshold: z.number().int().min(1).max(20).default(3),
+});
+
 const ServerEnvEntrySchema = z.object({
   name: z.string().min(1),
   value: z.string().optional(),
@@ -24,6 +32,7 @@ const ServerSpecSchema = z.object({
   containerPort: z.number().int().min(1).max(65535).optional(),
   replicas: z.number().int().min(0).max(10).default(1),
   env: z.array(ServerEnvEntrySchema).default([]),
+  healthCheck: HealthCheckSchema.optional(),
 });
 
 const SecretSpecSchema = z.object({
@@ -51,6 +60,7 @@ const TemplateSpecSchema = z.object({
   containerPort: z.number().int().min(1).max(65535).optional(),
   replicas: z.number().int().min(0).max(10).default(1),
   env: z.array(TemplateEnvEntrySchema).default([]),
+  healthCheck: HealthCheckSchema.optional(),
 });
 
 const ProjectSpecSchema = z.object({

src/cli/src/commands/create.ts

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import type { ApiClient } from '../api-client.js';
+import { type ApiClient, ApiError } from '../api-client.js';
 export interface CreateCommandDeps {
   client: ApiClient;
   log: (...args: unknown[]) => void;
@@ -72,6 +72,7 @@ export function createCreateCommand(deps: CreateCommandDeps): Command {
     .option('--replicas <count>', 'Number of replicas')
     .option('--env <entry>', 'Env var: KEY=value (inline) or KEY=secretRef:SECRET:KEY (secret ref, repeat for multiple)', collect, [])
     .option('--from-template <name>', 'Create from template (name or name:version)')
+    .option('--force', 'Update if already exists')
     .action(async (name: string, opts) => {
       let base: Record<string, unknown> = {};
 
@@ -92,9 +93,12 @@ export function createCreateCommand(deps: CreateCommandDeps): Command {
           if (!template) throw new Error(`Template '${tplName}' not found`);
         }
 
-        // Copy template fields as base (strip template-only fields)
-        const { id: _id, createdAt: _c, updatedAt: _u, ...tplFields } = template;
-        base = { ...tplFields };
+        // Copy template fields as base (strip template-only, internal, and null fields)
+        const { id: _id, createdAt: _c, updatedAt: _u, version: _v, name: _n, ...tplFields } = template;
+        base = {};
+        for (const [k, v] of Object.entries(tplFields)) {
+          if (v !== null && v !== undefined) base[k] = v;
+        }
 
         // Convert template env (description/required) to server env (name/value/valueFrom)
         const tplEnv = template.env as Array<{ name: string; description?: string; required?: boolean; defaultValue?: string }> | undefined;
@@ -144,8 +148,20 @@ export function createCreateCommand(deps: CreateCommandDeps): Command {
         if (!body.replicas) body.replicas = 1;
       }
 
+      try {
         const server = await client.post<{ id: string; name: string }>('/api/v1/servers', body);
         log(`server '${server.name}' created (id: ${server.id})`);
+      } catch (err) {
+        if (err instanceof ApiError && err.status === 409 && opts.force) {
+          const existing = (await client.get<Array<{ id: string; name: string }>>('/api/v1/servers')).find((s) => s.name === name);
+          if (!existing) throw err;
+          const { name: _n, ...updateBody } = body;
+          await client.put(`/api/v1/servers/${existing.id}`, updateBody);
+          log(`server '${name}' updated (id: ${existing.id})`);
+        } else {
+          throw err;
+        }
+      }
     });
 
   // --- create secret ---
@@ -153,13 +169,25 @@ export function createCreateCommand(deps: CreateCommandDeps): Command {
     .description('Create a secret')
     .argument('<name>', 'Secret name (lowercase, hyphens allowed)')
     .option('--data <entry>', 'Secret data KEY=value (repeat for multiple)', collect, [])
+    .option('--force', 'Update if already exists')
     .action(async (name: string, opts) => {
       const data = parseEnvEntries(opts.data);
+      try {
         const secret = await client.post<{ id: string; name: string }>('/api/v1/secrets', {
           name,
           data,
         });
         log(`secret '${secret.name}' created (id: ${secret.id})`);
+      } catch (err) {
+        if (err instanceof ApiError && err.status === 409 && opts.force) {
+          const existing = (await client.get<Array<{ id: string; name: string }>>('/api/v1/secrets')).find((s) => s.name === name);
+          if (!existing) throw err;
+          await client.put(`/api/v1/secrets/${existing.id}`, { data });
+          log(`secret '${name}' updated (id: ${existing.id})`);
+        } else {
+          throw err;
+        }
+      }
     });
 
   // --- create project ---
@@ -167,12 +195,24 @@ export function createCreateCommand(deps: CreateCommandDeps): Command {
     .description('Create a project')
     .argument('<name>', 'Project name')
     .option('-d, --description <text>', 'Project description', '')
+    .option('--force', 'Update if already exists')
     .action(async (name: string, opts) => {
+      try {
         const project = await client.post<{ id: string; name: string }>('/api/v1/projects', {
           name,
           description: opts.description,
         });
         log(`project '${project.name}' created (id: ${project.id})`);
+      } catch (err) {
+        if (err instanceof ApiError && err.status === 409 && opts.force) {
+          const existing = (await client.get<Array<{ id: string; name: string }>>('/api/v1/projects')).find((p) => p.name === name);
+          if (!existing) throw err;
+          await client.put(`/api/v1/projects/${existing.id}`, { description: opts.description });
+          log(`project '${name}' updated (id: ${existing.id})`);
+        } else {
+          throw err;
+        }
+      }
     });
 
   return cmd;

src/cli/src/commands/describe.ts

@@ -50,6 +50,19 @@ function formatServerDetail(server: Record<string, unknown>): string {
     }
   }
 
+  const hc = server.healthCheck as { tool: string; arguments?: Record<string, unknown>; intervalSeconds?: number; timeoutSeconds?: number; failureThreshold?: number } | null;
+  if (hc) {
+    lines.push('');
+    lines.push('Health Check:');
+    lines.push(`  ${pad('Tool:', 22)}${hc.tool}`);
+    if (hc.arguments && Object.keys(hc.arguments).length > 0) {
+      lines.push(`  ${pad('Arguments:', 22)}${JSON.stringify(hc.arguments)}`);
+    }
+    lines.push(`  ${pad('Interval:', 22)}${hc.intervalSeconds ?? 60}s`);
+    lines.push(`  ${pad('Timeout:', 22)}${hc.timeoutSeconds ?? 10}s`);
+    lines.push(`  ${pad('Failure Threshold:', 22)}${hc.failureThreshold ?? 3}`);
+  }
+
   lines.push('');
   lines.push('Metadata:');
   lines.push(`  ${pad('ID:', 12)}${server.id}`);
@@ -67,6 +80,16 @@ function formatInstanceDetail(instance: Record<string, unknown>, inspect?: Recor
   lines.push(`${pad('Container ID:')}${instance.containerId ?? '-'}`);
   lines.push(`${pad('Port:')}${instance.port ?? '-'}`);
 
+  // Health section
+  const healthStatus = instance.healthStatus as string | null;
+  const lastHealthCheck = instance.lastHealthCheck as string | null;
+  if (healthStatus || lastHealthCheck) {
+    lines.push('');
+    lines.push('Health:');
+    lines.push(`  ${pad('Status:', 16)}${healthStatus ?? 'unknown'}`);
+    if (lastHealthCheck) lines.push(`  ${pad('Last Check:', 16)}${lastHealthCheck}`);
+  }
+
   const metadata = instance.metadata as Record<string, unknown> | undefined;
   if (metadata && Object.keys(metadata).length > 0) {
     lines.push('');
@@ -88,6 +111,19 @@ function formatInstanceDetail(instance: Record<string, unknown>, inspect?: Recor
     }
   }
 
+  // Events section (k8s-style)
+  const events = instance.events as Array<{ timestamp: string; type: string; message: string }> | undefined;
+  if (events && events.length > 0) {
+    lines.push('');
+    lines.push('Events:');
+    const tsW = 26;
+    const typeW = 10;
+    lines.push(`  ${'TIMESTAMP'.padEnd(tsW)}${'TYPE'.padEnd(typeW)}MESSAGE`);
+    for (const ev of events) {
+      lines.push(`  ${(ev.timestamp ?? '').padEnd(tsW)}${(ev.type ?? '').padEnd(typeW)}${ev.message ?? ''}`);
+    }
+  }
+
   lines.push('');
   lines.push(`  ${pad('ID:', 12)}${instance.id}`);
   if (instance.createdAt) lines.push(`  ${pad('Created:', 12)}${instance.createdAt}`);
@@ -177,6 +213,19 @@ function formatTemplateDetail(template: Record<string, unknown>): string {
     }
   }
 
+  const hc = template.healthCheck as { tool: string; arguments?: Record<string, unknown>; intervalSeconds?: number; timeoutSeconds?: number; failureThreshold?: number } | null;
+  if (hc) {
+    lines.push('');
+    lines.push('Health Check:');
+    lines.push(`  ${pad('Tool:', 22)}${hc.tool}`);
+    if (hc.arguments && Object.keys(hc.arguments).length > 0) {
+      lines.push(`  ${pad('Arguments:', 22)}${JSON.stringify(hc.arguments)}`);
+    }
+    lines.push(`  ${pad('Interval:', 22)}${hc.intervalSeconds ?? 60}s`);
+    lines.push(`  ${pad('Timeout:', 22)}${hc.timeoutSeconds ?? 10}s`);
+    lines.push(`  ${pad('Failure Threshold:', 22)}${hc.failureThreshold ?? 3}`);
+  }
+
   lines.push('');
   lines.push('Usage:');
   lines.push(`  mcpctl create server my-${template.name} --from-template=${template.name}`);

src/cli/src/commands/get.ts

@@ -45,6 +45,7 @@ interface InstanceRow {
   status: string;
   containerId: string | null;
   port: number | null;
+  healthStatus: string | null;
 }
 
 const serverColumns: Column<ServerRow>[] = [
@@ -78,6 +79,7 @@ const templateColumns: Column<TemplateRow>[] = [
 
 const instanceColumns: Column<InstanceRow>[] = [
   { header: 'STATUS', key: 'status', width: 10 },
+  { header: 'HEALTH', key: (r) => r.healthStatus ?? '-', width: 10 },
   { header: 'SERVER ID', key: 'serverId' },
   { header: 'PORT', key: (r) => r.port != null ? String(r.port) : '-', width: 6 },
   { header: 'CONTAINER', key: (r) => r.containerId ? r.containerId.slice(0, 12) : '-', width: 14 },

src/cli/src/index.ts

@@ -14,7 +14,7 @@ import { createClaudeCommand } from './commands/claude.js';
 import { createProjectCommand } from './commands/project.js';
 import { createBackupCommand, createRestoreCommand } from './commands/backup.js';
 import { createLoginCommand, createLogoutCommand } from './commands/auth.js';
-import { ApiClient } from './api-client.js';
+import { ApiClient, ApiError } from './api-client.js';
 import { loadConfig } from './config/index.js';
 import { loadCredentials } from './auth/index.js';
 import { resolveNameOrId } from './commands/shared.js';
@@ -143,5 +143,21 @@ const isDirectRun =
   import.meta.url === `file://${process.argv[1]}`;
 
 if (isDirectRun) {
-  createProgram().parseAsync(process.argv);
+  createProgram().parseAsync(process.argv).catch((err: unknown) => {
+    if (err instanceof ApiError) {
+      let msg: string;
+      try {
+        const parsed = JSON.parse(err.body) as { error?: string; message?: string };
+        msg = parsed.error ?? parsed.message ?? err.body;
+      } catch {
+        msg = err.body;
+      }
+      console.error(`Error: ${msg}`);
+    } else if (err instanceof Error) {
+      console.error(`Error: ${err.message}`);
+    } else {
+      console.error(`Error: ${String(err)}`);
+    }
+    process.exit(1);
+  });
 }

src/cli/tests/commands/create.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { createCreateCommand } from '../../src/commands/create.js';
-import type { ApiClient } from '../../src/api-client.js';
+import { type ApiClient, ApiError } from '../../src/api-client.js';
 
 function mockClient(): ApiClient {
   return {
@@ -73,6 +73,59 @@ describe('create command', () => {
         transport: 'STDIO',
       }));
     });
+
+    it('strips null values from template when using --from-template', async () => {
+      vi.mocked(client.get).mockResolvedValueOnce([{
+        id: 'tpl-1',
+        name: 'grafana',
+        version: '1.0.0',
+        description: 'Grafana MCP',
+        packageName: '@leval/mcp-grafana',
+        dockerImage: null,
+        transport: 'STDIO',
+        repositoryUrl: 'https://github.com/test',
+        externalUrl: null,
+        command: null,
+        containerPort: null,
+        replicas: 1,
+        env: [{ name: 'TOKEN', required: true, description: 'A token' }],
+        healthCheck: { tool: 'test', arguments: {} },
+        createdAt: '2025-01-01',
+        updatedAt: '2025-01-01',
+      }] as never);
+      const cmd = createCreateCommand({ client, log });
+      await cmd.parseAsync([
+        'server', 'my-grafana', '--from-template=grafana',
+        '--env', 'TOKEN=secretRef:creds:TOKEN',
+      ], { from: 'user' });
+      const call = vi.mocked(client.post).mock.calls[0]![1] as Record<string, unknown>;
+      // null fields from template should NOT be in the body
+      expect(call).not.toHaveProperty('dockerImage');
+      expect(call).not.toHaveProperty('externalUrl');
+      expect(call).not.toHaveProperty('command');
+      expect(call).not.toHaveProperty('containerPort');
+      // non-null fields should be present
+      expect(call.packageName).toBe('@leval/mcp-grafana');
+      expect(call.healthCheck).toEqual({ tool: 'test', arguments: {} });
+      expect(call.templateName).toBe('grafana');
+    });
+
+    it('throws on 409 without --force', async () => {
+      vi.mocked(client.post).mockRejectedValueOnce(new ApiError(409, '{"error":"Server already exists: my-server"}'));
+      const cmd = createCreateCommand({ client, log });
+      await expect(cmd.parseAsync(['server', 'my-server'], { from: 'user' })).rejects.toThrow('API error 409');
+    });
+
+    it('updates existing server on 409 with --force', async () => {
+      vi.mocked(client.post).mockRejectedValueOnce(new ApiError(409, '{"error":"Server already exists"}'));
+      vi.mocked(client.get).mockResolvedValueOnce([{ id: 'srv-1', name: 'my-server' }] as never);
+      const cmd = createCreateCommand({ client, log });
+      await cmd.parseAsync(['server', 'my-server', '--force'], { from: 'user' });
+      expect(client.put).toHaveBeenCalledWith('/api/v1/servers/srv-1', expect.objectContaining({
+        transport: 'STDIO',
+      }));
+      expect(output.join('\n')).toContain("server 'my-server' updated");
+    });
   });
 
   describe('create secret', () => {
@@ -98,6 +151,21 @@ describe('create command', () => {
         data: {},
       });
     });
+
+    it('throws on 409 without --force', async () => {
+      vi.mocked(client.post).mockRejectedValueOnce(new ApiError(409, '{"error":"Secret already exists: my-creds"}'));
+      const cmd = createCreateCommand({ client, log });
+      await expect(cmd.parseAsync(['secret', 'my-creds', '--data', 'KEY=val'], { from: 'user' })).rejects.toThrow('API error 409');
+    });
+
+    it('updates existing secret on 409 with --force', async () => {
+      vi.mocked(client.post).mockRejectedValueOnce(new ApiError(409, '{"error":"Secret already exists"}'));
+      vi.mocked(client.get).mockResolvedValueOnce([{ id: 'sec-1', name: 'my-creds' }] as never);
+      const cmd = createCreateCommand({ client, log });
+      await cmd.parseAsync(['secret', 'my-creds', '--data', 'KEY=val', '--force'], { from: 'user' });
+      expect(client.put).toHaveBeenCalledWith('/api/v1/secrets/sec-1', { data: { KEY: 'val' } });
+      expect(output.join('\n')).toContain("secret 'my-creds' updated");
+    });
   });
 
   describe('create project', () => {
@@ -119,5 +187,14 @@ describe('create command', () => {
         description: '',
       });
     });
+
+    it('updates existing project on 409 with --force', async () => {
+      vi.mocked(client.post).mockRejectedValueOnce(new ApiError(409, '{"error":"Project already exists"}'));
+      vi.mocked(client.get).mockResolvedValueOnce([{ id: 'proj-1', name: 'my-proj' }] as never);
+      const cmd = createCreateCommand({ client, log });
+      await cmd.parseAsync(['project', 'my-proj', '-d', 'updated', '--force'], { from: 'user' });
+      expect(client.put).toHaveBeenCalledWith('/api/v1/projects/proj-1', { description: 'updated' });
+      expect(output.join('\n')).toContain("project 'my-proj' updated");
+    });
   });
 });

src/db/prisma/schema.prisma

@@ -62,6 +62,7 @@ model McpServer {
   containerPort Int?
   replicas      Int             @default(1)
   env           Json            @default("[]")
+  healthCheck   Json?
   version       Int             @default(1)
   createdAt     DateTime        @default(now())
   updatedAt     DateTime        @updatedAt
@@ -96,6 +97,7 @@ model McpTemplate {
   containerPort Int?
   replicas      Int       @default(1)
   env           Json      @default("[]")
+  healthCheck   Json?
   createdAt     DateTime  @default(now())
   updatedAt     DateTime  @updatedAt
 
@@ -141,6 +143,9 @@ model McpInstance {
   status      InstanceStatus @default(STOPPED)
   port        Int?
   metadata        Json           @default("{}")
+  healthStatus    String?
+  lastHealthCheck DateTime?
+  events          Json           @default("[]")
   version         Int            @default(1)
   createdAt       DateTime       @default(now())
   updatedAt       DateTime       @updatedAt

src/db/src/index.ts

@@ -15,4 +15,4 @@ export type {
 } from '@prisma/client';
 
 export { seedTemplates } from './seed/index.js';
-export type { SeedTemplate, TemplateEnvEntry } from './seed/index.js';
+export type { SeedTemplate, TemplateEnvEntry, HealthCheckSpec } from './seed/index.js';

src/db/src/seed/index.ts

@@ -7,6 +7,14 @@ export interface TemplateEnvEntry {
   defaultValue?: string;
 }
 
+export interface HealthCheckSpec {
+  tool: string;
+  arguments?: Record<string, unknown>;
+  intervalSeconds?: number;
+  timeoutSeconds?: number;
+  failureThreshold?: number;
+}
+
 export interface SeedTemplate {
   name: string;
   version: string;
@@ -20,6 +28,7 @@ export interface SeedTemplate {
   containerPort?: number;
   replicas?: number;
   env?: TemplateEnvEntry[];
+  healthCheck?: HealthCheckSpec;
 }
 
 export async function seedTemplates(
@@ -43,6 +52,7 @@ export async function seedTemplates(
         containerPort: tpl.containerPort ?? null,
         replicas: tpl.replicas ?? 1,
         env: (tpl.env ?? []) as unknown as Prisma.InputJsonValue,
+        healthCheck: (tpl.healthCheck ?? Prisma.JsonNull) as unknown as Prisma.InputJsonValue,
       },
       create: {
         name: tpl.name,
@@ -57,6 +67,7 @@ export async function seedTemplates(
         containerPort: tpl.containerPort ?? null,
         replicas: tpl.replicas ?? 1,
         env: (tpl.env ?? []) as unknown as Prisma.InputJsonValue,
+        healthCheck: (tpl.healthCheck ?? Prisma.JsonNull) as unknown as Prisma.InputJsonValue,
       },
     });
     upserted++;

src/mcpd/src/main.ts

@@ -69,6 +69,7 @@ async function main(): Promise<void> {
       transport: parsed.transport ?? 'STDIO',
       version: parsed.version ?? '1.0.0',
       description: parsed.description ?? '',
+      ...(parsed.healthCheck ? { healthCheck: parsed.healthCheck } : {}),
     };
   });
   await seedTemplates(prisma, templates);

src/mcpd/src/repositories/interfaces.ts

@@ -16,7 +16,7 @@ export interface IMcpInstanceRepository {
   findById(id: string): Promise<McpInstance | null>;
   findByContainerId(containerId: string): Promise<McpInstance | null>;
   create(data: { serverId: string; containerId?: string; status?: InstanceStatus; port?: number; metadata?: Record<string, unknown> }): Promise<McpInstance>;
-  updateStatus(id: string, status: InstanceStatus, fields?: { containerId?: string; port?: number; metadata?: Record<string, unknown> }): Promise<McpInstance>;
+  updateStatus(id: string, status: InstanceStatus, fields?: { containerId?: string; port?: number; metadata?: Record<string, unknown>; healthStatus?: string; lastHealthCheck?: Date; events?: unknown[] }): Promise<McpInstance>;
   delete(id: string): Promise<void>;
 }
 

src/mcpd/src/repositories/mcp-instance.repository.ts

@@ -44,7 +44,7 @@ export class McpInstanceRepository implements IMcpInstanceRepository {
   async updateStatus(
     id: string,
     status: InstanceStatus,
-    fields?: { containerId?: string; port?: number; metadata?: Record<string, unknown> },
+    fields?: { containerId?: string; port?: number; metadata?: Record<string, unknown>; healthStatus?: string; lastHealthCheck?: Date; events?: unknown[] },
   ): Promise<McpInstance> {
     const updateData: Prisma.McpInstanceUpdateInput = {
       status,
@@ -59,6 +59,15 @@ export class McpInstanceRepository implements IMcpInstanceRepository {
     if (fields?.metadata !== undefined) {
       updateData.metadata = fields.metadata as Prisma.InputJsonValue;
     }
+    if (fields?.healthStatus !== undefined) {
+      updateData.healthStatus = fields.healthStatus;
+    }
+    if (fields?.lastHealthCheck !== undefined) {
+      updateData.lastHealthCheck = fields.lastHealthCheck;
+    }
+    if (fields?.events !== undefined) {
+      updateData.events = fields.events as unknown as Prisma.InputJsonValue;
+    }
     return this.prisma.mcpInstance.update({
       where: { id },
       data: updateData,

src/mcpd/src/repositories/mcp-server.repository.ts

@@ -31,6 +31,7 @@ export class McpServerRepository implements IMcpServerRepository {
         containerPort: data.containerPort ?? null,
         replicas: data.replicas,
         env: data.env,
+        healthCheck: (data.healthCheck ?? Prisma.JsonNull) as Prisma.InputJsonValue,
       },
     });
   }
@@ -47,6 +48,7 @@ export class McpServerRepository implements IMcpServerRepository {
     if (data.containerPort !== undefined) updateData['containerPort'] = data.containerPort;
     if (data.replicas !== undefined) updateData['replicas'] = data.replicas;
     if (data.env !== undefined) updateData['env'] = data.env;
+    if (data.healthCheck !== undefined) updateData['healthCheck'] = (data.healthCheck ?? Prisma.JsonNull) as Prisma.InputJsonValue;
 
     return this.prisma.mcpServer.update({ where: { id }, data: updateData });
   }

src/mcpd/src/repositories/template.repository.ts

@@ -50,6 +50,7 @@ export class TemplateRepository implements ITemplateRepository {
         containerPort: data.containerPort ?? null,
         replicas: data.replicas,
         env: (data.env ?? []) as unknown as Prisma.InputJsonValue,
+        healthCheck: (data.healthCheck ?? Prisma.JsonNull) as Prisma.InputJsonValue,
       },
     });
   }
@@ -67,6 +68,7 @@ export class TemplateRepository implements ITemplateRepository {
     if (data.containerPort !== undefined) updateData.containerPort = data.containerPort;
     if (data.replicas !== undefined) updateData.replicas = data.replicas;
     if (data.env !== undefined) updateData.env = (data.env ?? []) as Prisma.InputJsonValue;
+    if (data.healthCheck !== undefined) updateData.healthCheck = (data.healthCheck ?? Prisma.JsonNull) as Prisma.InputJsonValue;
 
     return this.prisma.mcpTemplate.update({
       where: { id },

src/mcpd/src/seed-runner.ts

@@ -24,6 +24,7 @@ function loadTemplatesFromDir(dir: string): SeedTemplate[] {
         transport: parsed.transport ?? 'STDIO',
         version: parsed.version ?? '1.0.0',
         description: parsed.description ?? '',
+        ...(parsed.healthCheck ? { healthCheck: parsed.healthCheck } : {}),
       });
     }
   }

src/mcpd/src/validation/mcp-server.schema.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { HealthCheckSchema } from './template.schema.js';
 
 const SecretRefSchema = z.object({
   name: z.string().min(1),
@@ -30,6 +31,7 @@ export const CreateMcpServerSchema = z.object({
   containerPort: z.number().int().min(1).max(65535).optional(),
   replicas: z.number().int().min(0).max(10).default(1),
   env: z.array(ServerEnvEntrySchema).default([]),
+  healthCheck: HealthCheckSchema.optional(),
 });
 
 export const UpdateMcpServerSchema = z.object({
@@ -43,6 +45,7 @@ export const UpdateMcpServerSchema = z.object({
   containerPort: z.number().int().min(1).max(65535).nullable().optional(),
   replicas: z.number().int().min(0).max(10).optional(),
   env: z.array(ServerEnvEntrySchema).optional(),
+  healthCheck: HealthCheckSchema.nullable().optional(),
 });
 
 export type CreateMcpServerInput = z.infer<typeof CreateMcpServerSchema>;

src/mcpd/src/validation/template.schema.ts

@@ -7,6 +7,16 @@ const TemplateEnvEntrySchema = z.object({
   defaultValue: z.string().optional(),
 });
 
+export const HealthCheckSchema = z.object({
+  tool: z.string().min(1),
+  arguments: z.record(z.unknown()).default({}),
+  intervalSeconds: z.number().int().min(5).max(3600).default(60),
+  timeoutSeconds: z.number().int().min(1).max(120).default(10),
+  failureThreshold: z.number().int().min(1).max(20).default(3),
+});
+
+export type HealthCheckInput = z.infer<typeof HealthCheckSchema>;
+
 export const CreateTemplateSchema = z.object({
   name: z.string().min(1).max(100).regex(/^[a-z0-9-]+$/, 'Name must be lowercase alphanumeric with hyphens'),
   version: z.string().default('1.0.0'),
@@ -20,6 +30,7 @@ export const CreateTemplateSchema = z.object({
   containerPort: z.number().int().min(1).max(65535).optional(),
   replicas: z.number().int().min(0).max(10).default(1),
   env: z.array(TemplateEnvEntrySchema).default([]),
+  healthCheck: HealthCheckSchema.optional(),
 });
 
 export const UpdateTemplateSchema = CreateTemplateSchema.partial().omit({ name: true });

templates/github.yaml

@@ -4,6 +4,10 @@ description: GitHub MCP server for repos, issues, PRs, and code search
 packageName: "@anthropic/github-mcp"
 transport: STDIO
 repositoryUrl: https://github.com/modelcontextprotocol/servers/tree/main/src/github
+healthCheck:
+  tool: search_repositories
+  arguments:
+    query: "test"
 env:
   - name: GITHUB_TOKEN
     description: Personal access token with repo scope

templates/grafana.yaml

@@ -0,0 +1,16 @@
+name: grafana
+version: "1.0.0"
+description: Grafana MCP server for dashboards, datasources, and alerts
+packageName: "@leval/mcp-grafana"
+transport: STDIO
+repositoryUrl: https://github.com/levalhq/mcp-grafana
+healthCheck:
+  tool: list_datasources
+  arguments: {}
+env:
+  - name: GRAFANA_URL
+    description: Grafana instance URL (e.g. https://grafana.example.com)
+    required: true
+  - name: GRAFANA_SERVICE_ACCOUNT_TOKEN
+    description: Grafana service account token (glsa_...)
+    required: true

templates/home-assistant.yaml

@@ -0,0 +1,16 @@
+name: home-assistant
+version: "1.0.0"
+description: Home Assistant MCP server for smart home control and entity management
+packageName: "home-assistant-mcp-server"
+transport: STDIO
+repositoryUrl: https://github.com/tevonsb/homeassistant-mcp
+healthCheck:
+  tool: get_entities
+  arguments: {}
+env:
+  - name: HASS_URL
+    description: Home Assistant instance URL (e.g. http://homeassistant.local:8123)
+    required: true
+  - name: HASS_TOKEN
+    description: Home Assistant long-lived access token
+    required: true

templates/jira.yaml

@@ -4,6 +4,11 @@ description: Jira MCP server for issues, projects, and boards
 packageName: "@anthropic/jira-mcp"
 transport: STDIO
 repositoryUrl: https://github.com/modelcontextprotocol/servers/tree/main/src/jira
+healthCheck:
+  tool: search_issues
+  arguments:
+    jql: "created >= -1d"
+    maxResults: 1
 env:
   - name: JIRA_URL
     description: Jira instance URL (e.g. https://company.atlassian.net)

templates/node-red.yaml

@@ -0,0 +1,16 @@
+name: node-red
+version: "1.0.0"
+description: Node-RED MCP server for flow management and automation
+packageName: "mcp-node-red"
+transport: STDIO
+repositoryUrl: https://github.com/fx/mcp-node-red
+healthCheck:
+  tool: get_settings
+  arguments: {}
+env:
+  - name: NODE_RED_URL
+    description: Node-RED instance URL (e.g. http://nodered.local:1880)
+    required: true
+  - name: NODE_RED_TOKEN
+    description: Node-RED access token (optional if no auth)
+    required: false

templates/postgres.yaml

@@ -4,6 +4,10 @@ description: PostgreSQL MCP server for database queries and schema inspection
 packageName: "@anthropic/postgres-mcp"
 transport: STDIO
 repositoryUrl: https://github.com/modelcontextprotocol/servers/tree/main/src/postgres
+healthCheck:
+  tool: query
+  arguments:
+    sql: "SELECT 1"
 env:
   - name: POSTGRES_CONNECTION_STRING
     description: PostgreSQL connection string (e.g. postgresql://user:pass@host:5432/db)

templates/slack.yaml

@@ -4,6 +4,9 @@ description: Slack MCP server for reading channels, messages, and user info
 packageName: "@anthropic/slack-mcp"
 transport: STDIO
 repositoryUrl: https://github.com/modelcontextprotocol/servers/tree/main/src/slack
+healthCheck:
+  tool: list_channels
+  arguments: {}
 env:
   - name: SLACK_BOT_TOKEN
     description: Slack bot token (xoxb-...)