CONFIG → EVIDENCE → PLAN → AUTHORIZE
Codex plugin · MCP server · Windows-first · read-first by design
When a motorsport setup is split across proprietary files, installed Windows applications, and private manuals, an agent needs a local evidence trail—not guessed semantics. MoTeC MCP gives Codex bounded offline inspection, cross-file correlation, workflow planning, and carefully gated paths into the vendor software you have installed.
Important
Local data and trust boundary. The repository contains code, tests, authored guidance, schemas, and public source metadata—not your car files, calibrations, logs, screenshots, copied vendor manuals, extracted help, or generated indexes. Setup reads only the main root and additional roots you explicitly authorize. MCP-owned state is created beneath <main-root>\.motec-mcp; additional roots remain read-only. Runtime inspection is local; it does not send a configuration to a physical ECU, dash, PDM, or display. CSV logs must stay private in an explicitly authorized root; the MCP reads them in place and does not copy their source bytes into this clone or return raw rows in reports. Guarded text/XML/DBC edits are opt-in and require a matching hash, writes enabled, a backup, and an exact single-use confirmation. See the authorization policy.
For a new Windows PC or another Codex, use the deterministic hand-off path:
Authorization gate. The clone and install steps below are only for Herbertmt978 or people explicitly authorized in writing. They do not permit redistribution.
$pluginParent = Join-Path $HOME "plugins"
$pluginRoot = Join-Path $pluginParent "motec-mcp"
New-Item -ItemType Directory -Force -Path $pluginParent | Out-Null
git clone https://github.com/Herbertmt978/MoTeC-MCP.git $pluginRoot
Set-Location $pluginRoot
.\scripts\setup.ps1 -DryRun -NonInteractive
.\scripts\setup.ps1 `
-Workspace "D:\MoTeC" `
-AdditionalConfigRoot "D:\Cars\Car A\MoTeC","E:\Race Cars\Car B" `
-DisableWrites `
-ReadinessMode reduced `
-NonInteractive
.\scripts\register-codex-plugin.ps1
.\scripts\verify-install.ps1 -Mode reducedThe dry run does not install, write config, or register Codex. Setup asks for any missing private roots, software paths, help indexes, DBCs, and working configurations needed for the selected readiness mode. Use reduced for offline operation; full adds the installed-app/help inputs required by live and evidence-capture workflows. Read setup from GitHub before running a fresh install.
For logging, telemetry, or i2 work, start with the logging and telemetry analysis guide. It defines the current CSV boundary, vendor-native parity gate, and authorization/privacy rules.
For a fresh Codex, call motec_config and motec_workspace_report first. Then use
the bounded, read-only CSV sequence motec_log_summary → motec_log_channels →
motec_log_query and, when data-quality evidence is needed,
motec_log_quality_report. These tools accept only a CSV in a configured root and
return bounded, vendor-neutral observations; they do not activate i2, export a
native log, or communicate with a logger or vehicle.
For software work, call motec_software_navigation_catalog before touching a live
window. It returns the quickest version-bound menu/tab/tree route, the preferred
existing MCP tool, schema-checked fixed and still-required caller arguments, the
interaction class, a fallback, and only shortcuts that have direct user-facing
evidence. Claims bind to audited, normalized-content-hashed repository evidence in
data/software-navigation-evidence.json.
It is a static local index: it does not launch or
focus an application, read a private configuration, send input, or grant
authorization. Follow the fast-action and shortcut workflow
to route, open, capture, propose, authorize, verify, and recover.
For an Ultima or another multi-device build, start with
motec_resource_catalog, motec_manual_coverage, and
motec_vehicle_system_catalog; then create evidence-demoted plans with
motec_vehicle_system_profile_v2 and motec_signal_path_analysis_v2. Compile
and preview the original C125-primary/C1212-secondary study with the
motec_dual_display_bundle_* tools. The shipped bundle is simulation-only: it
does not create target fitment, invent CAN values, produce a native dash file,
or authorize software or hardware action. Follow the
Ultima dual-display builder for the exact
questions that turn the template into a real-car working plan, and use the
C1212 simulation channel pack
to exercise tangible TPMS, dynamics, aero, timing, and local-navigation pages
without claiming a DBC or device route.
Expect setup or readiness to ask for the existing main MoTeC data root, any additional read-only car/AiM roots, an optional knowledge registry or notes folder to preserve, and the exact vendor software/help paths that are installed outside their manifest defaults. A target build also needs the exact M150 package and configuration, engine and sensor inventory, TPMS revision, ABS revision, wiring/loom evidence, configuration software and software version, plus the private target files. Ask whether HVAC and front lift are fitted or intended before requesting either controller, kit, or type. File-class questions come from data/install-requirements.json; do not substitute a guessed path or copy a private file into the clone.
| Surface | Default behavior | How to undo or limit it |
|---|---|---|
| Dependencies and build | Runs npm ci and builds the server in the clone |
Remove the clone, or reinstall from a clean clone |
| MCP state | Creates manifest-declared directories under <main-root>\.motec-mcp |
Preserve what you need, then remove that state directory |
| Additional roots | Reads folders explicitly authorized with -AdditionalConfigRoot; setup merges and preserves existing roots |
Setup has no removal switch. To revoke a root, stop Codex, back up %USERPROFILE%\.motec-mcp\config.json, remove it from both additionalConfigRoots and compatibility-mirror exampleRoots, then run reduced verification; no MCP state is written inside the root |
| Guarded writes | A fresh setup defaults off; a reinstall preserves the prior policy | Pass -DisableWrites explicitly when you want a verified read-only policy. Hardware/device writes remain unavailable |
| Codex registration | Registers this clone as the motec MCP server |
Run codex mcp remove motec |
| Area | Offline / read-only evidence | Live or state-changing boundary |
|---|---|---|
| MoTeC ECU Manager / M800 | .e30–.e35 metadata and strings, ECU Manager menus/screens, exact file routing, identity-aware workflow and indirect-strategy planning |
Use ECU Manager for edits. Save, transmit, firmware, options, tests, and device communication need an operation-specific driver, revalidation, evidence, recovery, abort conditions, and exact authorization |
| MoTeC M1 Tune / M1 | .m1pkg, .m1wsp, .mtf, .mtccal, .mcs, .mfs metadata, package/workspace discovery, menus, trees, logs and checklist guidance |
M1 Tune owns package/calibration/device changes. Online, Send/Get, firmware, options, and ECU communication are not invoked by generic tools |
| MoTeC Dash Manager / C127 / C12x | Exact-snapshot .c127v65 framing, section tags, channel evidence and unknown regions; installed help, DBC relationships, menus, screenshots, no-save interrogation |
.c127v65 is the exact automatic C127 route. Other C12x variants require matching software/version evidence; Online, send, firmware, options, and tests remain gated |
| Display Creator | Exact-snapshot .dcproj container/media framing and schema-only layout/resource tags; installed help/assets; tabs and Pages-tree evidence; dashboard/alarm plans; path-free reference-dashboard reconstruction into calibrated C125/C127/C1212 regions, semantic objects, groups, paint order, palette/typography evidence, scenarios, and ambiguity questions; typed page/entity/style/layer/group/binding primitives; deterministic stateful icon and request/actual-menu compilation/simulation; caller-declared producer→CAN→Dash→generated-DBC→entity/property candidate-path analysis; configured-root path-free region-geometry diff receipts with no exact-region content hashes; caller-declared repeatability evaluation; 45 C125/C1212 concepts; a manual version-bound C1212 authoring recipe; and internal template-backed compilation of an exact six-page C1212 foundation plus one admitted frontmost power-on Animation |
The public semantic tools plan, hash, correlate, simulate, and report authoring readiness; they do not ingest reference-image bytes, infer exact fonts or DBC semantics, accept a capability profile, issue a verified channel binding, manipulate the UI, generate a DBC, write .dcproj, configure a device, or grant authorization. The internal compiler requires four opaque private target-pack inputs, preserves target-specific paint direction and returns only owned disposable bytes; native reopen/readback/Quick Check remains not-run. It is not a public apply route, general codec, arbitrary-media writer, menu writer, gauge writer, or DBC writer. One deep-internal Display Creator 6.5.0.31 C1212 Rectangle fill-colour transition passed its primary and independent disposable-copy holdout UAT, but its result is non-promoting. Every other value, object, property, display family, binding, structural edit, save/package/send, and Device > Configure Device action still requires its own proved route and action-specific authorization |
| PDM Manager / PDM16 / PDM32 | Exact-snapshot .pdm XML summaries plus bounded section/kind query pages for outputs, inputs, CAN, keypads and channels; edit previews; installed-help and menu/workflow evidence |
Query correlation is version-bound/partial and live-UAT-pending. XML/text previews can become guarded local writes. Monitor, Get Configuration, tests, firmware, and sending to a physical PDM are planned/gated operations |
| AiM Race Studio / MXG | Race Studio SQLite schema/count summaries, exact ECU protocol XML structure, official-source metadata, M800→MXG CAN/RS232 planning | Protocol structure alone does not prove vehicle compatibility. Race Studio transfers and device actions need the exact fitted hardware, firmware, wiring, source identity, and an operation-specific authorization path |
| Telemetry/i2 CSV | Configured-root, read-only CSV exact snapshots, channel discovery, bounded sample/aggregate queries, and quality observations through motec_log_summary, motec_log_channels, motec_log_query, and motec_log_quality_report |
CSV remains private and vendor-neutral. Installed i2 readiness proves only declared files are present; it does not prove activation, edition, API access, workspace load, or native export. MoTeC .ld and AiM .xrk/.xrz/.drk/.gpk require the matching application and a private original plus same-session CSV parity check; no native adapter is claimed |
| Whole-vehicle engineering | Signal-path/CAN analysis, commissioning and I/O plans, system fault-isolation, evidence-led tuning plans, lambda/fuel/sensor/knock/boost/logging guidance | Plans never invent values, prove a target fault from caller text alone, or authorize a live test. Physical work stays with the operator and the matched vendor workflow |
| Fast software navigation | Version-bound screen routes, schema-checked preferred-tool invocations, hash/audit-bound evidence, fallbacks, interaction classes, and verified user shortcuts for Dash Manager, Display Creator, PDM Manager, ECU Manager, M1 Tune, Race Studio, and i2 | The catalog is static knowledge, not current UI evidence or an executor. Opening, capture, edits, connected actions, and recovery use their existing guarded/action-specific tools and exact authorization contracts |
| Resource and manual coverage | Strict logical catalogue, all six coverage states, official-link metadata, local installed-help queries, permission-gated private acquisition, and path-free admission capabilities | The repository does not bundle vendor manuals. Catalogue knowledge is not target fitment; an empty search is not evidence of absence. Acquisition and admission require the local-only resource-store workflow |
| Ultima dual displays | Original simulation-only C125-primary/C1212-secondary designs, shared tokens/channels, DBC readiness, menus, alarms, request/actual feedback, deterministic preview and validation | No whole-display C125/C1212 native suffix, general driver, generated DBC, send route, or completed whole-display native UAT is claimed. The exact narrow C1212 Rectangle fill-colour proof described above is non-promoting. Exact manager/firmware/help/project evidence and operation-specific authorization are required before further native work |
No vehicle profile is active by default. The optional m800-evo48-13009a material is a conditional case study for an independently verified Evo4–8 four-plug M800 OEM family; never transfer it to an unverified car or to the Evo8/9 three-plug 13010A/EVO89 family.
The internal v0.7.0 Display Creator path can compile an exact six-page C1212
foundation and one descriptor-one power-on Animation entirely in memory from an
opaque, disposable private target pack. It uses target-specific C1212/C127 paint
order and reports state, menu, and channel readiness without claiming unproved
native behavior. Native vendor validation is still required: this is not a
general arbitrary-media, gauge, menu, DBC, or .dcproj writer, performs no
device action, and requires every private target pack and donor project to
remain outside Git.
authorized roots/files
↓
exact snapshot + format/version identity
↓
path-redacted single-file analysis, comparison, or workflow plan
↓
preview + diff + recovery path
↓
single-use authorization (only for a reviewed operation)
↓
revalidate target → execute → capture evidence → verify / abort / recover
The MCP keeps planning and evidence collection separate from execution. Generic keyboard/menu or screenshot tools are not an authorization escape hatch. Public and ordinary-use proprietary binary project/configuration workflows inspect rather than generically rewrite those files; use the matching MoTeC or AiM application for edits. The separately documented deep-internal C1212 disposable-copy proof is one exact non-promoting exception, not a public writer or general file codec.
Architecture and data boundaries
The TypeScript server exposes MCP tools over stdio. Offline workers perform bounded parsing, exact-snapshot hashing, metadata/string extraction, XML/DBC analysis, SQLite schema/count analysis, and path-free reports. Windows adapters can inspect installed applications and visible UI where the install contract matches the target version. Private knowledge and help indexes stay under MCP-owned state; reports replace private paths and filenames with tokens.
The source-of-truth flow is deliberately narrow:
- Admit a file or root through the configured-root contract.
- Bind the exact bytes, declared format, version, and relevant installed software/help.
- Run the recommended analyzer or summary before relying on semantics.
- Preview any supported text/XML/DBC change into a temporary copy.
- Apply only after hash, write policy, confirmation, backup, and recovery gates pass.
See offline data layout, configuration routing, and the capability matrix for the implementation contract.
- Install and hand-off: setup from GitHub, new-PC ECU Manager validation
- Resources and manuals: resource catalogue and local acquisition, third-party artifacts and notices, reference authority
- Choose a workflow: software and hardware guide, MCP capability matrix, Codex task workflow
- Navigate and act quickly: software navigation and shortcuts, software-action authorization
- Dash and power: Dash Manager + Display Creator, reference-dashboard reconstruction, fast authoring and offline learning, stateful icons and rotary menus, private C1212 target-pack inputs, C125/C1212 concept gallery, C1212 blank-project authoring, PDM Manager live workflow
- Ultima, sensors, and wiring: whole-vehicle instrumentation/control catalogue, wiring and pin-map workflow, knock and sensor integration, dual-display builder, C1212 simulation channel pack, controlled Red Mini UAT
- ECU and tuning: M1 Tune, M800 ECU Manager, rolling-road tuning, vehicle tuning fundamentals
- Logging and telemetry: logging and telemetry analysis
- AiM integration: Race Studio + M800 integration, offline protocol analysis, AiM guide
- Evidence and safety: software-action authorization, signal-path/CAN diagnostics, commissioning and I/O testing, reference authority
- Knowledge and operations: knowledge base, offline data layout, release checklist
Requires Windows PowerShell, Git, Node.js 20+, npm, and Codex CLI/Desktop for registration. GitHub CLI is optional. MoTeC/AiM applications and installed help are optional for offline operation and required only for separately authorized live UAT. Logs and CSV exports are not install prerequisites; provide them later from an explicitly authorized private root when a telemetry question needs them.
npm ci
npm run build
npm run typecheck
npm run typecheck:test
npm run validate:package
npm run smoke
npm run mcp-smoke
npm run mcp-full-smokeThe full smoke suite is synthetic-only: it uses bounded temporary fixtures, verifies the complete tool inventory, and runtime-guards an explicit offline probe allowlist. The harness does not invoke process discovery, application queries, focus, capture, or input tools, even when MoTeC/AiM applications are open. Live application and hardware checks remain separate, operator-authorized UAT workflows. Maintainers should also follow the release checklist.
Keep changes narrow and evidence-led. Do not commit private vehicle files, generated indexes, screenshots, vendor manuals, extracted help, credentials, or machine-specific paths. For parser or workflow changes, add a focused fixture/test and update the relevant capability or safety documentation. Review AGENTS.md and docs/codex-task-workflow.md before changing behavior.
For a reproducible bug or documentation gap, open a GitHub issue with the smallest redacted fixture and the command/test that demonstrates it. Never attach private configs, logs with identifying data, credentials, or proprietary manuals. For a suspected security issue, use a private GitHub security report if the repository enables that feature; otherwise contact the maintainer through the repository profile before disclosing details publicly.
Release v0.7.0 is documented in docs/release-notes-0.7.0.md, with its machine-readable capability and UAT dispositions in data/release-metadata.json. Before publishing, maintainers run the remote-state, CI, clean-install, private-data, and retired-repository checks in docs/release-checklist.md. A green CI run does not imply live vendor UI beyond an explicitly recorded UAT disposition, native-log parity, or hardware UAT.
Current and future MoTeC MCP project material is governed by the Herbertmt978 proprietary licence: Copyright © 2026 Herbertmt978. All rights reserved. Use and modification are permitted only by Herbertmt978 and people explicitly authorized in writing. Redistribution is prohibited.
This change applies prospectively from the repository revision that introduces the notice. Already-published v0.3.0 and v0.4.0 copies remain under their historical MIT terms; this change does not revoke or rewrite those grants. Public repository visibility does not grant permission to use, modify, or redistribute proprietary revisions.
MoTeC, AiM, Race Studio, and product names mentioned here are their respective owners' trademarks. This independent project is not endorsed by or affiliated with MoTeC or AiM.