Contributing

Development Commands

npm install
npm run build
npm test
npm run test:coverage:check
npm run validate:docs
npm run docs:build
npm run validate:package
npm run validate

Adding Tools

When adding a new MCP tool:

1. Add the tool in the relevant src/tools/* module.
2. Use existing client modules before introducing new API logic.
3. Mark read-only and destructive annotations accurately. Tools that overwrite or delete live state must use the shared DESTRUCTIVE_LIVE_WRITE constant from src/tools/annotations.ts; test/tool-annotations.test.mjs fails if a new import-/delete-/update-/run- tool is not annotated and listed there.
4. Add tests for success, error, confirmation, and formatting behavior.
5. Update the tool reference with a collapsible parameters section directly under the tool, and update relevant how-to docs.

Adding Resources Or Prompts

Resources and prompts are registered in the resource and prompt modules. Keep content concrete and discovery-first. When an agent needs environment-specific facts, prompts should direct it to discovery tools instead of relying on memory.

When adding or changing a prompt, update the prompt reference with a collapsible parameters section directly under the prompt.

npm run validate:docs compares registered tool, prompt, and resource names against the reference docs. It also checks documented tool-call examples for stale tool names and top-level argument names.

Artifact Work

When authoring or importing vRO artifacts, read the workflow authoring guide and run preflight before import. Prefer real importable artifacts over illustrative pseudocode.

Documentation

Docs live under docs/ and are built with VitePress.

• Add pages to the sidebar in docs/.vitepress/config.ts.
• Keep examples aligned with current tool names and schemas.
• Add or update root examples/ flows when new capabilities change common usage patterns.
• Keep tool and prompt parameters documented directly under each tool or prompt in collapsible sections.
• Distinguish read-only discovery from live write or destructive operations.
• Run npm run validate:docs and npm run docs:build before opening a docs PR.

Dependency Overrides

package.json carries a single dependency override, vite. It exists because vitepress 1.6.4 declares vite@^5.4.14, and the 5.x line no longer receives the security patches the project needs, so the docs toolchain is pushed onto the 6.x line instead. @vitejs/plugin-vue, which vitepress pins, accepts vite@^5.0.0 || ^6.0.0, so 6.x is within range; 7.x and 8.x are not, and would need a second cascading override.

Keep it a caret range rather than an exact version. Dependabot never edits an overrides block, so an exact pin silently blocks it from fixing vite advisories and the work falls back to a manual lockfile regeneration (see VCFO-066). A range lets Dependabot patch within the major on its own. The VitePress config is deliberately vanilla, with no vite block and no custom theme, so npm run docs:build in CI is a sufficient check on a vite bump.

An esbuild override sat alongside it until VCFO-066. Do not re-add one. It began as a security floor, when esbuild 0.24.2 and earlier were vulnerable, and outlived its purpose: vite declares esbuild@^0.25.0 and reaches a patched version on its own, while tsx declares esbuild@~0.28.0 and was being held three minor versions back by the floor. Both consumers now resolve to non-vulnerable versions unaided, and the two land on different versions, which is why npm ls esbuild shows one copy under tsx and another under vite.

The general rule both cases point at: reach for an override only when a dependency's own declared range cannot get you to a safe version, express it as a range, and write down here why it exists. An override with no recorded rationale is indistinguishable from an accident a year later.

To check a lockfile against the overrides without network access, npm ls --package-lock-only <package> resolves from package-lock.json alone and reports an invalid marker when a resolved version does not satisfy the override, which is the same condition that makes npm ci fail.

GitHub Actions

The repository uses GitHub Actions for CI, dependency review, CodeQL analysis, package dry-runs, documentation deployment, and npm publishing. Keep workflow changes narrow and prefer official GitHub/npm actions where possible.

• CI runs tests across supported Node versions and runs the full validation gate on Node 24.
• Package Check runs npm run validate:package on every pull request and every push to main, with no paths filter. It is a required status check, and GitHub does not auto-pass a path-filtered required check: a pull request touching nothing in the filter never fires the workflow, so the context stays unreported and the merge is blocked. A filter also let publish-affecting files skip the check that verifies them, since CHANGELOG.md, LICENSE and NOTICE ship verbatim and .npmignore subtracts from the included directories. Do not reintroduce one to save a 15s job (VCFO-102).
• Publish to npm runs only for published GitHub releases and expects npm trusted publishing to be configured.