ccu-mcp

ccu-mcp follows semantic versioning and provides an upgrade path rather than maintaining parallel older versions: fixes land in the current release line, and users upgrade with "npm install -g ccu-mcp@latest" or by bumping the pinned version. Older releases remain permanently available as signed git tags and as npm versions. CHANGELOG.md documents every release, and any release with a behaviour change carries an explicit "read before upgrading" section describing what changed and what to do about it — see v1.9.1. The supported-version table is in SECURITY.md.

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

No vulnerabilities have been reported or resolved in the last 12 months; the repository's security-advisory list is empty. The crediting policy exists and is published in advance: SECURITY.md states that reports are credited in the advisory and in CHANGELOG.md unless the reporter asks otherwise. https://github.com/claymore666/ccu-mcp/blob/dev/SECURITY.md#what-to-expect

A documented response process with explicit stage targets — acknowledgement within 14 days, initial assessment within 30 days, and a fix as fast as severity warrants with a date given once assessment completes — presented honestly as targets for a single-maintainer project rather than as an SLA. Private reporting runs through GitHub Security Advisories. https://github.com/claymore666/ccu-mcp/blob/dev/SECURITY.md#what-to-expect

The identified style guide is the Google TypeScript Style Guide, with two documented deviations: 120-column lines rather than 80, and double quotes. Contributions are required to comply. https://github.com/claymore666/ccu-mcp/blob/dev/CONTRIBUTING.md#code-style

"npm run lint" runs oxlint (MIT, FLOSS) over src, test, scripts and fuzz before tsc, and CI runs the same command in the required build-and-test check — so a violation fails the build rather than waiting for review. The ruleset is oxlint's correctness, suspicious and perf categories, all as errors, pinned in .oxlintrc.json in the repository. Every exception is listed there with the reason it is off; per-line exceptions use an oxlint-disable-next-line comment stating why. The gate was mutation-tested before being enabled — deliberately planted no-eval and no-unused-vars violations to confirm it exits non-zero, then confirmed it exits zero once reverted. oxlint is used rather than typescript-eslint because typescript-eslint's peer range is >=4.8.4 <6.1.0 and this project builds on TypeScript 7; no release of it supports the compiler in use.

No native binaries are produced. ccu-mcp is TypeScript compiled to JavaScript by tsc and executed by Node.js; there is no C/C++ compiler or linker in the build, so CC/CFLAGS/CXX/CXXFLAGS/LDFLAGS have nothing to apply to. There is also no native addon or FFI dependency.

tsconfig.json sets sourceMap: true, declaration: true and declarationMap: true, and nothing in the build strips or minifies. The published npm package ships dist/ whole, so .js.map and .d.ts.map reach consumers and a stack trace from an installed copy maps back to the TypeScript source. The build additionally stamps dist/build-info.json with the commit it was built from, surfaced at runtime by the get_system_info tool.

The build is a single tsc invocation over the whole program (include: src/**/*), followed by one script that stamps build metadata. TypeScript resolves the complete module graph itself and there is no per-directory or recursive make-style build, so no subdirectory is built in isolation and cross-directory dependency information cannot be stale.

Verified empirically, not assumed: building, deleting dist/ entirely, and building again from the same source produces byte-identical output — the SHA-256 over all emitted .js and .d.ts files matched exactly across both runs. The build has no private inputs and dependencies are pinned by package-lock.json ("npm ci"). The only file that varies is dist/build-info.json, which records the git commit and build timestamp on purpose so a running server can report which checkout it came from; it is generated metadata, not compiled output, and is a pure function of the commit apart from the timestamp.

Installed and uninstalled with the standard package manager for the language: "npm install -g ccu-mcp" / "npm uninstall -g ccu-mcp", or run without installing via "npx ccu-mcp". A Docker image is also provided, with a docker-compose.yml in the repository, so "docker compose up" / "docker compose down" works as an alternative. README.md documents both routes.

There is no POSIX-style installation step to parameterise. npm decides the install location itself, honouring its own standard configuration ("npm config set prefix", --prefix, NPM_CONFIG_PREFIX); DESTDIR has no meaning for a package manager install, and the project neither writes files outside npm's control nor ships a "make install".

"git clone && npm ci && npm run lint && npm test" — three standard commands, no bespoke tooling, and the test environment is included: the unit and end-to-end suites run against a mocked CCU and need no hardware at all. The only prerequisite is Node.js >= 24, declared in package.json engines. Documented step by step at https://github.com/claymore666/ccu-mcp/blob/dev/CONTRIBUTING.md#development-setup , including the live-integration suites, which are gated on CCU_HOST and skipped unless a real CCU is deliberately supplied.

