ccu-mcp

Repository on GitHub, which provides public git repositories with URLs.

Repository on GitHub, which uses git. git can track the changes, who made them, and when they were made.

The repository holds the full development history, not just releases. Work happens on feature/, fix/, ci/, docs/ and tests/ branches, lands on the "dev" integration branch via pull request with review and required status checks, and only then reaches "main" as a release PR. Every interim commit between releases is public and reviewable; "main" is protected against direct pushes, so no change bypasses that path.

Repository on GitHub, which uses git. git is distributed.

Every release carries a unique semantic version in package.json, published under that version to npm and to the MCP registry, and tagged vX.Y.Z in git. scripts/check-version-sync.mjs runs in CI and on prepublishOnly to verify that package.json, server.json and the compiled source all agree, so a mismatched or duplicated version cannot be released. A running server reports its own version, plus the exact commit it was built from, through the get_system_info tool.

Each release is identified by an annotated, cryptographically signed git tag vX.Y.Z on "main", verified by GitHub. Tags are the only record of older versions — the project deliberately keeps no long-lived version branches — and each has a corresponding GitHub Release.

Non-trivial release notes file in repository: https://github.com/claymore666/ccu-mcp/blob/dev/CHANGELOG.md.

CHANGELOG.md is maintained per release and is the release notes source. No publicly known run-time vulnerability with a CVE or similar assignment has ever applied to ccu-mcp itself, so there has been nothing of that kind to identify. Where a release cleared advisories in dependencies — which this criterion does not cover — the changelog names them anyway, e.g. the undici and SDK advisory clearances. Security-relevant fixes found by the project's own testing are described explicitly, including their severity assessment; v1.9.1's entry states plainly that its three fixes are not exploitable and why.

https://github.com/claymore666/ccu-mcp/issues

https://github.com/claymore666/ccu-mcp/issues

Bug reports are acknowledged and worked. 61 issues have been closed to date, the large majority of them by a fix that shipped in a named release and is credited in CHANGELOG.md. CONTRIBUTING.md tells reporters what to include (version, CCU type and firmware, Node version, the failing tool call), and SECURITY.md gives explicit response targets for security reports rather than an implied SLA.

Enhancement requests are triaged and answered, and are tracked in milestones alongside fixes; several shipped features originated as user requests. Where a request falls outside the project's intended scope it now gets a documented answer rather than silence: ROADMAP.md contains an explicit "Not planned" section stating what the project will never do and why, so a "no" comes with a reason.

https://github.com/claymore666/ccu-mcp/issues

https://github.com/claymore666/ccu-mcp/blob/dev/SECURITY.md

https://github.com/claymore666/ccu-mcp/security/advisories/new

No vulnerability reports have been received in the last 12 months, so there have been none to respond to — the repository's security-advisory list is empty. The response process itself exists and is published in advance, with explicit stage targets: acknowledgement within 14 days, initial assessment within 30 days, and a fix as fast as severity warrants. See https://github.com/claymore666/ccu-mcp/blob/dev/SECURITY.md#what-to-expect

"npm run build" rebuilds everything from source automatically: tsc compiles src/ to dist/, then scripts/gen-build-info.mjs stamps build metadata. "npm ci" restores the exact dependency set from package-lock.json. The build is also run automatically by the pretest hook, in the build-and-test CI job on every push and pull request, and inside the Dockerfile's builder stage. Verified repeatable: deleting dist/ and rebuilding produces byte-identical output.

Entirely standard tooling for the ecosystem, with nothing bespoke: Node.js, npm, and the TypeScript compiler (tsc), driven by ordinary package.json scripts. Tests use vitest, the container build uses a stock Dockerfile on node:24-alpine, and CI is GitHub Actions. A developer familiar with any TypeScript project can build this one without learning anything project-specific.

Every tool in the build and test path is FLOSS: Node.js (MIT), npm (Artistic-2.0), TypeScript (Apache-2.0), vitest (MIT), oxlint (MIT), and the three production dependencies — @modelcontextprotocol/sdk, undici and zod — all MIT. No proprietary compiler, linker, packer or license server is involved, and the build requires no network service beyond the npm registry.

The test suite is vitest (MIT, FLOSS) and lives in the repository under test/, publicly released with the source. It is run with "npm test", documented in CONTRIBUTING.md (Development setup) and in README.md, and executed automatically by the build-and-test CI job on every push and pull request. Four layers: type check over src AND test, unit tests, end-to-end tests that spawn the built server against a mocked CCU, and live-integration tests gated on CCU_HOST so they are skipped unless real hardware is deliberately supplied. Currently 469 passing tests.

