# FA-Technician-Brain-MCP

A Model Context Protocol (MCP) knowledge server for the **Technician Portal** module in FleetFocus FA/EAM (InfoCenter). This server provides structured, queryable information about the module's pages, workflows, API endpoints, database schema, field specifications, UI interaction patterns, and validation rules.

## Purpose

This MCP is designed to be consumed by AI agents (e.g., Playwright automation, test generation, code review) that need to understand the Technician Portal's behavior without making live API calls. All data is hardcoded from research documents — **no credentials, no live connections**.

## What's Covered

| Domain | Coverage |
|--------|----------|
| **Pages** | 18 screens/pages with full field specs, actions, and navigation |
| **Workflows** | 8 named workflow recipes (clock in, job on/off, create WO, finish/close, etc.) |
| **API Endpoints** | 50+ endpoints across Custom Web API, V2 OData, and V3 |
| **Database** | 23 tables with columns and relationships |
| **Fields** | Component-level specs (type, validation, API mapping) |
| **Interactions** | UI patterns (CCL components, dialogs, drawers, cards) |
| **Validation** | Server-side rules and client-side guards |
| **Transitions** | Work order status state machine |
| **Permissions** | Role/persona-based access by state |

## MCP Tools

| Tool | Description |
|------|-------------|
| `get_page` | Full page specification by page_id |
| `get_workflow` | Named workflow recipe with step-by-step instructions |
| `get_api_endpoint` | Endpoint spec by entity + operation |
| `get_table_schema` | Database table definition with columns |
| `get_field` | Field-level spec (component, validation, API mapping) |
| `get_interaction_pattern` | UI component interaction pattern |
| `get_validation_rules` | Validation rules for entity/operation |
| `get_transitions` | Status transitions from a given state |
| `get_persona_permissions` | What a persona can do at a given WO state |
| `search` | Full-text search across all data |
| `get_test_fixtures` | Get test fixture data by entity or ID for automation |
| `check_provenance` | Get provenance info for a data path (sources, last checked dates) |

## Setup

```bash
npm install
npm run build
npm start
```

## Module Context

- **Application**: FleetFocus FA/EAM InfoCenter
- **Module Path**: `InfoCenterBase/InfoCenter/ClientApp/src/app/modules/technician/`
- **Design System**: CCL (Component Class Library)
- **License**: Independent beta license key
- **Version**: 26.1 Beta (as of research date)
- **Legacy Screen ID**: 7003 (ASP.NET WebForms predecessor)

## Architecture

The Technician Portal uses two API layers:
1. **Custom InfoCenter Web API** (`/Infocenter/api/Technician/...`) — Session-cookie auth, business logic operations
2. **V2 OData API** (`:9001/api/v2/...`) — OAuth2 Bearer token, entity read/query operations

There are **no V3 technician-specific endpoints**. All business logic lives in FA-Suite controllers.

## Provenance Tracking

Every piece of data in this MCP is tracked back to its source. The provenance registry (`src/data/provenance.ts`) maps each data path to one or more sources with:

- **Source type**: `jira`, `github`, `figma`, `api`, `confluence`, or `manual`
- **URL**: Direct link to the source material
- **Description**: What information was extracted from the source
- **lastChecked**: When the source was last verified
- **lastChanged**: When the source was last observed to have changed

### Checking for Updates

Run the source checker to see if any sources have been updated since last check:

```bash
# Set credentials
export JIRA_EMAIL="your-email@example.com"
export JIRA_API_TOKEN="your-jira-api-token"
export GITHUB_TOKEN="your-github-pat"

# Run check
npm run check-sources
```

Or use the shell wrapper:

```bash
./scripts/update-sources.sh
```

The checker:
- Queries Jira REST API for issue `updated` timestamps
- Queries GitHub API for file last-commit dates
- Compares against recorded `lastChanged` dates
- Reports which sources have newer changes
- Does NOT auto-apply changes (manual review required)

Exit codes:
- `0` — All sources up to date
- `1` — Changes detected (review needed)
- `2` — Script error

### Using Provenance via MCP

```
Tool: check_provenance
Input: { "data_path": "pages.home" }
```

Returns the provenance entries showing where the home page data was sourced from and when it was last verified.

## Test Fixtures

The test fixture registry (`src/data/test-fixtures.ts`) provides stable test data values for automation. Fixtures include:

| ID | Entity | Description |
|----|--------|-------------|
| `default_technician` | Operator | CA user with full admin access |
| `test_equipment_fleet_001` | Equipment | QA-FLEET-001 vehicle |
| `test_equipment_fleet_004` | Equipment | QA-FLEET-004 (preferred for OM) |
| `test_vendor_qa` | Vendor | QA test vendor for outsourced maintenance |
| `test_task_ca_rp_01` | TaskCode | 001-CA-RP-01 task for OM tickets |
| `test_work_order_open` | WorkOrder | Template for OPEN WO creation |
| `test_time_code_regular` | TimeCode | REG time code for clock-in |
| `test_time_code_indirect` | TimeCode | IND time code for indirect labor |
| `test_location_main` | Location | Main shop location |
| `test_delay_code` | DelayCode | PARTS delay reason |
| `pw_auto_ticket_mgmt_user` | Operator | Playwright automation OM user |
| `test_infocenter_url` | Environment | QADEPLOY URLs and connection info |

### Using Fixtures via MCP

```
Tool: get_test_fixtures
Input: { "entity": "Equipment" }
```

Returns all equipment fixtures. Or get a specific fixture:

```
Tool: get_test_fixtures
Input: { "id": "default_technician" }
```