MCP Server (TypeScript)

The MCP Server connects AI tools directly to Payoo's GitLab and API platform. This enables AI agents, assistants, and chatbots to read repositories, manage issues, automate workflows, and interact with custom APIs—all through natural language.

Overview

A Model Context Protocol (MCP) server implementation in TypeScript for Payoo mobile development workflows. This server provides tools for GitLab integration, API interactions, and development utilities to enhance mobile app development productivity.

Use Cases

• Repository Management: Browse and query code, search files, analyze commits, and understand project structure across PayooMobile repositories.
• Issue & MR Automation: Create, update, and manage issues and merge requests. Automate triage, review code changes, and maintain project boards.
• CI/CD & Workflow Intelligence: Monitor pipeline runs, analyze build failures, manage releases, and get insights into your development pipeline.
• Code Analysis: Review code, analyze security findings, and get insights into your codebase.
• Team Collaboration: Access discussions, manage notifications, analyze team activity, and streamline processes for your team.

Prerequisites

1. Node.js 18+ and npm
2. TypeScript 5.4+
3. Access to GitLab API (API token required)
4. Model Context Protocol compatible client

Installation

npm install

Configuration

Set the following environment variables in your .env file or host configuration:

GITLAB_TOKEN=********
GITLAB_URL=https://your-gitlab-instance.com
GITLAB_PROJECT_NAME=your_default_project_name
GITLAB_USERNAME=your_gitlab_username
API_MERCHANT_NAME=api_merchant_name
API_USERNAME=api_username
API_PASSWORD=********
CHECKSUM_KEY=********
SALT_APP=********
IV_APP=********
API_HOST=api_host
SECURE_STORAGE_SECRET=********

Running the Server

Development Mode

npm run dev

Production Mode

npm run build
npm start

SSE/HTTP Mode (with REST API)

npm run sse

Runs the server with SSE transport and REST API endpoints accessible at http://localhost:3002/api

With Environment Configuration

# Development with GitLab credentials
GITLAB_URL=https://gitlab.example.com \
GITLAB_TOKEN=glpat-xxx \
GITLAB_PROJECT_NAME=group/project \
npm run dev

# SSE/HTTP mode with REST API
GITLAB_URL=https://gitlab.example.com \
GITLAB_TOKEN=glpat-xxx \
MCP_PORT=3002 \
npm run sse

# With OAuth authentication
npm run sse -- --oauth              # Enable OAuth
npm run sse -- --oauth-strict       # Enable OAuth with strict resource checking

Usage

MCP Protocol

Connect your MCP-compatible client to the server via stdin/stdout or SSE. Use the available tools to automate and interact with your GitLab and API workflows.

REST API

When running in SSE mode (npm run sse), all tools are also available as REST API endpoints:

# List all available tools
curl http://localhost:3002/api/tools

# Get specific tool details
curl http://localhost:3002/api/tools/gitlab-get-issue

# Execute a tool
curl -X POST http://localhost:3002/api/gitlab-get-issue \
  -H "Content-Type: application/json" \
  -H "X-GitLab-Token: glpat-xxx" \
  -H "X-GitLab-Url: https://gitlab.example.com" \
  -d '{"projectname": "group/project", "issueIid": 123}'

# Health check
curl http://localhost:3002/api/health

See REST API Documentation and Authentication Guide for detailed REST API information.

Available MCP Tools

Issue Management Tools

gitlab-fetch-issue / gitlab-get-issue

Retrieve detailed information for a specific issue by IID.

• Parameters: issueIid (number), projectname (string, optional)
• Returns: Complete issue metadata including title, description, state, assignees, labels, milestone, due date, and time tracking

gitlab-list-issues

List all issues in a milestone with filtering and label support.

• Parameters: projectname (string, optional), milestoneName (string, optional), labels (string[], optional)
• Returns: Array of issues with complete metadata including id, iid, title, description, state, assignees, labels, milestone, due date
• Features: Filter by milestone and/or labels. Supports square brackets in parameters (e.g., '[1.0.180]', '[bug]')

gitlab-list-issues-by-assignee

Retrieve issues assigned to a specific user with advanced filtering options.

• Parameters: assigneeUsername (string, optional), projectname (string, optional), state (opened/closed/all), excludeMilestone (boolean), excludeDueDate (boolean), milestone (string), dueDate (string), labels (array), notSetLabels (array)
• Features: Advanced filtering system with exclusion capabilities

