mirror of https://github.com/NickoScope/nickol-knx-mcp.git synced 2026-09-30 03:41:58 +02:00

Files

T

Nikolay MiroshnichenkoandClaude Opus 4.8 bba8befcde nickol-knx-mcp v0.1.0 — design-time KNX/ETS6 MCP server (public beta)

Design-time MCP server that reads .knxproj (read-only), validates naming/DPT/status,
and generates Home Assistant KNX YAML + ETS-importable group addresses (XML/CSV).
No live bus access — confined-workspace writes only.

Includes: 12 MCP tools, end-to-end smoke test, MIT license, English-first README
(+ Russian), CONTRIBUTING with a real-project test call, SECURITY policy, CHANGELOG,
GitHub Actions CI (Python 3.10–3.12), and issue/PR templates.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-28 09:25:57 +02:00

2.4 KiB

Raw Blame History

Contributing to nickol-knx-mcp

Thanks for helping! This project is in public beta, and the single most valuable contribution right now is testing against real ETS projects.

🧪 The #1 ask: test on your real `.knxproj`

The tool is read-only and never connects to a KNX bus, so running it against a production project is safe. Here is the fastest way to help:

git clone https://github.com/NickoScope/nickol-knx-mcp.git
cd nickol-knx-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
python tests/test_pipeline.py        # should pass

Then run it from Claude (Desktop or Code) and ask it to:

load_project your .knxproj (with the ETS password if it's protected),
analyze_all, and
project_report.

Open a Real-project test report issue and tell us:

ETS version (5 / 6) and roughly how many group addresses / devices,
what the report got right,
what it got wrong (false missing-status, wrong category, wrong DPT call, bad HA YAML),
any crash or stack trace.

Please do not attach your actual .knxproj (it can contain personal/topology data). A redacted snippet or a screenshot of the report is plenty. If a parse crash needs a sample, we'll coordinate a minimal redacted project privately.

🐛 Bugs & 💡 features

Use the issue templates. For bugs, include OS, Python version, the exact tool call, and the full error.

🔧 Code contributions

Keep the safety invariant: project.py is the only module allowed to read .knxproj, and it must stay read-only. No networking / bus libraries may enter the dependency tree.
Keep generators conservative: when in doubt, push an item to the review list rather than emitting a guessed entity.
Run the smoke test before opening a PR:
```
python tests/test_pipeline.py
```
Match the existing module boundaries (one responsibility per file) and naming style.
New classification rules should be backed by a case in tests/test_pipeline.py.

Dev setup

pip install -e .
python tests/test_pipeline.py

CI runs the smoke test on Python 3.10–3.12 for every push and PR.

Code of conduct

Be kind and constructive. This is a hobby/community project; assume good faith.

License

By contributing, you agree your contributions are licensed under the MIT License.

2.4 KiB Raw Blame History Unescape Escape