# MCP Workflow

> FastMCP + DSIM workflow for UVM test execution. Use when compiling tests, running simulations, executing regression suites, or troubleshooting MCP integration. Use when this capability is needed.

- Skill: `tomevault-io/mcp-workflow` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/mcp-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/mcp-workflow/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/mcp-workflow

---


# MCP Workflow for DSIM UVM Testing

FastMCP + VS Code MCP integration workflow for the AXIUART_RV32I verification environment.

## When to Use This Skill

- Compiling or running UVM tests
- Executing regression test suites
- Troubleshooting MCP server connectivity
- Understanding VS Code task integration
- Configuring test timeout policies

## Primary Workflow (MANDATORY)

**Use FastMCP + VS Code MCP integration** - configured in `.vscode/mcp.json`

**Do not violate this rule.** MCP server provides structured JSON outputs, automatic timeout management, and integrated telemetry.

## Standard UVM Test Sequence

### 1. Check DSIM Environment

```bash
python mcp_server/mcp_client.py \
    --workspace e:\Nautilus\workspace\fpgawork\AXIUART_RV32I \
    --tool check_dsim_environment
```

**Verifies:**
- `DSIM_HOME`, `DSIM_ROOT`, `DSIM_LIB_PATH`, `DSIM_LICENSE` environment variables
- DSIM executable accessibility
- License validity

### 2. List Available Tests

```bash
python mcp_server/mcp_client.py \
    --workspace e:\Nautilus\workspace\fpgawork\AXIUART_RV32I \
    --tool list_available_tests
```

**Returns:** JSON list of all UVM tests in [sim/tests/](../../sim/tests/)

### 3. Compile Test

```bash
python mcp_server/mcp_client.py \
    --workspace e:\Nautilus\workspace\fpgawork\AXIUART_RV32I \
    --tool run_uvm_simulation \
    --test-name <test> \
    --mode compile \
    --verbosity UVM_LOW
```

**Example:**
```bash
python mcp_server/mcp_client.py \
    --workspace e:\Nautilus\workspace\fpgawork\AXIUART_RV32I \
    --tool run_uvm_simulation \
    --test-name axiuart_basic_test \
    --mode compile \
    --verbosity UVM_LOW
```

### 4. Run Simulation

```bash
python mcp_server/mcp_client.py \
    --workspace e:\Nautilus\workspace\fpgawork\AXIUART_RV32I \
    --tool run_uvm_simulation \
    --test-name <test> \
    --mode run \
    --verbosity UVM_MEDIUM \
    --waves
```

**Example:**
```bash
python mcp_server/mcp_client.py \
    --workspace e:\Nautilus\workspace\fpgawork\AXIUART_RV32I \
    --tool run_uvm_simulation \
    --test-name axiuart_basic_test \
    --mode run \
    --verbosity UVM_MEDIUM \
    --waves
```

## Timeout Policy (CRITICAL)

**NEVER specify `--timeout` parameter**

MCP server auto-selects timeout from [test_timing_config.json](../../mcp_server/test_timing_config.json) or uses `null` (no timeout) by default.

### Timeout Configuration

```json
{
  "default_timeout": 300,
  "test_timeouts": {
    "axiuart_basic_test": 120,
    "axiuart_stress_test": 600,
    "axiuart_long_run_test": null
  }
}
```

**Rules:**
- `null` timeout = no timeout (runs until completion)
- Specific test timeout overrides default
- Do not hardcode timeouts in command line

## Regression Testing

### Smoke Suite (Quick Validation)

```bash
python mcp_server/run_regression.py --suite smoke
```

**Characteristics:**
- 2 tests: `axiuart_basic_test`, `uart_loopback_test`
- Runtime: ~40 seconds
- Use for: Quick sanity checks, pre-commit validation

### Full Suite (Complete Regression)

```bash
python mcp_server/run_regression.py --suite full --format html
```

**Characteristics:**
- All tests in [regression_tests.json](../../sim/regression_tests.json)
- HTML report generated in [sim/reports/](../../sim/reports/)
- Use for: Nightly builds, release validation

### Via MCP Tool

```bash
python mcp_server/mcp_client.py \
    --workspace e:\Nautilus\workspace\fpgawork\AXIUART_RV32I \
    --tool run_regression_suite \
    --suite smoke
```

## VS Code Task Integration

### Compile-Only Task

**Task:** `DSIM: Run Basic Test (Compile Only - MCP)`

Wraps:
```bash
python mcp_server/mcp_client.py --workspace . --tool run_uvm_simulation \
    --test-name axiuart_basic_test --mode compile --verbosity UVM_LOW
```

### Full Simulation Task

**Task:** `DSIM: Run Basic Test (Full Simulation - MCP)`

Wraps:
```bash
python mcp_server/mcp_client.py --workspace . --tool run_uvm_simulation \
    --test-name axiuart_basic_test --mode run --verbosity UVM_MEDIUM --waves
```

### MCP Server Startup

**Task:** `🚀 Start Enhanced MCP Server (FastMCP Edition)`

Starts background MCP server when required.

## JSON Output Consumption

MCP server produces structured JSON outputs:

### Test Results

Location: [sim/logs/<test_name>_result.json](../../sim/logs/)

```json
{
  "test_name": "axiuart_basic_test",
  "status": "PASSED",
  "duration_seconds": 45.3,
  "errors": 0,
  "warnings": 2,
  "coverage": {
    "line": 87.5,
    "toggle": 92.1
  }
}
```

