MCP GitLab + Jira (MVP)

This repository implements a read‑only Model Context Protocol (MCP) server that integrates with GitLab and Jira to expose project, merge request, and issue data to MCP‑enabled clients (e.g., editors or AI tools). It focuses on easy setup (env vars or a small JSON config), safety (no write actions in MVP), and a modular design that’s ready for future expansion.

How it’s built

• TypeScript with adapters for GitLab/Jira using a small HTTP helper (timeouts, retries, backoff) and structured logs with redaction.
• JSON‑RPC over stdio transport with tools listing and dispatch.
• Zod schemas validate inputs/outputs; errors are mapped via AppError into structured responses.
• Tests cover config, tool validation, adapters (mocked HTTP), and error sanitization.

Project history & planning

• Developer log: see developers_log.md for a step‑by‑step record of branches, changes, and merges.
• Task list: see task_list.md for current status and roadmap.

Architecture

High‑level components and request flow:

sequenceDiagram
  participant C as MCP Client
  participant S as MCP Server (CLI)
  participant T as Tools/Handlers
  participant G as GitLab API
  participant J as Jira API

  C->>S: JSON‑RPC (mcp.tools.call)
  S->>T: Validate + dispatch (Zod)
  alt GitLab tool
    T->>G: REST (GET, paginated)
    G-->>T: JSON data
  else Jira tool
    T->>J: REST (GET, paginated)
    J-->>T: JSON data
  end
  T-->>S: Result (sanitized)
  S-->>C: JSON‑RPC result

  note over S,T: Logs are structured JSON with redaction

Module Map

