@agenticmail/enterprise 0.5.244 → 0.5.246

package/dist/dashboard/components/help-button.js

@@ -21,13 +21,20 @@ export function HelpButton(props) {
       onMouseEnter: function(e) { e.currentTarget.style.borderColor = 'var(--brand-color, #6366f1)'; e.currentTarget.style.color = 'var(--brand-color, #6366f1)'; },
       onMouseLeave: function(e) { e.currentTarget.style.borderColor = 'var(--text-muted, #6b7280)'; e.currentTarget.style.color = 'var(--text-muted, #6b7280)'; }
     }, '?'),
-    isOpen && h(Modal, {
-      title: props.label || 'Help',
-      onClose: function() { setOpen(false); },
-      large: true
+    isOpen && h('div', {
+      style: { position: 'fixed', inset: 0, background: 'var(--bg-modal, rgba(0,0,0,0.7))', display: 'flex', alignItems: 'center', justifyContent: 'center', zIndex: 200, animation: 'fadeIn 150ms ease' },
+      onClick: function(e) { if (e.target === e.currentTarget) setOpen(false); }
     },
-      h('div', { style: { fontSize: 14, lineHeight: 1.7, color: 'var(--text-secondary, #9ca3af)', padding: '4px 0' } },
-        props.children
+      h('div', { className: 'modal', style: { zIndex: 201 } },
+        h('div', { className: 'modal-header' },
+          h('h2', null, props.label || 'Help'),
+          h('button', { className: 'btn btn-ghost btn-icon', onClick: function() { setOpen(false); } }, I.x())
+        ),
+        h('div', { className: 'modal-body' },
+          h('div', { style: { fontSize: 14, lineHeight: 1.7, color: 'var(--text-secondary, #9ca3af)', padding: '4px 0' } },
+            props.children
+          )
+        )
       )
     )
   );

package/dist/dashboard/pages/skill-connections.js

@@ -248,7 +248,10 @@ function McpServersSection() {
       h('div', { style: { display: 'flex', flexDirection: 'column', gap: 14 } },
         // Name
         h('div', { className: 'form-group' },
-          h('label', { className: 'form-label' }, 'Server Name *'),
+          h('label', { className: 'form-label', style: { display: 'flex', alignItems: 'center' } }, 'Server Name *', h(HelpButton, { label: 'Server Name' },
+            h('p', null, 'A friendly name so you can identify this server in the list. Use something descriptive like "GitHub Tools" or "Company Database".'),
+            h('p', null, 'This name is only for your reference — it doesn\'t affect how the server works.')
+          )),
           h('input', { className: 'input', placeholder: 'e.g., GitHub MCP, Filesystem, Database', value: form.name,
             onChange: function(e) { setForm(Object.assign({}, form, { name: e.target.value })); } })
         ),
@@ -260,7 +263,16 @@ function McpServersSection() {
         ),
         // Type selector
         h('div', { className: 'form-group' },
-          h('label', { className: 'form-label' }, 'Connection Type *'),
+          h('label', { className: 'form-label', style: { display: 'flex', alignItems: 'center' } }, 'Connection Type *', h(HelpButton, { label: 'Connection Type' },
+            h('p', null, 'How your agents communicate with this MCP server. If you\'re not sure, choose ', h('strong', null, 'Local Process'), ' — it\'s the most common and works out of the box.'),
+            h('ul', { style: { paddingLeft: 20, margin: '8px 0' } },
+              h('li', null, h('strong', null, 'Local Process'), ' — The server runs as a program on the same machine. Best for most use cases. Just provide the command to start it (like "npx" or "docker").'),
+              h('li', null, h('strong', null, 'SSE'), ' — Connects to an MCP server hosted elsewhere (another machine or cloud). Uses a live streaming connection.'),
+              h('li', null, h('strong', null, 'HTTP'), ' — Connects to a remote MCP server using simple web requests. Used by some cloud-hosted MCP services.')
+            ),
+            h('div', { style: { marginTop: 8, padding: 10, background: 'var(--bg-secondary)', borderRadius: 8, fontSize: 12 } },
+              h('strong', null, 'Not sure? '), 'Use a Quick Start Template below — it pre-fills everything for you.')
+          )),
           h('div', { style: { display: 'grid', gridTemplateColumns: '1fr 1fr 1fr', gap: 8 } },
             ['stdio', 'sse', 'http'].map(function(t) {
               var selected = form.type === t;
@@ -275,7 +287,7 @@ function McpServersSection() {
               },
                 h('div', { style: { fontWeight: 600, fontSize: 12 } }, t === 'stdio' ? 'Local Process' : t === 'sse' ? 'SSE' : 'HTTP'),
                 h('div', { style: { fontSize: 10, color: 'var(--text-muted)', marginTop: 2 } },
-                  t === 'stdio' ? 'stdin/stdout' : t === 'sse' ? 'Server-Sent Events' : 'Streamable HTTP')
+                  t === 'stdio' ? 'Runs on this machine' : t === 'sse' ? 'Remote with live stream' : 'Remote web requests')
               );
             })
           )
@@ -283,56 +295,110 @@ function McpServersSection() {
         // stdio fields
         form.type === 'stdio' && h(Fragment, null,
           h('div', { className: 'form-group' },
-            h('label', { className: 'form-label' }, 'Command *'),
+            h('label', { className: 'form-label', style: { display: 'flex', alignItems: 'center' } }, 'Command *', h(HelpButton, { label: 'Command' },
+              h('p', null, 'The program to run on your server. This is like typing a command in the terminal. Common examples:'),
+              h('ul', { style: { paddingLeft: 20, margin: '8px 0' } },
+                h('li', null, h('strong', null, 'npx'), ' — Runs Node.js packages without installing them first. Most MCP servers use this.'),
+                h('li', null, h('strong', null, 'node'), ' — Runs a JavaScript file directly.'),
+                h('li', null, h('strong', null, 'python'), ' or ', h('strong', null, 'python3'), ' — Runs Python-based MCP servers.'),
+                h('li', null, h('strong', null, 'docker'), ' — Runs the server inside a Docker container (advanced).')
+              ),
+              h('div', { style: { marginTop: 8, padding: 10, background: 'var(--bg-secondary)', borderRadius: 8, fontSize: 12 } },
+                h('strong', null, 'Tip: '), 'If you chose a Quick Start Template, this is already filled in. Most templates use "npx" which requires Node.js to be installed on your machine.')
+            )),
             h('input', { className: 'input', placeholder: 'npx, node, python, docker...', value: form.command,
               onChange: function(e) { setForm(Object.assign({}, form, { command: e.target.value })); } }),
-            h('div', { style: { fontSize: 11, color: 'var(--text-muted)', marginTop: 4 } }, 'The executable to run. Must be installed on this machine.')
+            h('div', { style: { fontSize: 11, color: 'var(--text-muted)', marginTop: 4 } }, 'The program to start the MCP server. Must be installed on this machine.')
           ),
           h('div', { className: 'form-group' },
-            h('label', { className: 'form-label' }, 'Arguments'),
-            h('input', { className: 'input', placeholder: '@modelcontextprotocol/server-filesystem /home/user/docs', value: form.args,
+            h('label', { className: 'form-label', style: { display: 'flex', alignItems: 'center' } }, 'Arguments', h(HelpButton, { label: 'Arguments' },
+              h('p', null, 'Extra instructions passed to the command. Think of it like telling the program what to do. For example:'),
+              h('ul', { style: { paddingLeft: 20, margin: '8px 0' } },
+                h('li', null, h('strong', null, '-y @modelcontextprotocol/server-filesystem /home'), ' — Tells npx to run the filesystem MCP server and give it access to /home'),
+                h('li', null, h('strong', null, '-y @modelcontextprotocol/server-github'), ' — Tells npx to run the GitHub MCP server')
+              ),
+              h('div', { style: { marginTop: 8, padding: 10, background: 'var(--bg-secondary)', borderRadius: 8, fontSize: 12 } },
+                h('strong', null, 'Tip: '), 'The "-y" flag tells npx to automatically install the package if needed, without asking. Always include it for npx commands.')
+            )),
+            h('input', { className: 'input', placeholder: '-y @modelcontextprotocol/server-filesystem /home/user/docs', value: form.args,
               onChange: function(e) { setForm(Object.assign({}, form, { args: e.target.value })); } }),
-            h('div', { style: { fontSize: 11, color: 'var(--text-muted)', marginTop: 4 } }, 'Space-separated arguments passed to the command.')
+            h('div', { style: { fontSize: 11, color: 'var(--text-muted)', marginTop: 4 } }, 'Additional options passed to the command. Separate multiple values with spaces.')
           ),
           h('div', { className: 'form-group' },
-            h('label', { className: 'form-label' }, 'Environment Variables'),
+            h('label', { className: 'form-label', style: { display: 'flex', alignItems: 'center' } }, 'Environment Variables', h(HelpButton, { label: 'Environment Variables' },
+              h('p', null, 'Some MCP servers need passwords, API keys, or settings to work. Environment variables are a secure way to pass this information.'),
+              h('p', { style: { marginTop: 8 } }, 'Format: a JSON object where each key is the variable name and each value is the secret. For example:'),
+              h('pre', { style: { background: 'var(--bg-secondary)', padding: 10, borderRadius: 8, fontSize: 12, marginTop: 8 } },
+                '{\n  "GITHUB_TOKEN": "ghp_abc123...",\n  "DATABASE_URL": "postgres://user:pass@host/db"\n}'
+              ),
+              h('div', { style: { marginTop: 8, padding: 10, background: 'var(--bg-secondary)', borderRadius: 8, fontSize: 12 } },
+                h('strong', null, 'Security: '), 'All values are encrypted before being stored. They\'re only decrypted when the server starts.')
+            )),
             h('textarea', { className: 'input', rows: 3, placeholder: '{\n  "GITHUB_TOKEN": "ghp_...",\n  "DATABASE_URL": "postgres://..."\n}', value: form.env,
               style: { fontFamily: 'var(--font-mono, monospace)', fontSize: 12 },
               onChange: function(e) { setForm(Object.assign({}, form, { env: e.target.value })); } }),
-            h('div', { style: { fontSize: 11, color: 'var(--text-muted)', marginTop: 4 } }, 'JSON object of environment variables. Secrets are encrypted at rest.')
+            h('div', { style: { fontSize: 11, color: 'var(--text-muted)', marginTop: 4 } }, 'API keys, tokens, and passwords needed by this server. Stored encrypted.')
           )
         ),
         // HTTP/SSE fields
         form.type !== 'stdio' && h(Fragment, null,
           h('div', { className: 'form-group' },
-            h('label', { className: 'form-label' }, 'Server URL *'),
+            h('label', { className: 'form-label', style: { display: 'flex', alignItems: 'center' } }, 'Server URL *', h(HelpButton, { label: 'Server URL' },
+              h('p', null, 'The web address of the remote MCP server. This is provided by whoever hosts the server.'),
+              h('p', { style: { marginTop: 8 } }, 'It usually looks like:'),
+              h('ul', { style: { paddingLeft: 20, margin: '4px 0' } },
+                h('li', null, h('strong', null, 'SSE: '), 'https://mcp.example.com/sse'),
+                h('li', null, h('strong', null, 'HTTP: '), 'https://mcp.example.com/mcp')
+              ),
+              h('div', { style: { marginTop: 8, padding: 10, background: 'var(--bg-secondary)', borderRadius: 8, fontSize: 12 } },
+                h('strong', null, 'Tip: '), 'Check the MCP server\'s documentation for the exact URL to use. If it\'s hosted on your local network, use the internal IP (e.g., http://192.168.1.100:3000/mcp).')
+            )),
             h('input', { className: 'input', placeholder: form.type === 'sse' ? 'https://mcp.example.com/sse' : 'https://mcp.example.com/mcp', value: form.url,
-              onChange: function(e) { setForm(Object.assign({}, form, { url: e.target.value })); } })
+              onChange: function(e) { setForm(Object.assign({}, form, { url: e.target.value })); } }),
+            h('div', { style: { fontSize: 11, color: 'var(--text-muted)', marginTop: 4 } }, 'The web address where the MCP server is running.')
           ),
           h('div', { className: 'form-group' },
-            h('label', { className: 'form-label' }, 'API Key / Bearer Token'),
-            h('input', { className: 'input', type: 'password', placeholder: 'Optional — for authenticated endpoints', value: form.apiKey,
-              onChange: function(e) { setForm(Object.assign({}, form, { apiKey: e.target.value })); } })
+            h('label', { className: 'form-label', style: { display: 'flex', alignItems: 'center' } }, 'API Key / Bearer Token', h(HelpButton, { label: 'API Key' },
+              h('p', null, 'If the remote server requires authentication, paste the API key or token here. This is like a password that proves you\'re allowed to use the server.'),
+              h('p', { style: { marginTop: 8 } }, 'You usually get this from the MCP server provider\'s dashboard or settings page. If the server is open/public, leave this empty.')
+            )),
+            h('input', { className: 'input', type: 'password', placeholder: 'Optional — only if the server requires authentication', value: form.apiKey,
+              onChange: function(e) { setForm(Object.assign({}, form, { apiKey: e.target.value })); } }),
+            h('div', { style: { fontSize: 11, color: 'var(--text-muted)', marginTop: 4 } }, 'Only needed if the server requires authentication. Leave empty for open servers.')
           ),
           h('div', { className: 'form-group' },
-            h('label', { className: 'form-label' }, 'Custom Headers'),
+            h('label', { className: 'form-label', style: { display: 'flex', alignItems: 'center' } }, 'Custom Headers', h(HelpButton, { label: 'Custom Headers' },
+              h('p', null, 'Advanced setting. Some servers need extra information sent with every request (like an organization ID or custom authentication format).'),
+              h('p', { style: { marginTop: 8 } }, 'Most users can leave this empty. If you need it, your MCP server provider will tell you what to put here.'),
+              h('div', { style: { marginTop: 8, padding: 10, background: 'var(--bg-secondary)', borderRadius: 8, fontSize: 12 } },
+                h('strong', null, 'Tip: '), 'This is rarely needed. If you\'re not sure, skip it.')
+            )),
             h('textarea', { className: 'input', rows: 2, placeholder: '{\n  "X-Custom-Header": "value"\n}', value: form.headers,
               style: { fontFamily: 'var(--font-mono, monospace)', fontSize: 12 },
-              onChange: function(e) { setForm(Object.assign({}, form, { headers: e.target.value })); } })
+              onChange: function(e) { setForm(Object.assign({}, form, { headers: e.target.value })); } }),
+            h('div', { style: { fontSize: 11, color: 'var(--text-muted)', marginTop: 4 } }, 'Advanced. Usually not needed — leave empty unless told otherwise.')
           )
         ),
         // Common settings
         h('div', { style: { display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 12 } },
           h('div', { className: 'form-group' },
-            h('label', { className: 'form-label' }, 'Connection Timeout (s)'),
+            h('label', { className: 'form-label', style: { display: 'flex', alignItems: 'center' } }, 'Connection Timeout', h(HelpButton, { label: 'Timeout' },
+              h('p', null, 'How long to wait (in seconds) for the server to respond before giving up. The default of 30 seconds works for most servers.'),
+              h('p', { style: { marginTop: 8 } }, 'Increase this if the server is slow to start (e.g., Docker containers) or on a slow network.')
+            )),
             h('input', { className: 'input', type: 'number', min: 5, max: 300, value: form.timeout,
-              onChange: function(e) { setForm(Object.assign({}, form, { timeout: e.target.value })); } })
+              onChange: function(e) { setForm(Object.assign({}, form, { timeout: e.target.value })); } }),
+            h('div', { style: { fontSize: 11, color: 'var(--text-muted)', marginTop: 4 } }, 'Seconds to wait. 30 is usually fine.')
           ),
           h('div', { className: 'form-group' },
             h('label', { style: { display: 'flex', alignItems: 'center', gap: 8, cursor: 'pointer', fontSize: 13, marginTop: 24 } },
               h('input', { type: 'checkbox', checked: form.autoRestart,
                 onChange: function(e) { setForm(Object.assign({}, form, { autoRestart: e.target.checked })); } }),
-              'Auto-restart on failure'
+              'Auto-restart on failure',
+              h(HelpButton, { label: 'Auto-restart' },
+                h('p', null, 'If the MCP server crashes or stops unexpectedly, we\'ll automatically restart it so your agents don\'t lose access to its tools.'),
+                h('p', { style: { marginTop: 8 } }, 'Keep this on unless you have a reason to disable it.')
+              )
             )
           )
         ),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/enterprise",
