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. Docker and Docker Compose (for n8n service)
4. Access to GitLab API (API token required)
5. Model Context Protocol compatible client

Installation

MCP Server

npm install

n8n (Docker Only)

Important: n8n is now exclusively installed and run via Docker. NPM-based n8n installations are no longer supported. If you previously had n8n installed via npm, please:

1. Uninstall the npm version:

   npm uninstall n8n

2. Use Docker Compose to run n8n:

   docker compose up -d n8n

See Docker Setup section below for details.

Configuration

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

# GitLab Configuration
GITLAB_TOKEN=********
GITLAB_URL=https://your-gitlab-instance.com
GITLAB_PROJECT_NAME=your_default_project_name
GITLAB_USERNAME=your_gitlab_username

# API Configuration
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=********

# Local CLI Execution Configuration (Optional)
CLI_STRICT_MODE=false                    # Set to 'true' to only allow whitelisted commands
CLI_ALLOWED_COMMANDS=git,npm,node,ls     # Comma-separated list of allowed commands (only used in strict mode)
CLI_MAX_TIMEOUT=300000                   # Maximum timeout in milliseconds (default: 300000 = 5 minutes)
CLI_DEFAULT_TIMEOUT=30000                # Default timeout in milliseconds (default: 30000 = 30 seconds)
CLI_MAX_OUTPUT_SIZE=1048576              # Maximum output size in bytes (default: 1048576 = 1MB)

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

Docker Setup

Running Services with Docker Compose

To start all services including the n8n workflow automation platform:

docker compose up -d

To start only the n8n service:

docker compose up -d n8n

To stop all services:

docker compose down

To view n8n logs:

docker compose logs -f n8n

n8n Service

• Access: http://localhost:5678
• User: Configured in n8n/.env file
• Data Volume: n8n_data (persisted between restarts)

Setup Instructions:

1. Copy the environment template:

   cp n8n/.env.example n8n/.env

2. Configure your encryption key in n8n/.env:

   • If migrating from npm-based n8n, get the key from your original ~/.n8n/config file
   • If fresh install, generate one: openssl rand -base64 32

3. Start the service:

   docker compose up -d n8n

4. Access at http://localhost:5678 and complete the setup wizard

Backup & Restore:

# Backup n8n data
./scripts/n8n-backup.sh

# Restore from backup
./scripts/n8n-restore.sh

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

AI Assistant Tools

copilot-cli-execute

Execute GitHub Copilot CLI commands to interact with AI models (GPT-4, GPT-3.5) for questions, explanations, and code assistance.

Prerequisites: GitHub Copilot CLI must be installed:

npm install -g @githubnext/github-copilot-cli
# OR
brew install github-copilot-cli

• Parameters:

  • prompt (string, required) - Question or prompt to send to the AI model
  • model (enum, optional) - AI model: 'gpt-4.1' (default), 'gpt-4', 'gpt-3.5-turbo'
  • timeout (number, optional) - Timeout in milliseconds (default: 30000ms, max: 300000ms)
  • format (enum, optional) - Response format: 'concise' (default) or 'detailed'

• Common Use Cases:

  • Ask questions: "what weather today in HCM city?"
  • Get code help: "how to use async/await in TypeScript?"
  • Explain concepts: "explain Docker containers"
  • Generate code: "create a React component for user login"

• Example (MCP):

  {
    "prompt": "what weather today in HCM city?",
    "model": "gpt-4.1",
    "format": "concise"
  }

• Example (REST API):

  curl -X POST http://localhost:3002/api/copilot-cli-execute \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "explain async/await in JavaScript",
      "model": "gpt-4.1",
      "format": "detailed"
    }'

• Response Time: AI queries typically take 10-30 seconds depending on complexity.

copilot-diff-analyzer

Analyzes Git diffs to determine if they contain enough context for thorough code review or if full file content is needed.

Prerequisites: GitHub Copilot CLI must be installed (same as above).

• Parameters:

  • filePath (string, required) - File path being analyzed (e.g., 'src/LoginViewModel.kt')
  • diffContent (string, required) - Git diff content to analyze
  • model (enum, optional) - AI model: 'gpt-4.1' (default), 'gpt-4', 'gpt-3.5-turbo'
  • timeout (number, optional) - Timeout in milliseconds (default: 120000ms = 2 minutes, max: 300000ms = 5 minutes)

• Output Format: DIFF_SUFFICIENT - filepath or NEED_FULL_FILE - filepath

• Use Cases:

  • Pre-screening diffs before code review
  • Determining which files need full content
  • Optimizing code review workflows
  • Batch analyzing multiple file diffs

• Example (REST API):

  curl -X POST http://localhost:3002/api/copilot-diff-analyzer \
    -H "Content-Type: application/json" \
    -d '{
      "filePath": "src/LoginViewModel.kt",
      "diffContent": "diff --git a/src/LoginViewModel.kt...",
      "model": "gpt-4.1"
    }'

copilot-code-reviewer

Performs comprehensive AI-powered code reviews for iOS (Swift/RxSwift) and Android (Kotlin/Java) with focus on memory leaks, architecture patterns, and best practices.

Prerequisites: GitHub Copilot CLI must be installed (same as above).

• Parameters:

  • platform (enum, required) - Platform: 'ios' or 'android'
  • filePath (string, required) - File path being reviewed
  • codeContent (string, required) - Complete file content or diff to review
  • reviewType (enum, optional) - Review focus: 'full' (default), 'diff', 'architecture', 'memory', 'security'
  • model (enum, optional) - AI model: 'gpt-4.1' (default), 'gpt-4', 'gpt-3.5-turbo'
  • timeout (number, optional) - Timeout in milliseconds (default: 120000ms = 2 minutes, max: 300000ms = 5 minutes)

• Review Focus:

  • 🔴 CRITICAL: Crashes, memory leaks, data loss
  • 🟠 HIGH: Security issues, performance problems
  • 🟡 MEDIUM: Best practice violations
  • 🔵 LOW: Style, naming improvements

• Platforms Supported:

  • iOS: Swift, RxSwift, UIKit, SwiftUI, MVVM, Clean Architecture
  • Android: Kotlin, Java, Coroutines, RxJava, MVVM, MVI, Clean Architecture

• Example (REST API):

  curl -X POST http://localhost:3002/api/copilot-code-reviewer \
    -H "Content-Type: application/json" \
    -d '{
      "platform": "android",
      "filePath": "src/LoginViewModel.kt",
      "codeContent": "class LoginViewModel : ViewModel() {...}",
      "reviewType": "full",
      "model": "gpt-4.1"
    }'

• Response Time: Analysis/reviews typically take 30-120 seconds depending on file size and complexity. Default timeout is 2 minutes (can be extended to 5 minutes).

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