gitlab-copy-issue-to-project

Copy an issue from one project to another with relationship linking and customization options.

• Parameters:
  • fromProjectName (string) - Source project name
  • toProjectName (string) - Target project name
  • issueIid (number) - Issue IID to copy
  • assignee (string, optional) - Username to assign the copied issue to
  • milestone (string, optional) - Milestone title to assign (e.g., '1.0.180'). Supports square brackets for lookup (e.g., '[1.0.180]'). If not provided, interactive selection will be prompted
  • issueTitle (string, optional) - Custom title (defaults to source issue title)
  • issueDescription (string, optional) - Custom description (defaults to "Copied from source issue: [URL]")
  • issueLabels (string[], optional) - Custom labels (defaults to source issue labels). Supports square brackets (e.g., '[bug]')
  • relatesTo (string, optional) - Link type between source and copied issue. Options: relates_to (default), blocks, is_blocked_by
• Features: Allows title/description/label/milestone customization, automatic milestone lookup by title, creates automatic link with specified relationship type

gitlab-update-issue-due-date-and-estimate

Update due date and/or time estimate for an issue.

• Parameters: issueIid (number), projectname (string, optional), dueDate (string), timeEstimate (number), clearDueDate (boolean), clearTimeEstimate (boolean)
• Features: Date format validation and change tracking

gitlab-manage-issue

Comprehensive issue management tool for getting, closing, reopening, adding labels, setting assignees, and setting due dates.

• Parameters:
  • issueIid (number) - Issue IID - Required
  • projectname (string, optional) - Project name (defaults to GITLAB_PROJECT_NAME)
  • action (string) - Action to perform - Required. Options: get, close, reopen, add-labels, set-assignee, set-due-date
  • labels (string[], optional) - Labels to add (for add-labels action). Supports square brackets (e.g., '[bug]', '[feature]')
  • assignee (string, optional) - Username to assign (for set-assignee action)
  • dueDate (string, optional) - Due date in YYYY-MM-DD format (for set-due-date action)
• Returns: Consistent response format with status (success/failure), action (type of action), message, and detailed issue information (id, iid, title, webUrl, plus action-specific fields)
• Features: Unified interface for multiple issue operations, consistent response formatting across all actions

gitlab-move-issue-to-testing

Move an issue to Testing stage by adding 'Testing' label.

• Parameters: issueIid (number)

gitlab-find-related-issues

Retrieve all related issues and child tasks using both issue links and Work Items hierarchy.

• Parameters: issueIid (number), projectname (string, optional), linkTypes (array, optional)
• Features: Uses both REST API issue links and GraphQL Work Items, groups results by link type

gitlab-link-issues

Create a relationship link between two GitLab issues. Supports linking issues within the same project or across different projects.

• Parameters:
  • sourceProjectName (string) - Source project name (e.g., 'group/project-name')
  • sourceIssueIid (number) - Source issue IID
  • targetProjectName (string) - Target project name (e.g., 'group/project-name')
  • targetIssueIid (number) - Target issue IID
  • linkType (string, optional) - Type of relationship link. Options: 'relates_to' (default), 'blocks', 'is_blocked_by'
• Features: Verifies both issues exist before linking, supports cross-project links, provides detailed link information

Task/Work Item Management

gitlab-create-task-for-issue

Create a child task linked to a parent issue using Work Items hierarchy.

• Parameters: issueIid (number), prefix (string, optional)
• Features: Inherits assignees, labels, and milestone from parent

gitlab-close-task

Close a task by IID or GID with time tracking.

• Parameters: taskId (string), estimate (string, optional)
• Features: Adds 'Done' label automatically, records time spent, supports both IID and GID identification

Merge Request Management

gitlab-fetch-merge-request

Retrieve MR details for a specific branch.

• Parameters: branch (string)
• Returns: MR metadata, diff versions, and SHAs for code review

gitlab-list-merge-requests-by-reviewer

Retrieve all MRs where specified user is a reviewer.

• Parameters: reviewerUsername (string)

gitlab-approve-merge-request

Approve a merge request by IID.

• Parameters: mrIid (number)
• Features: Interactive project selection

gitlab-create-merge-request

Create a merge request from source to target branch.

