runtime: capture MCP initialize instructions per connection

tests/test_runtime/mcp_fake_server.py

@@ -1,10 +1,17 @@
-"""Minimal MCP stdio server used by the client tests (echo + sleep tools)."""
+"""Minimal MCP stdio server used by the client tests (echo + sleep tools).
+
+Set ``PLYNGENT_MCP_FAKE_INSTRUCTIONS`` (env) to have the server return that
+text as ``InitializeResult.instructions`` (usage guidance).
+"""
 
 from __future__ import annotations
 
 import json
+import os
 import sys
 
+_FAKE_INSTRUCTIONS = os.environ.get("PLYNGENT_MCP_FAKE_INSTRUCTIONS", "")
+
 
 def respond(request_id: int, result: object) -> None:
     sys.stdout.write(json.dumps({"jsonrpc": "2.0", "id": request_id, "result": result}) + "\n")
@@ -22,14 +29,14 @@ def main() -> None:
         if request_id is None:
             continue  # notification (notifications/initialized)
         if method == "initialize":
-            respond(
-                int(request_id),
-                {
-                    "protocolVersion": "2025-06-18",
-                    "capabilities": {"tools": {}},
-                    "serverInfo": {"name": "fake-mcp", "version": "0.1.0"},
-                },
-            )
+            result: dict[str, object] = {
+                "protocolVersion": "2025-06-18",
+                "capabilities": {"tools": {}},
+                "serverInfo": {"name": "fake-mcp", "version": "0.1.0"},
+            }
+            if _FAKE_INSTRUCTIONS:
+                result["instructions"] = _FAKE_INSTRUCTIONS
+            respond(int(request_id), result)
         elif method == "tools/list":
             respond(
                 int(request_id),

tests/test_runtime/test_mcp_client.py

@@ -32,6 +32,7 @@ async def test_connection_handshake_lists_and_calls_tools() -> None:
     try:
         assert connection.connected
         assert connection.error is None
+        assert connection.instructions is None
         assert [tool.name for tool in connection.tools] == ["echo", "fail", "slow"]
         echo = connection.tools[0]
         assert echo.description == "Echo the given text back."
@@ -43,6 +44,20 @@ async def test_connection_handshake_lists_and_calls_tools() -> None:
         await connection.aclose()
 
 
+async def test_initialize_captures_server_instructions() -> None:
+    guidance = "Use echo to repeat text back to the user."
+    connection = McpServerConnection(
+        "fake",
+        _server_config(env={"PLYNGENT_MCP_FAKE_INSTRUCTIONS": guidance}),
+    )
+    await connection.start()
+    try:
+        assert connection.connected
+        assert connection.instructions == guidance
+    finally:
+        await connection.aclose()
+
+
 async def test_tool_error_returns_error_text() -> None:
     connection = McpServerConnection("fake", _server_config())
     await connection.start()
@@ -87,12 +102,31 @@ async def test_manager_start_status_and_call() -> None:
     await manager.ensure_started()
     try:
         assert [(name, status, count) for name, status, count in manager.statuses()] == [("fake", "connected", 3)]
+        assert manager.instructions() == []
         assert await manager.call("fake", "echo", {"text": "hi"}) == "echo: hi"
     finally:
         await manager.aclose()
     assert manager.statuses() == [("fake", "not started", 0)]
 
 
+async def test_manager_instructions_after_restart() -> None:
+    guidance = "Always answer with a haiku."
+    plain = McpManager(McpConfig(servers={"fake": _server_config()}, disable=[]))
+    await plain.ensure_started()
+    assert plain.instructions() == []
+    await plain.restart(
+        McpConfig(
+            servers={"fake": _server_config(env={"PLYNGENT_MCP_FAKE_INSTRUCTIONS": guidance})},
+            disable=[],
+        )
+    )
+    await plain.ensure_started()
+    try:
+        assert plain.instructions() == [("fake", guidance)]
+    finally:
+        await plain.aclose()
+
+
 async def test_manager_disable_and_restart() -> None:
     manager = McpManager(McpConfig(servers={"fake": _server_config()}, disable=["fake"]))
     await manager.ensure_started()