feat(servers): allow editing custom server definitions

Previously the per-server 'View Definition' action was read-only with
no save path. For UserSpace-sourced (custom) servers, make it
editable: build the standard MCP config shape (command/args/env or
url/headers, name, auth, etc.) instead of the full merged
ServerDefinition, and add a save path that patches the matching
mcpServers key back into the space JSON file.

- New update_server_in_config command (Tauri + admin REST), matching
  the target key by normalized id since the raw JSON key may differ
- ServerDefinitionModal is editable only when source.type is
  UserSpace; Registry/Bundled servers stay read-only
- Menu label switches to 'Edit Definition' when editable

Signed-off-by: crimsonsunset <jsangio1@gmail.com>

Author: crimsonsunset

apps/desktop/src-tauri/src/commands/space.rs

@@ -6,7 +6,9 @@
 //! built-in fallback. The desktop UI tracks which space the user is
 //! viewing in its own Zustand store (frontend-only state).
 
-use mcpmux_core::{validate_workspace_root, Space, SpaceBaseDir, WorkspaceRootValidation};
+use mcpmux_core::{
+    validate_workspace_root, Space, SpaceBaseDir, UserServerEntry, WorkspaceRootValidation,
+};
 use std::sync::Arc;
 use tauri::{AppHandle, State};
 use tokio::sync::RwLock;
@@ -284,6 +286,57 @@ pub async fn remove_server_from_config(
     Ok(false)
 }
 