-  "version": "0.5.244",
+  "version": "0.5.246",
   "description": "AgenticMail Enterprise — cloud-hosted AI agent identity, email, auth & compliance for organizations",
   "type": "module",
   "bin": {

package/src/dashboard/components/help-button.js

@@ -21,13 +21,20 @@ export function HelpButton(props) {
       onMouseEnter: function(e) { e.currentTarget.style.borderColor = 'var(--brand-color, #6366f1)'; e.currentTarget.style.color = 'var(--brand-color, #6366f1)'; },
       onMouseLeave: function(e) { e.currentTarget.style.borderColor = 'var(--text-muted, #6b7280)'; e.currentTarget.style.color = 'var(--text-muted, #6b7280)'; }
     }, '?'),
-    isOpen && h(Modal, {
-      title: props.label || 'Help',
-      onClose: function() { setOpen(false); },
-      large: true
+    isOpen && h('div', {
+      style: { position: 'fixed', inset: 0, background: 'var(--bg-modal, rgba(0,0,0,0.7))', display: 'flex', alignItems: 'center', justifyContent: 'center', zIndex: 200, animation: 'fadeIn 150ms ease' },
+      onClick: function(e) { if (e.target === e.currentTarget) setOpen(false); }
     },
-      h('div', { style: { fontSize: 14, lineHeight: 1.7, color: 'var(--text-secondary, #9ca3af)', padding: '4px 0' } },
-        props.children
+      h('div', { className: 'modal', style: { zIndex: 201 } },
+        h('div', { className: 'modal-header' },
+          h('h2', null, props.label || 'Help'),
+          h('button', { className: 'btn btn-ghost btn-icon', onClick: function() { setOpen(false); } }, I.x())
+        ),
+        h('div', { className: 'modal-body' },
+          h('div', { style: { fontSize: 14, lineHeight: 1.7, color: 'var(--text-secondary, #9ca3af)', padding: '4px 0' } },
+            props.children
+          )
+        )
       )
     )
   );

package/src/dashboard/pages/skill-connections.js

@@ -248,7 +248,10 @@ function McpServersSection() {
       h('div', { style: { display: 'flex', flexDirection: 'column', gap: 14 } },
         // Name
         h('div', { className: 'form-group' },
-          h('label', { className: 'form-label' }, 'Server Name *'),
+          h('label', { className: 'form-label', style: { display: 'flex', alignItems: 'center' } }, 'Server Name *', h(HelpButton, { label: 'Server Name' },
+            h('p', null, 'A friendly name so you can identify this server in the list. Use something descriptive like "GitHub Tools" or "Company Database".'),
+            h('p', null, 'This name is only for your reference — it doesn\'t affect how the server works.')
+          )),
           h('input', { className: 'input', placeholder: 'e.g., GitHub MCP, Filesystem, Database', value: form.name,
             onChange: function(e) { setForm(Object.assign({}, form, { name: e.target.value })); } })
         ),
@@ -260,7 +263,16 @@ function McpServersSection() {
         ),
         // Type selector
         h('div', { className: 'form-group' },
-          h('label', { className: 'form-label' }, 'Connection Type *'),
+          h('label', { className: 'form-label', style: { display: 'flex', alignItems: 'center' } }, 'Connection Type *', h(HelpButton, { label: 'Connection Type' },
+            h('p', null, 'How your agents communicate with this MCP server. If you\'re not sure, choose ', h('strong', null, 'Local Process'), ' — it\'s the most common and works out of the box.'),
+            h('ul', { style: { paddingLeft: 20, margin: '8px 0' } },
+              h('li', null, h('strong', null, 'Local Process'), ' — The server runs as a program on the same machine. Best for most use cases. Just provide the command to start it (like "npx" or "docker").'),
+              h('li', null, h('strong', null, 'SSE'), ' — Connects to an MCP server hosted elsewhere (another machine or cloud). Uses a live streaming connection.'),
+              h('li', null, h('strong', null, 'HTTP'), ' — Connects to a remote MCP server using simple web requests. Used by some cloud-hosted MCP services.')
+            ),
+            h('div', { style: { marginTop: 8, padding: 10, background: 'var(--bg-secondary)', borderRadius: 8, fontSize: 12 } },
+              h('strong', null, 'Not sure? '), 'Use a Quick Start Template below — it pre-fills everything for you.')
+          )),
           h('div', { style: { display: 'grid', gridTemplateColumns: '1fr 1fr 1fr', gap: 8 } },
             ['stdio', 'sse', 'http'].map(function(t) {
               var selected = form.type === t;
@@ -275,7 +287,7 @@ function McpServersSection() {
               },
                 h('div', { style: { fontWeight: 600, fontSize: 12 } }, t === 'stdio' ? 'Local Process' : t === 'sse' ? 'SSE' : 'HTTP'),
                 h('div', { style: { fontSize: 10, color: 'var(--text-muted)', marginTop: 2 } },
-                  t === 'stdio' ? 'stdin/stdout' : t === 'sse' ? 'Server-Sent Events' : 'Streamable HTTP')
+                  t === 'stdio' ? 'Runs on this machine' : t === 'sse' ? 'Remote with live stream' : 'Remote web requests')
               );
             })
           )
@@ -283,56 +295,110 @@ function McpServersSection() {
         // stdio fields
         form.type === 'stdio' && h(Fragment, null,
           h('div', { className: 'form-group' },
-            h('label', { className: 'form-label' }, 'Command *'),
+            h('label', { className: 'form-label', style: { display: 'flex', alignItems: 'center' } }, 'Command *', h(HelpButton, { label: 'Command' },
+              h('p', null, 'The program to run on your server. This is like typing a command in the terminal. Common examples:'),
+              h('ul', { style: { paddingLeft: 20, margin: '8px 0' } },
+                h('li', null, h('strong', null, 'npx'), ' — Runs Node.js packages without installing them first. Most MCP servers use this.'),
+                h('li', null, h('strong', null, 'node'), ' — Runs a JavaScript file directly.'),
+                h('li', null, h('strong', null, 'python'), ' or ', h('strong', null, 'python3'), ' — Runs Python-based MCP servers.'),
+                h('li', null, h('strong', null, 'docker'), ' — Runs the server inside a Docker container (advanced).')
+              ),
+              h('div', { style: { marginTop: 8, padding: 10, background: 'var(--bg-secondary)', borderRadius: 8, fontSize: 12 } },
+                h('strong', null, 'Tip: '), 'If you chose a Quick Start Template, this is already filled in. Most templates use "npx" which requires Node.js to be installed on your machine.')
+            )),
             h('input', { className: 'input', placeholder: 'npx, node, python, docker...', value: form.command,
               onChange: function(e) { setForm(Object.assign({}, form, { command: e.target.value })); } }),
-            h('div', { style: { fontSize: 11, color: 'var(--text-muted)', marginTop: 4 } }, 'The executable to run. Must be installed on this machine.')
+            h('div', { style: { fontSize: 11, color: 'var(--text-muted)', marginTop: 4 } }, 'The program to start the MCP server. Must be installed on this machine.')
           ),
           h('div', { className: 'form-group' },
-            h('label', { className: 'form-label' }, 'Arguments'),
-            h('input', { className: 'input', placeholder: '@modelcontextprotocol/server-filesystem /home/user/docs', value: form.args,
+            h('label', { className: 'form-label', style: { display: 'flex', alignItems: 'center' } }, 'Arguments', h(HelpButton, { label: 'Arguments' },
+              h('p', null, 'Extra instructions passed to the command. Think of it like telling the program what to do. For example:'),
+              h('ul', { style: { paddingLeft: 20, margin: '8px 0' } },
+                h('li', null, h('strong', null, '-y @modelcontextprotocol/server-filesystem /home'), ' — Tells npx to run the filesystem MCP server and give it access to /home'),
+                h('li', null, h('strong', null, '-y @modelcontextprotocol/server-github'), ' — Tells npx to run the GitHub MCP server')
+              ),
+              h('div', { style: { marginTop: 8, padding: 10, background: 'var(--bg-secondary)', borderRadius: 8, fontSize: 12 } },
+                h('strong', null, 'Tip: '), 'The "-y" flag tells npx to automatically install the package if needed, without asking. Always include it for npx commands.')
+            )),
+            h('input', { className: 'input', placeholder: '-y @modelcontextprotocol/server-filesystem /home/user/docs', value: form.args,
               onChange: function(e) { setForm(Object.assign({}, form, { args: e.target.value })); } }),
-            h('div', { style: { fontSize: 11, color: 'var(--text-muted)', marginTop: 4 } }, 'Space-separated arguments passed to the command.')
+            h('div', { style: { fontSize: 11, color: 'var(--text-muted)', marginTop: 4 } }, 'Additional options passed to the command. Separate multiple values with spaces.')
           ),
           h('div', { className: 'form-group' },
-            h('label', { className: 'form-label' }, 'Environment Variables'),
+            h('label', { className: 'form-label', style: { display: 'flex', alignItems: 'center' } }, 'Environment Variables', h(HelpButton, { label: 'Environment Variables' },
+              h('p', null, 'Some MCP servers need passwords, API keys, or settings to work. Environment variables are a secure way to pass this information.'),
+              h('p', { style: { marginTop: 8 } }, 'Format: a JSON object where each key is the variable name and each value is the secret. For example:'),
+              h('pre', { style: { background: 'var(--bg-secondary)', padding: 10, borderRadius: 8, fontSize: 12, marginTop: 8 } },
+                '{\n  "GITHUB_TOKEN": "ghp_abc123...",\n  "DATABASE_URL": "postgres://user:pass@host/db"\n}'
+              ),
+              h('div', { style: { marginTop: 8, padding: 10, background: 'var(--bg-secondary)', borderRadius: 8, fontSize: 12 } },
+                h('strong', null, 'Security: '), 'All values are encrypted before being stored. They\'re only decrypted when the server starts.')
+            )),
             h('textarea', { className: 'input', rows: 3, placeholder: '{\n  "GITHUB_TOKEN": "ghp_...",\n  "DATABASE_URL": "postgres://..."\n}', value: form.env,
               style: { fontFamily: 'var(--font-mono, monospace)', fontSize: 12 },
               onChange: function(e) { setForm(Object.assign({}, form, { env: e.target.value })); } }),
-            h('div', { style: { fontSize: 11, color: 'var(--text-muted)', marginTop: 4 } }, 'JSON object of environment variables. Secrets are encrypted at rest.')
+            h('div', { style: { fontSize: 11, color: 'var(--text-muted)', marginTop: 4 } }, 'API keys, tokens, and passwords needed by this server. Stored encrypted.')
           )
         ),
         // HTTP/SSE fields
         form.type !== 'stdio' && h(Fragment, null,
           h('div', { className: 'form-group' },
-            h('label', { className: 'form-label' }, 'Server URL *'),
+            h('label', { className: 'form-label', style: { display: 'flex', alignItems: 'center' } }, 'Server URL *', h(HelpButton, { label: 'Server URL' },
+              h('p', null, 'The web address of the remote MCP server. This is provided by whoever hosts the server.'),
+              h('p', { style: { marginTop: 8 } }, 'It usually looks like:'),
+              h('ul', { style: { paddingLeft: 20, margin: '4px 0' } },
+                h('li', null, h('strong', null, 'SSE: '), 'https://mcp.example.com/sse'),
+                h('li', null, h('strong', null, 'HTTP: '), 'https://mcp.example.com/mcp')
+              ),
+              h('div', { style: { marginTop: 8, padding: 10, background: 'var(--bg-secondary)', borderRadius: 8, fontSize: 12 } },
+                h('strong', null, 'Tip: '), 'Check the MCP server\'s documentation for the exact URL to use. If it\'s hosted on your local network, use the internal IP (e.g., http://192.168.1.100:3000/mcp).')
+            )),
             h('input', { className: 'input', placeholder: form.type === 'sse' ? 'https://mcp.example.com/sse' : 'https://mcp.example.com/mcp', value: form.url,
-              onChange: function(e) { setForm(Object.assign({}, form, { url: e.target.value })); } })
+              onChange: function(e) { setForm(Object.assign({}, form, { url: e.target.value })); } }),
+            h('div', { style: { fontSize: 11, color: 'var(--text-muted)', marginTop: 4 } }, 'The web address where the MCP server is running.')
           ),
           h('div', { className: 'form-group' },
-            h('label', { className: 'form-label' }, 'API Key / Bearer Token'),
-            h('input', { className: 'input', type: 'password', placeholder: 'Optional — for authenticated endpoints', value: form.apiKey,
-              onChange: function(e) { setForm(Object.assign({}, form, { apiKey: e.target.value })); } })
+            h('label', { className: 'form-label', style: { display: 'flex', alignItems: 'center' } }, 'API Key / Bearer Token', h(HelpButton, { label: 'API Key' },
+              h('p', null, 'If the remote server requires authentication, paste the API key or token here. This is like a password that proves you\'re allowed to use the server.'),
+              h('p', { style: { marginTop: 8 } }, 'You usually get this from the MCP server provider\'s dashboard or settings page. If the server is open/public, leave this empty.')
+            )),
+            h('input', { className: 'input', type: 'password', placeholder: 'Optional — only if the server requires authentication', value: form.apiKey,
+              onChange: function(e) { setForm(Object.assign({}, form, { apiKey: e.target.value })); } }),
+            h('div', { style: { fontSize: 11, color: 'var(--text-muted)', marginTop: 4 } }, 'Only needed if the server requires authentication. Leave empty for open servers.')
           ),
           h('div', { className: 'form-group' },
-            h('label', { className: 'form-label' }, 'Custom Headers'),
+            h('label', { className: 'form-label', style: { display: 'flex', alignItems: 'center' } }, 'Custom Headers', h(HelpButton, { label: 'Custom Headers' },
+              h('p', null, 'Advanced setting. Some servers need extra information sent with every request (like an organization ID or custom authentication format).'),
+              h('p', { style: { marginTop: 8 } }, 'Most users can leave this empty. If you need it, your MCP server provider will tell you what to put here.'),
+              h('div', { style: { marginTop: 8, padding: 10, background: 'var(--bg-secondary)', borderRadius: 8, fontSize: 12 } },
+                h('strong', null, 'Tip: '), 'This is rarely needed. If you\'re not sure, skip it.')
+            )),
             h('textarea', { className: 'input', rows: 2, placeholder: '{\n  "X-Custom-Header": "value"\n}', value: form.headers,
               style: { fontFamily: 'var(--font-mono, monospace)', fontSize: 12 },
-              onChange: function(e) { setForm(Object.assign({}, form, { headers: e.target.value })); } })
+              onChange: function(e) { setForm(Object.assign({}, form, { headers: e.target.value })); } }),
+            h('div', { style: { fontSize: 11, color: 'var(--text-muted)', marginTop: 4 } }, 'Advanced. Usually not needed — leave empty unless told otherwise.')
           )
         ),
         // Common settings
         h('div', { style: { display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 12 } },
           h('div', { className: 'form-group' },
-            h('label', { className: 'form-label' }, 'Connection Timeout (s)'),
+            h('label', { className: 'form-label', style: { display: 'flex', alignItems: 'center' } }, 'Connection Timeout', h(HelpButton, { label: 'Timeout' },
+              h('p', null, 'How long to wait (in seconds) for the server to respond before giving up. The default of 30 seconds works for most servers.'),
+              h('p', { style: { marginTop: 8 } }, 'Increase this if the server is slow to start (e.g., Docker containers) or on a slow network.')
+            )),
             h('input', { className: 'input', type: 'number', min: 5, max: 300, value: form.timeout,
-              onChange: function(e) { setForm(Object.assign({}, form, { timeout: e.target.value })); } })
+              onChange: function(e) { setForm(Object.assign({}, form, { timeout: e.target.value })); } }),
+            h('div', { style: { fontSize: 11, color: 'var(--text-muted)', marginTop: 4 } }, 'Seconds to wait. 30 is usually fine.')
           ),
           h('div', { className: 'form-group' },
             h('label', { style: { display: 'flex', alignItems: 'center', gap: 8, cursor: 'pointer', fontSize: 13, marginTop: 24 } },
               h('input', { type: 'checkbox', checked: form.autoRestart,
                 onChange: function(e) { setForm(Object.assign({}, form, { autoRestart: e.target.checked })); } }),
-              'Auto-restart on failure'
+              'Auto-restart on failure',
+              h(HelpButton, { label: 'Auto-restart' },
+                h('p', null, 'If the MCP server crashes or stops unexpectedly, we\'ll automatically restart it so your agents don\'t lose access to its tools.'),
+                h('p', { style: { marginTop: 8 } }, 'Keep this on unless you have a reason to disable it.')
+              )
             )
           )
         ),