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:
startJsonRpcStdiocatches errors, maps viatoMcpError, and returns{ error: { code: -32000, message, data } }. - Redaction:
sanitizeand 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_TOKENJIRA_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" }
- Input:
-
GitLab: list projects
- Input:
{ "jsonrpc": "2.0", "id": 2, "method": "mcp.tools.call", "params": { "name": "gitlab_list_projects", "args": {} } }
- Input:
-
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" } } }
- Input:
-
GitLab: list issues
- Input:
{ "jsonrpc": "2.0", "id": 4, "method": "mcp.tools.call", "params": { "name": "gitlab_list_issues", "args": { "projectId": 123 } } }
- Input:
-
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 } } }
- Input:
-
Jira: get issue
- Input:
{ "jsonrpc": "2.0", "id": 6, "method": "mcp.tools.call", "params": { "name": "jira_get_issue", "args": { "key": "TEST-123" } } }
- Input:
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 dependenciesmake build: Compile TypeScript todist/make test: Run tests with coveragemake test-watch: Run tests in watch modemake lint/make lint-fix: Check/fix lint issuesmake format/make format-check: Apply/check formattingmake check: Run lint, format-check, and testsmake run: Start the server (uses compiled dist or tsx fallback)make list: Send mcp.tools.list via JSON-RPCmake rpc METHOD=... PARAMS='{}': Send arbitrary JSON-RPCmake demo: Build and run the demo JSONL requestsmake docker-build IMAGE=...: Build Docker imagemake 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 remotemake push-all REMOTE=gitlab: Push all branches to the specified remotemake 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.
- Sensitive tokens and headers are replaced with