What is Polarionmcpservers

PolarionMcpServers is a set of Model Context Protocol (MCP) server implementations designed for integration with Polarion Application Lifecycle Management (ALM). It facilitates the management of Polarion work items through a standardized protocol.

Use cases

Use cases for PolarionMcpServers include automating the retrieval of work items from Polarion, integrating Polarion with other development tools, and enhancing collaboration within teams by providing a centralized access point for work item data.

How to use

To use PolarionMcpServers, set up a directory for configuration and logs on your Linux server, pull the Docker image, create a tailored appsettings.json file with your Polarion configuration, and run the Docker container. Access the server via the specified URL.

Key features

Key features include the ability to read Polarion work items, support for both server-based and local workstation installations, and configuration options for logging and server connection settings.

Where to use

PolarionMcpServers can be used in software development environments that utilize Polarion for Application Lifecycle Management, particularly in organizations that require integration of work item management with other tools.

Polarion MCP Servers

This repository contains Model Context Protocol (MCP) server implementations for Polarion Application Lifecycle Management (ALM) integration.

MCP Tools are available for Polarion work items, including:

• get_text_for_workitems_by_id: Gets the main text content for specified WorkItem IDs.
• get_documents: Lists documents in the project, optionally filtered by title.
• get_documents_by_space_names: Lists documents within specified space names.
• get_space_names: Lists all available space names in the project.
• search_workitems_in_document: Searches for WorkItems within a document based on text criteria.
• get_configured_custom_fields: Retrieves the list of custom fields configured for a specific WorkItem type ID, based on the current project’s settings.
• list_configured_workitem_types: Lists all WorkItem type IDs that have custom field configurations defined in the current project’s settings.
• get_custom_fields_for_workitems: Retrieves specified custom field values for a given list of WorkItem IDs.

Projects

• PolarionRemoteMcpServer: SSE-based MCP server for server based installations
• PolarionMcpServer: Console-based MCP server for Polarion integration for local workstation installations

Running via Docker & Linux Server (Recommended)

1. From your Linux server, create a directory for your configuration and logs:

   mkdir -p /opt/polarion-mcp-server
   cd /opt/polarion-mcp-server
   

2. Pull the Docker image:

   docker pull peakflames/polarion-remote-mcp-server
   

3. Create a tailored /opt/polarion-mcp-server/appsettings.json file to your Polarion configuration:

   {
     "Logging": {
       "LogLevel": {
         "Default": "Information",
         "Microsoft.AspNetCore": "Warning"
       }
     },
     "AllowedHosts": "*",
     "PolarionProjects": [
       {
         "ProjectUrlAlias": "starlight",
         "Default": true,
         "SessionConfig": {
           "ServerUrl": "https://polarion.int.mycompany.com/",
           "Username": "shared_user_read_only",
           "Password": "linear-Vietnam-FLIP-212824",
           "ProjectId": "Starlight_Main",
           "TimeoutSeconds": 60
         },
         "PolarionWorkItemTypes": [
           {
             "id": "requirement",
             "fields": [
               "custom_field_1",
               "priority",
               "severity"
             ]
           },
           {
             "id": "defect",
             "fields": [
               "defect_type",
               "found_in_build"
             ]
           }
         ]
       },
       {
         "ProjectUrlAlias": "octopus",
         "Default": false,
         "SessionConfig": {
           "ServerUrl": "https://polarion.int.mycompany.com/",
           "Username": "some_other_user",
           "Password": "linear-Vietnam-FLIP-212824",
           "ProjectId": "octopus_gov",
           "TimeoutSeconds": 60
         }
       },
       {
         "ProjectUrlAlias": "grogu",
         "Default": false,
         "SessionConfig": {
           "ServerUrl": "https://polarion-dev.int.mycompany.com/",
           "Username": "vader",
           "Password": "12345",
           "ProjectId": "grogu_boss",
           "TimeoutSeconds": 60
         }
       }
     ]
   }
   

