Protrak Forge
Developer tooling for Protrak customisation projects.
The extension does two things:
- Schema import / export — synchronise your local JSON schema files with a Protrak server, or export them to a portable JSON file for review or migration.
- MCP server auto-registration — makes the
@prorigo/protrak-forge MCP server available to GitHub Copilot and other MCP-capable agents inside VS Code, pointed at the right project root automatically.
Features
Schema Import & Export
Manage your Protrak customisation schema directly from VS Code without leaving the editor.
- Import from server — connects to a named Protrak instance, downloads the live schema, and writes it into your local project. Shows a dry-run summary (files to write, and — only if
protrakForge.import.deleteMissingFiles is enabled — files to delete) before making any changes.
- Import from file — applies a previously exported
.json schema file to your project, with the same pre-write confirmation.
- Export to server — reads your local schema files and pushes them to a Protrak server via the schema import API.
- Export to file — serialises your local schema to a single
.json file for review, archiving, or migration.
All commands support three scopes:
| Scope |
What it touches |
| All |
Every collection in the project |
| Collection |
A single folder (e.g. Programs, Types) |
| Element |
A single schema element (e.g. one Program) |
Create New Project
Run Protrak Forge: Create New Protrak Project from the Command Palette to scaffold a fresh customisation project anywhere on disk. The generator:
- prompts for a project name (auto-appends the conventional
.Customization suffix)
- prompts for the parent folder
- writes a net8.0 SDK-style
.csproj referencing Prorigo.Protrak.Toolkit 2.1.8
- creates
Program.cs with a minimal IocContainer bootstrap
- creates all 26 schema folders (
Types/, Programs/, …) with .gitkeep placeholders so they survive Git
- offers to open the new folder in the current or a new VS Code window
Because the scaffold has both Types/ and Programs/ (and a Toolkit-referencing csproj), the extension's auto-detection picks it up immediately — MCP server and Explorer context menu both activate. For non-standard layouts that auto-detection misses, use Protrak Forge: Set Protrak Project Root… (see Manually setting the project root) to point Forge at any folder explicitly.
In a Protrak workspace, right-clicking any file or folder in the Explorer reveals a Protrak Forge submenu with the four import/export commands. The scope is inferred from where you clicked, so you don't need to choose it manually:
| Right-click target |
Inferred scope |
| Project root |
All |
Schema folder (e.g. Programs/, Types/) |
Collection for that folder |
Schema file (.json, or its sidecar .cs / .js / .html) |
Element for that file |
The submenu only appears when the current workspace contains a recognised Protrak project (i.e. a .csproj referencing Prorigo.Protrak.Toolkit, or both Programs/ and Types/) — or when you have explicitly set a project root via the Set Protrak Project Root command described below.
Saved Connections
Use Protrak Forge: Manage Server Connections to store named server connections (name + URL). API tokens are stored in VS Code's SecretStorage — they are never written to settings.json or committed to source control.
MCP Server for Coding Agents
The extension registers @prorigo/protrak-forge as an MCP server for GitHub Copilot (Agent mode) and any other MCP-capable tool running in VS Code. The server exposes your local schema, API interface definitions, pattern documentation, and 11 schema-element generators (Type, Attribute, Lifecycle, RelationType, Form, LayoutTemplate, TypeWidget, Program, NotificationTemplate, QueryDefinition, Rule) so the agent has full project context when generating Protrak Programs and authoring new schema.
Detection is automatic: the extension scans your workspace for a .csproj referencing Prorigo.Protrak.Toolkit, or for the standard Programs/ and Types/ directory layout.
Manually setting the project root
If your customisation project doesn't match either auto-detection marker — or you want to override which folder Forge uses in a multi-root workspace — run Protrak Forge: Set Protrak Project Root… from the Command Palette. The command shows a Quick Pick with:
- any detected Protrak roots (marked Detected)
- the open workspace folders
- a Browse for folder… option to pick any folder on disk
- a Clear override option (shown only when an override is already set)
Any folder you pick — even one that doesn't satisfy the auto-detection heuristic — is accepted and used as the project root for both Forge commands and the MCP server (PROTRAK_PROJECT_ROOT). The MCP server is restarted automatically so the new root takes effect immediately.
Two persistence options are supported, in order of precedence:
protrakForge.projectRoot (window-scoped setting) — checked-in default, useful when the whole team needs the same override for a workspace.- Workspace-state override (written by the command above) — per-workspace, not visible in
settings.json, doesn't follow Git.
The override applies to every Forge command and to the MCP server's PROTRAK_PROJECT_ROOT. Clear it via the command's Clear override entry or by deleting the setting.
Requirements
- VS Code 1.101 or later
- A Protrak server instance (for import/export commands)
- Node.js 18+ and
npx on your PATH (for the MCP server — installed automatically on first use via npx --yes)
Getting Started
- Open your Protrak customisation project (the folder containing
Programs/, Types/, etc.).
- Open the Command Palette (
Ctrl+Shift+P / Cmd+Shift+P) and run Protrak Forge: Manage Server Connections to add your first server.
- Run Protrak Forge: Import Schema from Server to pull down the schema from your Protrak instance.
For MCP / Copilot: once the extension is installed and a Protrak project is open, the MCP server starts automatically. No additional configuration is needed.
Commands
All commands are available from the Command Palette under the Protrak Forge category, and (except for connection management) also under the Explorer context menu's Protrak Forge submenu.
| Command |
Description |
Create New Protrak Project |
Scaffold a fresh customisation project (csproj + Program.cs + schema folders) |
Generate Type |
Create a new Types/<Name>.json interactively (lifecycle picker + multi-select attribute picker). Available from the Command Palette and the Explorer Protrak Forge submenu. |
Import Schema from Server |
Download and apply schema from a Protrak server |
Import Schema File into Project |
Apply a local .json schema file to the project |
Export Local Schema to Server |
Push local schema files to a Protrak server |
Export Local Schema to File |
Save local schema as a .json file |
Manage Server Connections |
Add, edit, or remove saved server connections |
Set Protrak Project Root… |
Pick (or browse to) any folder and use it as the Protrak project root. Bypasses auto-detection; applies to both MCP server (PROTRAK_PROJECT_ROOT) and all Forge commands. |
Settings
| Setting |
Default |
Description |
protrakForge.connections |
[] |
Saved server connections. Each entry has a name and url. Tokens are stored separately in SecretStorage. |
protrakForge.import.deleteMissingFiles |
false |
When importing schema (All or Collection scope), also delete local files not present in the incoming schema. Off by default — imports only write/overwrite. Turn on to mirror the legacy VS C# extension cleanup behavior. Has no effect on Element-scope imports. |
protrakForge.projectRoot |
"" |
Absolute path to the Protrak customisation project. When set, overrides auto-detection and is used both by Forge command handlers and as PROTRAK_PROJECT_ROOT for the MCP server. Leave blank to auto-detect. Set this through the Set Protrak Project Root command or by editing settings.json directly. |
protrakForge.operationTimeoutMinutes |
10 |
Maximum time (in minutes) that server-bound schema operations (Import from Server, Export to Server) may run before being cancelled automatically. Increase if you regularly import/export very large schemas. Operations can also be cancelled manually by clicking Cancel on the progress notification. |
Extension and Package Versions
The VS Code extension (prorigo.protrak-forge) and the npm MCP package (@prorigo/protrak-forge) are versioned together. The extension pins the MCP server to the matching major version so patch and minor updates are picked up automatically without reinstalling the extension.
License
MIT
