feat(servers): persistent volumes + self-hosted web search and docs templates

Instances are immutable and get recreated on any server edit, so anything an
MCP server wrote to its container filesystem was lost at exactly that point.
That ruled out every stateful MCP server, docs-mcp among them: its index is a
SQLite file (better-sqlite3 + sqlite-vec) and it has no external-database mode,
so no amount of Postgres helps.

A server or template can now declare volumes. The backing store is keyed on the
server, not the instance — `mcpctl-<server>-<name>` — which is the whole point:
an instance-scoped claim would be destroyed precisely when the data needs to
survive. On Kubernetes that is a PVC ensured in the servers namespace before the
pod is created and never deleted with it; on Docker, a named volume (named, not
anonymous, so `removeContainer`'s `v: true` leaves it alone).

Claims are ReadWriteOnce, so volumes and replicas > 1 are mutually exclusive;
validation rejects that pair instead of leaving the extra replicas
unschedulable. storageClassName is omitted rather than sent empty when no class
is configured — to Kubernetes those mean different things.

Also fixes a pre-existing bug in the same path: seedTemplates dropped `runtime`,
so every PyPI-backed template seeded from YAML silently defaulted to node and
would run `npx` against a package that only exists on PyPI. `unifi-network`
declares `runtime: python` and had been seeding with runtime unset.

Templates added, all self-hosted and none needing an API key:
  - duckduckgo — no backing service at all
  - searxng    — needs a SearXNG engine (compose profile in stack/)
  - docs-mcp   — open-source Context7/Ref alternative, uses the new volume

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017BMXdb2qZbPSh8Q7XpTyjB

src/mcpd/tests/instance-service.test.ts

@@ -70,10 +70,11 @@ function mockOrchestrator(): McpOrchestrator {
   };
 }
 
