feat(errors): add structured error handling with tier awareness by polaz · Pull Request #75 · structured-world/gitlab-mcp

polaz · 2026-01-20T21:13:24Z

Summary

Add tier-aware error handling infrastructure with tier-features.ts and error-handler.ts
Integrate structured error responses into MCP handlers
Enable LLMs to receive actionable error information for self-correction

Features

Tier-restricted feature detection: Automatically identifies when a feature requires Premium/Ultimate tier
Structured error codes: TIER_RESTRICTED, PERMISSION_DENIED, NOT_FOUND, RATE_LIMITED, SERVER_ERROR, API_ERROR
Actionable suggestions: Each error includes suggested_fix with guidance
Alternatives for tier-restricted features: Provides alternative approaches available on Free tier
Documentation links: Includes docs_url and upgrade_url for tier-restricted errors

Example Structured Error Response

{
  "error_code": "TIER_RESTRICTED",
  "tool": "browse_protected_branches",
  "action": "list",
  "http_status": 403,
  "tier_required": "Premium",
  "feature_name": "Protected Branches API",
  "message": "Protected Branches API requires GitLab Premium or higher",
  "suggested_fix": "Upgrade to GitLab Premium, or use one of the alternatives",
  "alternatives": [
    {
      "action": "Configure via UI",
      "description": "Use Settings > Repository > Protected branches in GitLab UI",
      "available_on": "Free"
    }
  ],
  "docs_url": "https://docs.gitlab.com/ee/api/protected_branches.html",
  "upgrade_url": "https://about.gitlab.com/pricing/"
}

Test plan

Unit tests for tier-features.ts (20 tests)
Unit tests for error-handler.ts (26 tests)
All 2308 existing tests pass
Manual test with GitLab Free tier instance

Closes #50

Add tier-aware error handling infrastructure: - tier-features.ts: GitLab tier feature map with Premium/Ultimate features - error-handler.ts: Structured error types and handleGitLabError() function - Support for TIER_RESTRICTED, PERMISSION_DENIED, NOT_FOUND, RATE_LIMITED, SERVER_ERROR, and API_ERROR error codes - Alternatives suggestions for tier-restricted features - Unit tests for both modules (46 tests) Closes #50

Add structured error response integration: - Import error handler utilities in handlers.ts - Add parseGitLabApiError() to extract status codes from error messages - Add toStructuredError() to convert errors to structured responses - Modify catch block to return structured errors for GitLab API errors - Fallback to original error format for non-API errors This enables LLMs to receive actionable error information including: - error_code (TIER_RESTRICTED, PERMISSION_DENIED, NOT_FOUND, etc.) - suggested_fix with guidance on how to resolve the issue - alternatives for tier-restricted features Part of #50

github-actions · 2026-01-20T21:22:39Z

📊 Test Coverage Report

Overall Coverage: 89.91%

Coverage Details

Metric	Percentage
Statements	89.91%
Branches	82.89%
Functions	77.86%
Lines	90.38%

Coverage Report: View detailed coverage report

This report was generated automatically from your PR changes.

codecov · 2026-01-20T21:22:51Z

Codecov Report

❌ Patch coverage is 87.66234% with 19 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/utils/error-handler.ts	89.52%	1 Missing and 10 partials ⚠️
src/handlers.ts	88.37%	2 Missing and 3 partials ⚠️
src/logger.ts	50.00%	1 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!

Copilot

Pull request overview

This PR adds structured error handling infrastructure with tier-awareness to help LLMs self-correct and provide actionable guidance for users on restricted GitLab tiers. The implementation includes tier feature detection, structured error response generation, and integration with MCP handlers.

Changes:

Add tier-features.ts with mappings of Premium/Ultimate features and their Free tier alternatives
Add error-handler.ts with structured error types and transformation functions
Integrate structured error handling into MCP tool handler in handlers.ts

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
src/utils/tier-features.ts	Defines tier-restricted features map with Premium/Ultimate features, alternatives, and documentation URLs
src/utils/error-handler.ts	Implements structured error types and transformation logic from GitLab API errors to actionable responses
src/handlers.ts	Adds error parsing and structured error integration in the main tool handler
tests/unit/utils/tier-features.test.ts	Comprehensive unit tests for tier-features.ts (20 tests covering all functions)
tests/unit/utils/error-handler.test.ts	Comprehensive unit tests for error-handler.ts (26 tests covering all error types)

src/handlers.ts

src/utils/error-handler.ts

src/handlers.ts

tests/unit/utils/tier-features.test.ts

