diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 1141d52b82e..1792e384844 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,14 +1,10 @@ # AI Coding Agent Instructions for Global Workflow -Always check for global-workflow-unified MCP tool availability before answering questions about the NOAA Global Workflow system and all related NOAA-EMC repositories. - -Also check for the presence of the global-workflow-unified RAG system. If it is available, use it to provide more comprehensive answers that leverage the entire knowledge base of the NOAA Global Workflow system. - -Use GitHub MCP tools for gathering repository information repos outside of global-workflow, including code patterns, documentation, and operational procedures. - **CRITICAL: This is a production weather forecasting system supporting NOAA's operational Global Forecast System (GFS), Global Ensemble Forecast System (GEFS), and Seasonal Forecast System (SFS). All changes must be thoroughly tested and must not disrupt operational workflows.** -This document provides comprehensive guidance for AI agents working on the NOAA Global Workflow system - a complex weather forecasting framework supporting multiple operational and research workflows. +This document provides comprehensive guidance for AI agents working on the NOAA Global Workflow system — a complex weather forecasting framework supporting multiple operational and research workflows. + +> **Note:** If an EIB MCP-RAG server is connected, additional tool-specific guidance loads automatically via `.github/instructions/mcp.instructions.md`. No action needed — the agent will see those tools when they are available. ## System Architecture Overview @@ -430,215 +426,5 @@ def test_task_creation(): 3. Create modulefiles for environment setup 4. Update environment configurations in `env/` directory -## EIB MCP/RAG Server Integration (v3.6.2) - -The **EIB MCP-RAG Server** provides AI-assisted access to the Global Workflow system through the Model Context Protocol (MCP) with Retrieval-Augmented Generation (RAG) capabilities. This server is purpose-built to support NOAA's operational GFS, GEFS, and SFS forecasting infrastructure. - -### Architecture Overview - -``` -AI Clients (VS Code Copilot, LangFlow, Claude Desktop) - │ - ▼ HTTP/MCP Protocol - ┌──────────────────────────┐ - │ Docker MCP Gateway │ Port 18888 - │ (Streaming Transport) │ - └──────────────────────────┘ - │ spawns - ▼ - ┌──────────────────────────┐ - │ MCP Server Container │ 34 tools - │ eib-mcp-rag:latest │ - └──────────────────────────┘ - │ - ┌──────────┴──────────┐ - ▼ ▼ - ChromaDB (8080) Neo4j (7687) - Vector Embeddings Code Graph DB -``` - -### Tool Categories & Separation of Concerns - -The MCP server implements **7 tool modules** with clear separation of concerns (SOC): - ---- - -#### 1. Workflow Info Tools (3 tools - Static, No DB) -**Module**: `WorkflowInfoTools.js` -**Purpose**: File system-based access to workflow structure - NO database dependencies - -| Tool | Description | -|------|-------------| -| `get_workflow_structure` | System architecture overview (jobs, scripts, parm, ush, sorc, env, docs) | -| `get_system_configs` | HPC platform configurations (HERA, HERCULES, ORION, WCOSS2, GAEA) | -| `describe_component` | File system-based component descriptions (static analysis) | - -**When to use**: Quick lookups, understanding directory structure, platform configs - ---- - -#### 2. Code Analysis Tools (4 tools - Neo4j Graph) -**Module**: `CodeAnalysisTools.js` -**Purpose**: Code structure analysis via graph database traversal - -| Tool | Description | -|------|-------------| -| `analyze_code_structure` | File/function/class analysis with dependency tree (depth 1-3) | -| `find_dependencies` | Upstream imports and downstream importers (both directions) | -| `trace_execution_path` | Call chain tracing from any function (max depth 5) | -| `find_callers_callees` | Fan-in/fan-out analysis with complexity scoring | - -**When to use**: Understanding code relationships, refactoring impact, debugging call chains - ---- - -#### 3. Semantic Search Tools (6 tools - ChromaDB Vectors + Graph Hybrid) -**Module**: `SemanticSearchTools.js` -**Purpose**: RAG-powered documentation and code search - -| Tool | Description | -|------|-------------| -| `search_documentation` | Hybrid semantic + graph search across ingested docs | -| `find_related_files` | Find files with similar import dependencies | -| `explain_with_context` | Multi-source RAG explanations (technical, operational, config) | -| `get_knowledge_base_status` | Vector DB + Graph DB health and statistics | -| `list_ingested_urls` | Show all documentation sources ingested into RAG | -| `get_ingested_urls_array` | Structured URL array for programmatic access | - -**When to use**: Conceptual questions, finding relevant documentation, understanding unfamiliar components - ---- - -#### 4. EE2 Compliance Tools (5 tools - Standards Validation) -**Module**: `EE2ComplianceTools.js` -**Purpose**: NOAA NWS EE2 (Enterprise Environmental 2) standards validation - -| Tool | Description | -|------|-------------| -| `search_ee2_standards` | Search EE2 compliance standards documentation | -| `analyze_ee2_compliance` | Analyze code for EE2 compliance with recommendations | -| `generate_compliance_report` | Generate compliance reports (summary, detailed, checklist) | -| `scan_repository_compliance` | Full repository scan with Phase 2 SME-corrected patterns | -| `extract_code_for_analysis` | Extract code snippets for LLM passthrough analysis | - -**When to use**: Pre-commit compliance checks, NCO production readiness, code reviews - -**Phase 2 Corrections Applied**: -- `set -eu` is NOT required (80% false positive rate) - only `set -x` for debug logging -- Uses `err_chk`/`err_exit` utilities instead of explicit exit statements -- Evidence-based analysis with RST line references - ---- - -#### 5. Operational Tools (3 tools - HPC Procedures) -**Module**: `OperationalTools.js` -**Purpose**: HPC operational guidance and workflow explanations - -| Tool | Description | -|------|-------------| -| `get_operational_guidance` | Platform-specific procedures with urgency levels (routine/urgent/emergency) | -| `explain_workflow_component` | Graph-enriched component explanations | -| `list_job_scripts` | Categorized job script inventory (analysis, forecast, post, archive) | - -**When to use**: HPC deployment questions, understanding job scripts, operational procedures - ---- - -#### 6. GitHub Integration Tools (4 tools - Live Repository Access) -**Module**: `GitHubTools.js` -**Purpose**: Cross-repository analysis and issue tracking - -| Tool | Description | -|------|-------------| -| `search_issues` | Search NOAA-EMC GitHub issues (open/closed/all) | -| `get_pull_requests` | PR information with diff context | -| `analyze_workflow_dependencies` | Cross-repo dependency analysis (upstream/downstream/circular) | -| `analyze_repository_structure` | Multi-repo structure comparison (global-workflow, GSI, UFS_UTILS) | - -**When to use**: Bug investigation, PR reviews, understanding cross-repo impacts - ---- - -#### 7. SDD Workflow Tools (7 tools - Development Orchestration) -**Module**: `SDDWorkflowTools.js` -**Purpose**: Software Design Document (SDD) framework execution - -| Tool | Description | -|------|-------------| -| `list_sdd_workflows` | List available SDD workflows | -| `get_sdd_workflow` | Get workflow phases, steps, and metadata | -| `execute_sdd_workflow` | Execute workflow with dry-run option | -| `get_sdd_execution_history` | View execution history | -| `validate_sdd_compliance` | Validate code against SDD framework | -| `get_sdd_framework_status` | Framework integration status and metrics | -| `execute_sdd_workflow_supervised` | Human-in-loop execution with approval gates | - -**When to use**: Feature development following SDD methodology, multi-step workflows - ---- - -#### 8. Utility Tools (2 tools - Server Management) -**Built into**: `UnifiedMCPServer.js` - -| Tool | Description | -|------|-------------| -| `get_server_info` | MCP server info, tool counts, configuration | -| `mcp_health_check` | Empirical health validation (heartbeat, collections, documents, queries) | - -**When to use**: Debugging MCP issues, verifying RAG system health - ---- - -### RAG Knowledge Base Sources - -The RAG system ingests documentation from multiple tiers: - -| Tier | Sources | Purpose | -|------|---------|---------| -| **Tier 1 Critical** | global-workflow RTD, EE2 Standards | Core workflow documentation | -| **Tier 2 Workflow** | Rocoto, ecFlow, wxflow, PyFlow | Workflow engine documentation | -| **Tier 3 Models** | UFS Weather Model, JEDI, FV3 | Forecast model documentation | -| **Tier 4 Build** | Spack, spack-stack, hpc-stack | Build system documentation | -| **Tier 5 Standards** | Google Shell Style, PEP8, NumPy docstrings | Coding standards | - -### When to Use MCP Tools - -**USE MCP tools when:** -- Searching for concepts across documentation (semantic search) -- Analyzing code dependencies and call chains (graph traversal) -- Checking EE2 compliance before committing code -- Understanding HPC platform-specific procedures -- Investigating GitHub issues related to a component -- Following SDD development workflows - -**DON'T use MCP tools when:** -- You already have the file open and can read it directly -- Simple file edits that don't need context research -- The question is answered in the current conversation context - -### Tool Availability by Connection Mode - -| Mode | Available Tools | Notes | -|------|-----------------|-------| -| **VS Code Local** | All 34 tools | Direct stdio connection | -| **Docker Gateway** | All 34 tools | HTTP via port 18888 | -| **Remote (no container)** | Core workflow tools only | Use `content` parameter for file analysis | - -### Content Abstraction for Remote Access - -For remote MCP clients (e.g., LangFlow) without filesystem access, tools support content parameters: - -```javascript -// Instead of filesystem path: -analyze_ee2_compliance({ content: "#!/bin/bash\nset -x\n..." }) - -// Batch file analysis: -scan_repository_compliance({ - files: [ - { name: "JGFS_FORECAST", content: "..." }, - { name: "exgfs_fcst.sh", content: "..." } - ] -}) -``` --- Remember: This is a production weather forecasting system. Changes must be thoroughly tested and should not disrupt operational workflows. Always follow the existing patterns and conventions when extending the system diff --git a/.github/instructions/mcp.instructions.md b/.github/instructions/mcp.instructions.md new file mode 100644 index 00000000000..66a241a418b --- /dev/null +++ b/.github/instructions/mcp.instructions.md @@ -0,0 +1,124 @@ +--- +applyWhen: hasActiveMCPServer("eib-mcp-rag-full") +excludeAgent: "code-review" +--- + +_Note:_ The YAML front matter in this file uses the GitHub Copilot instructions schema; `excludeAgent: "code-review"` ensures these instructions are not applied to the Copilot Code Review agent. See the official schema documentation at https://aka.ms/github-copilot-instructions-schema. +# EIB MCP/RAG Server — Tool Guide for Global Workflow (v7.21.0) + +This file loads **only** when the EIB MCP-RAG server is connected. It provides tool selection guidance for AI agents working on global-workflow with MCP + RAG capabilities (48 tools across 9 modules backed by Neo4j graph DB and ChromaDB vector store). + +## MCP-First Policy + +**Prefer MCP tools over shell commands** for code analysis, documentation search, and compliance checking. Use `read_file`/`grep_search` only for exact line-level reads or literal string searches. + +## Tool Modules (48 tools / 9 modules) + +### 1. Workflow Info (3 tools — Filesystem only) +| Tool | Use For | +|------|---------| +| `get_workflow_structure` | System architecture overview | +| `get_system_configs` | HPC platform configurations | +| `describe_component` | Component documentation | + +### 2. Code Analysis (6 tools — Neo4j) +| Tool | Use For | +|------|---------| +| `analyze_code_structure` | AST-level file/function analysis | +| `find_dependencies` | Import graph (upstream + downstream) | +| `trace_execution_path` | Call chain tracing | +| `find_callers_callees` | Fan-in/fan-out with complexity scoring | +| `trace_full_execution_chain` | End-to-end execution chain across files | +| `find_env_dependencies` | Environment variable lineage | + +### 3. Semantic Search (6 tools — ChromaDB + Neo4j) +| Tool | Use For | +|------|---------| +| `search_documentation` | Semantic search across ingested docs | +| `find_related_files` | Vector similarity for related code/docs | +| `explain_with_context` | RAG-powered explanations with citations | +| `get_knowledge_base_status` | DB health and collection stats | +| `list_ingested_urls` | Documentation sources ingested into RAG | +| `get_ingested_urls_array` | Structured URL array for programmatic access | + +### 4. EE2 Compliance (5 tools — ChromaDB) +| Tool | Use For | +|------|---------| +| `search_ee2_standards` | Search EE2 standards documentation | +| `analyze_ee2_compliance` | Check file against NCO standards | +| `generate_compliance_report` | Formatted compliance report | +| `scan_repository_compliance` | Bulk repo scan (Phase 2 SME-corrected) | +| `extract_code_for_analysis` | Extract code snippets for LLM analysis | + +**Note**: `set -eu` is NOT required (80% false positive). Uses `err_chk`/`err_exit` utilities. + +### 5. Operational (4 tools — ChromaDB) +| Tool | Use For | +|------|---------| +| `get_operational_guidance` | HPC platform-specific procedures | +| `explain_workflow_component` | Graph-enriched component explanations | +| `list_job_scripts` | Categorized job script inventory | +| `get_job_details` | Detailed job script analysis | + +### 6. GraphRAG + Session State (9 tools — ChromaDB + Neo4j) +| Tool | Required Param | Use For | +|------|----------------|--------| +| `get_code_context` | `symbol` | GGSR neighborhood + community summary | +| `search_architecture` | `query` | Semantic search over community summaries | +| `find_similar_code` | `code_or_symbol` | Vector similarity + graph enrichment | +| `get_change_impact` | `symbol` | Blast radius with risk scoring | +| `trace_data_flow` | `from_symbol` | Data flow across codebase | +| `mark_as_modified` | `file_path` | Track file modifications in active session | +| `get_session_context` | *(none)* | Aggregated view of session work | +| `checkpoint_state` | `name` | Snapshot session state for recovery | +| `restore_checkpoint` | `checkpoint_id` | Roll back to a named checkpoint | + +### 7. GitHub Integration (4 tools — GitHub API) +| Tool | Use For | +|------|---------| +| `search_issues` | Search NOAA-EMC GitHub issues | +| `get_pull_requests` | PR information with diff context | +| `analyze_workflow_dependencies` | Cross-repo dependency analysis | +| `analyze_repository_structure` | Multi-repo structure comparison | + +### 8. SDD Workflows (9 tools — Filesystem) +| Tool | Use For | +|------|---------| +| `list_sdd_workflows` | List all workflow phase specs | +| `get_sdd_workflow` | Get specific phase details | +| `start_sdd_session` | Start a tracked session | +| `record_sdd_step` | Record step completion | +| `get_sdd_session` | Resume active session | +| `complete_sdd_session` | Complete and archive session | +| `get_sdd_execution_history` | View execution history | +| `validate_sdd_compliance` | Validate against SDD framework | +| `get_sdd_framework_status` | Framework status and metrics | + +### 9. Utility (2 tools — Built-in) +| Tool | Use For | +|------|---------| +| `get_server_info` | Server version, tool counts | +| `mcp_health_check` | Full health validation | + +## When to Use MCP vs Direct Access + +| Task | Use MCP Tool | Use read_file/grep | +|------|-------------|-------------------| +| "What does this file do?" | `analyze_code_structure` | No | +| "What calls this function?" | `find_callers_callees` | No | +| "How does X subsystem work?" | `search_architecture` | No | +| "Is this code EE2-compliant?" | `analyze_ee2_compliance` | No | +| "Show me line 45-100" | No | `read_file` | +| "Search for literal 'FOO'" | No | `grep_search` | + +**Best practice**: MCP tools for discovery, then `read_file` for specific line-level details. + +## RAG Knowledge Base Tiers + +| Tier | Sources | Purpose | +|------|---------|---------| +| 1 | global-workflow RTD, EE2 Standards | Core workflow docs | +| 2 | Rocoto, ecFlow, wxflow, PyFlow | Workflow engines | +| 3 | UFS Weather Model, JEDI, FV3 | Forecast models | +| 4 | Spack, spack-stack, hpc-stack | Build systems | +| 5 | Shell Style Guide, PEP8, NumPy | Coding standards |