UI tweaks, code cleanup, documentation improvement around external MCP tools

Author: kaleko

docs/custom-MCP-agent.md

@@ -147,7 +147,7 @@ In the AWS account where the IDP solution is deployed, create a secret with your
 
 1. **Navigate to AWS Secrets Manager** in the AWS Console
 2. **Find the External MCP Agents Secret**:
-   - Look for a secret named `{StackName}/external-mcp-agents/credentials` (where StackName is your IDP stack name)
+   - Look for a secret named `{StackName}/external-mcp-agents/credentials` (where StackName is your IDP stack name).
    - This secret is automatically created by the CloudFormation template with an empty array `[]`
    - You can find the exact secret name in your CloudFormation stack outputs
 
@@ -243,6 +243,11 @@ The authentication process works as follows:
 - Verify secret exists at path: `{StackName}/external-mcp-agents/credentials` (check CloudFormation outputs for exact name)
 - Check secret contains a valid JSON array format (not a single object)
 - Review CloudWatch logs for agent registration errors
+- **Lambda Caching**: The ListAvailableAgentsFunction has caching that may delay new agents appearing for up to 15 minutes. To force refresh:
+  - Find the function named `{StackName}-ListAvailableAgentsFunction-*` in AWS Console → Lambda → Functions
+  - Go to Configuration → Environment variables
+  - Add a temporary variable like `REFRESH=1` and save to restart the function
+  - Remove the temporary variable after agents appear
 
 **Authentication Failures:**
 - Verify Cognito User Pool ID and Client ID are correct