4. Run the Docker container:

   docker run -d \
     --name polarion-mcp-server \
     -p 8080:8080 \
     -v appsettings.json:/app/appsettings.json \
     peakflames/polarion-remote-mcp-server
   

5. The server should now be running. MCP clients will connect using a URL specific to the desired project configuration alias: http://{{your-server-ip}}:8080/{ProjectUrlAlias}/sse.

6. 📢IMPORTANT - Do NOT run with replica instances of the server as the session connection will not be shared between replicas.

Configuration Options (appsettings.json)

The server uses a PolarionProjects array in appsettings.json to define one or more Polarion instance configurations. Each object in the array represents a distinct configuration accessible via a unique URL alias.

Top-Level Setting	Description
PolarionProjects	(Array) Contains one or more Polarion project configuration objects.

Each Project Configuration Object:

Setting	Description	Required	Default
ProjectUrlAlias	A unique string used in the connection URL (/{ProjectUrlAlias}/sse) to identify this configuration.	Yes	N/A
Default	(boolean) If true, this configuration is used if the client connects without specifying a ProjectUrlAlias. Only one entry can be true.	No	false
SessionConfig	(Object) Contains the specific connection details for this Polarion instance.	Yes	N/A
PolarionWorkItemTypes	(Array, Optional) Defines custom fields to retrieve for specific WorkItem types within this project. Each object in the array should have an id (string, WorkItem type ID) and fields (array of strings, custom field names).	No	Empty List

SessionConfig Object Details:

Setting	Description	Required	Default
ServerUrl	URL of the Polarion server (e.g., “https://polarion.example.com/”)	Yes	N/A
Username	Polarion username with appropriate permissions.	Yes	N/A
Password	Password for the Polarion user. (Consider secure alternatives)	Yes	N/A
ProjectId	The actual ID of the Polarion project to interact with.	Yes	N/A
TimeoutSeconds	Connection timeout in seconds.	No	60

Note: It is strongly recommended to use more secure methods for storing credentials (like User Secrets, Azure Key Vault, etc.) rather than placing plain text passwords in appsettings.json.

Configuring MCP Clients

To configure Cline:

1. Open Cline’s MCP settings UI
2. Click the “Remote Servers” tab
3. For each ProjectUrlAlias in your appsettings.json that the user wants to connect to:

1. Repeat for each ProjectUrlAlias you want to connect to.

To configure Visual Studio Code:

Add the following configuration to your settings.json file:

To Claude Desktop:

Claude Desktop currently doesn’t support SSE, but you can use a proxy with the following addition to the claude_desktop_config.json file:

Building the Projects

Prerequisites

• .NET 9.0 SDK or later
• Docker (for container deployment)

Building Locally

To build the projects locally:

dotnet build PolarionMcpServers.sln

Building Docker Image

1. Roll the version and image tag by setting the Version & ContainerImageTag properties in PolarionRemoteMcpServer/PolarionRemoteMcpServer.csproj
2. Build the project and image locally:

dotnet publish PolarionRemoteMcpServer/PolarionRemoteMcpServer.csproj /t:PublishContainer -r linux-x64 

Publishing to a Docker Registry

1. Roll the version and image tag by setting the Version & ContainerImageTag properties in PolarionRemoteMcpServer/PolarionRemoteMcpServer.csproj
2. Build the project and image and publish to your Docker registry:

dotnet publish PolarionRemoteMcpServer/PolarionRemoteMcpServer.csproj /t:PublishContainer -r linux-x64 
docker push peakflames/polarion-remote-mcp-server:{{VERSION}}

Debugging the SSE MCP Server

1. Start the MCP Server project
2. From a terminal, run npx @modelcontextprotocol/inspector
3. From you browser, navigate to http://localhost:{{PORT}}
4. Configure the inspector to connect to the server
   i. TransportType: SSE
   i. URL: http://{{your-server-ip}}:5090/{ProjectUrlAlias}/sse