feat(webui): editable MCP instructions textarea in Advanced settings

Adds a 'MCP server instructions' accordion to Settings → Advanced with an
editable textarea bound to the top-level `instructions` config key via the
key-driven SettingsSection pattern (getPath/buildPartial).

- New `textarea` control type in the settings field catalogue + SettingField.
- Built-in default shown as the placeholder, fetched live from
  /api/v1/status `default_instructions` (never hardcoded in the frontend);
  degrades gracefully when an older core doesn't expose it.
- Empty-means-default: clearing the box (incl. whitespace-only) persists "",
  which the backend maps back to the built-in default.
- vitest unit tests for the textarea control + field catalogue; docs row note.

Related #389
Related MCP-2175

Author: Dumbris

docs/configuration.md

@@ -770,6 +770,8 @@ Text returned in the MCP `initialize` response to guide AI agents on how to use
 |-------|------|---------|-------------|
 | `instructions` | string | _(built-in)_ | Custom instructions sent in the MCP `initialize` response. When empty, a built-in default explains the `retrieve_tools` → `call_tool_*` workflow and warns against using `search_servers` for existing tools. |
 
+You can edit this from the Web UI under **Settings → Advanced → MCP server instructions**. The textarea shows the built-in default as a greyed-out placeholder; clearing it restores that default.
+
 **Note:** Applied at startup / on the next client connect — editing this value does not hot-reload into already-connected MCP sessions.
 
 ---

frontend/src/components/settings/SettingField.vue

@@ -135,6 +135,20 @@
         <span v-if="validationError" class="text-error text-xs mt-1" :data-test="`setting-error-${field.key}`">{{ validationError }}</span>
       </div>
 
+      <!-- textarea (multi-line text, e.g. MCP server instructions) -->
+      <div v-else-if="field.control === 'textarea'" class="flex flex-col items-stretch w-full sm:w-96">
+        <textarea
+          class="textarea textarea-bordered textarea-sm w-full font-mono leading-snug"
+          :class="{ 'textarea-error': validationError }"
+          rows="6"
+          :value="modelValue ?? ''"
+          :placeholder="field.placeholder"
+          :data-test="`setting-textarea-${field.key}`"
+          @input="emitText(($event.target as HTMLTextAreaElement).value)"
+        ></textarea>
+        <span v-if="validationError" class="text-error text-xs mt-1" :data-test="`setting-error-${field.key}`">{{ validationError }}</span>
+      </div>
+
       <!-- multiselect (checkbox group) -->
       <div v-else-if="field.control === 'multiselect'" class="flex flex-wrap gap-3 justify-end max-w-xs">
         <label v-for="opt in field.options" :key="opt.value" class="label cursor-pointer gap-1 p-0">
@@ -210,6 +224,12 @@ function emitText(raw: string) {
     emitVal(null)
     return
   }
+  // Empty-means-default: a textarea cleared to only whitespace persists as ""
+  // (the backend maps "" → built-in default), never a whitespace-only string.
+  if (props.field.control === 'textarea' && raw.trim() === '') {
+    emitVal('')
+    return
+  }
   emitVal(raw)
 }
 

frontend/src/services/api.ts

@@ -246,8 +246,11 @@ class APIService {
   }
 
   // Status endpoint