"npm test" — the standard invocation for a Node.js project, and the only one needed. A pretest hook rebuilds dist/ first, so the end-to-end suite always exercises the current source rather than a stale build; CONTRIBUTING.md calls out explicitly that a bare "npx vitest" must not be used for exactly that reason. "npm run lint" and "npm run fuzz" follow the same convention.

Coverage is measured on every CI run and enforced at two levels. vitest applies global thresholds, and scripts/coverage-ratchet.mjs additionally enforces a per-directory floor recorded in .github/coverage-baseline.txt — currently above 96% statements for src overall, and 100% for several directories. The second layer exists because a global average hides local collapse: deleting one directory's tests takes it from 100% to 0% while moving the global figure by a quarter of a point. Beyond line coverage, property-based tests explore input space over the parsing and escaping helpers, and a nightly fuzzer targets the same code with a seeded corpus.

GitHub Actions runs the full pipeline on every push and every pull request to both long-lived branches, and build-and-test is a required status check on "dev" and "main". It runs version-sync, lint and type check, the full test suite with coverage, the coverage-ratchet self-test, the coverage ratchet, workflow linting via actionlint and shellcheck, and the AI-attribution gate. The job is hermetic by contract — every step is a function of the commit under test — which is why dependency scanning deliberately lives in separate scheduled and release-gate workflows instead.

https://github.com/claymore666/ccu-mcp/blob/main/CONTRIBUTING.md#test-policy

Demonstrable in the history rather than merely asserted: roughly 72% of "fix:" commits in the last six months modified files under test/ in the same commit, and the exceptions are dependency bumps and documentation corrections. Recent major changes each shipped with their tests — the prototype-key fixes with test/unit/prototype-key-handling.test.ts, the property/fuzzing work with test/unit/utils-properties.test.ts, the config-parsing hardening with its own regression cases. The policy is enforced as well as written: coverage thresholds are checked globally and per directory in the required CI job, so untested new code fails the build.

https://github.com/claymore666/ccu-mcp/blob/dev/CONTRIBUTING.md#test-policy

Several independent layers. TypeScript runs in strict mode, and "npm run lint" type-checks both src and test with tsc --noEmit. oxlint (MIT, FLOSS) then runs over src, test, scripts and fuzz with its correctness, suspicious and perf rule categories all set to error. CodeQL scans the repository for security issues. Workflow files are linted by actionlint with shellcheck over embedded shell. Every one of these runs in CI, not just locally.

Warnings are errors here, so they cannot accumulate: "npm run lint" fails the build on any oxlint finding or any TypeScript error, and it is a required status check, so nothing merges with a warning outstanding. The lint gate was mutation-tested before being enabled — deliberately planted violations to confirm it goes red — and it immediately found two unit tests that asserted nothing at all, both of which were fixed rather than suppressed. Where a rule is genuinely wrong for this project it is disabled in .oxlintrc.json WITH the reason recorded next to it, never silently. CodeQL currently reports zero open alerts.

Maximally strict where it is practical. TypeScript strict is on with forceConsistentCasingInFileNames, and type checking covers the test sources as well as src — which "npm test" alone does not do. oxlint runs three rule categories as errors rather than warnings. The stricter categories oxlint also offers (pedantic, restriction) are deliberately not enabled: they include rules like no-optional-chaining and no-async-await that would fight the language rather than find defects, and turning them on would mean mass-suppressing them, which is worse than not claiming them.

Applied and documented rather than merely claimed: docs/assurance-case.md maps each Saltzer and Schroeder principle to the mechanism implementing it — fail-safe defaults (default-deny CORS, unconditional DNS-rebinding protection, safety-gate variables that throw rather than read as false), complete mediation (no path to the CCU bypasses validation, write gate and rate limiter), least privilege (dedicated USER-level CCU account recommended, non-root container), separation of privilege (protected writes need both configuration and explicit confirmation), economy of mechanism (one process, no database, three production dependencies) and open design. The same document names the one place the project knowingly violates fail-safe defaults, CCU TLS verification, rather than omitting it.

docs/assurance-case.md contains a table of the weakness classes that apply to this program, each with the countermeasure in place: injection (no shell, no eval — now mechanically prohibited by the lint gate — and escaped HM Script), prototype pollution (Object.fromEntries on write, Object.hasOwn on read), broken authentication (constant-time digest comparison, rotation with grace, rate limiting), sensitive data exposure (log redaction asserted end-to-end, 0600 cache, scrypt-derived credential fingerprint), improper certificate validation (pinning, including the session-resumption trap that made an earlier pin silently pass), ReDoS (a polynomial pattern found and rewritten), path traversal (hash-suffixed cache filenames), and resource exhaustion (bounded maps, queues and retry budgets). Each is backed by a named regression test, and several were found by the project's own fuzzing and property testing rather than read about.

