Skip to content

Add MCP server integration instructions and update Copilot guidance #4494

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
DavidHuber-NOAA merged 11 commits into from
Feb 25, 2026
Merged

Add MCP server integration instructions and update Copilot guidance #4494

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
8b59762
Add MCP server integration instructions and update Copilot guidance
TerrenceMcGuinness-NOAA Jan 29, 2026
b710beb
Merge branch 'develop' into update_copilot_instructions
aerorahul Feb 3, 2026
5210382
Update .github/instructions/mcp.instructions.md
TerrenceMcGuinness-NOAA Feb 4, 2026
b83d4e3
Merge branch 'NOAA-EMC:develop' into update_copilot_instructions
TerrenceMcGuinness-NOAA Feb 6, 2026
3af7f34
Merge branch 'NOAA-EMC:develop' into update_copilot_instructions
TerrenceMcGuinness-NOAA Feb 11, 2026
6eda0bc
Merge branch 'NOAA-EMC:develop' into update_copilot_instructions
TerrenceMcGuinness-NOAA Feb 17, 2026
1ba36df
Merge branch 'NOAA-EMC:develop' into update_copilot_instructions
TerrenceMcGuinness-NOAA Feb 20, 2026
c309c32
Refactor AI instruction files for conditional MCP loading (#4578)
TerrenceMcGuinness-NOAA Feb 24, 2026
2c9c806
fix: sync GraphRAG tool parameter names in mcp.instructions.md
TerrenceMcGuinness-NOAA Feb 24, 2026
35bec79
fix: sync mcp.instructions.md with v7.21.0 (44→48 tools)
TerrenceMcGuinness-NOAA Feb 24, 2026
990972e
Apply suggestion from @Copilot
TerrenceMcGuinness-NOAA Feb 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
220 changes: 3 additions & 217 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -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
124 changes: 124 additions & 0 deletions .github/instructions/mcp.instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 |
Loading