@@ -292,45 +297,6 @@ The authentication process works as follows:
      -d '{"method": "list_tools", "params": {}}'
    ```
 
-## Example MCP Tools
-
-Here are examples of tools you might implement in your MCP server:
-
-### Calculator Tool
-```python
-@mcp_server.tool()
-def calculator(expression: str) -> dict:
-    """Evaluate mathematical expressions safely."""
-    try:
-        result = eval(expression, {"__builtins__": {}})
-        return {"result": result}
-    except Exception as e:
-        return {"error": str(e)}
-```
-
-### Weather API Tool
-```python
-@mcp_server.tool()
-def get_weather(city: str) -> dict:
-    """Get current weather for a city."""
-    # Call external weather API
-    weather_data = call_weather_api(city)
-    return {
-        "city": city,
-        "temperature": weather_data["temp"],
-        "conditions": weather_data["conditions"]
-    }
-```
-
-### Database Query Tool
-```python
-@mcp_server.tool()
-def query_database(query: str) -> dict:
-    """Execute safe database queries."""
-    # Implement with proper SQL injection protection
-    results = execute_safe_query(query)
-    return {"results": results}
-```
 
 ## Best Practices
 

lib/idp_common_pkg/idp_common/agents/common/idp_agent.py

@@ -80,7 +80,7 @@ def __init__(
         Args:
             agent_name: Human-readable name for the agent (e.g., "Analytics Agent")
             agent_description: Description of what the agent does
-            agent_id: Unique identifier for the agent (e.g., "analytics-20250813-v0-kaleko")
+            agent_id: Unique identifier for the agent (e.g., "analytics-20250813-v0")
             agent: Existing Strands Agent instance to wrap (required)
             sample_queries: List of example queries that demonstrate the agent's capabilities
             job_id: Job ID for monitoring purposes. When provided with user_id, enables

lib/idp_common_pkg/idp_common/agents/factory/registry.py

@@ -14,7 +14,7 @@
     agents = agent_factory.list_available_agents()
 
     # Create an agent
-    agent = agent_factory.create_agent("analytics-20250813-v0-kaleko", config=config)
+    agent = agent_factory.create_agent("analytics-20250813-v0", config=config)
 """
 
 import logging
@@ -31,7 +31,7 @@
 
 # Register analytics agent
 agent_factory.register_agent(
-    agent_id="analytics-20250813-v0-kaleko",
+    agent_id="Analytics-Agent-v1",
     agent_name="Analytics Agent",
     agent_description="""
     Converts natural language questions into SQL queries and generates visualizations from document data.
@@ -100,7 +100,9 @@
         ]
         for field in required_fields:
             if field not in mcp_config:
-                logger.warning(f"Skipping MCP config {i}: missing required field '{field}'")
+                logger.warning(
+                    f"Skipping MCP config {i}: missing required field '{field}'"
+                )
                 continue
 
         # Create wrapper function for this specific MCP config
@@ -113,6 +115,7 @@ def wrapper(config=None, session=None, model_id=None, **kwargs):
                     mcp_server_config=mcp_server_config,
                     **kwargs,
                 )
+
             return wrapper
 
         # Try to discover available tools for dynamic description
@@ -126,7 +129,10 @@ def wrapper(config=None, session=None, model_id=None, **kwargs):
 
             # Extract available tools for dynamic description
             dynamic_description = f"Agent {i} which connects to external MCP servers to provide additional tools and capabilities"
-            if hasattr(test_strands_agent, "tool_names") and test_strands_agent.tool_names:
+            if (
+                hasattr(test_strands_agent, "tool_names")
+                and test_strands_agent.tool_names
+            ):
                 tool_names = list(test_strands_agent.tool_names)
                 if tool_names:
                     tools_list = ", ".join(tool_names)

src/ui/src/components/document-agents-layout/AgentQueryInput.jsx

@@ -12,6 +12,9 @@ import {
   SpaceBetween,
   ButtonDropdown,
   Checkbox,
+  Modal,
+  Header,
+  Link,
 } from '@awsui/components-react';
 import listAgentJobs from '../../graphql/queries/listAgentJobs';
 import deleteAgentJob from '../../graphql/queries/deleteAgentJob';
@@ -40,6 +43,7 @@ const AgentQueryInput = ({ onSubmit, isSubmitting, selectedResult }) => {
   const [availableAgents, setAvailableAgents] = useState([]);
   const [selectedAgents, setSelectedAgents] = useState([]);
   const [isLoadingAgents, setIsLoadingAgents] = useState(false);
+  const [showMcpInfoModal, setShowMcpInfoModal] = useState(false);
   const [hoveredAgent, setHoveredAgent] = useState(null);
   const [hoverTimeout, setHoverTimeout] = useState(null);
   const [mousePosition, setMousePosition] = useState({ x: 0, y: 0 });
@@ -81,6 +85,17 @@ const AgentQueryInput = ({ onSubmit, isSubmitting, selectedResult }) => {
     }
   };
 
+  const handleSelectAllAgents = (e) => {
+    e.preventDefault();
+    e.stopPropagation();
+    const allSelected = selectedAgents.length === availableAgents.length;
+    if (allSelected) {
+      setSelectedAgents([]);
+    } else {
+      setSelectedAgents(availableAgents.map((agent) => agent.agent_id));
+    }
+  };
+
   const fetchAvailableAgents = async () => {
     try {
       setIsLoadingAgents(true);
@@ -90,11 +105,6 @@ const AgentQueryInput = ({ onSubmit, isSubmitting, selectedResult }) => {
 
       const agents = response?.data?.listAvailableAgents || [];
       setAvailableAgents(agents);
-
-      // Auto-select first agent if none selected
-      if (agents.length > 0 && selectedAgents.length === 0) {
-        setSelectedAgents([agents[0].agent_id]);
-      }
     } catch (err) {
       logger.error('Error fetching available agents:', err);
       setAvailableAgents([]);
@@ -323,7 +333,7 @@ const AgentQueryInput = ({ onSubmit, isSubmitting, selectedResult }) => {
   // Create dropdown items with delete functionality
   const createDropdownItems = () => {
     if (queryHistory.length === 0) {
-      return [{ text: 'No previous queries found', disabled: true }];
+      return [{ text: 'No previous questions found', disabled: true }];
     }
 
     return queryHistory.map((job) => {
@@ -404,9 +414,14 @@ const AgentQueryInput = ({ onSubmit, isSubmitting, selectedResult }) => {
       <form onSubmit={handleSubmit}>
         <SpaceBetween size="l">
           <Box>
-            <Box fontSize="body-m" fontWeight="bold" padding={{ bottom: 'xs' }}>
-              Select from available agents
-            </Box>
+            <SpaceBetween direction="horizontal" size="s" alignItems="center">
+              <Box fontSize="body-m" fontWeight="bold">
+                Select from available agents
+              </Box>
+              <Button variant="link" onClick={() => setShowMcpInfoModal(true)} fontSize="body-s">
+                🚀 NEW: Integrate your own systems with MCP!
+              </Button>
+            </SpaceBetween>
             <div
               style={{
                 maxHeight: '200px',
@@ -454,6 +469,17 @@ const AgentQueryInput = ({ onSubmit, isSubmitting, selectedResult }) => {
                 </SpaceBetween>
               )}
             </div>
+            {!isLoadingAgents && availableAgents.length > 0 && (
+              <Box padding={{ top: 's' }}>
+                <Button
+                  type="button"
+                  variant={selectedAgents.length === availableAgents.length ? 'normal' : 'primary'}
+                  onClick={handleSelectAllAgents}
+                >
+                  {selectedAgents.length === availableAgents.length ? 'Deselect All Agents' : 'Select All Agents'}
+                </Button>
+              </Box>
+            )}
             {hoveredAgent && (
               <div
                 style={{
@@ -509,7 +535,7 @@ const AgentQueryInput = ({ onSubmit, isSubmitting, selectedResult }) => {
                   selectedAgents.length > 0
                     ? availableAgents.find((agent) => agent.agent_id === selectedAgents[0])?.sample_queries?.[0] ||
                       'Enter your question here...'
-                    : 'Select an agent first...'
+                    : 'Select at least one available agent to get started'
                 }
                 value={currentInputText}
                 onChange={({ detail }) => updateAnalyticsState({ currentInputText: detail.value })}
@@ -526,16 +552,16 @@ const AgentQueryInput = ({ onSubmit, isSubmitting, selectedResult }) => {
                   disabled={!currentInputText.trim() || selectedAgents.length === 0 || isSubmitting}
                   fullWidth
                 >
-                  {isSubmitting ? 'Submitting...' : 'Submit query'}
+                  {isSubmitting ? 'Submitting...' : 'Submit question'}
                 </Button>
                 <Button variant="normal" onClick={handleClearQuery} disabled={isSubmitting} fullWidth>
-                  Clear query
+                  Clear question
                 </Button>
               </SpaceBetween>
             </Box>
           </Grid>
 
-          <FormField label="Previous queries">
+          <FormField>
             <ButtonDropdown
               items={createDropdownItems()}
               onItemClick={handleDropdownItemClick}
@@ -544,16 +570,67 @@ const AgentQueryInput = ({ onSubmit, isSubmitting, selectedResult }) => {
               disabled={isSubmitting}
             >
               {(() => {
-                if (!selectedOption) return 'Select a previous query';
+                if (!selectedOption) return 'Select a previous question';
                 if (selectedOption.label?.length > 40) {
                   return `${selectedOption.label.substring(0, 40)}...`;
                 }
-                return selectedOption.label || 'Selected query';
+                return selectedOption.label || 'Selected question';
               })()}
             </ButtonDropdown>
           </FormField>
         </SpaceBetween>
       </form>
+
+      <Modal
+        onDismiss={() => setShowMcpInfoModal(false)}
+        visible={showMcpInfoModal}
+        header={<Header>Custom MCP Agents</Header>}
+        footer={
+          <Box float="right">
+            <Button variant="primary" onClick={() => setShowMcpInfoModal(false)}>
+              Close
+            </Button>
+          </Box>
+        }
+      >
+        <SpaceBetween size="m">
+          <Box>
+            <Box fontWeight="bold" fontSize="body-m">
+              What are MCP Agents?
+            </Box>
+            <Box>
+              Model Context Protocol (MCP) agents allow you to connect external tools and services to extend the
+              capabilities of your document analysis workflow.
+            </Box>
+          </Box>
+
+          <Box>
+            <Box fontWeight="bold" fontSize="body-m">
+              Adding Custom Agents
+            </Box>
+            <Box>
+              You can add your own MCP agents by configuring external MCP servers in AWS Secrets Manager. This allows
+              you to integrate custom tools, APIs, and services specific to your organization&apos;s needs without any
+              code changes or redeployments.
+            </Box>
+          </Box>
+
+          <Box>
+            <Box fontWeight="bold" fontSize="body-m">
+              Learn More
+            </Box>
+            <Box>
+              For detailed setup instructions and examples, see the{' '}
+              <Link
+                external
+                href="https://github.com/aws-samples/genaiic-idp-accelerator/blob/main/docs/custom-MCP-agent.md"
+              >
+                Custom MCP Agent Documentation
+              </Link>
+            </Box>
+          </Box>
+        </SpaceBetween>
+      </Modal>
     </>
   );
 };

src/ui/src/components/document-agents-layout/DocumentsAgentsLayout.jsx

@@ -255,7 +255,7 @@ const DocumentsAgentsLayout = () => {
   }, [jobId, jobStatus, updateAnalyticsState]);
 
   return (
-    <Container header={<Header variant="h1">Agent HQ</Header>}>
+    <Container header={<Header variant="h2">Agent Analysis</Header>}>
       <SpaceBetween size="l">
         <AgentQueryInput onSubmit={handleSubmitQuery} isSubmitting={isSubmitting} selectedResult={null} />
 

src/ui/src/components/document-agents-layout/tools-panel.jsx

@@ -6,7 +6,7 @@ import { HelpPanel, Icon } from '@awsui/components-react';
 const ToolsPanel = () => {
   return (
     <HelpPanel
-      header={<h2>Agent HQ</h2>}
+      header={<h2>Agent Analysis</h2>}
       footer={
         <div>
           <h3>
@@ -24,7 +24,7 @@ const ToolsPanel = () => {
     >
       <div>
         <p>
-          Use Agent HQ to interact with AI agents using natural language and receive interactive visualizations and
+          Use Agent Analysis to interact with AI agents using natural language and receive interactive visualizations and
           insights.
         </p>
         <h3>How to use</h3>