Protrak Forge

Protrak Forge is an MCP server for Protrak customization workspaces. It gives AI assistants the project context they need to help with Protrak C# programs, query definitions, and Design Studio layouts without relying on generic guesses.

What You Can Do

• Generate Protrak C# programs with workspace-aware context
• Review existing programs and validate generated code before using it
• Explore types, available services, and existing project artifacts
• Create or inspect query definitions used by your customization
• Design new layouts with awareness of existing forms, widgets, and templates
• Scaffold new entity types — Types, Lifecycles, Attributes, and RelationTypes — in one shot
• Create notification templates using the correct Razor syntax and @Model variables

Requirements

• Node.js 18 or later
• A Protrak customization workspace

Path and Platform Notes

The examples below use macOS/Linux-style paths such as /path/to/Your.Customization. On Windows, use a Windows path instead. In JSON strings, escape backslashes:

"C:\\path\\to\\Your.Customization"

In Codex config.toml, you can use a TOML literal string to avoid double escaping:

cwd = 'C:\path\to\Your.Customization'

If a native Windows MCP client cannot launch npx directly, use cmd /c as the command wrapper. WSL users can use the macOS/Linux examples from inside the WSL environment.

Installation

VS Code with GitHub Copilot

Install the Protrak Forge extension from the VS Code Marketplace (publisher: prorigo). This is the simplest setup for VS Code and starts the MCP server automatically when you open a supported Protrak workspace.

Visual Studio 2022 (v17.14+)

Visual Studio runs on Windows and can discover MCP configuration from several locations. For a team-shared solution setup, add a .mcp.json file to your solution folder:

{
  "inputs": [],
  "servers": {
    "protrak-forge": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "@prorigo/protrak-forge"],
      "env": {
        "PROTRAK_PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}

For a user-wide setup, put the same file at %USERPROFILE%\.mcp.json. For a private solution-local setup, use <SOLUTIONDIR>\.vs\mcp.json.

If your customization project is not the solution root, replace ${workspaceFolder} with the path to the customization folder.

For a Windows absolute path in JSON, escape backslashes:

"PROTRAK_PROJECT_ROOT": "C:\\path\\to\\Your.Customization"

If Visual Studio cannot launch npx directly on a native Windows machine, use the cmd /c wrapper:

{
  "inputs": [],
  "servers": {
    "protrak-forge": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "--yes", "@prorigo/protrak-forge"],
      "env": {
        "PROTRAK_PROJECT_ROOT": "C:\\path\\to\\Your.Customization"
      }
    }
  }
}

Claude Code

Add this to .claude/settings.local.json in your Protrak customization repository:

{
  "mcpServers": {
    "protrak-forge": {
      "command": "npx",
      "args": ["--yes", "@prorigo/protrak-forge"],
      "type": "stdio",
      "cwd": "/path/to/Your.Customization"
    }
  }
}

On native Windows, wrap npx with cmd /c:

{
  "mcpServers": {
    "protrak-forge": {
      "command": "cmd",
      "args": ["/c", "npx", "--yes", "@prorigo/protrak-forge"],
      "type": "stdio",
      "cwd": "C:\\path\\to\\Your.Customization"
    }
  }
}

You can also install globally and use the protrak-forge command directly:

npm install -g @prorigo/protrak-forge

{
  "mcpServers": {
    "protrak-forge": {
      "command": "protrak-forge",
      "type": "stdio",
      "cwd": "/path/to/Your.Customization"
    }
  }
}

On Windows, use the npm-generated .cmd shim:

{
  "mcpServers": {
    "protrak-forge": {
      "command": "protrak-forge.cmd",
      "type": "stdio",
      "cwd": "C:\\path\\to\\Your.Customization"
    }
  }
}

Optional: if you installed the package globally, you can copy the included CLAUDE.md template into your customization repo for ready-made Claude Code guidance.

macOS/Linux:

cp $(npm root -g)/@prorigo/protrak-forge/data/CLAUDE.md.template /path/to/Your.Customization/CLAUDE.md

Windows PowerShell:

Copy-Item "$(npm root -g)\@prorigo\protrak-forge\data\CLAUDE.md.template" "C:\path\to\Your.Customization\CLAUDE.md"

Codex and Codex CLI

Codex app, the Codex IDE extension, and Codex CLI share MCP configuration through config.toml. Add this to ~/.codex/config.toml for a user-wide setup:

[mcp_servers.protrak-forge]
command = "npx"
args = ["--yes", "@prorigo/protrak-forge"]
cwd = "/path/to/Your.Customization"