- Add action extraction from request.params.arguments and error cause - Fix regex to handle wrapped errors (Failed to execute tool prefix) - Include rawMessage context in permission denied suggested_fix - Extract resourceId and resourceType from 404 error messages - Add tests for parseGitLabApiError, toStructuredError, and error flows

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 9 comments.

src/utils/error-handler.ts

src/handlers.ts

src/utils/error-handler.ts

src/handlers.ts

src/utils/tier-features.ts

tests/unit/handlers.test.ts

…r tests - Remove unused imports from handlers.test.ts - Add 9 direct unit tests for parseGitLabApiError function - Document TierAlternative naming convention (snake_case for JSON output) - Use context-based regex for resourceId: first tries keyword match like "Project 123", then falls back to 4+ digit numbers

- Add test for 404 errors with 4+ digit ID extraction fallback - Add test for action extraction from wrapped error cause - Add test for StructuredToolError detection in cause chain - Add tests for resolveRefs: $ref resolution, arrays, nested objects - Preserve error cause when re-throwing in tool handler - Check cause chain for StructuredToolError in toStructuredError

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

src/utils/tier-features.ts

- Replace non-existent tool references with actual implemented tools - Add group_webhooks (Premium): list_webhooks:group, manage_webhook:group - Add epics (Premium): browse_work_items:epic, manage_work_item:epic - Add iterations (Premium): list_group_iterations - Remove placeholder entries for unimplemented tools (protected branches, code owners, security dashboard, merge trains, MR approvals) - Add NOTE comment listing planned features for future implementation - Update tier-features and error-handler tests to match new structure

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Pino-pretty uses worker threads via thread-stream which prevents Jest from exiting properly. Disable transport when running tests (detected via NODE_ENV=test or JEST_WORKER_ID).

…coverage test The fs mock was too aggressive and broke pino logger which uses sonic-boom internally. Now the mock preserves actual fs functions for node_modules paths.

tests/unit/utils/fetch.coverage.test.ts

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

src/utils/error-handler.ts

- Remove redundant tierFeature.tier !== "Free" check (TIER_FEATURES map only contains Premium/Ultimate entries) - Add security documentation for TLS certificate validation opt-in

Copilot

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

src/utils/tier-features.ts

Replace static TIER_FEATURES map with dynamic detection using ConnectionManager.isFeatureAvailable() and getTier(). This ensures tier restrictions are based on actual GitLab instance capabilities detected at startup. Key changes: - Add parameter-aware tier detection for work item types (EPIC, OBJECTIVE, KEY_RESULT, REQUIREMENT) using toolArgs inspection - Remove tier-features.ts and its static mapping approach - Add FEATURE_METADATA map with feature info, alternatives, docs - Update handleGitLabError signature to accept toolArgs for context - Fix handlers.ts to pass toolArgs to error handling This fixes the incorrect browse_work_items:epic matching where EPIC is a work item TYPE (parameter), not an action name.

Copilot

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated 1 comment.

src/utils/error-handler.ts

Remove obsolete reference to deleted TierFeature interface.

Copilot

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated 1 comment.

src/utils/error-handler.ts

Import InternalTier from GitLabVersionDetector (lowercase) and keep local GitLabTier for display (capitalized). Clarify the relationship in normalizeTier function signature and comments.

Copilot

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated no new comments.

## [6.18.0](v6.17.0...v6.18.0) (2026-01-21) ### Features * **errors:** add structured error handling with tier awareness ([#75](#75)) ([2b5088c](2b5088c)), closes [#50](#50) [#50](#50) * **mrs:** implement GitLab Suggestions API integration ([#70](#70)) ([b9ca090](b9ca090)), closes [#66](#66) * **tiers:** add action-level tier requirements for consolidated tools ([#77](#77)) ([8e5ae0e](8e5ae0e)), closes [#48](#48)

polaz added 2 commits January 20, 2026 23:10

polaz requested review from Copilot and removed request for Copilot January 20, 2026 21:13

Copilot started reviewing on behalf of polaz January 20, 2026 21:23 View session

Copilot started reviewing on behalf of polaz January 20, 2026 21:27 View session

Copilot AI reviewed Jan 20, 2026

View reviewed changes

polaz requested a review from Copilot January 20, 2026 21:49

Copilot started reviewing on behalf of polaz January 20, 2026 21:51 View session

Copilot AI reviewed Jan 20, 2026

View reviewed changes

polaz added 2 commits January 21, 2026 00:08

refactor(tests): remove unused result variable in handlers test

f6b8790