-  async getStatus(): Promise<APIResponse<{ edition: string; running: boolean; routing_mode: string }>> {
-    return this.request<{ edition: string; running: boolean; routing_mode: string }>('/api/v1/status')
+  // `default_instructions` is the resolved built-in MCP instructions default
+  // (MCP-2175) — present once the backend exposes it; optional so the Web UI
+  // degrades gracefully against older cores.
+  async getStatus(): Promise<APIResponse<{ edition: string; running: boolean; routing_mode: string; default_instructions?: string }>> {
+    return this.request<{ edition: string; running: boolean; routing_mode: string; default_instructions?: string }>('/api/v1/status')
   }
 
   // Routing mode endpoint

frontend/src/views/Settings.vue

@@ -193,6 +193,7 @@ import {
   DOCS_BASE,
   docsUrl,
   type SettingField,
+  type SettingsAccordion,
 } from '@/views/settings/fields'
 import api from '@/services/api'
 
@@ -201,10 +202,28 @@ const systemStore = useSystemStore()
 
 const securityFields = SECURITY_FIELDS
 const generalFields = GENERAL_FIELDS
-const advancedAccordions = ADVANCED_ACCORDIONS
 const serverEditionFields = SERVER_EDITION_FIELDS
 const serverEditionTitle = SERVER_EDITION_SECTION_TITLE
 
+// Resolved built-in MCP `instructions` default (MCP-2175), fetched from the
+// backend so the `instructions` textarea placeholder never drifts from Go.
+const defaultInstructions = ref<string>('')
+
+// Inject the live default as the `instructions` field placeholder. Until the
+// fetch resolves (or against an older core that doesn't expose it) the static
+// catalogue placeholder ("Loading built-in default…") is used.
+const advancedAccordions = computed<SettingsAccordion[]>(() =>
+  ADVANCED_ACCORDIONS.map((acc) => {
+    if (!defaultInstructions.value || !acc.fields.some((f) => f.key === 'instructions')) return acc
+    return {
+      ...acc,
+      fields: acc.fields.map((f) =>
+        f.key === 'instructions' ? { ...f, placeholder: defaultInstructions.value } : f
+      ),
+    }
+  })
+)
+
 // ---- form state ----
 const loading = ref(false)
 const loaded = ref(false)
@@ -224,7 +243,7 @@ const search = ref('')
 const allFields = computed<SettingField[]>(() => [
   ...securityFields,
   ...generalFields,
-  ...advancedAccordions.flatMap((a) => a.fields),
+  ...advancedAccordions.value.flatMap((a) => a.fields),
   ...(hasServerEdition.value ? serverEditionFields : []),
 ])
 const filteredFields = computed<SettingField[]>(() => {
@@ -399,8 +418,23 @@ function handleConfigSaved() {
   loadConfig()
 }
 
+// Fetch the resolved built-in MCP instructions default for the textarea
+// placeholder (MCP-2175). Non-fatal: a failure or an older core just leaves the
+// static catalogue placeholder in place.
+async function loadDefaultInstructions() {
+  try {
+    const resp = await api.getStatus()
+    if (resp.success && typeof resp.data?.default_instructions === 'string') {
+      defaultInstructions.value = resp.data.default_instructions
+    }
+  } catch {
+    /* leave placeholder as the static fallback */
+  }
+}
+
 onMounted(() => {
   loadConfig()
+  loadDefaultInstructions()
   window.addEventListener('mcpproxy:config-saved', handleConfigSaved)
 })
 onUnmounted(() => {

frontend/src/views/settings/fields.ts

@@ -9,6 +9,7 @@ export type ControlType =
   | 'select'
   | 'number'
   | 'text'
+  | 'textarea'
   | 'secret'
   | 'duration'
   | 'multiselect'
@@ -278,6 +279,26 @@ export const SERVER_EDITION_FIELDS: SettingField[] = [
 
 // ---- Section 3: Advanced (subsystem accordions) ----
 export const ADVANCED_ACCORDIONS: SettingsAccordion[] = [
+  {
+    id: 'mcp',
+    title: 'MCP server instructions',
+    description:
+      'Text sent to AI clients in the MCP initialize response, guiding how to use the proxy. Power-user, set-once option.',
+    fields: [
+      {
+        key: 'instructions',
+        label: 'Server instructions',
+        // Empty saves "" — Go maps that back to the built-in default, which is
+        // shown here as the placeholder (fetched live so it never drifts from
+        // the backend). Applied at startup / on the next client connect; it
+        // does not hot-reload into already-connected MCP sessions.
+        help: 'Leave blank to use the built-in default (shown greyed-out below). Applied on the next client connect, not to already-connected sessions.',
+        control: 'textarea',
+        optional: true,
+        placeholder: 'Loading built-in default…',
+      },
+    ],
+  },
   {
     id: 'code-execution',
     docs: '/features/code-execution',

frontend/tests/unit/settings-instructions.spec.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from 'vitest'
+import { mount } from '@vue/test-utils'
+import SettingField from '@/components/settings/SettingField.vue'
+import { ADVANCED_ACCORDIONS, validateField, type SettingField as Field } from '@/views/settings/fields'
+
+// MCP-2175 — editable `instructions` textarea in Advanced settings.
+// The built-in default (Go: defaultInstructions) is shown as the placeholder
+// and clearing the box must persist "" (Go maps "" -> default), never whitespace.
+
+const instrField: Field = {
+  key: 'instructions',
+  label: 'Server instructions',
+  control: 'textarea',
+  optional: true,
+  placeholder: 'BUILT-IN DEFAULT',
+}
+
+describe('SettingField textarea control', () => {
+  it('renders a <textarea> with the default bound as placeholder', () => {
+    const w = mount(SettingField, { props: { field: instrField, modelValue: '' } })
+    const ta = w.find('[data-test="setting-textarea-instructions"]')
+    expect(ta.exists()).toBe(true)
+    expect(ta.element.tagName).toBe('TEXTAREA')
+    expect(ta.attributes('placeholder')).toBe('BUILT-IN DEFAULT')
+  })
+
+  it('emits "" when cleared to whitespace-only (empty-means-default)', async () => {
+    const w = mount(SettingField, { props: { field: instrField, modelValue: 'old custom' } })
+    const ta = w.find('[data-test="setting-textarea-instructions"]')
+    await ta.setValue('   \n  ')
+    const emits = w.emitted('update:modelValue')
+    expect(emits).toBeTruthy()
+    expect(emits![emits!.length - 1][0]).toBe('')
+  })
+
+  it('preserves real multi-line content verbatim', async () => {
+    const w = mount(SettingField, { props: { field: instrField, modelValue: '' } })
+    const ta = w.find('[data-test="setting-textarea-instructions"]')
+    await ta.setValue('Use retrieve_tools first.\nThen call_tool_read.')
+    const emits = w.emitted('update:modelValue')
+    expect(emits![emits!.length - 1][0]).toBe('Use retrieve_tools first.\nThen call_tool_read.')
+  })
+})
+
+describe('instructions field catalogue (MCP-2175)', () => {
+  it('exposes an Advanced "mcp" accordion with an optional textarea instructions field', () => {
+    const mcp = ADVANCED_ACCORDIONS.find((a) => a.id === 'mcp')
+    expect(mcp, 'expected an Advanced accordion with id "mcp"').toBeTruthy()
+    const f = mcp!.fields.find((x) => x.key === 'instructions')
+    expect(f, 'expected an "instructions" field in the mcp accordion').toBeTruthy()
+    expect(f!.control).toBe('textarea')
+    expect(f!.optional).toBe(true)
+  })
+
+  it('treats any blank/whitespace instructions value as valid', () => {
+    const f: Field = { key: 'instructions', label: 'x', control: 'textarea', optional: true }
+    expect(validateField(f, '')).toBeNull()
+    expect(validateField(f, '   ')).toBeNull()
+    expect(validateField(f, 'custom instructions text')).toBeNull()
+  })
+})