You can also scope the server to a trusted Protrak customization repository by adding the same configuration to .codex/config.toml in that repository.

On native Windows, if npx does not launch from Codex, use cmd /c:

[mcp_servers.protrak-forge]
command = "cmd"
args = ["/c", "npx", "--yes", "@prorigo/protrak-forge"]
cwd = 'C:\path\to\Your.Customization'

If you prefer the Codex CLI command, run:

codex mcp add protrak-forge --env PROTRAK_PROJECT_ROOT=/path/to/Your.Customization -- npx --yes @prorigo/protrak-forge

Windows PowerShell:

codex mcp add protrak-forge --env PROTRAK_PROJECT_ROOT=C:\path\to\Your.Customization -- cmd /c npx --yes @prorigo/protrak-forge

To verify the server is configured:

codex mcp list

In the Codex terminal UI, run /mcp to see active MCP servers for the current session.

If you installed the package globally, you can use the protrak-forge command directly:

[mcp_servers.protrak-forge]
command = "protrak-forge"
cwd = "/path/to/Your.Customization"

Windows:

[mcp_servers.protrak-forge]
command = "protrak-forge.cmd"
cwd = 'C:\path\to\Your.Customization'

Optional: Codex reads project guidance from AGENTS.md. If you want Codex to consistently use Protrak Forge while working in the customization repo, add a short note to that file telling Codex to use the Protrak Forge MCP tools for Protrak programs, query definitions, layouts, and scaffolding.

Other MCP Clients

Use the same server with any MCP-compatible client:

{
  "mcpServers": {
    "protrak-forge": {
      "command": "npx",
      "args": ["--yes", "@prorigo/protrak-forge"],
      "env": {
        "PROTRAK_PROJECT_ROOT": "/path/to/Your.Customization"
      }
    }
  }
}

On native Windows clients that cannot launch npx directly, use:

{
  "mcpServers": {
    "protrak-forge": {
      "command": "cmd",
      "args": ["/c", "npx", "--yes", "@prorigo/protrak-forge"],
      "env": {
        "PROTRAK_PROJECT_ROOT": "C:\\path\\to\\Your.Customization"
      }
    }
  }
}

Example Prompts

Once the server is connected, you can ask your assistant things like:

• "Create a PreCreate program for Project that validates required fields."
• "Review this existing program and explain what it does."
• "Create a query definition for active projects assigned to the current user."
• "Design a dashboard layout for Diary using the existing workspace patterns."
• "Scaffold a Diary entity with an Active/Inactive lifecycle and a FarmerGatToDiary relation."
• "Create a notification template for the Invoice type that emails the manager when an invoice is promoted to Sent."
• "Create a rule named OverdueAllocation that fires when AllocationEndDate is on or before today, and attach it as background-color conditional formatting on the AllocationEndDate column of ProjectActiveAllocationsRelationWidget."
• "Set the OwnerOnly rule as the Access Policy on the Project type."
• "Make the In Use option on ResourceStatus depend on the EquipmentStatusEqualsToolUp rule."

Workspace Detection

Protrak Forge tries to detect your customization workspace automatically. If detection does not land on the right folder, set PROTRAK_PROJECT_ROOT explicitly in your MCP configuration.

Tool Catalog And Conventions

• Upfront catalog. tools/list advertises ~11 first-class entry points (the unified list_protrak_artifacts / read_protrak_artifact / validate_protrak_artifact / generate_protrak_layout dispatchers plus the discovery, scaffolding, and program / form generation tools). Deprecated aliases, focused mutators, and niche generators are still registered and callable by name but hidden from the catalog so the agent's tool picker stays sharp.
• Discovery. Call protrak_capabilities to enumerate every registered tool (including hidden ones) along with its domain, category, keywords, and required arguments. Set the environment variable PROTRAK_FORGE_ALL_TOOLS=1 to expose all registered tools in tools/list instead.
• Dry-run + diff. Every generator (single-file and paired-file) accepts dry_run: true — it returns the proposed file content and a unified diff against any existing target, without touching disk. Paired-file writers (generate_protrak_program, generate_protrak_widget, generate_protrak_notification_template) pre-flight both files before committing either, so an overwrite refusal never leaves a half-written artifact.
• Validator levels. validate_protrak_program, validate_protrak_widget, and validate_protrak_artifact accept level: 'all' | 'errors_only' (default all). Use errors_only to drop warnings when you're gating an auto-fix loop or summarizing blocking issues only.

License

MIT © Prorigo