# GitLab Pipeline Analyzer MCP Server
A FastMCP server that analyzes GitLab CI/CD pipeline failures, extracts errors and warnings from job traces, and returns structured JSON responses.
## Features
- Analyze failed GitLab CI/CD pipelines by pipeline ID
- Extract failed jobs from pipelines
- Retrieve and parse job traces
- Extract errors and warnings from logs
- Return structured JSON responses for AI analysis
- Support for Python projects with lint, test, and build stages
- Multiple transport protocols: STDIO, HTTP, and SSE
## Installation
```bash
# Install dependencies
uv pip install -e .
# Or with pip
pip install -e .
```
## Configuration
Set the following environment variables:
```bash
export GITLAB_URL="https://gitlab.com" # Your GitLab instance URL
export GITLAB_TOKEN="your-access-token" # Your GitLab personal access token
# Optional: Configure transport settings
export MCP_HOST="127.0.0.1" # Host for HTTP/SSE transport (default: 127.0.0.1)
export MCP_PORT="8000" # Port for HTTP/SSE transport (default: 8000)
export MCP_PATH="/mcp" # Path for HTTP transport (default: /mcp)
```
Note: Project ID is now passed as a parameter to each tool, making the server more flexible.
## Running the Server
The server supports three transport protocols:
### 1. STDIO Transport (Default)
Best for local tools and command-line scripts:
```bash
# Default STDIO transport
python server.py
# Or explicitly specify
python server.py --transport stdio
```
### 2. HTTP Transport
Recommended for web deployments and remote access:
```bash
# Start HTTP server
python http_server.py
# Or using the main server script
python server.py --transport http --host 127.0.0.1 --port 8000 --path /mcp
# Or using environment variables
MCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=8080 python server.py
```
The HTTP server will be available at: `http://127.0.0.1:8000/mcp`
### 3. SSE Transport
For compatibility with existing SSE clients:
```bash
# Start SSE server
python sse_server.py
# Or using the main server script
python server.py --transport sse --host 127.0.0.1 --port 8000
```
The SSE server will be available at: `http://127.0.0.1:8000`
## Using with MCP Clients
### HTTP Transport Client Example
```python
from fastmcp.client import Client
# Connect to HTTP MCP server
async with Client("http://127.0.0.1:8000/mcp") as client:
# List available tools
tools = await client.list_tools()
# Analyze a pipeline
result = await client.call_tool("analyze_pipeline", {
"project_id": "123",
"pipeline_id": "456"
})
```
### Configuration for Multiple Servers
```python
config = {
"mcpServers": {
"gitlab": {
"url": "http://127.0.0.1:8000/mcp",
"transport": "http"
}
}
}
async with Client(config) as client:
result = await client.call_tool("gitlab_analyze_pipeline", {
"project_id": "123",
"pipeline_id": "456"
})
```
## Development
### Setup
```bash
# Install dependencies
uv sync --all-extras
# Install pre-commit hooks
uv run pre-commit install
```
### Running tests
```bash
# Run all tests
uv run pytest
# Run tests with coverage
uv run pytest --cov=gitlab_analyzer --cov-report=html
# Run security scans
uv run bandit -r src/
```
### Code quality
```bash
# Format code
uv run ruff format
# Lint code
uv run ruff check --fix
# Type checking
uv run mypy src/
```
## GitHub Actions
This project includes comprehensive CI/CD workflows:
### CI Workflow (`.github/workflows/ci.yml`)
- **Triggers**: Push to `main`/`develop`, Pull requests
- **Features**:
- Tests across Python 3.10, 3.11, 3.12
- Code formatting with Ruff
- Linting with Ruff
- Type checking with MyPy
- Security scanning with Bandit
- Test coverage reporting
- Build validation
### Release Workflow (`.github/workflows/release.yml`)
- **Triggers**: GitHub releases, Manual dispatch
- **Features**:
- Automated PyPI publishing with trusted publishing
- Support for TestPyPI deployment
- Build artifacts validation
- Secure publishing without API tokens
### Security Workflow (`.github/workflows/security.yml`)
- **Triggers**: Push, Pull requests, Weekly schedule
- **Features**:
- Bandit security scanning
- Trivy vulnerability scanning
- SARIF upload to GitHub Security tab
- Automated dependency scanning
### Setting up PyPI Publishing
1. **Configure PyPI Trusted Publishing**:
- Go to [PyPI](https://pypi.org/manage/account/publishing/) or [TestPyPI](https://test.pypi.org/manage/account/publishing/)
- Add a new trusted publisher with:
- PyPI project name: `gitlab-pipeline-analyzer`
- Owner: `your-github-username`
- Repository name: `your-repo-name`
- Workflow name: `release.yml`
- Environment name: `pypi` (or `testpypi`)
2. **Create GitHub Environment**:
- Go to repository Settings → Environments
- Create environments named `pypi` and `testpypi`
- Configure protection rules as needed
3. **Publishing**:
- **TestPyPI**: Use workflow dispatch in Actions tab
- **PyPI**: Create a GitHub release to trigger automatic publishing
### Pre-commit Hooks
The project uses pre-commit hooks for code quality:
```bash
# Install hooks
uv run pre-commit install
# Run hooks manually
uv run pre-commit run --all-files
```
Hooks include:
- Trailing whitespace removal
- End-of-file fixing
- YAML/TOML validation
- Ruff formatting and linting
- MyPy type checking
- Bandit security scanning
## Usage
### Running the server
```bash
# Run with Python
python gitlab_analyzer.py
# Or with FastMCP CLI
fastmcp run gitlab_analyzer.py:mcp
```
### Available tools
1. **analyze_failed_pipeline(project_id, pipeline_id)** - Analyze a failed pipeline by ID
2. **get_pipeline_jobs(project_id, pipeline_id)** - Get all jobs for a pipeline
3. **get_job_trace(project_id, job_id)** - Get trace log for a specific job
4. **extract_log_errors(log_text)** - Extract errors and warnings from log text
5. **get_pipeline_status(project_id, pipeline_id)** - Get basic pipeline status
## Example
```python
import asyncio
from fastmcp import Client
async def analyze_pipeline():
client = Client("gitlab_analyzer.py")
async with client:
result = await client.call_tool("analyze_failed_pipeline", {
"project_id": "19133", # Your GitLab project ID
"pipeline_id": 12345
})
print(result)
asyncio.run(analyze_pipeline())
```
## Environment Setup
Create a `.env` file with your GitLab configuration:
```env
GITLAB_URL=https://gitlab.com
GITLAB_TOKEN=your-personal-access-token
```
## Development
```bash
# Install development dependencies
uv sync
# Run tests
uv run pytest
# Run linting and type checking
uv run tox -e lint,type
# Run all quality checks
uv run tox
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Author
**Siarhei Skuratovich**
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run the test suite
5. Submit a pull request
---
**Note**: This MCP server is designed to work with GitLab CI/CD pipelines and requires appropriate API access tokens.
Raw data
{
"_id": null,
"home_page": null,
"name": "gitlab-pipeline-analyzer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "gitlab, ci/cd, pipeline, analysis, mcp, fastmcp",
"author": null,
"author_email": "Siarhei Skuratovich <sOraCool@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f4/dd/19344e693e28b32a9b766d99af75a4084407288c7b8f70ebaf3385ebcc9b/gitlab_pipeline_analyzer-0.1.1.tar.gz",
"platform": null,
"description": "# GitLab Pipeline Analyzer MCP Server\n\nA FastMCP server that analyzes GitLab CI/CD pipeline failures, extracts errors and warnings from job traces, and returns structured JSON responses.\n\n## Features\n\n- Analyze failed GitLab CI/CD pipelines by pipeline ID\n- Extract failed jobs from pipelines\n- Retrieve and parse job traces\n- Extract errors and warnings from logs\n- Return structured JSON responses for AI analysis\n- Support for Python projects with lint, test, and build stages\n- Multiple transport protocols: STDIO, HTTP, and SSE\n\n## Installation\n\n```bash\n# Install dependencies\nuv pip install -e .\n\n# Or with pip\npip install -e .\n```\n\n## Configuration\n\nSet the following environment variables:\n\n```bash\nexport GITLAB_URL=\"https://gitlab.com\" # Your GitLab instance URL\nexport GITLAB_TOKEN=\"your-access-token\" # Your GitLab personal access token\n\n# Optional: Configure transport settings\nexport MCP_HOST=\"127.0.0.1\" # Host for HTTP/SSE transport (default: 127.0.0.1)\nexport MCP_PORT=\"8000\" # Port for HTTP/SSE transport (default: 8000)\nexport MCP_PATH=\"/mcp\" # Path for HTTP transport (default: /mcp)\n```\n\nNote: Project ID is now passed as a parameter to each tool, making the server more flexible.\n\n## Running the Server\n\nThe server supports three transport protocols:\n\n### 1. STDIO Transport (Default)\n\nBest for local tools and command-line scripts:\n\n```bash\n# Default STDIO transport\npython server.py\n\n# Or explicitly specify\npython server.py --transport stdio\n```\n\n### 2. HTTP Transport\n\nRecommended for web deployments and remote access:\n\n```bash\n# Start HTTP server\npython http_server.py\n\n# Or using the main server script\npython server.py --transport http --host 127.0.0.1 --port 8000 --path /mcp\n\n# Or using environment variables\nMCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=8080 python server.py\n```\n\nThe HTTP server will be available at: `http://127.0.0.1:8000/mcp`\n\n### 3. SSE Transport\n\nFor compatibility with existing SSE clients:\n\n```bash\n# Start SSE server\npython sse_server.py\n\n# Or using the main server script\npython server.py --transport sse --host 127.0.0.1 --port 8000\n```\n\nThe SSE server will be available at: `http://127.0.0.1:8000`\n\n## Using with MCP Clients\n\n### HTTP Transport Client Example\n\n```python\nfrom fastmcp.client import Client\n\n# Connect to HTTP MCP server\nasync with Client(\"http://127.0.0.1:8000/mcp\") as client:\n # List available tools\n tools = await client.list_tools()\n\n # Analyze a pipeline\n result = await client.call_tool(\"analyze_pipeline\", {\n \"project_id\": \"123\",\n \"pipeline_id\": \"456\"\n })\n```\n\n### Configuration for Multiple Servers\n\n```python\nconfig = {\n \"mcpServers\": {\n \"gitlab\": {\n \"url\": \"http://127.0.0.1:8000/mcp\",\n \"transport\": \"http\"\n }\n }\n}\n\nasync with Client(config) as client:\n result = await client.call_tool(\"gitlab_analyze_pipeline\", {\n \"project_id\": \"123\",\n \"pipeline_id\": \"456\"\n })\n```\n\n## Development\n\n### Setup\n\n```bash\n# Install dependencies\nuv sync --all-extras\n\n# Install pre-commit hooks\nuv run pre-commit install\n```\n\n### Running tests\n\n```bash\n# Run all tests\nuv run pytest\n\n# Run tests with coverage\nuv run pytest --cov=gitlab_analyzer --cov-report=html\n\n# Run security scans\nuv run bandit -r src/\n```\n\n### Code quality\n\n```bash\n# Format code\nuv run ruff format\n\n# Lint code\nuv run ruff check --fix\n\n# Type checking\nuv run mypy src/\n```\n\n## GitHub Actions\n\nThis project includes comprehensive CI/CD workflows:\n\n### CI Workflow (`.github/workflows/ci.yml`)\n- **Triggers**: Push to `main`/`develop`, Pull requests\n- **Features**:\n - Tests across Python 3.10, 3.11, 3.12\n - Code formatting with Ruff\n - Linting with Ruff\n - Type checking with MyPy\n - Security scanning with Bandit\n - Test coverage reporting\n - Build validation\n\n### Release Workflow (`.github/workflows/release.yml`)\n- **Triggers**: GitHub releases, Manual dispatch\n- **Features**:\n - Automated PyPI publishing with trusted publishing\n - Support for TestPyPI deployment\n - Build artifacts validation\n - Secure publishing without API tokens\n\n### Security Workflow (`.github/workflows/security.yml`)\n- **Triggers**: Push, Pull requests, Weekly schedule\n- **Features**:\n - Bandit security scanning\n - Trivy vulnerability scanning\n - SARIF upload to GitHub Security tab\n - Automated dependency scanning\n\n### Setting up PyPI Publishing\n\n1. **Configure PyPI Trusted Publishing**:\n - Go to [PyPI](https://pypi.org/manage/account/publishing/) or [TestPyPI](https://test.pypi.org/manage/account/publishing/)\n - Add a new trusted publisher with:\n - PyPI project name: `gitlab-pipeline-analyzer`\n - Owner: `your-github-username`\n - Repository name: `your-repo-name`\n - Workflow name: `release.yml`\n - Environment name: `pypi` (or `testpypi`)\n\n2. **Create GitHub Environment**:\n - Go to repository Settings \u2192 Environments\n - Create environments named `pypi` and `testpypi`\n - Configure protection rules as needed\n\n3. **Publishing**:\n - **TestPyPI**: Use workflow dispatch in Actions tab\n - **PyPI**: Create a GitHub release to trigger automatic publishing\n\n### Pre-commit Hooks\n\nThe project uses pre-commit hooks for code quality:\n\n```bash\n# Install hooks\nuv run pre-commit install\n\n# Run hooks manually\nuv run pre-commit run --all-files\n```\n\nHooks include:\n- Trailing whitespace removal\n- End-of-file fixing\n- YAML/TOML validation\n- Ruff formatting and linting\n- MyPy type checking\n- Bandit security scanning\n\n## Usage\n\n### Running the server\n\n```bash\n# Run with Python\npython gitlab_analyzer.py\n\n# Or with FastMCP CLI\nfastmcp run gitlab_analyzer.py:mcp\n```\n\n### Available tools\n\n1. **analyze_failed_pipeline(project_id, pipeline_id)** - Analyze a failed pipeline by ID\n2. **get_pipeline_jobs(project_id, pipeline_id)** - Get all jobs for a pipeline\n3. **get_job_trace(project_id, job_id)** - Get trace log for a specific job\n4. **extract_log_errors(log_text)** - Extract errors and warnings from log text\n5. **get_pipeline_status(project_id, pipeline_id)** - Get basic pipeline status\n\n## Example\n\n```python\nimport asyncio\nfrom fastmcp import Client\n\nasync def analyze_pipeline():\n client = Client(\"gitlab_analyzer.py\")\n async with client:\n result = await client.call_tool(\"analyze_failed_pipeline\", {\n \"project_id\": \"19133\", # Your GitLab project ID\n \"pipeline_id\": 12345\n })\n print(result)\n\nasyncio.run(analyze_pipeline())\n```\n\n## Environment Setup\n\nCreate a `.env` file with your GitLab configuration:\n\n```env\nGITLAB_URL=https://gitlab.com\nGITLAB_TOKEN=your-personal-access-token\n```\n\n## Development\n\n```bash\n# Install development dependencies\nuv sync\n\n# Run tests\nuv run pytest\n\n# Run linting and type checking\nuv run tox -e lint,type\n\n# Run all quality checks\nuv run tox\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Author\n\n**Siarhei Skuratovich**\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run the test suite\n5. Submit a pull request\n\n---\n\n**Note**: This MCP server is designed to work with GitLab CI/CD pipelines and requires appropriate API access tokens.\n",
"bugtrack_url": null,
"license": null,
"summary": "FastMCP server for analyzing GitLab CI/CD pipeline failures",
"version": "0.1.1",
"project_urls": null,
"split_keywords": [
"gitlab",
" ci/cd",
" pipeline",
" analysis",
" mcp",
" fastmcp"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6814b5530792b28231facb5d2a6b8532d5e2e9d2e9b8200b3af6086b8935c984",
"md5": "d99e3bc019b542e4ae456e09caee5363",
"sha256": "b44650ffd3cefe4ae26546726a4eaaad2beb3b61f99f2f0de460948b50df80b5"
},
"downloads": -1,
"filename": "gitlab_pipeline_analyzer-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d99e3bc019b542e4ae456e09caee5363",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 20934,
"upload_time": "2025-08-04T14:34:52",
"upload_time_iso_8601": "2025-08-04T14:34:52.555113Z",
"url": "https://files.pythonhosted.org/packages/68/14/b5530792b28231facb5d2a6b8532d5e2e9d2e9b8200b3af6086b8935c984/gitlab_pipeline_analyzer-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f4dd19344e693e28b32a9b766d99af75a4084407288c7b8f70ebaf3385ebcc9b",
"md5": "38fb3aeac06b8ac7a2dd8e55c0df7636",
"sha256": "10a202e87871187962a32617256ef5c793652923af7b6814b5aab51a7994ac1b"
},
"downloads": -1,
"filename": "gitlab_pipeline_analyzer-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "38fb3aeac06b8ac7a2dd8e55c0df7636",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 29944,
"upload_time": "2025-08-04T14:34:53",
"upload_time_iso_8601": "2025-08-04T14:34:53.813285Z",
"url": "https://files.pythonhosted.org/packages/f4/dd/19344e693e28b32a9b766d99af75a4084407288c7b8f70ebaf3385ebcc9b/gitlab_pipeline_analyzer-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-04 14:34:53",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "gitlab-pipeline-analyzer"
}
JSON