English Français العربية

Weapon Lab

Official registry Games, sports and entertainment

Find and fix first-person weapon bugs behind a gate: your game's probe measures, the Gate judges

Source code Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

PYPI package weaponlab-mcp
Claude Code 
claude mcp add weapon-lab -e 'WEAPONLAB_PROJECT=<WEAPONLAB_PROJECT>' -e 'WEAPONLAB_BLENDER=<WEAPONLAB_BLENDER>' -- uvx weaponlab-mcp==0.1.0
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "weapon-lab": {
            "command": "uvx",
            "args": [
                "weaponlab-mcp==0.1.0"
            ],
            "env": {
                "WEAPONLAB_PROJECT": "<WEAPONLAB_PROJECT>",
                "WEAPONLAB_BLENDER": "<WEAPONLAB_BLENDER>"
            }
        }
    }
}

Environment variables

  • WEAPONLAB_PROJECT The project folder holding weaponlab.json; the current folder if not set
  • WEAPONLAB_BLENDER Blender's executable for Motion Lab, if it is not on the PATH or in the usual install folder

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. Weapon Lab
  2. What it does
  3. Try it on the demo
  4. Use it in your game
  5. Add it to an MCP client
  6. Requirements
  7. Where it came from
  8. License

Weapon Lab

First-person weapon bugs fixed once per kind, then for every weapon, behind a gate.

An MCP server that finds and fixes first-person weapon bugs behind a gate: hands off the gun, a magazine crooked in its well, a blade held wrong, arms covering the screen.

Each bug becomes a case: a metric, a weapon, an action and a pass rule. Your game's own probe measures the weapons. The Gate passes a change only when its target cases pass and nothing else got worse. Fix each kind of bug once, then check every weapon with it.

Weapon Lab never runs your game itself. You write a small probe for your engine that follows the probe contract: a job file in, a rows file out. Everything else works on what the probe writes back.

What it does

GroupToolsWhat for
Gategate_run, gate_verdict, gate_propose, gate_approve, gate_set_baseline, gate_cases, ...Keeps the bugs as cases, measures, compares against a baseline, judges a change, records a person's approval.
Probeprobe_run, probe_plan, probe_statusStarts your game's probe. Tries a fix before it is written: tuned fields, staged assets, screenshots, parts dumps.
Rig Labrig_pieces, rig_facts, rig_align, rig_part_line, rig_fistReads the posed weapon from a parts dump: its pieces, real-world facts (the magazine behind the barrel), a magazine's line into its well, a hilt in the fist.
Motion Labmotion_roll, motion_roll_profile, motion_roll_set, motion_track, motion_renderRebuilds clips in Blender: turns a hand about its forearm inside the forearm's range, puts a sliding part back on its axis.
Specsspec_list, spec_read, spec_validate, spec_writeOne file a weapon: marks (grip, support), anchors (pieces to find), facts, limits.
Contractcontract_checkChecks a probe's job, rows or parts dump.
Gun Kitgunkit_inspect, gunkit_draft, gunkit_from_modellab, gunkit_proxy, gunkit_rig, gunkit_build, gunkit_verify, gunkit_export, gunkit_cases, gunkit_actions, gunkit_actionTakes any gun model to the game: rigs it for one of 18 actions, makes its own clips and the hand clips on one shared pair of arms, checks them, stages the files. See docs/GUNKIT.md.
Blueprint Labblueprint_source_add, blueprint_scan, blueprint_specs, blueprint_figure_add, blueprint_calibrate, blueprint_trace, blueprint_part, blueprint_check, blueprint_build, blueprint_to_gunkit, ...Makes a real gun's visual copy from its public sources (manuals, patents, photos): facts from the data tables, outlines traced from scaled figures, a blueprint with the source of every number, the model built in Blender. See docs/BLUEPRINT.md.

Try it on the demo

The demo is a toy game with two planted bugs and a probe in about 150 lines. It needs no engine.

pip install -e .
cd examples/demo
weaponlab gate run probe,rig

(python -m weaponlab works the same when pip's scripts folder is not on your PATH.)

The rifle's left hand misses its handguard by 3.75 cm. The knife's hilt lies 90 degrees across the fist. tests/test_demo.py walks the whole loop: measure, find the fix, try it by tune, judge it.

Use it in your game

  1. weaponlab init in your project. It writes weaponlab.json and empty data files.
  2. Write your probe from the contract, starting from examples/demo/probe/demo_probe.py. Set its command in weaponlab.json.
  3. List your weapons in weaponlab/data/weapons.json and their actions in actions.json.
  4. Add a case for each bug you know. Measure everything once and set the baseline.
  5. Fix through the loop: try by tune or staging, look at the screenshots, propose, approve, import.

Check your probe on its own with weaponlab contract job|rows|parts <file>.

Add it to an MCP client

{"mcpServers": {"weaponlab": {"command": "weaponlab-mcp", "env": {"WEAPONLAB_PROJECT": "C:/path/to/your/game"}}}}
SettingMeaning
WEAPONLAB_PROJECTThe project folder with weaponlab.json. The current folder by default.
WEAPONLAB_BLENDERBlender, for Motion Lab. Found on the PATH or in the usual install folders otherwise.

Requirements

  • Python 3.10 or later.
  • Blender 4.4 or later for Motion Lab and renders. Nothing else needs it.
  • Hand bones named as Unreal's mannequin names them (hand_r, index_01_r, lowerarm_r) for the fist measure and the forearm roll.

Where it came from

Weapon Lab is the general part of the tools built for ToangTown, an Unreal 5.8 game with 46 weapons. Its first probe is ToangTown's. The contract's lessons come from that probe. Pose Lab (poselab-mcp) answers the body's side: clipping, the view, a grip solver. The Gate can use it as a provider.

License

MIT

Frequently asked questions

What is Weapon Lab?

Find and fix first-person weapon bugs behind a gate: your game's probe measures, the Gate judges

How do I install Weapon Lab?

It runs on your machine. In Claude Code: claude mcp add weapon-lab -e 'WEAPONLAB_PROJECT=<WEAPONLAB_PROJECT>' -e 'WEAPONLAB_BLENDER=<WEAPONLAB_BLENDER>' -- uvx weaponlab-mcp==0.1.0. For other clients, paste the JSON configuration from this page into their MCP settings.

Does Weapon Lab need an API key?

Its registry entry lists no required key or secret. Some features may still need an account with the service it connects to.

Is Weapon Lab open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains Weapon Lab?

It is published by hpdkhoa. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.