README.md•7.72 kB
# 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:
```mermaid
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):
```json
{
"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`
```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):
```json
{
"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
```bash
# 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:
```bash
make demo
```
Sample output (truncated):
```json
{"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.