--- slug: "polarionmcpservers" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/peakflames/PolarionMcpServers@main/README.md" repo: "https://github.com/peakflames/PolarionMcpServers" source_file: "README.md" branch: "main" --- # 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_text_for_workitem_at_revision`: Gets the text content for a single WorkItem at a specific revision. - `get_details_for_workitems`: Gets detailed information for specified WorkItem IDs including status, type, assignee, custom fields, and linked work items. - `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. - `get_sections_in_document`: Gets the list of sections in a document. - `get_section_content_for_document`: Gets the content of a specific section in a document. - `search_workitems_in_document`: Searches for WorkItems within a document based on text criteria. - `list_available_custom_fields_for_workitem_types`: Lists all available custom fields for specific WorkItem types. - `list_available_workitem_types`: Lists all WorkItem types available in the project. - `get_revisions_list_for_workitem`: Gets the list of revision IDs for a specific work item, ordered from newest to oldest. - `get_revisions_content_for_workitem`: Gets the content of a work item at different revisions, including title, status, description, and other standard fields. ## Projects - **PolarionRemoteMcpServer**: (Streamable HTTP or 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: ```bash mkdir -p /opt/polarion-mcp-server cd /opt/polarion-mcp-server ``` 1. Pull the Docker image: ```bash docker pull peakflames/polarion-remote-mcp-server ``` 1. Create a tailored `/opt/polarion-mcp-server/appsettings.json` file to your Polarion configuration: ```json { "Logging": { "LogLevel": { "Default": "Information", "Microsoft.AspNetCore": "Warning" } }, "AllowedHosts": "*", "ApiConsumers": { "Consumers": { "my_app": { "Name": "My Application", "ApplicationKey": "your-secure-api-key-here", "Active": true, "AllowedScopes": ["polarion:read"], "Description": "API consumer for my application" } } }, "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 } } ] } ``` 1. Run the Docker container: ```bash docker run -d \ --name polarion-mcp-server \ -p 8080:8080 \ -v appsettings.json:/app/appsettings.json \ peakflames/polarion-remote-mcp-server ``` 1. The server should now be running. MCP clients will connect using a URL specific to the desired project configuration alias: 1. Streamable HTTP Transport: `http://{{your-server-ip}}:8080/{ProjectUrlAlias}`. 2. SSE Transport: `http://{{your-server-ip}}:8080/{ProjectUrlAlias}/sse`. 2. The server also provides: - REST API: `http://{{your-server-ip}}:8080/polarion/rest/v1/projects/{ProjectId}/...` (uses `SessionConfig.ProjectId`) - **Note:** REST API endpoints require API key authentication via `X-API-Key` header - API Documentation: `http://{{your-server-ip}}:8080/scalar/v1` (includes authentication UI) - Health Check: `http://{{your-server-ip}}:8080/api/health` 3. 📢IMPORTANT - Do NOT run with replica instances of the server as the session connection will not be shared between replicas. ### Configuration Options **Configuration Files:** - `appsettings.json` - Base configuration for production/server deployments - `appsettings.Development.json` - Overrides base settings for local development (gitignored, takes precedence in Development mode) - `.env` - Optional environment variables (copy from `.env.example`), can set `POLARION_DEFAULT_PROJECT` 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` | ### Environment Variable Password Override Instead of placing passwords in configuration files, set the `POLARION_PASSWORD` environment variable. When set, it overrides `SessionConfig.Password` for all configured projects. **Docker example:** ```bash docker run -d \ --name polarion-mcp-server \ -p 8080:8080 \ -e POLARION_PASSWORD=your-secret-password \ -v appsettings.json:/app/appsettings.json \ peakflames/polarion-remote-mcp-server ``` This works for both `PolarionRemoteMcpServer` (HTTP) and `PolarionMcpServer` (stdio). *Note: It is strongly recommended to use the `POLARION_PASSWORD` environment variable or more secure methods for storing credentials (like User Secrets, Azure Key Vault, etc.) rather than placing plain text passwords in `appsettings.json`.* ### REST API Specification Alignment The REST API is designed to align with the **official Polarion REST API** specification available at `https://testdrive.polarion.com/polarion/rest/v1/definition`. A local copy of this definition is maintained at `docs/polarion-rest-vq-definition.json` for reference when implementing or extending endpoints. ### API Key Authentication (REST API Only) REST API endpoints require authentication via API key. Configure API consumers in the `ApiConsumers` section of `appsettings.json`: | Setting | Description | Required | | ------- | ----------- | -------- | | `ApiConsumers.Consumers` | Dictionary of consumer configurations keyed by consumer ID | Yes | | `Name` | Display name for the API consumer | Yes | | `ApplicationKey` | The API key used for authentication | Yes | | `Active` | Whether the consumer is allowed to authenticate | Yes | | `AllowedScopes` | List of scopes (e.g., `["polarion:read"]`) | Yes | | `Description` | Optional description of the consumer | No | **Available Scopes:** - `polarion:read` - Read access to all REST API endpoints **Usage:** ```bash curl -H "X-API-Key: your-api-key" http://localhost:8080/polarion/rest/v1/projects/{projectId}/spaces ``` **Note:** MCP endpoints, health checks (`/api/health`, `/api/version`), and API documentation (`/scalar/v1`) do not require authentication. ## Configuring MCP Clients **To configure Cline:** 1. Open Cline's MCP settings UI 1. Click the "Remote Servers" tab 1. For each `ProjectUrlAlias` in your `appsettings.json` that the user wants to connect to: ```json { "mcpServers": { ... ... "Polarion Starling": { "autoApprove": [], "disabled": true, "timeout": 60, "url": "http://{{your-server-ip}}:8080/starlight/sse", "transportType": "sse" }, "Polarion Octopus": { "autoApprove": [], "disabled": true, "timeout": 60, "url": "http://{{your-server-ip}}:8080/octopus/sse", "transportType": "sse" } ... ... } ``` 1. Repeat for each `ProjectUrlAlias` you want to connect to. **To configure Visual Studio Code:** Add the following configuration to your settings.json file: ```json "servers": { "polarion-starlight": { // Use a descriptive key "type": "sse", "url": "http://{{your-server-ip}}:8080/starlight/sse", // Replace with your alias "env": {} }, "polarion-octopus": { "type": "sse", "url": "http://{{your-server-ip}}:8080/octopus/sse", // Replace with your alias "env": {} } // Add entries for each ProjectUrlAlias } ``` **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: ```json { "mcpServers": { "polarion-remote": { "command": "npx", "args": [ "mcp-remote", "http://{{your-server-ip}}:8080/{ProjectUrlAlias}/sse" // Replace {ProjectUrlAlias} ] } // Add entries for each ProjectUrlAlias, potentially using different keys like "polarion-starlight" } } ``` ## Running Locally (stdio) For local development or workstation use, you can run the stdio-based MCP server: 1. Download the appropriate executable for your platform from the [releases page](https://github.com/peakflames/PolarionMcpServers/releases) 2. Configure your MCP client to use the stdio transport with the executable path ## Contributing For developers who want to contribute or build from source, see [CONTRIBUTING.md](https://github.com/peakflames/PolarionMcpServers/blob/HEAD/CONTRIBUTING.md). ## License See [LICENSE](https://github.com/peakflames/PolarionMcpServers/tree/HEAD/LICENSE) for details.