feat: health check with mcp server version

[devtronaut]

Summary

The health_check tool and the health endpoint (in streamable HTTP mode) now return the currently deployed version of the GitLab MCP server. The field is called mcp_server_version in the health_check response and version in the health endpoint response.

So far, only the health endpoint in SSE mode and the initialize handshake response contain the version field. This PR closes that gap in an additive way. It does not introduce any breaking changes.

Having the version information is useful for automation purposes, such as validating upgrades or auto-generating MCP server specs for local MCP server registries. Relying on extracting the version information from the initialize handshake is impractical.

Changes

• README.md, docs/tools/index.md, docs/tools/projects.md, tools/registry.ts: Update tool descriptions for health_check tool with newly added mcp_server_version field.
• index.ts: Add new mcp_server_version field to health_check tool and version field to /health endpoint.
• test/streamable-http-concurrent-session.test.ts: Extend streamable http health unit test with newly added version field.
• test/test-health-check.ts: Extend health_check tool unit tests with newly added mcp_server_version field.

Verification

health_check tool

npx @modelcontextprotocol/inspector \
  --cli http://127.0.0.1:3002/mcp \
  --transport http \
  --header "Private-Token: $GITLAB_PERSONAL_ACCESS_TOKEN" \
  --method tools/call \
  --tool-name health_check \
  | jq '.content[0].text | fromjson'

{
  "status": "ok",
  "authenticated": true,
  "gitlab_url": "http://localhost:80/api/v4",
  "mcp_server_version": "2.1.61",
  "version": "19.2.6-ee",
  "revision": "684d9581bfe",
  "enterprise": true
}

health endpoint of streamable http server

curl -s http://127.0.0.1:3002/health | jq .

{
  "status": "healthy",
  "version": "2.1.61",
  "activeSessions": 14,
  "maxSessions": 1000,
  "uptime": 374.005282625
}

Tests

npm run test:mock, npm run test:consumer-smoke and npx tsc --noEmit passed locally without issues.

Worth to mention

Personally, I'd align version names in all response bodies. For now, I introduced a slight drift in naming to avoid making this a breaking change. The existing structure of the health endpoint of the SSE server was respected for the health endpoint on the streamable HTTP server, with both endpoints now returning a version field in the response body. For the health_check tool, the version field is reserved for the GitLab server version. Hence, I went with mcp_server_version.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 0316bb64-5645-424f-960c-4371254c865b

📥 Commits

Reviewing files that changed from the base of the PR and between f786b13 and 6006735.

📒 Files selected for processing (7)

• README.md
• docs/tools/index.md
• docs/tools/projects.md
• index.ts
• test/streamable-http-concurrent-session.test.ts
• test/test-health-check.ts
• tools/registry.ts

Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.

📜 Recent review details

🧰 Additional context used

🪛 ast-grep (0.45.3)

test/streamable-http-concurrent-session.test.ts

[warning] 23-23: Filesystem path is not a string literal; a request-/variable-derived path can enable path traversal. Validate and normalize the path before use.
Context: fs.readFileSync(packageJsonPath, "utf8")
Note: [CWE-22] Improper Limitation of a Pathname to a Restricted Directory ('Path Traversal').

(detect-non-literal-fs-filename-typescript)

test/test-health-check.ts

[warning] 13-13: Filesystem path is not a string literal; a request-/variable-derived path can enable path traversal. Validate and normalize the path before use.
Context: fs.readFileSync(packageJsonPath, "utf8")
Note: [CWE-22] Improper Limitation of a Pathname to a Restricted Directory ('Path Traversal').

(detect-non-literal-fs-filename-typescript)

🔇 Additional comments (7)

index.ts (1)

14093-14093: LGTM!

Also applies to: 15647-15647

test/streamable-http-concurrent-session.test.ts (1)

4-6: LGTM!

Also applies to: 21-24, 187-187, 194-194

test/test-health-check.ts (1)

4-6: LGTM!

Also applies to: 11-14, 99-99, 123-123

tools/registry.ts (1)

1196-1196: LGTM!

README.md (1)

783-783: LGTM!

docs/tools/index.md (1)

66-66: LGTM!

docs/tools/projects.md (1)

223-223: LGTM!

---

📝 Summary

Summary by CodeRabbit

• New Features

  • Health check responses now always include the MCP server version.
  • The HTTP health endpoint now reports the server version.
  • Authenticated health checks continue to include GitLab instance version details.

• Documentation

  • Updated health check documentation to describe the server and GitLab version information provided.

Walkthrough

The health check tool now always reports the MCP server version. The Streamable HTTP /health endpoint also reports the server version. Tests and documentation cover both response fields.

Changes

Health version reporting

Layer / File(s)	Summary
Add server version fields index.ts	The health check response now includes mcp_server_version. The /health response now includes version.
Verify version fields test/test-health-check.ts, test/streamable-http-concurrent-session.test.ts	Tests compare both response fields with the package version. The health check tests cover successful and failed GitLab version lookups.
Document version reporting tools/registry.ts, README.md, docs/tools/index.md, docs/tools/projects.md	Tool descriptions document unconditional MCP server version reporting and authenticated GitLab version reporting.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~8 minutes

Change: Feature

Suggested reviewers: zereight

Merge Risk: ⚪ Minimal · up to 60067

The health responses now expose the server version without changing existing fields, and the supplied verification covers both endpoints.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 3 files. (4 skipped: 3 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly identifies the main change: adding the MCP server version to health-check responses.
Description check	✅ Passed	The description accurately explains the new version fields, affected endpoints, documentation updates, tests, verification, and compatibility impact.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 3 files. (4 skipped: 3 unsupported, 1 too large.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

✨ Simplify code

• Create PR with simplified code

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}