shinro-python-modulesCAUTION
Shinro Python Control Modules
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
[](https://shinro-xyz.github.io/shinro-python-modules/)
A clean, modular Python control framework built on five abstract base classes — Controller, Plant, StateEstimator, TrajectoryGenerator, and PhysicsEngine — with registry-based factories that compose them from TOML config. The architecture is robot-agnostic: the demos drive a generic control loop over any registered plant, controller, estimator, and trajectory.
Naming note: this repo was previously scoped for a single reference robot. It was renamed to shinro-python-modules because the registry/factory/ABC pattern generalized beyond one robot.Documentation
Conceptual and operational documentation lives in docs.shinro.xyz:
- [Control Architecture](https://docs.shinro.xyz/control-architecture/) — why the five ABCs exist, how they compose, sim/hardware parity
- [Python Modules](https://docs.shinro.xyz/python-modules/) — the operational guide: install, run, extend, component catalog
API Reference — Every exported symbol — the five ABCs, controllers, estimators, plants, trajectories, factories, utilities — with signatures, parameter tables and source links. Generated from the package's own __all__ on every push, so it cannot go stale.
The same guides live in-repo under docs/ (no internet required):
- `docs/quickstart.md` — install → build a controller from TOML → run a scenario → trace/lower. Start here.
- `docs/how-it-works.md` — the five ABCs, the dataflow, and each layer (factories, sim, backends, codegen, MCP).
- `docs/components.md` — catalog of every registered component (class, registered name, file, config).
- `docs/codegen.md` — tracing →
bfbf07737e73OBSERVED · 2026-10-11Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control.
claude mcp add shinro -- uvx shinro
{
"mcpServers": {
"shinro": {
"command": "uvx",
"args": [
"shinro"
]
}
}
}Exposed tools (25)
16 read · 7 write · 2 destructive. Blast radius: 2 tools can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.
| Tool | Risk | Description |
|---|---|---|
analyze_controllability | read | Check controllability of a state-space system via Kalman rank test. |
analyze_observability | read | Check observability of a state-space system via Kalman rank test. |
balanced_truncation | write | Perform balanced truncation to obtain an order-r reduced model. |
controller_compute | read | Compute a control action from a named controller. |
controller_reset | destructive | Reset a named controller |
create_controller | write | Create a controller from a TOML config file or inline parameters. |
create_estimator | write | Create a state estimator from a TOML config file or inline parameters. |
create_trajectory | write | Create a trajectory generator from a TOML config file or inline parameters. |
estimator_estimate | write | Run one predict-update cycle of a named estimator. |
estimator_reset | destructive | Reset a named estimator |
get_mpc_constraints | read | Get the current constraints of a stored MPC controller. |
gramian_continuous | read | Compute infinite-horizon continuous-time Gramians and Hankel singular values. |
gramian_discrete | read | Compute infinite-horizon discrete-time Gramians and Hankel singular values. |
gramian_finite | read | Compute finite-horizon Gramians via ODE integration. |
list_controller_types | read | List all registered controller types available for creation. |
list_controllers | read | List all created controller instances. |
list_estimator_types | read | List all registered estimator types available for creation. |
list_estimators | read | List all created estimator instances. |
list_trajectories | read | List all created trajectory instances. |
list_trajectory_types | read | List all registered trajectory types available for creation. |
set_mpc_constraints | write | Set or update linear constraints on a stored MPC controller. |
set_pid_output_limits | write | Set output clamping limits on a stored PID controller. |
system_summary | read | Produce a human-readable summary of system properties. |
trajectory_generate | read | Generate a trajectory by computing polynomial coefficients. |
trajectory_position_at | read | Evaluate a generated trajectory at time t. |
Trust audit
CAUTIONgrade C · trust 78/100 Install with care. The audit found things worth knowing before you trust its output.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | WARN |
| L1 | Static analysis of the code | WARN |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | WARN |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (3 observation(s))
- Network
- none-observed
- Shell
- declared (3 observation(s))
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (15)
graph_data_consts.bin
mod = importlib.import_module(modname)
importlib.import_module(f"shinro.physics_engine.{engine_type}")importlib.import_module(name)
controller_reset, estimator_reset
drone_gru_weights.bin
go2_weights.bin
toy_lstm_weights.bin
toy_lstm.onnx
.pi-lens.json
- `make docs-serve` — regenerate reference + serve at <http://127.0.0.1:8000>.
mkdocs serve # preview at http://127.0.0.1:8000
return [float.fromhex(tok.strip()) for tok in m.group(1).split(",") if tok.strip()]fromhex( ... subprocess.
pyrefly, ruff, build, setuptools, setuptools-scm, onnx
Gates applied: no_behavioural_pass.
bfbf07737e73full audit observations/trust-audit/mcp-server/shinro-xyz__shinro-python-modules.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-11 | bfbf07737e73 | CAUTION | C | 78 | first audit |
Questions
What is the shinro-python-modules MCP server?
Shinro Python Control Modules
What tools does shinro-python-modules expose?
25 in total: 16 read-only, 7 that write, and 2 that can delete or overwrite (controller_reset, estimator_reset). Every one is listed on this page with its risk.
Is shinro-python-modules safe to connect to an agent?
With care. The audit graded it C (78/100) and found 15 things worth knowing before you trust this server, listed below with the exact line each was found on. Separately from the audit: 2 of its tools can destroy data, so scope the token you give it to what you actually need.
What credentials does shinro-python-modules need?
No credential environment variables were found in its source, so it appears to need none.
How does shinro-python-modules run?
It speaks stdio, so it runs as a local process your client starts. It is published on PyPI as shinro.
How current is this page?
The grade is for one exact copy of the source (bfbf07737e73), read on 2026-10-11. The repository is watched and re-audited when it changes.