feellab-mcp 0.1.0__tar.gz

feellab_mcp-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+dist/
+.venv/

feellab_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.0
+
+The first release, built for ToangTown (2026-10-15).
+
+* **The checklist:** 82 interactions of a first-person shooter in ten groups (shooting, hitting, getting hit,
+  movement, the world, enemies, explosions, the sound mix, the screen, smoothness), each with what the player should
+  get; 23 measured from a timeline, the rest left for a person with what to look for.
+* **The timeline contract** (`feellab-timeline/1`, docs/TIMELINE.md): the camera every frame and every event (input,
+  shot, sound, effect, decal, impact, marker, damage dealt and taken, camera, screen, debug) with its time.
+* **26 metrics** over 11 standard scenes: latency, sound-to-picture sync, kick and its recovery, shake and its fall
+  with distance, presence of every answer, footstep cadence, head bob, frame hitches. Each rule names its source or
+  is marked an estimate.
+* **Verdicts, a report and gate rows** in Weapon Lab's row format.
+* **An example:** timelines of two made-up games, one with every answer and one bare prototype.

feellab_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Khoa Hoang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

feellab_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.5
+Name: feellab-mcp
+Version: 0.1.0
+Summary: An MCP server that checks how a first-person shooter feels: an 82-item checklist of every interaction, a timeline contract any game's probe can write, and measures of latency, kick, shake, presence and smoothness.
+Project-URL: Homepage, https://github.com/hpdkhoa/feellab-mcp
+Project-URL: Issues, https://github.com/hpdkhoa/feellab-mcp/issues
+Author: Khoa Hoang
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fps,game-development,game-feel,juice,mcp,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: mcp<3,>=2.0
+Description-Content-Type: text/markdown
+
+<h1 align="center">Feel Lab</h1>
+
+<!-- mcp-name: io.github.hpdkhoa/feellab-mcp -->
+
+<p align="center"><strong>An FPS feel checklist, measured: every interaction a player has, checked from what the game really did.</strong></p>
+
+<p align="center">
+  <a href="LICENSE"><img alt="license: MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>
+  <a href="pyproject.toml"><img alt="Python 3.10+" src="https://img.shields.io/badge/Python-3.10%2B-3776ab?logo=python&logoColor=white"></a>
+  <a href="https://pypi.org/project/feellab-mcp/"><img alt="PyPI: feellab-mcp" src="https://img.shields.io/pypi/v/feellab-mcp?label=PyPI&logo=pypi&logoColor=white&color=3775a9"></a>
+  <a href="https://registry.modelcontextprotocol.io/v0/servers?search=feellab-mcp"><img alt="MCP Registry: feellab-mcp" src="https://img.shields.io/badge/MCP%20Registry-feellab--mcp-6f42c1"></a>
+  <a href="#the-checklist"><img alt="checklist: 82 interactions" src="https://img.shields.io/badge/checklist-82%20interactions-orange"></a>
+  <a href="#tools"><img alt="tools: 6" src="https://img.shields.io/badge/tools-6-orange"></a>
+  <a href="docs/TIMELINE.md"><img alt="timeline contract: v1" src="https://img.shields.io/badge/timeline%20contract-v1-orange"></a>
+</p>
+
+Game feel is what a player feels between pressing a key and seeing the world answer. A shot should flash, sound and
+kick on the same frame; a round striking a wall should throw dust, make a sound and leave a hole; a hit taken should
+jerk the view and show where it came from; a blast nearby should shake the screen more than one far away. When one
+answer is missing or late, the game feels floaty or cheap, and nobody can say why.
+
+Feel Lab turns that into checks. Your game's probe plays standard scenes and writes a **timeline**: the camera every
+frame, and every sound, effect, mark and damage event with its time. Feel Lab measures latency, kick, shake,
+presence, match and smoothness from it, and judges each item of an 82-item checklist. It never runs your game: any
+engine can write the timeline ([docs/TIMELINE.md](docs/TIMELINE.md)).
+
+## The checklist
+
+| Group | Items | Measured from a timeline |
+|---|---|---|
+| A. Shooting (your own gun) | 19 | 9 |
+| B. Hitting (your bullets land) | 15 | 6 |
+| C. Getting hit (damage taken) | 9 | 4 |
+| D. Movement and the body | 11 | 2 |
+| E. Interacting with the world | 7 | 0 |
+| F. Enemies (zombies) | 5 | 0 |
+| G. Explosions, fire and the world | 5 | 1 |
+| H. Sound mix | 4 | 0 |
+| I. Screen and comfort | 4 | 0 |
+| J. Smoothness (feel breaks when the frame does) | 3 | 1 |
+
+Items no timeline can show (a colour-blind option, a reload cancel's timing) are left for a person, with what to
+look for. `feellab checklist` prints them all.
+
+## What it measures
+
+| Measure | Example |
+|---|---|
+| Latency | the shot's flash and sound on the shot's frame; the hit marker within 50 ms of the hit |
+| Sync | the shot's sound within 45 ms of its flash (ITU-R BT.1359) |
+| Kick | the camera turns at least 0.3 degrees on a burst and settles within 0.6 s |
+| Shake | a blast 5 m away shakes the view; one 50 m away at least 3 times less |
+| Presence | every impact has an effect, a sound and a mark; every round fired ejects a case |
+| Rhythm | footsteps at walking cadence (about 100 steps a minute and up); the head bobs |
+| Smoothness | no frame twice the median length round a shot or a blast |
+
+Every rule names its source. A range from game practice rather than evidence is marked as an estimate.
+
+## Try it
+
+```bash
+pip install feellab-mcp
+feellab demo demo
+feellab judge demo
+```
+
+The demo writes timelines for two made-up games: "Juicy" passes every measured item; "Bare" (a debug dot where a
+round lands, no shake, silent steps) fails 17.
+
+## Use it in your game
+
+1. Have your probe play the scenes in `src/feellab/data/scenes.json` and write one timeline each
+   ([docs/TIMELINE.md](docs/TIMELINE.md)). Wrap the calls that start sounds and effects so each is recorded with its
+   time; note the moments with no sound or effect of their own (a shot, an impact, a hit marker, damage, a flinch).
+2. Record a camera frame before the scene's cause (a shot, a hit, a blast): kick and flinch are measured from it.
+3. Tag what you can (`"tags": ["muzzle"]`). Where your asset names do not say what a sound or effect is for, put a
+   `feel_rules.json` beside the timelines: `{"dry": "slidelock"}` tells Feel Lab that a sound named after a slide lock
+   is the click of an empty gun.
+4. `feellab judge <folder>`, or `gate_rows` for a gate.
+
+The first game to use it (ToangTown) found 52 failing cases on four guns: a debug dot where a round lands, no shake
+anywhere, no blood, no footsteps, a climb that never comes back, a stall on the first shot.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `list_checklist` | The checklist by group: what the player should get, measured or for a person. |
+| `list_scenes` | The standard scenes a probe plays. |
+| `list_metrics` | Every metric: scene, unit, rule and source. |
+| `check_timeline` | A timeline file against the contract. |
+| `judge_folder` | A folder of timelines judged: each item's values and verdict, and a Markdown report. |
+| `gate_rows` | The metrics as rows for a gate (Weapon Lab's row format). |
+
+```json
+{"mcpServers": {"feellab": {"command": "feellab-mcp"}}}
+```
+
+`FEELLAB_OUT` is the only folder Feel Lab writes to (its reports); `~/.feellab` by default.
+
+## Where it came from
+
+Feel Lab was built for ToangTown, an Unreal 5.8 co-op zombie FPS, next to Weapon Lab
+([weaponlab-mcp](https://github.com/hpdkhoa/weaponlab-mcp)), whose Gate can judge Feel Lab's rows as cases.
+
+## License
+
+MIT

feellab_mcp-0.1.0/PUBLISHING.md

@@ -0,0 +1,18 @@
+# Publishing Feel Lab
+
+The MCP Registry accepts the listing only after the PyPI package is live, and checks that the README on PyPI carries
+`mcp-name: io.github.hpdkhoa/feellab-mcp` (README.md holds it as an HTML comment).
+
+1. **GitHub:** push `main` to https://github.com/hpdkhoa/feellab-mcp and tag the release (`git tag v0.1.0`,
+   `git push --tags`).
+2. **PyPI**, with your token from your password manager (never in a file):
+
+       python -m pip install build twine
+       python -m build
+       python -m twine check dist/*
+       python -m twine upload dist/*
+
+3. **The MCP Registry**, in this folder: `mcp-publisher login github`, then `mcp-publisher publish`.
+
+Each release: `python -m pytest tests` (set nothing else needed), raise the
+version in `pyproject.toml`, `src/feellab/__init__.py` and `server.json` (both fields), add it to CHANGELOG.md.

feellab_mcp-0.1.0/README.md

@@ -0,0 +1,108 @@
+<h1 align="center">Feel Lab</h1>
+
+<!-- mcp-name: io.github.hpdkhoa/feellab-mcp -->
+
+<p align="center"><strong>An FPS feel checklist, measured: every interaction a player has, checked from what the game really did.</strong></p>
+
+<p align="center">
+  <a href="LICENSE"><img alt="license: MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>
+  <a href="pyproject.toml"><img alt="Python 3.10+" src="https://img.shields.io/badge/Python-3.10%2B-3776ab?logo=python&logoColor=white"></a>
+  <a href="https://pypi.org/project/feellab-mcp/"><img alt="PyPI: feellab-mcp" src="https://img.shields.io/pypi/v/feellab-mcp?label=PyPI&logo=pypi&logoColor=white&color=3775a9"></a>
+  <a href="https://registry.modelcontextprotocol.io/v0/servers?search=feellab-mcp"><img alt="MCP Registry: feellab-mcp" src="https://img.shields.io/badge/MCP%20Registry-feellab--mcp-6f42c1"></a>
+  <a href="#the-checklist"><img alt="checklist: 82 interactions" src="https://img.shields.io/badge/checklist-82%20interactions-orange"></a>
+  <a href="#tools"><img alt="tools: 6" src="https://img.shields.io/badge/tools-6-orange"></a>
+  <a href="docs/TIMELINE.md"><img alt="timeline contract: v1" src="https://img.shields.io/badge/timeline%20contract-v1-orange"></a>
+</p>
+
+Game feel is what a player feels between pressing a key and seeing the world answer. A shot should flash, sound and
+kick on the same frame; a round striking a wall should throw dust, make a sound and leave a hole; a hit taken should
+jerk the view and show where it came from; a blast nearby should shake the screen more than one far away. When one
+answer is missing or late, the game feels floaty or cheap, and nobody can say why.
+
+Feel Lab turns that into checks. Your game's probe plays standard scenes and writes a **timeline**: the camera every
+frame, and every sound, effect, mark and damage event with its time. Feel Lab measures latency, kick, shake,
+presence, match and smoothness from it, and judges each item of an 82-item checklist. It never runs your game: any
+engine can write the timeline ([docs/TIMELINE.md](docs/TIMELINE.md)).
+
+## The checklist
+
+| Group | Items | Measured from a timeline |
+|---|---|---|
+| A. Shooting (your own gun) | 19 | 9 |
+| B. Hitting (your bullets land) | 15 | 6 |
+| C. Getting hit (damage taken) | 9 | 4 |
+| D. Movement and the body | 11 | 2 |
+| E. Interacting with the world | 7 | 0 |
+| F. Enemies (zombies) | 5 | 0 |
+| G. Explosions, fire and the world | 5 | 1 |
+| H. Sound mix | 4 | 0 |
+| I. Screen and comfort | 4 | 0 |
+| J. Smoothness (feel breaks when the frame does) | 3 | 1 |
+
+Items no timeline can show (a colour-blind option, a reload cancel's timing) are left for a person, with what to
+look for. `feellab checklist` prints them all.
+
+## What it measures
+
+| Measure | Example |
+|---|---|
+| Latency | the shot's flash and sound on the shot's frame; the hit marker within 50 ms of the hit |
+| Sync | the shot's sound within 45 ms of its flash (ITU-R BT.1359) |
+| Kick | the camera turns at least 0.3 degrees on a burst and settles within 0.6 s |
+| Shake | a blast 5 m away shakes the view; one 50 m away at least 3 times less |
+| Presence | every impact has an effect, a sound and a mark; every round fired ejects a case |
+| Rhythm | footsteps at walking cadence (about 100 steps a minute and up); the head bobs |
+| Smoothness | no frame twice the median length round a shot or a blast |
+
+Every rule names its source. A range from game practice rather than evidence is marked as an estimate.
+
+## Try it
+
+```bash
+pip install feellab-mcp
+feellab demo demo
+feellab judge demo
+```
+
+The demo writes timelines for two made-up games: "Juicy" passes every measured item; "Bare" (a debug dot where a
+round lands, no shake, silent steps) fails 17.
+
+## Use it in your game
+
+1. Have your probe play the scenes in `src/feellab/data/scenes.json` and write one timeline each
+   ([docs/TIMELINE.md](docs/TIMELINE.md)). Wrap the calls that start sounds and effects so each is recorded with its
+   time; note the moments with no sound or effect of their own (a shot, an impact, a hit marker, damage, a flinch).
+2. Record a camera frame before the scene's cause (a shot, a hit, a blast): kick and flinch are measured from it.
+3. Tag what you can (`"tags": ["muzzle"]`). Where your asset names do not say what a sound or effect is for, put a
+   `feel_rules.json` beside the timelines: `{"dry": "slidelock"}` tells Feel Lab that a sound named after a slide lock
+   is the click of an empty gun.
+4. `feellab judge <folder>`, or `gate_rows` for a gate.
+
+The first game to use it (ToangTown) found 52 failing cases on four guns: a debug dot where a round lands, no shake
+anywhere, no blood, no footsteps, a climb that never comes back, a stall on the first shot.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `list_checklist` | The checklist by group: what the player should get, measured or for a person. |
+| `list_scenes` | The standard scenes a probe plays. |
+| `list_metrics` | Every metric: scene, unit, rule and source. |
+| `check_timeline` | A timeline file against the contract. |
+| `judge_folder` | A folder of timelines judged: each item's values and verdict, and a Markdown report. |
+| `gate_rows` | The metrics as rows for a gate (Weapon Lab's row format). |
+
+```json
+{"mcpServers": {"feellab": {"command": "feellab-mcp"}}}
+```
+
+`FEELLAB_OUT` is the only folder Feel Lab writes to (its reports); `~/.feellab` by default.
+
+## Where it came from
+
+Feel Lab was built for ToangTown, an Unreal 5.8 co-op zombie FPS, next to Weapon Lab
+([weaponlab-mcp](https://github.com/hpdkhoa/weaponlab-mcp)), whose Gate can judge Feel Lab's rows as cases.
+
+## License
+
+MIT

feellab_mcp-0.1.0/docs/TIMELINE.md

@@ -0,0 +1,30 @@
+# The timeline contract (feellab-timeline/1)
+
+measure. A timeline is one JSON file a scene:
+
+{"contract": "feellab-timeline/1",
+ "scene": "fire_wall",                    which standard scene this is (scenes.json), or the game's own name
+ "subject": "Rifle_M4",                   the weapon (or whatever the scene is about)
+ "params": {"distance_m": 5},             the scene's settings as the probe ran it
+ "frames": [{"t": 0.0, "dt": 16.6,        seconds from the scene's start; the frame's length in ms
+             "cam": [x, y, z, pitch, yaw, roll, fov]}],   the player's camera in the world (cm, degrees)
+ "events": [{"t": 0.21, "kind": "sound", "name": "sfx_wpn_ar_fire_01", "at": [x, y, z], "value": 1.0, "tags": ["shot"]}]}
+
+Event kinds (a probe reports the ones it has; Feel Lab judges what it gets):
+  input        the probe pressed something (name: fire, reload, jump, ...)
+  shot         a round left the gun (value: rounds; tags: calibre)
+  sound        a sound started (name: the asset; value: volume; tags: what it is for, when the game knows)
+  fx           a visual effect started (name: the asset; tags: muzzle, shell, impact, blood, explosion, tracer, ...)
+  decal        a mark was left on a surface (tags: the surface)
+  impact       a round met the world or a body (tags: the surface or "flesh"; value: the damage)
+  marker       a hit marker was shown (tags: hit, kill, headshot)
+  damage_dealt the player's hit landed (value: the damage; tags: headshot, kill)
+  damage_taken the player was hurt (value: the damage; at: where the hit came from)
+  camera       a camera effect started (name: shake, flinch, kick; value: its size)
+  ui           a screen effect started or changed (name: damage_indicator, blood_overlay, low_health, ...)
+  debug        something drawn for developers only (a debug point where an impact should be)
+Positions in cm, the world's axes; time in seconds from the scene's start.
+
+## Files
+
+One file a scene: `<subject>_<scene>_timeline.json`. `feellab check <file>` checks one. `src/feellab/data/scenes.json` lists the standard scenes and what each asks the probe to do.

feellab_mcp-0.1.0/examples/demo_timelines.py

@@ -0,0 +1,12 @@
+"""Writes example timelines for two made-up games (feellab.demo): python examples/demo_timelines.py <folder>"""
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+from feellab.demo import game  # noqa: E402
+
+if __name__ == "__main__":
+    out = sys.argv[1] if len(sys.argv) > 1 else "demo_timelines"
+    game(out, "Juicy", True)
+    game(out, "Bare", False)
+    print("written to", out)

feellab_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "feellab-mcp"
+version = "0.1.0"
+description = "An MCP server that checks how a first-person shooter feels: an 82-item checklist of every interaction, a timeline contract any game's probe can write, and measures of latency, kick, shake, presence and smoothness."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Khoa Hoang" }]
+requires-python = ">=3.10"
+keywords = ["mcp", "game-feel", "fps", "game-development", "testing", "juice"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Games/Entertainment",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = ["mcp>=2.0,<3"]
+
+[project.urls]
+Homepage = "https://github.com/hpdkhoa/feellab-mcp"
+Issues = "https://github.com/hpdkhoa/feellab-mcp/issues"
+
+[project.scripts]
+feellab-mcp = "feellab.server:main"
+feellab = "feellab.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/feellab"]

feellab_mcp-0.1.0/server.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.hpdkhoa/feellab-mcp",
+  "title": "Feel Lab",
+  "description": "An FPS feel checklist, measured from a timeline any game's probe can write",
+  "version": "0.1.0",
+  "repository": {
+    "url": "https://github.com/hpdkhoa/feellab-mcp",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "feellab-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "FEELLAB_OUT",
+          "description": "The only folder Feel Lab writes to (its reports); defaults to ~/.feellab",
+          "isRequired": false
+        }
+      ]
+    }
+  ]
+}

feellab_mcp-0.1.0/src/feellab/__init__.py

@@ -0,0 +1,4 @@
+"""Feel Lab: an FPS feel checklist, measured. Every interaction a player has with a first-person shooter (a shot, a
+hit, a hit taken, a step) and what they should get from it; a timeline contract any game's probe can write; measures
+of latency, kick, shake, presence, match and smoothness from it; verdicts and rows a gate can judge."""
+__version__ = "0.1.0"

feellab_mcp-0.1.0/src/feellab/__main__.py

@@ -0,0 +1,46 @@
+"""feellab <command>
+  serve                          the MCP server (also: feellab-mcp)
+  checklist [group]              the checklist
+  judge <folder> [subject]       judge a folder of timelines (prints the report)
+  check <timeline.json>          a timeline against the contract
+  demo <folder>                  example timelines of two made-up games"""
+import json
+import sys
+
+
+def main(argv=None):
+    a = list(sys.argv[1:] if argv is None else argv)
+    if not a or a[0] in ("-h", "--help"):
+        print(__doc__)
+        return 0
+    if a[0] == "serve":
+        from .server import main as serve
+        serve()
+        return 0
+    from . import evaluate as E, timeline as T
+    if a[0] == "checklist":
+        c = E.checklist()
+        for i in c["items"]:
+            if len(a) < 2 or i["group"] == a[1]:
+                print("%-4s %-8s %s: %s" % (i["id"], i["check"], i["name"], i["expect"]))
+        return 0
+    if a[0] == "judge":
+        for s, tls in E.load_folder(a[1], a[2] if len(a) > 2 else None).items():
+            print(E.report_md(s, E.judge(tls)))
+        return 0
+    if a[0] == "demo":
+        from .demo import game
+        game(a[1], "Juicy", True)
+        game(a[1], "Bare", False)
+        print("written to", a[1])
+        return 0
+    if a[0] == "check":
+        from pathlib import Path
+        bad = T.check(json.loads(Path(a[1]).read_text(encoding="utf-8-sig")))
+        print(json.dumps({"ok": not bad, "problems": bad}, indent=1))
+        return 0 if not bad else 1
+    raise SystemExit(__doc__)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

feellab_mcp-0.1.0/src/feellab/config.py

@@ -0,0 +1,12 @@
+"""Where Feel Lab keeps its data (the checklist, the scenes) and writes its reports (FEELLAB_OUT, ~/.feellab)."""
+import os
+from pathlib import Path
+
+PACKAGE = Path(__file__).resolve().parent
+DATA = PACKAGE / "data"
+
+
+def out(*parts):
+    p = Path(os.environ.get("FEELLAB_OUT") or Path.home() / ".feellab").joinpath(*parts)
+    p.mkdir(parents=True, exist_ok=True)
+    return p