feat(ai-chat): per-MCP-server instructions in the agent system prompt (#180)

Admins can now give each EXTERNAL MCP server a free-text instruction ("how/
when to use this server's tools") that the agent receives in its SYSTEM
PROMPT next to the tool descriptions — porting the built-in SERVER_INSTRUCTIONS
idea to admin-configured servers. Trusted, admin-authored text (like a system
prompt); NON-secret, so unlike headersEnc it IS returned in views/forms.

- Migration: nullable `instructions text` on ai_mcp_servers (old rows = null =
  no guidance). Table type + repo insert/update (blank/whitespace -> null via
  blankToNull). DTO `@MaxLength(4000)`. Service threads it through
  McpServerView/toView.
- mcp-clients: `McpServerInstruction { serverName, toolPrefix, instructions }`
  threaded through the toolset/cache/lease. Guidance is built ONLY for a server
  that actually connected AND contributed >=1 callable tool (the allowlist may
  filter all of them out) AND has non-blank text — so a guide never appears for
  tools the agent cannot call. Cached with the toolset, so an edit is picked up
  next turn via the existing CRUD cache invalidation.
- System prompt: `buildMcpToolingBlock` renders an <mcp_tooling> block INSIDE
  the safety sandwich (after context, before the trailing SAFETY_FRAMEWORK) so
  it informs tool choice but cannot override the rules; each section is headed
  by the server's `prefix_*` namespace. Empty/blank -> block omitted. The
  caller (ai-chat.service) now builds the external toolset BEFORE the prompt and
  passes external.instructions; client-handle lifecycle (close-once) unchanged.
- Client: instructions field in types + a Textarea (autosize, maxLength 4000)
  in the MCP-server form with a namespace-prefix hint; i18n (en/ru).

Tests across every layer (prompt block placement + both SAFETY copies; view
blank->null; buildEntry includes guidance only for connected+>=1-tool+non-blank;
DTO MaxLength; repo + integration round-trip; service wiring). Delegated impl
reviewed (APPROVE); applied the import-type follow-up.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

apps/server/src/database/repos/ai-chat/ai-mcp-server.repo.spec.ts

@@ -1,4 +1,4 @@
-import { parseToolAllowlist } from './ai-mcp-server.repo';
+import { parseToolAllowlist, blankToNull } from './ai-mcp-server.repo';
 
 /**
  * The `tool_allowlist` jsonb column historically round-trips as a JSON STRING
@@ -10,7 +10,10 @@ import { parseToolAllowlist } from './ai-mcp-server.repo';
  */
 describe('parseToolAllowlist', () => {
   it('passes a real string array through unchanged', () => {
-    expect(parseToolAllowlist(['search', 'crawl'])).toEqual(['search', 'crawl']);
+    expect(parseToolAllowlist(['search', 'crawl'])).toEqual([
+      'search',
+      'crawl',
+    ]);
   });
 
   it('parses a JSON-string array (the double-encoded read) into an array', () => {
@@ -46,3 +49,26 @@ describe('parseToolAllowlist', () => {
     expect(parseToolAllowlist(true as unknown)).toBeNull();
   });
 });
+
+/**
+ * `blankToNull` normalizes the per-server `instructions` free text before it is
+ * stored (#180): a missing/blank/whitespace-only value becomes null (so an empty
+ * guide is never persisted), any other value is trimmed.
+ */
+describe('blankToNull', () => {
+  it('returns null for null / undefined', () => {
+    expect(blankToNull(null)).toBeNull();
+    expect(blankToNull(undefined)).toBeNull();
+  });
+
+  it('returns null for an empty / whitespace-only string', () => {
+    expect(blankToNull('')).toBeNull();
+    expect(blankToNull('   ')).toBeNull();
+    expect(blankToNull('\n\t ')).toBeNull();
+  });
+
+  it('trims and returns a non-blank string', () => {
+    expect(blankToNull('  use the search tool  ')).toBe('use the search tool');
+    expect(blankToNull('guide')).toBe('guide');
+  });
+});

apps/server/src/database/repos/ai-chat/ai-mcp-server.repo.ts

@@ -61,6 +61,8 @@ export class AiMcpServerRepo {
       url: string;
       headersEnc?: string | null;
       toolAllowlist?: string[] | null;
+      // Admin-authored prompt guidance; blank/whitespace normalizes to null.
+      instructions?: string | null;
       enabled?: boolean;
     },
     trx?: KyselyTransaction,
@@ -77,6 +79,8 @@ export class AiMcpServerRepo {
         // jsonb column: the postgres driver would otherwise encode a JS array as
         // a Postgres array literal. Bind the JSON text and cast it to jsonb.
         toolAllowlist: jsonbBind(values.toolAllowlist),
+        // Plain text column: blank/whitespace-only guidance is stored as null.
+        instructions: blankToNull(values.instructions),
         enabled: values.enabled ?? true,
       })
       .returningAll()
@@ -94,6 +98,8 @@ export class AiMcpServerRepo {
       headersEnc?: string | null;
       // undefined => leave unchanged; null => clear; string[] => set.
       toolAllowlist?: string[] | null;
+      // undefined => leave unchanged; null/blank => clear; string => set.
+      instructions?: string | null;
       enabled?: boolean;
     },
     trx?: KyselyTransaction,
@@ -107,6 +113,10 @@ export class AiMcpServerRepo {
     if (patch.toolAllowlist !== undefined) {
       set.toolAllowlist = jsonbBind(patch.toolAllowlist);
     }
+    if (patch.instructions !== undefined) {
+      // Blank/whitespace-only guidance clears the column (stored as null).
+      set.instructions = blankToNull(patch.instructions);
+    }
     if (patch.enabled !== undefined) set.enabled = patch.enabled;
     await db
       .updateTable('aiMcpServers')
@@ -130,6 +140,17 @@ export class AiMcpServerRepo {
   }
 }
 
+/**
+ * Normalize an optional free-text field to a stored value: a missing/blank/
+ * whitespace-only string becomes null (so an "empty" guide is never persisted),
+ * any other string is trimmed. Returns null for null/undefined input.
+ */
+export function blankToNull(value: string | null | undefined): string | null {
+  if (value == null) return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
 /**
  * Parse the `toolAllowlist` value read from the DB into the `string[] | null`
  * the entity type promises. The jsonb column historically round-trips as a JSON