-function makeServer(overrides: Partial<{ id: string; name: string; replicas: number; dockerImage: string | null; externalUrl: string | null; transport: string; command: unknown; containerPort: number | null }> = {}) {
+function makeServer(overrides: Partial<{ id: string; name: string; replicas: number; dockerImage: string | null; externalUrl: string | null; transport: string; command: unknown; containerPort: number | null; volumes: unknown }> = {}) {
   return {
     id: overrides.id ?? 'srv-1',
     name: overrides.name ?? 'slack',
+    volumes: overrides.volumes ?? [],
     dockerImage: overrides.dockerImage ?? 'ghcr.io/slack-mcp:latest',
     packageName: null,
     transport: overrides.transport ?? 'STDIO',
@@ -143,6 +144,53 @@ describe('InstanceService', () => {
     });
   });
 
+  describe('volumes', () => {
+    it('names the claim after the server, not the instance', async () => {
+      // The whole point of the feature: instances are recreated on every server
+      // edit, so an instance-scoped claim would be destroyed exactly when the
+      // data needs to survive.
+      vi.mocked(serverRepo.findById).mockResolvedValue(makeServer({
+        name: 'docs',
+        volumes: [{ name: 'data', mountPath: '/data', sizeGb: 20, storageClass: 'longhorn' }],
+      }));
+      vi.mocked(instanceRepo.findAll).mockResolvedValue([]);
+
+      await service.reconcile('srv-1');
+
+      const spec = vi.mocked(orchestrator.createContainer).mock.calls[0]![0];
+      expect(spec.volumes).toEqual([
+        { claimName: 'mcpctl-docs-data', mountPath: '/data', sizeGb: 20, storageClass: 'longhorn' },
+      ]);
+      // Container name carries the instance id; the claim must not.
+      expect(spec.name).toContain('inst-1');
+      expect(spec.volumes![0]!.claimName).not.toContain('inst-1');
+    });
+
+    it('defaults size and leaves storageClass unset when unspecified', async () => {
+      vi.mocked(serverRepo.findById).mockResolvedValue(makeServer({
+        name: 'docs',
+        volumes: [{ name: 'data', mountPath: '/data' }],
+      }));
+      vi.mocked(instanceRepo.findAll).mockResolvedValue([]);
+
+      await service.reconcile('srv-1');
+
+      const spec = vi.mocked(orchestrator.createContainer).mock.calls[0]![0];
+      expect(spec.volumes![0]!.sizeGb).toBe(10);
+      expect(spec.volumes![0]).not.toHaveProperty('storageClass');
+    });
+
+    it('leaves the spec free of volumes when the server declares none', async () => {
+      vi.mocked(serverRepo.findById).mockResolvedValue(makeServer({}));
+      vi.mocked(instanceRepo.findAll).mockResolvedValue([]);
+
+      await service.reconcile('srv-1');
+
+      const spec = vi.mocked(orchestrator.createContainer).mock.calls[0]![0];
+      expect(spec.volumes).toBeUndefined();
+    });
+  });
+
   describe('reconcile', () => {
     it('starts instances when below desired replicas', async () => {
       vi.mocked(serverRepo.findById).mockResolvedValue(makeServer({ replicas: 2 }));

src/mcpd/tests/k8s-manifest.test.ts

@@ -3,6 +3,7 @@ import {
   generatePodSpec,
   generateDeploymentSpec,
   generateNamespaceSpec,
+  generatePvcSpec,
   formatMemory,
   formatCpu,
   sanitizeName,
@@ -156,6 +157,70 @@ describe('generateDeploymentSpec', () => {
   });
 });
 
+describe('volumes', () => {
+  const volumeSpec: ContainerSpec = {
+    ...baseSpec,
+    volumes: [{ claimName: 'mcpctl-docs-data', mountPath: '/data', sizeGb: 20, storageClass: 'longhorn' }],
+  };
+
+  it('mounts the claim in the pod and declares the volume', () => {
+    const pod = generatePodSpec(volumeSpec, 'mcpctl-servers');
+    expect(pod.spec.volumes).toEqual([
+      { name: 'mcpctl-docs-data', persistentVolumeClaim: { claimName: 'mcpctl-docs-data' } },
+    ]);
+    expect(pod.spec.containers[0]!.volumeMounts).toEqual([
+      { name: 'mcpctl-docs-data', mountPath: '/data' },
+    ]);
+  });
+
+  it('omits volume fields entirely when none are declared', () => {
+    const pod = generatePodSpec(baseSpec, 'mcpctl-servers');
+    expect(pod.spec.volumes).toBeUndefined();
+    expect(pod.spec.containers[0]!.volumeMounts).toBeUndefined();
+  });
+
+  it('carries volumes into a deployment pod template', () => {
+    const dep = generateDeploymentSpec(volumeSpec, 'mcpctl-servers', 1);
+    expect(dep.spec.template.spec.volumes).toHaveLength(1);
+    expect(dep.spec.template.spec.containers[0]!.volumeMounts).toHaveLength(1);
+  });
+
+  it('builds a PVC with the requested size and class', () => {
+    const pvc = generatePvcSpec(volumeSpec.volumes![0]!, 'mcpctl-servers');
+    expect(pvc.kind).toBe('PersistentVolumeClaim');
+    expect(pvc.metadata.name).toBe('mcpctl-docs-data');
+    expect(pvc.metadata.namespace).toBe('mcpctl-servers');
+    expect(pvc.spec.resources.requests.storage).toBe('20Gi');
+    expect(pvc.spec.accessModes).toEqual(['ReadWriteOnce']);
+    expect(pvc.spec.storageClassName).toBe('longhorn');
+  });
+
+  it('omits storageClassName rather than sending an empty string', () => {
+    // An empty string means "no storage class" to Kubernetes, which is NOT the
+    // same as omitting the field (use the cluster default).
+    const prev = process.env['MCPD_VOLUME_STORAGE_CLASS'];
+    delete process.env['MCPD_VOLUME_STORAGE_CLASS'];
+    try {
+      const pvc = generatePvcSpec({ claimName: 'c', mountPath: '/d', sizeGb: 1 }, 'ns');
+      expect('storageClassName' in pvc.spec).toBe(false);
+    } finally {
+      if (prev !== undefined) process.env['MCPD_VOLUME_STORAGE_CLASS'] = prev;
+    }
+  });
+
+  it('falls back to MCPD_VOLUME_STORAGE_CLASS when the volume omits a class', () => {
+    const prev = process.env['MCPD_VOLUME_STORAGE_CLASS'];
+    process.env['MCPD_VOLUME_STORAGE_CLASS'] = 'longhorn';
+    try {
+      const pvc = generatePvcSpec({ claimName: 'c', mountPath: '/d', sizeGb: 5 }, 'ns');
+      expect(pvc.spec.storageClassName).toBe('longhorn');
+    } finally {
+      if (prev === undefined) delete process.env['MCPD_VOLUME_STORAGE_CLASS'];
+      else process.env['MCPD_VOLUME_STORAGE_CLASS'] = prev;
+    }
+  });
+});
+
 describe('generateNamespaceSpec', () => {
   it('generates namespace manifest', () => {
     const ns = generateNamespaceSpec('mcpctl-prod');