metamcp: add reconciliation knobs (runOnUpgrade, updateExisting); docs: README sections + examples; bump to 0.1.22

Author: masterkain

charts/metamcp/Chart.yaml

@@ -2,7 +2,7 @@ apiVersion: v2
 name: metamcp
 description: MetaMCP aggregator Helm chart for Kubernetes
 type: application
-version: 0.1.21
+version: 0.1.22
 appVersion: "latest"
 icon: https://icoretech.github.io/helm/charts/metamcp/logo.png
 keywords:

charts/metamcp/README.md

@@ -112,6 +112,42 @@ users:
     apiKeyName: cli
 ```
 
+### Reconciliation modes (Flux/Helm upgrades)
+
+By default the provisioning job runs after every Helm install and upgrade and will upsert Namespaces/Endpoints to match values. You can tune this behavior:
+
+- `provision.runOnUpgrade` (bool, default `true`)
+  - `true`: run provisioning on every Helm upgrade (continuous upsert)
+  - `false`: run only on initial install (post-install). Upgrades do not re-run provisioning
+
+- `provision.updateExisting` (bool, default `true`)
+  - `true`: update existing Namespaces (description + membership) and Endpoints when names already exist
+  - `false`: create-only; existing objects are left untouched (good for “seed once, then manage via UI”)
+
+Notes
+- Servers are always create-only (by name). The job does not modify or delete existing servers.
+- Deletions are not automatic. Removing items from values does not delete them in MetaMCP. If you need prune semantics, open an issue so we can add an opt‑in `prune` mode.
+
+Examples
+
+Continuous upsert (Git is the source of truth):
+
+```yaml
+provision:
+  enabled: true
+  runOnUpgrade: true
+  updateExisting: true
+```
+
+Seed once, keep UI changes later:
+
+```yaml
+provision:
+  enabled: true
+  runOnUpgrade: false
+  updateExisting: false
+```
+
 Provisioning authentication
 
 - The provisioning Job authenticates using the first entry in `users` (email/password).

charts/metamcp/README.md.gotmpl

@@ -112,6 +112,42 @@ users:
     apiKeyName: cli
 ```
 
+### Reconciliation modes (Flux/Helm upgrades)
+
+By default the provisioning job runs after every Helm install and upgrade and will upsert Namespaces/Endpoints to match values. You can tune this behavior:
+
+- `provision.runOnUpgrade` (bool, default `true`)
+  - `true`: run provisioning on every Helm upgrade (continuous upsert)
+  - `false`: run only on initial install (post-install). Upgrades do not re-run provisioning
+
+- `provision.updateExisting` (bool, default `true`)
+  - `true`: update existing Namespaces (description + membership) and Endpoints when names already exist
+  - `false`: create-only; existing objects are left untouched (good for “seed once, then manage via UI”)
+
+Notes
+- Servers are always create-only (by name). The job does not modify or delete existing servers.
+- Deletions are not automatic. Removing items from values does not delete them in MetaMCP. If you need prune semantics, open an issue so we can add an opt‑in `prune` mode.
+
+Examples
+
+Continuous upsert (Git is the source of truth):
+
+```yaml
+provision:
+  enabled: true
+  runOnUpgrade: true
+  updateExisting: true
+```
+
+Seed once, keep UI changes later:
+
+```yaml
+provision:
+  enabled: true
+  runOnUpgrade: false
+  updateExisting: false
+```
+
 Provisioning authentication
 
 - The provisioning Job authenticates using the first entry in `users` (email/password).

charts/metamcp/scripts/provision.py

@@ -15,6 +15,7 @@ def log(msg):
 BACKEND = f"http://{SVC}:12009"
 ADMIN_EMAIL = os.environ.get('ADMIN_EMAIL','[email protected]')
 ADMIN_PASSWORD = os.environ.get('ADMIN_PASSWORD','change-me')
+UPDATE_EXISTING = (os.environ.get('UPDATE_EXISTING','true').lower() == 'true')
 
 cfg = json.load(open('/cfg/provision.json','r')).get('provision',{})
 servers = cfg.get('servers', [])
@@ -260,11 +261,12 @@ def k8s_get_configmap_data(name: str):
 
 def ensure_namespace(name, description=None):
     ns_uuid = None
+    existed = False
     lr = trpc_get('/trpc/frontend/frontend.namespaces.list?input=%7B%7D')
     if lr.ok:
         for ns in lr.json().get('result',{}).get('data',{}).get('data',[]):
             if ns.get('name') == name:
-                ns_uuid = ns.get('uuid'); break
+                ns_uuid = ns.get('uuid'); existed = True; break
     if not ns_uuid:
         payload = {'name': name}
         if description:
@@ -277,26 +279,27 @@ def ensure_namespace(name, description=None):
             except Exception:
                 pass
     else:
