prd.md•4.86 kB
# PRD – MCP GitLab + Jira Server (Easy Install MVP)
## Purpose
Provide a plug-and-play **Model Context Protocol (MCP) server** that integrates with **GitLab** and **Jira** to bring project and issue data into AI-assisted workflows (e.g. within VS Code and Cline). The goal is minimal friction: after installation the user only needs to supply service URLs and API tokens.
## Objectives
- **Read-only access to GitLab and Jira:** enable AI tools to query lists of projects, merge requests and issues without writing or deleting anything.
- **Easy installation:** available via NPM or Docker with no build or setup scripts required.
- **Quick configuration:** tokens and URLs can be specified through environment variables or a single JSON config file.
- **Future-proof design:** modular code base that can later be extended to support write operations and other services.
## Scope (MVP)
### GitLab
- **Authentication:** use the GitLab instance URL and a personal access token.
- **Tools:**
- `gitlab_list_projects` – return all projects accessible to the user.
- `gitlab_list_merge_requests` – list merge requests for a project with optional status filter (open/closed/merged).
- `gitlab_list_issues` – list issues for a given project.
### Jira
- **Authentication:** use the Jira base URL and a Jira API token.
- **Tools:**
- `jira_search_issues` – run a JQL query to retrieve issues.
- `jira_get_issue` – fetch detailed information for a specific issue key.
## Out of Scope (MVP)
- No graphical user interface – the server is headless and only implements the MCP protocol.
- No write operations such as creating or updating issues or approving merge requests.
- No pipeline, webhook or sprint reporting features.
## Installation Requirements
- **NPM package:**
```bash
npm install -g mcp-gitlab-jira
mcp-gitlab-jira --help
```
- **Docker image:**
```bash
docker run -e GITLAB_URL=... -e GITLAB_TOKEN=... -e JIRA_URL=... -e JIRA_TOKEN=... ghcr.io/yourorg/mcp-gitlab-jira
```
## Configuration
The server can be configured using either environment variables or a configuration file.
### Option A: Environment variables
```bash
export GITLAB_URL="https://gitlab.com"
export GITLAB_TOKEN="<your-token>"
export JIRA_URL="https://company.atlassian.net"
export JIRA_TOKEN="<your-token>"
```
### Option B: JSON config file
Create a file at `~/.mcp-gitlab-jira.json` containing:
```json
{
"gitlab": { "url": "https://gitlab.com", "token": "<your-token>" },
"jira": { "url": "https://company.atlassian.net", "token": "<your-token>" }
}
```
## Usage Flow
1. **Install** the server globally via NPM or run it as a Docker container.
2. **Configure** your credentials using environment variables or the JSON file.
3. **Launch** the server by running the `mcp-gitlab-jira` command; it will start listening for MCP requests.
4. **Register** the server in your MCP-enabled client (such as VS Code or Cline) by adding an entry like:
```json
{
"servers": {
"gitlab-jira": {
"command": "mcp-gitlab-jira"
}
}
}
```
5. **Query** GitLab and Jira through the exposed tools (e.g. `gitlab_list_projects`, `jira_search_issues`) from within the client.
## Functional Requirements
- **Server lifecycle:** runs as a CLI exposing an MCP endpoint via standard input/output or HTTP.
- **Authentication:** securely reads tokens from environment variables or the configuration file; tokens must never be logged or hard-coded.
- **Error handling:** returns structured MCP error responses when the GitLab or Jira APIs return errors or invalid data.
- **Performance:** able to list up to 100 issues or merge requests in under two seconds.
## Non-Functional Requirements
- **Security:** sensitive tokens are loaded at runtime but never written to logs or returned in responses.
- **Portability:** the CLI works on Linux, macOS and Windows and can run in a containerised environment.
- **Extensibility:** the code base is modular so that write operations and additional services (e.g. pipelines, sprint reporting) can be added in later phases.
## Deliverables
1. **NPM package** `mcp-gitlab-jira` published to a public registry for global installation.
2. **Docker image** hosted on a container registry.
3. A **README** explaining installation, configuration, and usage, along with example MCP client configuration and commands.
4. **Example client configuration** for VS Code/Cline showing how to register the MCP server.
## Roadmap
- **Phase 1 (MVP):** implement the read-only GitLab and Jira tools defined in this PRD with easy installation and configuration.
- **Phase 2:** add write capabilities such as creating issues or comments and approving merge requests.
- **Phase 3:** support advanced features like pipeline status retrieval, Jira sprint reporting and notifications.