+/// Replace a custom server's entry in the space configuration file.
+///
+/// Matches the target `mcpServers` key by comparing its normalized form
+/// (see `UserServerEntry::normalize_server_id`) against `server_id`, since
+/// the installed server id is normalized but the raw JSON key may not be.
+#[tauri::command]
+pub async fn update_server_in_config(
+    space_id: String,
+    server_id: String,
+    entry: serde_json::Value,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    if !entry.is_object() {
+        return Err("Server entry must be a JSON object".to_string());
+    }
+
+    let config_path = state.space_config_path(&space_id)?;
+
+    let content = std::fs::read_to_string(&config_path)
+        .map_err(|e| format!("Failed to read config file: {}", e))?;
+
+    let mut config: serde_json::Value =
+        serde_json::from_str(&content).map_err(|e| format!("Failed to parse config: {}", e))?;
+
+    let servers = config
+        .get_mut("mcpServers")
+        .and_then(|v| v.as_object_mut())
+        .ok_or_else(|| "Config file has no mcpServers object".to_string())?;
+
+    let matching_key = servers
+        .keys()
+        .find(|key| UserServerEntry::normalize_server_id(key) == server_id)
+        .cloned()
+        .ok_or_else(|| format!("Server '{}' not found in config", server_id))?;
+
+    servers.insert(matching_key, entry);
+
+    let new_content = serde_json::to_string_pretty(&config)
+        .map_err(|e| format!("Failed to serialize config: {}", e))?;
+
+    std::fs::write(&config_path, new_content)
+        .map_err(|e| format!("Failed to write config file: {}", e))?;
+
+    info!(
+        "[update_server_in_config] Updated server '{}' in space '{}'",
+        server_id, space_id
+    );
+
+    Ok(())
+}
+
 /// Refresh the system tray menu to reflect current spaces
 #[tauri::command]
 pub async fn refresh_tray_menu(app: AppHandle, state: State<'_, AppState>) -> Result<(), String> {

apps/desktop/src-tauri/src/lib.rs

@@ -971,6 +971,7 @@ pub fn run() {
             commands::read_space_config,
             commands::save_space_config,
             commands::remove_server_from_config,
+            commands::update_server_in_config,
             commands::refresh_tray_menu,
             // Server Discovery commands (v2)
             commands::discover_servers,

apps/desktop/src/components/ServerDefinitionModal.tsx

@@ -1,14 +1,17 @@
 import { useState, useEffect, useCallback } from 'react';
 import { useTranslation } from 'react-i18next';
-import { X, Copy, Check, Loader2 } from 'lucide-react';
+import { X, Copy, Check, Loader2, Save } from 'lucide-react';
 import type { ServerViewModel, ServerDefinition } from '../types/registry';
 import { MonacoJsonEditor } from './monaco-json-editor.component';
+import { updateServerInConfig } from '@/lib/api/spaces';
 
 const EDITOR_MOUNT_TIMEOUT_MS = 10_000;
 
 interface ServerDefinitionModalProps {
   server: ServerViewModel;
   onClose: () => void;
+  /** Called after a successful save so the caller can reload the server list. */
+  onSaved?: () => void;
 }
 
 const RUNTIME_SERVER_FIELDS = [
@@ -36,15 +39,49 @@ function extractDefinition(server: ServerViewModel): ServerDefinition {
   return copy as ServerDefinition;
 }
 
-export function ServerDefinitionModal({ server, onClose }: ServerDefinitionModalProps) {
+/**
+ * Build the standard MCP config format (the shape that lives under a
+ * `mcpServers` key in a space JSON file) from a server's current view model.
+ * This is the editable subset — no id/source/badges or other derived fields.
+ */
+function buildEditableEntry(server: ServerViewModel): Record<string, unknown> {
+  const entry: Record<string, unknown> = {};
+
+  if (server.transport.type === 'stdio') {
+    entry.command = server.transport.command;
+    entry.args = server.transport.args;
+    entry.env = server.transport.env;
+  } else {
+    entry.url = server.transport.url;
+    entry.headers = server.transport.headers;
+  }
+
+  entry.name = server.name;
+  if (server.description) entry.description = server.description;
+  if (server.icon) entry.icon = server.icon;
+  if (server.alias) entry.alias = server.alias;
+  if (server.auth && server.auth.type !== 'none') entry.auth = server.auth;
+  if (server.transport.metadata.inputs.length > 0) {
+    entry.metadata = { inputs: server.transport.metadata.inputs };
+  }
+
+  return entry;
+}
+
+export function ServerDefinitionModal({ server, onClose, onSaved }: ServerDefinitionModalProps) {
   const { t } = useTranslation('servers');
   const [copied, setCopied] = useState(false);
   const [editorReady, setEditorReady] = useState(false);
   const [editorMounted, setEditorMounted] = useState(false);
   const [editorLoadFailed, setEditorLoadFailed] = useState(false);
+  const [isSaving, setIsSaving] = useState(false);
+  const [saveError, setSaveError] = useState<string | null>(null);
 
-  const definition = extractDefinition(server);
-  const json = JSON.stringify(definition, null, 2);
+  const isEditable = server.source.type === 'UserSpace';
+  const [content, setContent] = useState(() =>
+    JSON.stringify(isEditable ? buildEditableEntry(server) : extractDefinition(server), null, 2),
+  );
+  const json = content;
 
   useEffect(() => {
     const timer = setTimeout(() => setEditorReady(true), 100);
@@ -97,17 +134,48 @@ export function ServerDefinitionModal({ server, onClose }: ServerDefinitionModal
     setEditorLoadFailed(true);
   };
 
+  const handleContentChange = (value: string | undefined) => {
+    if (value !== undefined) {
+      setContent(value);
+      setSaveError(null);
+    }
+  };
+
+  const handleSave = useCallback(async () => {
+    let parsed: Record<string, unknown>;
+    try {
+      parsed = JSON.parse(content);
+    } catch (e) {
+      setSaveError(t('definitionModal.invalidJson', { message: (e as Error).message }));
+      return;
+    }
+
+    if (server.source.type !== 'UserSpace') {
+      return;
+    }
+
+    setIsSaving(true);
+    setSaveError(null);
+    try {
+      await updateServerInConfig(server.source.space_id, server.id, parsed);
+      onSaved?.();
+      onClose();
+    } catch (e) {
+      setSaveError(e instanceof Error ? e.message : String(e));
+    } finally {
+      setIsSaving(false);
+    }
+  }, [content, onClose, onSaved, server, t]);
+
   return (
     <div className="fixed inset-0 bg-black/60 backdrop-blur-sm flex items-center justify-center z-50 p-4">
       <div className="bg-[rgb(var(--surface))] w-full max-w-3xl h-[70vh] rounded-xl shadow-2xl flex flex-col border border-[rgb(var(--border))] animate-in fade-in scale-in duration-150">
         {/* Header */}
         <div className="flex items-center justify-between p-4 border-b border-[rgb(var(--border))]">
           <div className="min-w-0">
-            <h3 className="text-lg font-semibold truncate">
-              {server.name}
-            </h3>
+            <h3 className="text-lg font-semibold truncate">{server.name}</h3>
             <p className="text-sm text-[rgb(var(--muted))]">
-              {t('definitionModal.subtitle')}
+              {isEditable ? t('definitionModal.subtitleEditable') : t('definitionModal.subtitle')}
             </p>
           </div>
           <div className="flex items-center gap-2">
@@ -128,6 +196,20 @@ export function ServerDefinitionModal({ server, onClose }: ServerDefinitionModal
                 </>
               )}
             </button>
+            {isEditable && (
+              <button
+                onClick={handleSave}
+                disabled={isSaving}
+                className="flex items-center gap-1.5 px-3 py-1.5 text-sm rounded-lg bg-[rgb(var(--primary))] text-white hover:bg-[rgb(var(--primary))]/90 transition-colors disabled:opacity-50"
+              >
+                {isSaving ? (
+                  <Loader2 className="h-4 w-4 animate-spin" />
+                ) : (
+                  <Save className="h-4 w-4" />
+                )}
+                {t('definitionModal.save')}
+              </button>
+            )}
             <button
               onClick={onClose}
               className="p-2 hover:bg-[rgb(var(--surface-hover))] rounded-lg transition-colors"
@@ -145,23 +227,31 @@ export function ServerDefinitionModal({ server, onClose }: ServerDefinitionModal
             </div>
           ) : editorLoadFailed ? (
             <textarea
-              readOnly
+              readOnly={!isEditable}
               value={json}
+              onChange={(e) => handleContentChange(e.target.value)}
               className="h-full w-full resize-none bg-[#1e1e1e] p-3 font-mono text-sm text-[#d4d4d4] focus:outline-none"
               spellCheck={false}
               aria-label={t('definitionModal.subtitle')}
             />
           ) : (
             <MonacoJsonEditor
               value={json}
-              readOnly
+              onChange={handleContentChange}
+              readOnly={!isEditable}
               onMount={handleEditorMount}
               onMountFailed={handleEditorMountFailed}
               testId="server-definition-monaco"
             />
           )}
         </div>
 
+        {saveError && (
+          <div className="border-t border-[rgb(var(--error))]/20 bg-[rgb(var(--error))]/10 px-4 py-2 text-xs text-[rgb(var(--error))]">
+            {saveError}
+          </div>
+        )}
+
         {editorLoadFailed && (
           <div className="border-t border-[rgb(var(--border))] bg-[rgb(var(--surface-dim))] px-4 py-2 text-xs text-[rgb(var(--muted))]">
             {t('definitionModal.editorLoadFailed')}

apps/desktop/src/features/servers/ServerActionMenu.tsx

@@ -47,6 +47,8 @@ export interface ServerActionMenuProps {
   onLockToCurrentVersion?: () => void;
   onViewLogs: () => void;
   onViewDefinition: () => void;
+  /** Whether the server's config is stored locally and can be edited (UserSpace source). */
+  canEditDefinition?: boolean;
   onCloneAccount?: () => void;
   onUninstall: () => void;
 }
@@ -73,6 +75,7 @@ export function ServerActionMenu({
   onLockToCurrentVersion,
   onViewLogs,
   onViewDefinition,
+  canEditDefinition = false,
   onCloneAccount,
   onUninstall,
 }: ServerActionMenuProps) {
@@ -168,7 +171,7 @@ export function ServerActionMenu({
         />
         <DropdownMenuAction
           icon={Code}
-          label={t('actions.viewDefinition')}
+          label={canEditDefinition ? t('actions.editDefinition') : t('actions.viewDefinition')}
           onSelect={onViewDefinition}
           data-testid={`view-definition-${serverId}`}
         />

apps/desktop/src/features/servers/ServersPage.tsx

@@ -1964,6 +1964,7 @@ export function ServersPage() {
                         onLockToCurrentVersion={() => handleLockToCurrentVersion(server)}
                         onViewLogs={() => setLogViewerServer({ id: server.id, name: server.name })}
                         onViewDefinition={() => setDefinitionServer({ id: server.id, name: server.name })}
+                        canEditDefinition={server.source.type === 'UserSpace'}
                         onCloneAccount={() =>
                           setCloneModalServer(resolveCloneSource(server, installedServers))
                         }
@@ -2680,6 +2681,7 @@ export function ServersPage() {
           <ServerDefinitionModal
             server={server}
             onClose={() => setDefinitionServer(null)}
+            onSaved={() => loadData()}
           />
         ) : null;
       })()}

apps/desktop/src/lib/api/spaces.ts

@@ -59,6 +59,19 @@ export async function removeServerFromConfig(spaceId: string, serverId: string):
   return apiCall('remove_server_from_config', { spaceId, serverId });
 }
 
+/**
+ * Replace a custom server's entry in the space configuration file.
+ * `entry` is the standard MCP format object (command/args/env or url/headers, etc.)
+ * that goes under the server's `mcpServers` key.
+ */
+export async function updateServerInConfig(
+  spaceId: string,
+  serverId: string,
+  entry: Record<string, unknown>,
+): Promise<void> {
+  return apiCall('update_server_in_config', { spaceId, serverId, entry });
+}
+
 /** Reveal a space config file in the system editor (desktop only). */
 export async function openSpaceConfigFile(spaceId: string): Promise<void> {
   return shellOpenSpaceConfigFile(spaceId);

apps/desktop/src/lib/backend/data/fetch-api.routes/spaces.routes.ts

@@ -41,6 +41,11 @@ export const spacesRoutes: Record<string, RouteHandler> = {
     method: 'DELETE',
     path: `/api/v1/spaces/${encodeURIComponent(String(args.spaceId))}/config/servers/${encodeURIComponent(String(args.serverId))}`,
   }),
+  update_server_in_config: (args) => ({
+    method: 'PUT',
+    path: `/api/v1/spaces/${encodeURIComponent(String(args.spaceId))}/config/servers/${encodeURIComponent(String(args.serverId))}`,
+    body: { entry: args.entry },
+  }),
   list_space_base_dirs: (args) => ({
     method: 'GET',
     path: `/api/v1/spaces/${encodeURIComponent(String(args.spaceId))}/base-dirs`,

apps/desktop/src/locales/en/servers.json

@@ -82,6 +82,7 @@
     "lockVersion": "Lock to current version",
     "viewLogs": "View Logs",
     "viewDefinition": "View Definition",
+    "editDefinition": "Edit Definition",
     "cloneAccount": "Add another account…",
     "uninstall": "Uninstall",
     "updateBadge": "Update available"
@@ -269,9 +270,12 @@
   },
   "definitionModal": {
     "subtitle": "Server Definition",
+    "subtitleEditable": "Edit the server's config entry",
     "copy": "Copy",
     "copied": "Copied",
     "copyTitle": "Copy to clipboard",
+    "save": "Save",
+    "invalidJson": "Invalid JSON: {{message}}",
     "editorLoadFailed": "Editor failed to load. Showing plain JSON instead."
   }
 }