poselab-mcp 0.1.0__tar.gz

poselab_mcp-0.1.0/.gitignore

@@ -0,0 +1,220 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# uv
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs/Zensical documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore that
+#   can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, you
+#   could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

poselab_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.

poselab_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.5
+Name: poselab-mcp
+Version: 0.1.0
+Summary: An MCP server of measured spatial answers for posing first-person arms and a rifle in Blender: clipping depth, what the eye sees, and a solver that says which goals no move can meet.
+Project-URL: Homepage, https://github.com/hpdkhoa/poselab-mcp
+Project-URL: Issues, https://github.com/hpdkhoa/poselab-mcp/issues
+Author: Khoa Hoang
+License-Expression: MIT
+License-File: LICENSE
+Keywords: animation,blender,first-person,game-development,mcp,spatial-reasoning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Requires-Python: >=3.10
+Requires-Dist: mcp<3,>=2.0
+Requires-Dist: pillow>=10
+Description-Content-Type: text/markdown
+
+# Pose Lab
+
+<!-- mcp-name: io.github.hpdkhoa/poselab-mcp -->
+
+**Measured spatial answers for posing first-person arms and a rifle in Blender, over MCP.**
+
+![The built-in sample rig: four Blender views of first-person arms holding a rifle](https://raw.githubusercontent.com/hpdkhoa/poselab-mcp/main/docs/sample-rig.png)
+
+Models are weak at judging 3D space from pictures: which side of a rifle faces the eye, whether a finger sits inside
+the receiver, whether any turn of the gun can ever show its ejection port. Pose Lab gives a model numbers instead. It reports positions in named frames and how deep anything clips. It
+measures how squarely a surface faces the eye and what the eye can see. Its solver searches rifle moves against goals
+and reports which goals no move can meet.
+
+I built it while hand-making chamber checks for my first-person shooter. One question took me several full Blender
+runs: can turning the rifle show its ejection port to the eye? With Pose Lab it is one `solve` call. On my game's AK
+rig, turning alone met the goal in 0 of 60 samples. That is a fact of the geometry: the eye looks along the barrel.
+Turning and moving the rifle met every goal in about 20 s. The built-in sample rig shows the same result: 0 of 60
+samples for turning alone, and every goal met in 9 s for turning and moving.
+
+## What it gives a model
+
+| Tool | Answers |
+|---|---|
+| `list_rigs`, `load_rig`, `describe` | the rigs, the frames, the sign rules, named points, clips, moving parts |
+| `pose_idle`, `pose_clip`, `move_part`, `snapshot` | put the rig in a pose: a clip at a time, the carrier drawn back, saved poses |
+| `move_gun` | roll, swing, pitch and move the rifle; the hands keep their hold by arm IK |
+| `reach` | a wrist onto a point by arm IK (try elbow poles to clear a forearm) |
+| `where`, `distance` | positions in a named frame |
+| `clearance` | how deep the rifle sits inside a forearm, palm or finger, and where |
+| `faces_eye`, `visible`, `screen` | how squarely a surface faces the eye, how much of it the eye sees, where it falls on screen |
+| `solve` | searches rifle moves against goals; reports each goal and how often any sample met it |
+| `render` | a contact sheet: the player's eye and outside views, each tile labelled as a Blender view |
+
+### Frames and signs
+
+Every position goes in and comes out in a named frame, so no one has to guess axes:
+
+* `gun`: the gun bone as it stands, Unreal-style axes, cm: +X the gun's left, +Y along the barrel, +Z up (the default)
+* `arms`: the arms' space, Unreal-style axes, cm
+* `view`: from the eye, cm: +X right, +Y forward, +Z up
+
+Turns use the player's words: `roll` + turns the gun's right side up, `swing` + takes the muzzle left, `pitch` + the
+muzzle up. Moves (`right`, `forward`, `up`) are in the view.
+
+A hand round its grip touches the rifle on the idle pose already (a finger on the trigger, fingers round the
+handguard). Call `clearance` at `pose_idle` for that baseline, and leave those segments out with `ignore` wildcards.
+
+## Install
+
+You need [Blender](https://www.blender.org/download/) and Python 3.10 or newer. I tested it on Windows 10 with
+Blender 5.2.2 and Python 3.14. I have not tested macOS, Linux or older Blender versions yet.
+
+```
+uvx poselab-mcp
+```
+
+or `pip install poselab-mcp` and run `poselab-mcp`.
+
+Add it to Claude Code:
+
+```
+claude mcp add poselab -- uvx poselab-mcp
+```
+
+or to any MCP client's configuration:
+
+```json
+{
+  "mcpServers": {
+    "poselab": {
+      "command": "uvx",
+      "args": ["poselab-mcp"],
+      "env": { "POSELAB_BLENDER": "C:/Program Files/Blender Foundation/Blender 5.2/blender.exe" }
+    }
+  }
+}
+```
+
+### Settings
+
+| Variable | Meaning |
+|---|---|
+| `POSELAB_BLENDER` | Blender's executable, if it is not on the PATH or in the usual install folder |
+| `POSELAB_RIGS` | a `rigs.json` describing your own rigs (see `examples/rigs.example.json`) |
+| `POSELAB_OUT` | the only folder Pose Lab writes to (renders, the worker's log); default `~/.poselab` |
+
+## Rigs
+
+**The built-in sample** (`load_rig {"rig": "sample"}`) needs no files. Pose Lab builds it in Blender from code: two
+arms with Unreal mannequin bone names hold an AR-style rifle with a charging handle that slides back.
+
+**Your own rigs** come from FBX files: the arms mesh, an idle pose, the rifle, and clips. Describe them in a
+`rigs.json` (copy `examples/rigs.example.json`) and point `POSELAB_RIGS` at it. Clips can be FBX animations on the same
+skeleton, or `<clip>.pose.json` bone data: `{"fps": 30, "frames": [{"bone": [[x, y, z], [w, x, y, z]], ...}, ...]}`,
+local location and rotation per bone on the idle armature. (Blender misreads an FBX animation it exported itself when
+it imports it again; bone data avoids that. `describe` reports each FBX clip's skeleton fit.)
+
+## Safety
+
+* Pose Lab only reads your rig files. It writes nothing but renders and its log, and only inside `POSELAB_OUT`.
+* The Blender worker listens on 127.0.0.1 only, on a free port, and answers only requests that carry the session's
+  random token. It runs only Pose Lab's own commands.
+
+## How it works
+
+* `poselab_mcp/server.py`: the MCP server (the official Python SDK, stdio).
+* `poselab_mcp/worker_client.py`: starts one headless Blender on the first call and keeps the rig loaded.
+* `poselab_mcp/blender/lab.py`: inside Blender: the rig, the frames, the measures, the IK, the solver, the renders.
+* `poselab_mcp/blender/sample.py`: the built-in sample rig.
+
+## Test
+
+```
+python examples/selftest.py
+```
+
+It starts the server as an MCP client does and loads the sample rig. Then it replays the question above: turning
+alone never shows the port, and turning and moving does. The contact sheet lands in `~/.poselab/renders/sheet.png`.
+
+## License
+
+MIT

poselab_mcp-0.1.0/PUBLISHING.md

@@ -0,0 +1,53 @@
+# Publishing Pose Lab
+
+The order matters. The MCP Registry accepts the listing only after the PyPI package is live. It also checks that the
+README on PyPI carries `mcp-name: io.github.hpdkhoa/poselab-mcp`. README.md holds that line as an HTML comment.
+
+## 1. GitHub
+
+The GitHub repo already holds a first commit (its `.gitignore` and `LICENSE`). Build on it:
+
+    git init -b main
+    git remote add origin https://github.com/hpdkhoa/poselab-mcp.git
+    git fetch origin
+    git reset origin/main
+    git add .
+    git commit -F <message file>
+    git push -u origin main
+
+`git reset origin/main` points the new branch at GitHub's commit and keeps every file here as it is.
+
+## 2. PyPI
+
+Make a PyPI account and an API token (pypi.org, Account settings, API tokens). Then, with uv:
+
+    uv build
+    uv publish --token <your PyPI token>
+
+or with pip tools:
+
+    python -m pip install build twine
+    python -m build
+    python -m twine upload dist/*
+
+Check it: `uvx poselab-mcp` starts the server (it waits for a client on stdin; Ctrl+C to stop).
+
+## 3. The MCP Registry
+
+Install the publisher (one of):
+
+    npm install -g mcp-publisher
+    # or download mcp-publisher from https://github.com/modelcontextprotocol/registry/releases
+
+Then, in this folder (server.json is here):
+
+    mcp-publisher login github
+    mcp-publisher publish
+
+`login github` proves you own the io.github.hpdkhoa namespace. Search for it afterwards:
+https://registry.modelcontextprotocol.io/v0/servers?search=poselab
+
+## Each release
+
+Raise the version in three places: `pyproject.toml`, `src/poselab_mcp/__init__.py`, and `server.json` (both
+`version` fields). Build and upload to PyPI first, then `mcp-publisher publish`.

poselab_mcp-0.1.0/README.md

@@ -0,0 +1,122 @@
+# Pose Lab
+
+<!-- mcp-name: io.github.hpdkhoa/poselab-mcp -->
+
+**Measured spatial answers for posing first-person arms and a rifle in Blender, over MCP.**
+
+![The built-in sample rig: four Blender views of first-person arms holding a rifle](https://raw.githubusercontent.com/hpdkhoa/poselab-mcp/main/docs/sample-rig.png)
+
+Models are weak at judging 3D space from pictures: which side of a rifle faces the eye, whether a finger sits inside
+the receiver, whether any turn of the gun can ever show its ejection port. Pose Lab gives a model numbers instead. It reports positions in named frames and how deep anything clips. It
+measures how squarely a surface faces the eye and what the eye can see. Its solver searches rifle moves against goals
+and reports which goals no move can meet.
+
+I built it while hand-making chamber checks for my first-person shooter. One question took me several full Blender
+runs: can turning the rifle show its ejection port to the eye? With Pose Lab it is one `solve` call. On my game's AK
+rig, turning alone met the goal in 0 of 60 samples. That is a fact of the geometry: the eye looks along the barrel.
+Turning and moving the rifle met every goal in about 20 s. The built-in sample rig shows the same result: 0 of 60
+samples for turning alone, and every goal met in 9 s for turning and moving.
+
+## What it gives a model
+
+| Tool | Answers |
+|---|---|
+| `list_rigs`, `load_rig`, `describe` | the rigs, the frames, the sign rules, named points, clips, moving parts |
+| `pose_idle`, `pose_clip`, `move_part`, `snapshot` | put the rig in a pose: a clip at a time, the carrier drawn back, saved poses |
+| `move_gun` | roll, swing, pitch and move the rifle; the hands keep their hold by arm IK |
+| `reach` | a wrist onto a point by arm IK (try elbow poles to clear a forearm) |
+| `where`, `distance` | positions in a named frame |
+| `clearance` | how deep the rifle sits inside a forearm, palm or finger, and where |
+| `faces_eye`, `visible`, `screen` | how squarely a surface faces the eye, how much of it the eye sees, where it falls on screen |
+| `solve` | searches rifle moves against goals; reports each goal and how often any sample met it |
+| `render` | a contact sheet: the player's eye and outside views, each tile labelled as a Blender view |
+
+### Frames and signs
+
+Every position goes in and comes out in a named frame, so no one has to guess axes:
+
+* `gun`: the gun bone as it stands, Unreal-style axes, cm: +X the gun's left, +Y along the barrel, +Z up (the default)
+* `arms`: the arms' space, Unreal-style axes, cm
+* `view`: from the eye, cm: +X right, +Y forward, +Z up
+
+Turns use the player's words: `roll` + turns the gun's right side up, `swing` + takes the muzzle left, `pitch` + the
+muzzle up. Moves (`right`, `forward`, `up`) are in the view.
+
+A hand round its grip touches the rifle on the idle pose already (a finger on the trigger, fingers round the
+handguard). Call `clearance` at `pose_idle` for that baseline, and leave those segments out with `ignore` wildcards.
+
+## Install
+
+You need [Blender](https://www.blender.org/download/) and Python 3.10 or newer. I tested it on Windows 10 with
+Blender 5.2.2 and Python 3.14. I have not tested macOS, Linux or older Blender versions yet.
+
+```
+uvx poselab-mcp
+```
+
+or `pip install poselab-mcp` and run `poselab-mcp`.
+
+Add it to Claude Code:
+
+```
+claude mcp add poselab -- uvx poselab-mcp
+```
+
+or to any MCP client's configuration:
+
+```json
+{
+  "mcpServers": {
+    "poselab": {
+      "command": "uvx",
+      "args": ["poselab-mcp"],
+      "env": { "POSELAB_BLENDER": "C:/Program Files/Blender Foundation/Blender 5.2/blender.exe" }
+    }
+  }
+}
+```
+
+### Settings
+
+| Variable | Meaning |
+|---|---|
+| `POSELAB_BLENDER` | Blender's executable, if it is not on the PATH or in the usual install folder |
+| `POSELAB_RIGS` | a `rigs.json` describing your own rigs (see `examples/rigs.example.json`) |
+| `POSELAB_OUT` | the only folder Pose Lab writes to (renders, the worker's log); default `~/.poselab` |
+
+## Rigs
+
+**The built-in sample** (`load_rig {"rig": "sample"}`) needs no files. Pose Lab builds it in Blender from code: two
+arms with Unreal mannequin bone names hold an AR-style rifle with a charging handle that slides back.
+
+**Your own rigs** come from FBX files: the arms mesh, an idle pose, the rifle, and clips. Describe them in a
+`rigs.json` (copy `examples/rigs.example.json`) and point `POSELAB_RIGS` at it. Clips can be FBX animations on the same
+skeleton, or `<clip>.pose.json` bone data: `{"fps": 30, "frames": [{"bone": [[x, y, z], [w, x, y, z]], ...}, ...]}`,
+local location and rotation per bone on the idle armature. (Blender misreads an FBX animation it exported itself when
+it imports it again; bone data avoids that. `describe` reports each FBX clip's skeleton fit.)
+
+## Safety
+
+* Pose Lab only reads your rig files. It writes nothing but renders and its log, and only inside `POSELAB_OUT`.
+* The Blender worker listens on 127.0.0.1 only, on a free port, and answers only requests that carry the session's
+  random token. It runs only Pose Lab's own commands.
+
+## How it works
+
+* `poselab_mcp/server.py`: the MCP server (the official Python SDK, stdio).
+* `poselab_mcp/worker_client.py`: starts one headless Blender on the first call and keeps the rig loaded.
+* `poselab_mcp/blender/lab.py`: inside Blender: the rig, the frames, the measures, the IK, the solver, the renders.
+* `poselab_mcp/blender/sample.py`: the built-in sample rig.
+
+## Test
+
+```
+python examples/selftest.py
+```
+
+It starts the server as an MCP client does and loads the sample rig. Then it replays the question above: turning
+alone never shows the port, and turning and moving does. The contact sheet lands in `~/.poselab/renders/sheet.png`.
+
+## License
+
+MIT

poselab_mcp-0.1.0/examples/rigs.example.json

@@ -0,0 +1,39 @@
+{
+  "_about": "Your own rigs for Pose Lab: point POSELAB_RIGS at a file like this one. Folders are relative to this file. Points and normals are in the gun frame: the gun bone at the idle pose, Unreal-style axes, cm (+X the gun's left, +Y forward along the barrel, +Z up). The eye is in the arms' space, cm. Bone names default to the Unreal mannequin's; rename any under bones.",
+  "my_rifle": {
+    "title": "My rifle on my first-person arms",
+    "folder": "my_rifle",
+    "arms": "Arms.fbx",
+    "idle": "Arms_Idle.fbx",
+    "gun": "Rifle.fbx",
+    "gun_offset": [0.0, 0.0, 0.0],
+    "eye": [0.0, -2.3, 162.6],
+    "clips": {
+      "reload": "A_Reload.fbx",
+      "check": "A_ChamberCheck.pose.json"
+    },
+    "parts": {
+      "carrier": ["Bolt", "ChargingHandle"]
+    },
+    "points": {
+      "port": [-1.6, 2.0, 3.8],
+      "bore": [0.0, 0.0, 3.0],
+      "stock": [0.0, -25.0, 0.0],
+      "muzzle": [0.0, 48.0, 3.0]
+    },
+    "normals": {
+      "port": [-1.0, 0.0, 0.0]
+    },
+    "poles": {
+      "l": [45.0, -20.0, 95.0],
+      "r": [-45.0, -20.0, 95.0]
+    },
+    "bones": {
+      "gun": "ik_hand_gun",
+      "upperarm": "upperarm_{s}",
+      "lowerarm": "lowerarm_{s}",
+      "hand": "hand_{s}",
+      "finger": "{f}_{j}_{s}"
+    }
+  }
+}

poselab_mcp-0.1.0/examples/selftest.py

@@ -0,0 +1,80 @@
+"""Pose Lab's end-to-end test: starts the server as an MCP client would (stdio), loads the sample rig, measures the
+port on the rifle's right side from the eye, asks the solver whether turning alone can show it, then whether turning
+and moving can, and saves a contact sheet.
+
+    python examples/selftest.py            (needs Blender; see the README)
+"""
+import json
+import subprocess
+import sys
+import time
+
+
+class Client:
+    def __init__(self):
+        self.p = subprocess.Popen([sys.executable, "-m", "poselab_mcp"], stdin=subprocess.PIPE, stdout=subprocess.PIPE)
+        self.n = 0
+
+    def send(self, msg):
+        self.p.stdin.write((json.dumps(msg) + "\n").encode())
+        self.p.stdin.flush()
+
+    def rpc(self, method, params=None):
+        self.n += 1
+        self.send({"jsonrpc": "2.0", "id": self.n, "method": method, "params": params or {}})
+        while True:
+            reply = json.loads(self.p.stdout.readline())
+            if reply.get("id") == self.n:
+                return reply
+
+    def tool(self, _tool, **args):
+        t = time.time()
+        r = self.rpc("tools/call", {"name": _tool, "arguments": args})["result"]
+        texts = [c["text"] for c in r["content"] if c["type"] == "text"]
+        images = [c for c in r["content"] if c["type"] == "image"]
+        print("--- %s (%.1f s)%s%s" % (_tool, time.time() - t, " ERROR" if r.get("isError") else "", " + image" if images else ""))
+        print((texts[0] if texts else "")[:1500])
+        if r.get("isError"):
+            raise SystemExit(1)
+        data = r.get("structuredContent")
+        if isinstance(data, dict) and set(data) == {"result"}:
+            data = data["result"]
+        if data is None and texts:
+            try:
+                data = json.loads(texts[0])
+            except ValueError:
+                data = texts[0]
+        return data
+
+
+def main():
+    c = Client()
+    init = c.rpc("initialize", {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "selftest", "version": "0"}})
+    print("server:", init["result"]["serverInfo"])
+    c.send({"jsonrpc": "2.0", "method": "notifications/initialized"})
+    print("tools:", [t["name"] for t in c.rpc("tools/list")["result"]["tools"]])
+    c.tool("list_rigs")
+    c.tool("load_rig", rig="sample")
+    c.tool("clearance", parts="both")          # the baseline: what the hands touch on the idle grip
+    c.tool("move_part", part="carrier", cm=4.0)
+    c.tool("faces_eye", point="port")
+    c.tool("visible", point="port")
+    c.tool("screen", point="port")
+    c.tool("snapshot", action="save", name="start")
+    grip = ["index*", "middle*", "ring*", "pinky*", "thumb*", "palm*"]   # the hands keep their grips
+    goals = [{"type": "faces_eye", "point": "port", "min": 0.5},
+             {"type": "clearance", "parts": "both", "ignore": grip, "max_cm": 0.0},
+             {"type": "visible", "point": "port", "min": 0.6},
+             {"type": "on_screen", "point": "port"}]
+    # turning alone: the eye looks along the barrel, so no turn of the rifle about the shoulder shows the port
+    c.tool("solve", dofs={"roll": [-90, 90], "swing": [-40, 40]}, goals=goals, samples=60)
+    c.tool("snapshot", action="load", name="start")
+    # turning and moving: lowered and brought across in front of the face
+    c.tool("solve", dofs={"roll": [-30, 90], "swing": [-40, 40], "right": [-25, 10], "up": [-30, 5]}, goals=goals, samples=200, maximize=0)
+    c.tool("render", views=["eye", "right", "top", "front"])
+    c.p.stdin.close()
+    c.p.wait(timeout=60)
+
+
+if __name__ == "__main__":
+    main()