### Telemetry

Location: [sim/logs/<test_name>_telemetry.json](../../sim/logs/)

Contains DSIM performance metrics, memory usage, compilation time.

### Coverage Data

Location: [sim/reports/coverage/](../../sim/reports/coverage/)

Parse coverage database for detailed metrics.

## MCP Client API Usage

### Python Integration

```python
from mcp_server.client_api import DSIMClient

client = DSIMClient(workspace="e:\\Nautilus\\workspace\\fpgawork\\AXIUART_RV32I")

# Check environment
env_status = client.check_dsim_environment()
print(f"DSIM ready: {env_status['valid']}")

# List tests
tests = client.list_available_tests()
print(f"Available tests: {tests}")

# Run test
result = client.run_uvm_simulation(
    test_name="axiuart_basic_test",
    mode="run",
    verbosity="UVM_MEDIUM",
    waves=True
)
print(f"Test result: {result['status']}")
```

## Fallback Path (Only if MCP Unavailable)

### When to Use Fallback

- MCP server unreachable
- Python environment issues
- Debugging MCP infrastructure problems

**Document the reason for fallback in development diary.**

### Initialization

```powershell
cd e:\Nautilus\workspace\fpgawork\AXIUART_RV32I
.\workspace_init.ps1
Test-WorkspaceMCPUVM
```

### Execution

```powershell
.\sim\exec\run_uvm.ps1 `
    -TestName axiuart_basic_test `
    -Waves `
    -Coverage
```

### Prohibited

**Never call archived scripts or `archive/legacy_mcp_files/` assets.**

## MCP Server Configuration

### Server Location

[mcp_server/dsim_fastmcp_server.py](../../mcp_server/dsim_fastmcp_server.py)

### Configuration File

[.vscode/mcp.json](../../.vscode/mcp.json)

```json
{
  "mcpServers": {
    "dsim-uvm": {
      "command": "python",
      "args": ["mcp_server/dsim_fastmcp_server.py"],
      "env": {
        "WORKSPACE_ROOT": "e:\\Nautilus\\workspace\\fpgawork\\AXIUART_RV32I"
      }
    }
  }
}
```

## Common Workflows

### Quick Compile-Run Cycle

```bash
# Compile
python mcp_server/mcp_client.py --workspace . --tool run_uvm_simulation \
    --test-name my_test --mode compile --verbosity UVM_LOW

# If successful, run
python mcp_server/mcp_client.py --workspace . --tool run_uvm_simulation \
    --test-name my_test --mode run --verbosity UVM_MEDIUM --waves
```

### Debug with Assertions Enabled

```bash
python mcp_server/mcp_client.py --workspace . --tool run_uvm_simulation \
    --test-name my_test --mode run --waves \
    --compile-args "+define+ENABLE_ASSERTIONS"
```

### Coverage-Enabled Run

```bash
python mcp_server/mcp_client.py --workspace . --tool run_uvm_simulation \
    --test-name my_test --mode run --coverage --waves
```

## Output Locations

| Output Type | Location |
|-------------|----------|
| **Test logs** | [sim/logs/<test_name>.log](../../sim/logs/) |
| **Result JSON** | [sim/logs/<test_name>_result.json](../../sim/logs/) |
| **Telemetry** | [sim/logs/<test_name>_telemetry.json](../../sim/logs/) |
| **Waveforms** | [sim/logs/<test_name>.mxd](../../sim/logs/) |
| **Coverage** | [sim/reports/coverage/](../../sim/reports/coverage/) |
| **Regression reports** | [sim/reports/regression_<timestamp>.html](../../sim/reports/) |

## Troubleshooting

### MCP Server Not Responding

1. Check background task: `🚀 Start Enhanced MCP Server (FastMCP Edition)`
2. Verify Python environment: `python --version` (requires 3.8+)
3. Test direct invocation: `python mcp_server/dsim_fastmcp_server.py --help`

### DSIM Environment Errors

```bash
python mcp_server/mcp_client.py --workspace . --tool check_dsim_environment
```

Review output for missing environment variables. See `dsim-debugging` skill for detailed troubleshooting.

### Test Not Found

```bash
python mcp_server/mcp_client.py --workspace . --tool list_available_tests
```

Verify test exists in [sim/tests/](../../sim/tests/) and is registered in [regression_tests.json](../../sim/regression_tests.json).

## Additional Resources

- **MCP server implementation**: [mcp_server/README.md](../../mcp_server/README.md)
- **Regression configuration**: [mcp_server/REGRESSION.md](../../mcp_server/REGRESSION.md)
- **DSIM debugging**: Reference `dsim-debugging` skill
- **Test execution**: [docs/vexriscv_test_quickstart.md](../../docs/vexriscv_test_quickstart.md)

## Summary

MCP workflow principles:
1. Always use FastMCP + VS Code MCP integration (mandatory)
2. Never specify `--timeout` parameter (auto-selected from [test_timing_config.json](../../mcp_server/test_timing_config.json))
3. Standard sequence: `check_dsim_environment` → `list_available_tests` → `compile` → `run`
4. Prefer VS Code tasks for common operations
5. Consume JSON outputs from [sim/logs/](../../sim/logs/) and [sim/reports/](../../sim/reports/)
6. Use fallback PowerShell path only when MCP unavailable (document reason)
7. Smoke suite (~40s) for quick validation, full suite for complete regression

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/mamemame777) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-15 -->