-        # Update description if provided
-        if description:
+        # Update description if provided and allowed
+        if description and UPDATE_EXISTING:
             try:
                 trpc_post('/trpc/frontend/frontend.namespaces.update', {'uuid': ns_uuid,'name': name,'description': description})
             except Exception:
                 pass
-    return ns_uuid
+    return ns_uuid, existed
 
 for ns in namespaces:
     name = ns.get('name'); nssrvs = ns.get('servers') or []
     if not name: continue
     desc = ns.get('description')
-    nid = ensure_namespace(name, desc)
+    nid, existed = ensure_namespace(name, desc)
     # Map server names to UUIDs if available
     srv_ids = []
     for nm in nssrvs:
         sid = srv_map.get(nm)
         if sid:
             srv_ids.append(sid)
-    if nid and srv_ids:
+    # Update namespace membership if allowed or if the namespace was just created
+    if nid and srv_ids and (UPDATE_EXISTING or not existed):
         try:
             payload = {'uuid': nid, 'name': name, 'mcpServerUuids': srv_ids}
             if desc:
@@ -305,7 +308,7 @@ def ensure_namespace(name, description=None):
         except Exception:
             pass
 
-def create_endpoint(name, nsref, transport='SSE', extra=None, description=None):
+def create_endpoint(name, nsref, transport='SSE', extra=None, description=None, update_existing=True):
     lr = trpc_get('/trpc/frontend/frontend.namespaces.list?input=%7B%7D')
     nid = None
     if lr.ok:
@@ -335,7 +338,7 @@ def create_endpoint(name, nsref, transport='SSE', extra=None, description=None):
                 flags[k] = extra[k]
     if description:
         flags['description'] = description
-    if e_uuid:
+    if e_uuid and update_existing:
         # update existing endpoint (use tRPC batch form as UI does)
         up = {'uuid': e_uuid, 'name': name, 'namespaceUuid': nid}
         up.update(flags)
@@ -353,7 +356,7 @@ def create_endpoint(name, nsref, transport='SSE', extra=None, description=None):
     name = ep.get('name'); nsref = ep.get('namespace') or ep.get('namespaceUuid')
     if not (name and nsref): continue
     extra = {k: ep[k] for k in ('enableApiKeyAuth','enableOauth','useQueryParamAuth') if k in ep}
-    create_endpoint(name, nsref, ep.get('transport'), extra, ep.get('description'))
+    create_endpoint(name, nsref, ep.get('transport'), extra, ep.get('description'), UPDATE_EXISTING)
 
 # Post-fix auto-generated endpoint servers URLs when APP_URL pointed to 12008 at creation time.
 # Newer MetaMCP creates a server named '<namespace>-endpoint' per endpoint and derives its URL from APP_URL.

charts/metamcp/templates/provision-config.yaml

@@ -50,7 +50,7 @@ metadata:
     {{- include "metamcp.labels" . | nindent 4 }}
     app.kubernetes.io/component: provision
   annotations:
-    helm.sh/hook: post-install,post-upgrade
+    helm.sh/hook: post-install{{- if (default true .Values.provision.runOnUpgrade) }},post-upgrade{{- end }}
     helm.sh/hook-weight: "5"
     helm.sh/hook-delete-policy: before-hook-creation
 spec:
@@ -74,6 +74,8 @@ spec:
               valueFrom:
                 fieldRef:
                   fieldPath: metadata.namespace
+            - name: UPDATE_EXISTING
+              value: {{ (default true .Values.provision.updateExisting) | ternary "true" "false" | quote }}
             - name: SVC
               value: {{ printf "%s.%s.svc.cluster.local" (include "metamcp.fullname" .) .Release.Namespace | quote }}
             - name: FRONTEND_PORT

charts/metamcp/values.schema.json

@@ -30,6 +30,8 @@
       "type": "object",
       "properties": {
         "enabled": { "type": "boolean" },
+        "runOnUpgrade": { "type": "boolean", "default": true },
+        "updateExisting": { "type": "boolean", "default": true },
         "servers": {
           "type": "array",
           "items": {

charts/metamcp/values.yaml

@@ -106,6 +106,14 @@ auth:
 # Generalized provisioning (multiple servers, namespaces, endpoints)
 provision:
   enabled: false
+  # Control when the provisioning job runs
+  # - runOnUpgrade: if true, run on every Helm upgrade (default)
+  # - if false, run only on initial install (post-install hook only)
+  runOnUpgrade: true
+  # Control whether existing namespaces/endpoints are updated when they already exist.
+  # When false, the job will only create missing objects and leave existing ones untouched
+  # (useful for "initial provision then manage via UI").
+  updateExisting: true
   # Single source of truth for servers MetaMCP exposes. Each entry can be:
   # - STDIO (MetaMCP runs it)
   # - STREAMABLE_HTTP/SSE with either: