feat(mcp): add version command and clearer unknown-command guidance

[glorydavid03023]

Summary

The gittensory-mcp CLI defines a packageVersion constant but exposes no way to query it — the conventional --version flag was missing, so users and tooling had no quick way to confirm which CLI build is installed (e.g. for bug reports).

This adds a version command with --version and -v aliases:

$ gittensory-mcp version
@jsonbored/gittensory-mcp/0.4.0 (node v22.x.x)

$ gittensory-mcp version --json
{
  "name": "@jsonbored/gittensory-mcp",
  "version": "0.4.0",
  "apiVersion": "0.1.0",
  "node": "v22.x.x"
}

It reports the installed package version, the targeted API version, and the Node.js runtime — useful context for diagnostics and issue reports. The --json form keeps output parseable for tooling.

As a tightly-related ergonomics touch, the unknown-command error now points at gittensory-mcp --help so a mistyped command guides the user to the command list.

Why no linked issue

Low-risk, additive CLI ergonomics only. No public-behavior, auth/session, schema, deploy, or frontend-architecture change, so per CONTRIBUTING this does not require an issue first. Happy to file one if maintainers prefer.

Changes

• packages/gittensory-mcp/bin/gittensory-mcp.js — version/--version/-v dispatch in runCli, new printVersion(), help-text usage line, and the improved unknown-command message.
• test/unit/mcp-cli.test.ts — cover all three aliases (plain output), the --json payload shape, and the unknown-command guidance.
• packages/gittensory-mcp/README.md — document the new command and aliases.

Contract notes

No MCP tool or HTTP/OpenAPI contract changes. This only adds a local CLI command surface; stable JSON output is preserved and the new --json payload is additive.

Validation

Intended gate (CONTRIBUTING required checks):

npm run build:mcp
npm run test:mcp-pack
npm run typecheck
npm run test:coverage
npm run test:ci

Transparency note: my local authoring environment had no Node runtime available, so I could not execute the gate locally before opening this PR. The change was prepared against the existing CLI dispatch/test patterns and is intended to be validated by CI on this PR (and I will run the full gate locally as well). If any check needs adjustment I'll follow up promptly.

Security / privacy

No auth, cookie, CORS, GitHub App output, identity, or contributor-evidence changes. The version output contains only static package/API/runtime version strings — no tokens, paths, wallet/hotkey, or scoring context.

[JSONbored]

@glorydavid03023 this is a good small CLI ergonomics improvement, but it needs validation evidence.

A few notes:

• version, --version, and -v are conventional and useful.
• The JSON output is appropriately parseable.
• The blocker is that the body lists intended validation rather than completed validation.

Required changes:

• Run the relevant MCP gate locally or clearly state the exact blocker for skipped checks.
• Keep README examples aligned with actual output.

Validation expected:

• npm run build:mcp
• npm run test:mcp-pack
• npm run typecheck
• Focused test/unit/mcp-cli.test.ts

[glorydavid03023]

Thanks for the review. I've addressed both points and rebased onto the latest main.

README alignment

The plain version output now includes the targeted API version, so it matches the README's description (package version + API version + Node runtime). Actual output:

$ gittensory-mcp version
@jsonbored/gittensory-mcp/0.4.0 (api 0.1.0, node v20.18.1)

$ gittensory-mcp version --json
{
  "name": "@jsonbored/gittensory-mcp",
  "version": "0.4.0",
  "apiVersion": "0.1.0",
  "node": "v20.18.1"
}

$ gittensory-mcp -v
@jsonbored/gittensory-mcp/0.4.0 (api 0.1.0, node v20.18.1)

$ gittensory-mcp bogus
Error: Unknown command: bogus. Run `gittensory-mcp --help` to list commands.

The README now shows these literal examples, and the test asserts the plain form reports all three fields.

Completed validation

Run locally from the repo root (environment note: a portable Node v20.18.1; CI runs Node 22):

• npm run build:mcp → pass (exit 0)
• npm run typecheck (tsc --noEmit, against the rebased main) → pass (exit 0)
• Focused test/unit/mcp-cli.test.ts → my three new cases pass:
  • reports the package version via version, --version, and -v ✓
  • emits machine-readable version output with --json ✓
  • guides unknown commands to --help ✓

Two honest caveats about my local box (neither related to this change):

• npm run test:mcp-pack could not run locally because scripts/check-mcp-package.mjs calls spawnSync("npm", …), which can't resolve npm.cmd on Windows without a shell (ERR_STREAM_NULL_VALUES). This passed on CI (Linux/Node 22) on the previous push and the script is untouched by this PR.
• In a full mcp-cli.test.ts run, one pre-existing test (rejects unsafe server-provided packet markdown before non-json output, which does git init + subprocess work) timed out at the 10s limit under the slow portable Node. It is unrelated to the version command; my three cases pass in isolation and the file otherwise passes.

CI on this push should give the authoritative full-gate result on Node 22. Happy to adjust anything further.