Only published, expert-reviewed primitives, all provided by Node.js/OpenSSL: TLS 1.2 and 1.3 for transport, SHA-256 for bearer-token and certificate-fingerprint digests, and scrypt (RFC 7914) for the credential fingerprint. No proprietary, obscure or home-grown algorithm is used anywhere, and no cipher list or protocol version is overridden in this project's code.

ccu-mcp implements no cryptography. Its purpose is bridging MCP to a CCU, and every cryptographic operation is delegated to node:crypto and to the TLS stack in Node.js/OpenSSL via undici — createHash, timingSafeEqual, scryptSync and randomBytes. There is no hand-rolled hash, cipher, MAC or random-number generator in the codebase.

All cryptography comes from Node.js and its bundled OpenSSL, both FLOSS, reached through the standard node:crypto and TLS APIs and through undici (MIT). No proprietary cryptographic library, hardware module or licensed component is required to build or run any part of the project.

Key lengths are those of the underlying platform defaults, all comfortably above the NIST 2030 minimums: TLS 1.2/1.3 with 2048-bit-or-larger RSA and 256-bit elliptic-curve key agreement, SHA-256 (256-bit) digests, scrypt deriving a 256-bit key from a random salt, and randomBytes for token generation. Nothing in the project reduces a key length below the platform default, and because no cipher list or protocol version is pinned, weaker suites are already excluded by Node's TLS 1.2 floor.

No broken algorithm is used in any default path. There is no MD4, MD5, SHA-1, single DES, RC4 or Dual_EC_DRBG anywhere in the codebase or in the security mechanisms it relies on. Node's TLS floor of 1.2 excludes SSLv3 and the cipher modes associated with it, and the project does not override the cipher list. Notably the credential fingerprint uses scrypt rather than a fast hash — this was deliberately changed from SHA-256 in response to a CodeQL finding, because a fast hash over a credential is the wrong primitive even when it is not a "broken" one.

No algorithm or mode with a known serious weakness is used by default. SHA-1 appears nowhere; digests are SHA-256. CBC-mode concerns do not arise, since cipher-suite selection is left entirely to Node/OpenSSL under a TLS 1.2 minimum, where AEAD suites (AES-GCM, ChaCha20-Poly1305) are preferred. Password-equivalent material is handled with scrypt, a deliberately slow salted KDF, rather than any fast hash.

Perfect forward secrecy is provided by the platform and not undermined by this project. TLS 1.3 mandates ephemeral (EC)DHE key agreement, and Node's default TLS 1.2 cipher preferences are ECDHE suites. Because the project pins no cipher list and sets no secureProtocol or minVersion, non-PFS static-RSA key exchange is not available in the negotiated set. One deliberate related choice: when TLS fingerprint pinning is enabled, session resumption is disabled — a resumed handshake returns an empty peer certificate, which would let the pin silently pass.

ccu-mcp does not authenticate external users and therefore stores no user passwords — authentication of humans is the CCU's job. The one credential-derived value it does persist is a fingerprint of the configured CCU credential, used to detect that the credential changed and invalidate a cached session. That is derived with scrypt and a per-installation random salt (src/ccu/session.ts), explicitly chosen over the SHA-256 it originally used, so the cache file cannot be used for an offline guess at the CCU password. Bearer tokens are stored only as SHA-256 digests and compared with timingSafeEqual.

All security-relevant random values come from randomBytes() in node:crypto, a CSPRNG. This covers generated bearer tokens and the scrypt salt. Math.random() is not used for any security purpose anywhere in the codebase.

Distribution channels use HTTPS exclusively. [osps_br_03_02]

Nothing is fetched over plain HTTP anywhere in the build, release or install path. Dependencies come from the npm registry over HTTPS with integrity hashes pinned in package-lock.json and verified by "npm ci". GitHub Actions are pinned by commit SHA, and the one binary the release workflow downloads (mcp-publisher) is fetched over HTTPS and verified against a hardcoded SHA-256 checksum before use. Releases are published to npm with build provenance (SLSA) via trusted publishing (OIDC), so no long-lived token exists to intercept, and every release tag is cryptographically signed.