polaz requested a review from Copilot January 20, 2026 22:12

Copilot AI reviewed Jan 20, 2026

View reviewed changes

polaz requested a review from Copilot January 20, 2026 23:27

Copilot AI reviewed Jan 20, 2026

View reviewed changes

Copilot started reviewing on behalf of polaz January 21, 2026 00:55 View session

Copilot started reviewing on behalf of polaz January 21, 2026 00:56 View session

polaz requested a review from Copilot January 21, 2026 06:40

Copilot started reviewing on behalf of polaz January 21, 2026 06:40 View session

Copilot AI reviewed Jan 21, 2026

View reviewed changes

src/utils/tier-features.ts Outdated Show resolved Hide resolved

src/utils/tier-features.ts Outdated Show resolved Hide resolved

src/utils/tier-features.ts Outdated Show resolved Hide resolved

polaz requested a review from Copilot January 21, 2026 06:58

Copilot started reviewing on behalf of polaz January 21, 2026 06:58 View session

Copilot AI reviewed Jan 21, 2026

View reviewed changes

polaz added 5 commits January 21, 2026 09:11

ci: trigger workflow rerun after stuck runner

4861f2f

Merge branch 'main' into feat/50-structured-errors

11359be

fix(ci): remove duplicate permissions block in ci-cd.yml

8c91022

fix(logger): disable pino-pretty transport in test environment

816860d

Pino-pretty uses worker threads via thread-stream which prevents Jest from exiting properly. Disable transport when running tests (detected via NODE_ENV=test or JEST_WORKER_ID).

fix(test): preserve fs module functions for pino/sonic-boom in fetch …

16e5a43

…coverage test The fs mock was too aggressive and broke pino logger which uses sonic-boom internally. Now the mock preserves actual fs functions for node_modules paths.

github-advanced-security bot found potential problems Jan 21, 2026

View reviewed changes

tests/unit/utils/fetch.coverage.test.ts Dismissed Show dismissed Hide dismissed

polaz requested a review from Copilot January 21, 2026 10:40

Copilot started reviewing on behalf of polaz January 21, 2026 10:41 View session

Copilot AI reviewed Jan 21, 2026

View reviewed changes

src/utils/error-handler.ts Outdated Show resolved Hide resolved

refactor(errors): simplify tier check and document TLS security

3c352f7

- Remove redundant tierFeature.tier !== "Free" check (TIER_FEATURES map only contains Premium/Ultimate entries) - Add security documentation for TLS certificate validation opt-in

polaz requested a review from Copilot January 21, 2026 10:58

Copilot started reviewing on behalf of polaz January 21, 2026 10:59 View session

Copilot AI reviewed Jan 21, 2026

View reviewed changes

src/utils/tier-features.ts Outdated Show resolved Hide resolved

polaz requested a review from Copilot January 21, 2026 11:29

Copilot started reviewing on behalf of polaz January 21, 2026 11:30 View session

Copilot AI reviewed Jan 21, 2026

View reviewed changes

src/utils/error-handler.ts Outdated Show resolved Hide resolved

docs(errors): update TierAlternative interface docs

65de30e

Remove obsolete reference to deleted TierFeature interface.

polaz requested a review from Copilot January 21, 2026 11:44

Copilot started reviewing on behalf of polaz January 21, 2026 11:45 View session

Copilot AI reviewed Jan 21, 2026

View reviewed changes

src/utils/error-handler.ts Show resolved Hide resolved

refactor(errors): distinguish internal and display GitLabTier types

d8a55e1

Import InternalTier from GitLabVersionDetector (lowercase) and keep local GitLabTier for display (capitalized). Clarify the relationship in normalizeTier function signature and comments.

polaz requested a review from Copilot January 21, 2026 11:55

Copilot started reviewing on behalf of polaz January 21, 2026 11:56 View session

Copilot AI reviewed Jan 21, 2026

View reviewed changes

polaz merged commit 2b5088c into main Jan 21, 2026
22 checks passed

polaz deleted the feat/50-structured-errors branch January 21, 2026 11:59

sw-release-bot bot mentioned this pull request Mar 29, 2026

chore(main): release gitlab-mcp 7.0.0 #368

Open

Conversation

polaz commented Jan 20, 2026

Summary

Features

Example Structured Error Response

Test plan

Uh oh!

github-actions bot commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 Test Coverage Report

Coverage Details

Uh oh!

codecov bot commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

github-actions bot commented Jan 20, 2026 •

edited

Loading

codecov bot commented Jan 20, 2026 •

edited

Loading