Dependencies are declared in package.json in the standard computer-processable npm format, with exact resolution pinned in package-lock.json. Production dependencies are deliberately few — three: @modelcontextprotocol/sdk, undici and zod. https://github.com/claymore666/ccu-mcp/blob/dev/package.json

Three independent layers, all automated. (1) Dependabot opens PRs for outdated dependencies, with auto-merge configured. (2) .github/workflows/audit.yml runs "npm audit --omit=dev" daily against production dependencies for high/critical advisories and maintains a single labelled tracking issue; it is green whenever the audit ran and red only when it could not run. (3) release-gate.yml's release-audit job is a required check on every pull request into "main", so no release can go out with an unresolved high or critical advisory in production dependencies. A dependency-review workflow also runs on pull requests. Scanning is deliberately kept out of the required per-commit check, because an advisory database changes with no diff and would make that check non-hermetic.

Every external component is a normal npm dependency resolved from the registry at install time. There are no vendored, bundled or forked convenience copies anywhere in the tree, and no source of a third-party library is checked in. Updating any component is "npm update" or a version bump in package.json, which is exactly what Dependabot automates.

Verified rather than assumed: the source was swept for the deprecated Node.js APIs (new Buffer(), url.parse(), util.isArray(), crypto.createCipher(), fs.exists(), domain) and uses none of them. The project targets Node.js >= 24 and uses current APIs throughout — node:crypto with timingSafeEqual/scryptSync, node:fs/promises, WHATWG URL, and undici's fetch. "tsc --noEmit" runs over both src and test in CI, so a TypeScript-visible deprecation surfaces at build time.

The build-and-test job in .github/workflows/ci.yml runs on every push and every pull request to both long-lived branches, and is a required status check on "dev" and on "main". It runs lint, type check over src and test, the full unit and end-to-end suites, coverage measurement, the coverage-ratchet self-test and the coverage ratchet itself, and reports success or failure per run in the GitHub Checks UI — so a pull request cannot merge without a visible pass. Currently 469 passing tests.

Measured from the git history rather than estimated: of the commits with a "fix:" subject in the last six months, roughly 72% touched files under test/ in the same commit — comfortably above the 50% threshold. The remainder are dependency bumps and documentation-only corrections, which have no behavioural regression to pin. The policy behind the number is written down and mandatory: CONTRIBUTING.md states that a bug fix must include a test that fails before the fix and passes after it, and that a fix without one is not considered complete. Recent examples: test/unit/prototype-key-handling.test.ts (v1.9.1) and the regression block in test/unit/utils-properties.test.ts.

86.05% statements, enforced globally by vitest.config.ts and per-directory by .github/coverage-baseline.txt

CONTRIBUTING.md contains a written, mandatory test policy: "Any pull request that adds or changes functionality must add or update tests covering it. This is not negotiable for major new functionality: a new tool, a new transport, a new configuration surface, or a change in how an existing tool behaves all require tests in the same PR." Documentation-only and formatting-only changes are the sole exemption. It is backed mechanically: coverage thresholds are enforced globally by vitest and per directory by scripts/coverage-ratchet.mjs in the required CI check, so a change that adds untested code fails the build even when every existing test passes. https://github.com/claymore666/ccu-mcp/blob/dev/CONTRIBUTING.md#test-policy

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

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.

Secure design principles are applied deliberately and documented criterion-by-criterion at https://github.com/claymore666/ccu-mcp/blob/dev/docs/assurance-case.md , which maps each Saltzer and Schroeder principle to the mechanism implementing it. Concretely: FAIL-SAFE DEFAULTS — CORS is default-deny with an allowlisted origin reflected exactly and never as a wildcard, DNS-rebinding protection is unconditional, the HTTP transport requires a bearer token, and a malformed safety-gate variable (CCU_PROFILE_PROTECTED=yes) is a hard startup error rather than a silently unprotected CCU. COMPLETE MEDIATION — every tool call passes through the same wrapper: zod validation, then the write gate, then the rate limiter; there is no code path to the CCU that bypasses them. LEAST PRIVILEGE — the documented recommendation is a dedicated USER-level CCU account, and the container runs as non-root. SEPARATION OF PRIVILEGE — writing to a protected CCU requires both configuration and an explicit per-session confirmation, with run_script and delete_system_variable requiring it on every call. ECONOMY OF MECHANISM — one process, no database, three production dependencies. The one known deviation, CCU TLS verification being off by default, is stated openly in the same document rather than argued around.