There are no known unpatched vulnerabilities of medium or higher severity in ccu-mcp, and none has ever been reported: the repository's security-advisory list is empty. Dependency advisories are monitored on three independent tracks — Dependabot, a daily production-only "npm audit" for high/critical findings, and a release-audit gate that blocks any pull request into "main" while a high or critical advisory is outstanding — so a vulnerable dependency cannot sit unnoticed, let alone ship in a release. CodeQL currently reports zero open alerts.

No critical vulnerability has been reported against ccu-mcp to date, so the record is of process rather than of incidents. That process is in place and has been exercised on adjacent findings: dependency advisories have been cleared promptly and within a release each time, and a CodeQL high-severity finding (a fast hash over the credential fingerprint) was fixed by moving to scrypt. SECURITY.md publishes explicit response targets, and a release is blocked outright while a high or critical advisory is open.

No credential has been committed. .env and .env.* are gitignored; .env.example ships variable NAMES with placeholder or default values only (CCU_HOST=your-ccu-hostname-or-ip) and contains no password, token, key or fingerprint. Live testing configuration, the maintainer's CCU credentials, the certificate pin and the Smithery API key all live outside the repository entirely. Publishing uses OIDC-based trusted publishing for both npm and the MCP registry, so there is no long-lived publish token in existence to leak; the single remaining stored secret is scoped to an approval-gated GitHub environment, and the repository holds zero repository-wide secrets. GitHub secret scanning and push protection are enabled.

strict tsc across source and tests on every push, actionlint plus shellcheck over workflows, and daily npm audit in audit.yml with a hard release gate

CodeQL is enabled via GitHub default setup (state: configured, default query suite) over javascript-typescript and actions; its default suite includes security queries.

Zero open CodeQL alerts. Findings have been fixed rather than dismissed — including a high-severity one where the CCU credential fingerprint was derived with SHA-256, corrected to scrypt with a random salt, and a clear-text-logging finding that led to the CCU_CA_CERT path being kept out of thrown error messages. Both landed with tests. Static analysis now runs on every commit through three tools: CodeQL, oxlint, and tsc --noEmit in strict mode over both src and test.

On every commit, not merely daily. CodeQL runs on pushes and pull requests to both long-lived branches; oxlint and the strict TypeScript type check run in the required build-and-test job, so every commit that reaches a branch has been analysed. Workflow files are separately linted by actionlint with shellcheck on the same trigger. A daily scheduled job additionally audits production dependencies.

Two forms of dynamic analysis, both automated. Coverage-guided FUZZING with Jazzer.js (@jazzer.js/core) runs nightly via .github/workflows/fuzz.yml against three targets — HM Script escaping, CCU response parsing and bearer-token extraction — each with a seeded corpus checked into the repository. PROPERTY-BASED TESTING with fast-check runs as part of the ordinary test suite on every commit, exercising the same helpers against thousands of generated inputs per run under a pinned seed, using a differential oracle for the escaping round-trip. This is not decorative: it found three real defects that shipped as fixes in v1.9.1, which is what prompted the sweep for the same defect class across the rest of the codebase. The end-to-end suite additionally runs the built server as a subprocess against a mocked CCU.

The project produces no software written in a memory-unsafe language. ccu-mcp is TypeScript running on Node.js, with no C/C++ source, no native addon and no FFI dependency, so there is no buffer-overwrite class of defect for a memory-safety tool to detect. Dynamic analysis is nevertheless applied for other defect classes: nightly coverage-guided fuzzing with Jazzer.js against a seeded corpus, plus property-based testing with fast-check on every commit.

The fuzzing and property-testing configuration is assertion-heavy by construction. Fuzz targets assert invariants on every input rather than only catching crashes — for example that escaping round-trips exactly through an independent unescape oracle, and that quote parity holds for odd runs of backslashes. Property tests assert the same invariants across generated input space. The build itself compiles with TypeScript strict, which turns a large class of assumptions into compile-time checks, and the runtime validates every tool input against a zod schema, so an invalid value is rejected rather than propagated. The fuzz runner also treats a missing corpus as a hard failure rather than a clean run, so the harness cannot pass vacuously.

Every defect found by dynamic analysis has been fixed, each with a regression test, and each in the next release rather than deferred. The three defects found by the initial fuzzing and property-testing work — a String() conversion that could throw on an exotic object, a prototype-key write path, and an IPv4-mapped-IPv6 address truncation — were all fixed in v1.9.1, and the same defect class was then swept across logger, utils, device-type-cache and resolver, producing a fourth fix in the same release. Regression tests live in test/unit/prototype-key-handling.test.ts and in a dedicated block of test/unit/utils-properties.test.ts, and the corresponding inputs were added to the fuzzing seed corpus so they cannot silently regress.