• src/cli.ts: CLI entry; parses flags, loads config, starts server; uses structured logging.
• src/mcp/jsonrpc.ts: Line‑delimited JSON‑RPC over stdio; parses requests and writes responses.
• src/mcp/server.ts: Wires adapters and tools; exposes tools.list and tools.call.
• src/tools/index.ts: Tool handlers; validates inputs/outputs with Zod; maps validation errors.
• src/adapters/gitlab.ts / src/adapters/jira.ts: Service clients with pagination and robust HTTP.
• src/lib/http.ts: requestJson with timeouts, retries, backoff; logs requests/responses with redaction.
• src/lib/errors.ts: AppError and toMcpError; sanitization.
• src/lib/log.ts: JSON structured logger with redaction.
• src/schemas/*.ts: Zod schemas for tool IO and schema metadata transformer.
• scripts/*: Demo JSONL requests and helper runner.
• tests/*: Unit tests for config, tools, adapters, and errors.

Error Propagation

• Validation: Zod throws; handlers wrap into AppError('INVALID_INPUT', ...) → transported as JSON‑RPC error data.
• Config: Missing/invalid config raises AppError('CONFIG_MISSING', ...) before server start.
• Upstream: Adapters throw AppError('UPSTREAM_HTTP_ERROR', ...) with status; HTTP helper retries on 429/5xx or timeouts.
• Transport: startJsonRpcStdio catches errors, maps via toMcpError, and returns { error: { code: -32000, message, data } }.
• Redaction: sanitize and logger redact tokens/headers and strip URL query params in logs.

Example JSON‑RPC error (shape):

{
  "jsonrpc": "2.0",
  "id": 7,
  "error": {
    "code": -32000,
    "message": "Invalid input",
    "data": { "code": "INVALID_INPUT", "message": "projectId is required" }
  }
}

Install (dev)

• make install
• make build
• make run

Configure

• Env vars:
  • GITLAB_URL, GITLAB_TOKEN
  • JIRA_URL, JIRA_TOKEN
• Or JSON: ~/.mcp-gitlab-jira.json

{
  "gitlab": { "url": "https://gitlab.com", "token": "<token>" },
  "jira": { "url": "https://company.atlassian.net", "token": "<email:api_token>" }
}

Tools

• gitlab_list_projects
• gitlab_list_merge_requests
• gitlab_list_issues
• jira_search_issues
• jira_get_issue

Note: This MVP includes server/adapters stubs; transport wiring will evolve.

MCP Client Config

Add the server to your MCP-enabled client configuration (example):

{
  "servers": {
    "gitlab-jira": {
      "command": "mcp-gitlab-jira"
    }
  }
}

Then invoke tools like gitlab_list_projects or jira_search_issues from your client.

Tool Examples

Assuming env is set and the server runs via stdio, these JSON-RPC lines illustrate usage.

Tools Overview

• gitlab_list_projects: List projects accessible to the token. Example args: {}

• gitlab_list_merge_requests: List MRs for a project; optional state. Example args: { "projectId": 123, "state": "opened" }

• gitlab_list_issues: List issues for a project. Example args: { "projectId": 123 }

• jira_search_issues: Search via JQL; supports maxResults. Example args: { "jql": "project=TEST", "maxResults": 10 }

• jira_get_issue: Get a Jira issue by key. Example args: { "key": "TEST-123" }

• List tools

  • Input: { "jsonrpc": "2.0", "id": 1, "method": "mcp.tools.list" }

• GitLab: list projects

  • Input: { "jsonrpc": "2.0", "id": 2, "method": "mcp.tools.call", "params": { "name": "gitlab_list_projects", "args": {} } }

• GitLab: list merge requests (opened)

  • Input: { "jsonrpc": "2.0", "id": 3, "method": "mcp.tools.call", "params": { "name": "gitlab_list_merge_requests", "args": { "projectId": 123, "state": "opened" } } }

• GitLab: list issues

  • Input: { "jsonrpc": "2.0", "id": 4, "method": "mcp.tools.call", "params": { "name": "gitlab_list_issues", "args": { "projectId": 123 } } }

• Jira: search issues (JQL)

  • Input: { "jsonrpc": "2.0", "id": 5, "method": "mcp.tools.call", "params": { "name": "jira_search_issues", "args": { "jql": "project=TEST ORDER BY updated DESC", "maxResults": 10 } } }

• Jira: get issue

  • Input: { "jsonrpc": "2.0", "id": 6, "method": "mcp.tools.call", "params": { "name": "jira_get_issue", "args": { "key": "TEST-123" } } }

Makefile quick commands

# List tools
make list

# Call a tool
make rpc METHOD="mcp.tools.call" \
  PARAMS='{"name":"gitlab_list_projects","args":{}}'

Demo Script

• Batch example requests are in scripts/requests.jsonl (newline-delimited JSON).
• Run them against the server:

make demo

Sample output (truncated):

{"jsonrpc":"2.0","id":1,"result":[
  {"name":"gitlab_list_projects","params":{"type":"object","properties":{}},"result":{"type":"array"}},
  {"name":"gitlab_list_merge_requests","params":{"type":"object","properties":{"projectId":{},"state":{}}},"result":{"type":"array"}}
]}
{"jsonrpc":"2.0","id":2,"result":[{"id":123,"name":"example"}]} 
{"jsonrpc":"2.0","id":3,"result":{"issues":[{"key":"TEST-1"}]}}

Makefile

• make install: Install dependencies
• make build: Compile TypeScript to dist/
• make test: Run tests with coverage
• make test-watch: Run tests in watch mode
• make lint / make lint-fix: Check/fix lint issues
• make format / make format-check: Apply/check formatting
• make check: Run lint, format-check, and tests
• make run: Start the server (uses compiled dist or tsx fallback)
• make list: Send mcp.tools.list via JSON-RPC
• make rpc METHOD=... PARAMS='{}': Send arbitrary JSON-RPC
• make demo: Build and run the demo JSONL requests
• make docker-build IMAGE=...: Build Docker image
• make docker-run IMAGE=...: Run Docker container (requires env vars)
• make add-remote NAME=gitlab REMOTE_URL=git@gitlab.com:group/repo.git: Add or update a git remote
• make push-all REMOTE=gitlab: Push all branches to the specified remote
• make push-tags REMOTE=gitlab: Push all tags to the specified remote

Logging

• Control verbosity with LOG_LEVEL (debug, info, warn, error). Default: info.
• Logs are structured JSON lines with redaction:
  • Sensitive tokens and headers are replaced with ***.
  • URLs in HTTP logs omit query parameters.