• Parameters: sourceBranch (string), title (string), description (string), targetBranch (string, optional)
• Features: Interactive milestone selection, automatic assignee assignment, branch name normalization

gitlab-update-merge-request-description

Update merge request description.

• Parameters: mrIid (number), newDescription (string)

gitlab-review-merge-request-code

Add or update inline code review comments on merge requests at specific file and line positions.

• Parameters: projectId (number), mrIid (number), body (string), positionType (string), baseSha (string), startSha (string), headSha (string), newPath (string), newLine (number, optional), oldPath (string, optional), oldLine (number, optional)
• Features: Intelligent comment deduplication (updates existing comments at same position), precise line-level code review positioning with diff SHA references

Branch and Development Workflow

gitlab-create-branch-for-issue

Create a new branch based on an issue.

• Parameters: issueIid (number), targetBranch (string, optional)
• Features: Automatic branch naming from issue title, branch name normalization and validation

gitlab-compare-branch-diff

Get git diff between source and target branches.

• Parameters: sourceBranch (string), targetBranch (string, optional)
• Returns: Structured diff data with file paths, line numbers, and content changes

CI/CD Pipeline Management

gitlab-create-pipeline-for-branch

Create CI/CD pipeline for a specific branch with delivery options.

• Parameters: branchName (string), scheme (string, optional), recipient (string, optional), replyOnThread (string, optional), description (string, optional)
• Features: Interactive scheme and recipient selection, Slack integration for notifications, delivery-specific pipeline configuration

Project Management and Reporting

gitlab-show-milestone-progress

Retrieve latest milestone details and associated issues.

• Returns: Milestone metadata, issue counts, and complete issue list with states and assignees

gitlab-create-milestone

Create a new milestone in a GitLab project.

• Parameters:
  • projectName (string, optional) - Project name (e.g., 'group/project-name'). If not provided, interactive selection will be prompted
  • title (string) - Milestone title (e.g., 'Sprint 12', '1.0.180')
  • description (string, optional) - Milestone description (e.g., 'Milestone for feature X and bug fixes')
  • startDate (string) - Start date in YYYY-MM-DD format (e.g., '2025-10-16')
  • dueDate (string) - Due date in YYYY-MM-DD format (e.g., '2025-10-30')
• Features: Validates date formats, checks for duplicate milestone titles, returns full milestone details including web URL

gitlab-update-milestone

Update an existing milestone in a GitLab project.

• Parameters:
  • projectName (string) - Project name (e.g., 'group/project-name') - Required
  • milestoneId (number) - Milestone ID to update - Required
  • description (string, optional) - New milestone description
  • startDate (string, optional) - Start date in YYYY-MM-DD format (e.g., '2025-10-16')
  • dueDate (string, optional) - Due date in YYYY-MM-DD format (e.g., '2025-10-30')
• Features: Validates date formats, ensures at least one field is provided for update, returns updated milestone details including web URL

API Integration

api-response

Generic API endpoint caller with authentication handling.

• Parameters: endpoint (string), params (any, optional)
• Features: Automatic access token generation and refresh, handles HTTP POST requests, automatic retry on token expiration, secure storage integration

Development

Adding New Tools

1. Create tool function in appropriate file (e.g., src/tools/newTool.ts)
2. Register tool in server (src/index.ts)
3. Define input schema using Zod
4. Implement tool logic with proper error handling
5. Update README with tool documentation

Code Style

• Use TypeScript strict mode
• Follow ESLint configuration
• Use Zod for input validation
• Implement proper error handling
• Add JSDoc comments for functions

Troubleshooting

Common Issues

1. Build Errors: Ensure all dependencies are installed

   npm install

2. GitLab API Access: Verify your GITLAB_TOKEN has appropriate permissions

3. Type Errors: Check TypeScript configuration in tsconfig.json

4. Runtime Errors: Check environment variables and network connectivity

Debug Logging

Enable debug logging by setting:

DEBUG=mcp:*

Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/new-tool
3. Make changes with tests
4. Run build: npm run build
5. Submit pull request

License

This project is licensed under the MIT license. See LICENSE for details.

Related Projects

• MCP Inspector: inspector/ - Development and testing interface

Support

For issues and questions:

1. Check the troubleshooting section
2. Review the main project README
3. Create an issue in the repository
4. Contact the development team