Polarion MCP Server

오픈소스이며 설치 가능하고 쓰기 보호 기능이 있는 Polarion Model Context Protocol(MCP) 서버입니다. 대상 Polarion 설치에 내장된 SOAP Web Services를 통해 LiveDoc, 작업 항목 및 추적 관계를 읽고, 명시적 확인 후 생성·수정·삭제를 수행합니다.

Windows는 원클릭 설치와 DPAPI 자격 증명 암호화를 제공합니다. Linux/macOS는 Node.js와 환경 변수로 수동 실행할 수 있습니다. 이 저장소에는 계정, 비밀번호, 토큰, 쿠키, 비공개 서버 주소, 프로젝트 ID 또는 요구사항 본문이 포함되어 있지 않습니다.

주요 기능

전체 검증 경계는 기능 적용 범위 매트릭스를 참조하세요.

Related MCP server: permission-aware-mcp

작동 원리

MCP 프로세스는 웹 페이지를 크롤링하지 않고, 브라우저 쿠키를 읽지 않으며, Polarion 권한을 우회하지 않습니다. 브라우저 자동 연결은 현재 Polarion 탭 URL을 MCP에 전달하는 역할만 합니다. 요구사항 데이터의 읽기와 쓰기는 여전히 모두 SOAP MCP를 통해 수행됩니다.

Windows 원클릭 설치

사전 요구 사항

• Windows 10/11

• Node.js 20 이상

• Git

• Codex CLI(codex 명령 사용 가능)

• 접근 가능한 Polarion 서버(/polarion/ws/services/*?wsdl이 열려 있어야 함)

• 해당 프로젝트 권한이 있는 Polarion 계정 또는 PAT

1. 클론

git clone https://github.com/suzike/polarion-mcp-server.git
cd polarion-mcp-server

2. 설치 및 등록

대화형 설치:

.\scripts\install.ps1

설치 프로그램은 다음을 수행합니다:

1. Node.js, npm 및 Codex CLI 확인;

2. npm ci, 엄격한 컴파일 및 테스트 실행;

3. Polarion 주소와 인증 방식 질문;

4. Windows 보안 자격 증명 프롬프트에서 비밀번호 또는 PAT 입력;

5. 기존 ~/.codex/config.toml 백업;

6. 사용자 수준 polarion MCP 등록;

7. Codex가 새 구성을 읽을 수 있는지 확인.

비대화형 구성 예시(자격 증명은 여전히 보안 프롬프트를 통해 입력):

.\scripts\install.ps1 `
  -BaseUrl "https://polarion.example.com/polarion" `
  -DefaultProject "MY_PROJECT" `
  -DefaultDocumentLocation "Requirements/Software Requirements" `
  -AuthMode password `
  -Force

설치 완료 후 Codex를 다시 시작하세요.

3. 환경 확인

.\scripts\doctor.ps1
codex mcp get polarion

자격 증명 처리

자격 증명은 절대 저장소나 config.toml에 들어가지 않습니다. Windows 설치 프로세스는 기본적으로 다음에 기록합니다:

%LOCALAPPDATA%\PolarionMcp\credentials.json

여기서 secret은 Windows DPAPI를 사용하여 현재 Windows 사용자에 바인딩되어 암호화되며, 파일 ACL은 상속을 비활성화하고 현재 사용자만 접근할 수 있도록 합니다. MCP 시작 시 launcher가 secret을 하위 프로세스 환경에 임시로 주입하고, 종료 시 즉시 제거합니다.

자격 증명 재설정:

.\scripts\setup-credentials.ps1 -AuthMode password
# 或
.\scripts\setup-credentials.ps1 -AuthMode access_token

일부 Polarion 서버는 PAT SOAP 로그인을 비활성화할 수 있습니다. 이 경우 비밀번호 인증을 사용하거나 관리자에게 AccessToken 인증 활성화를 요청하세요.

사용 방법

Codex를 다시 시작한 후 직접 말할 수 있습니다:

检查 Polarion 连接状态。
读取项目 MY_PROJECT 的需求文档 Requirements/Software Requirements。
读取工作项 REQ-123，并列出它的追踪链接。
查询 MY_PROJECT 中状态为 approved 的 requirement，最多返回 20 条。

현재 브라우저 프로젝트 자동 연결

브라우저 제어를 지원하는 MCP Host에서 다음과 같이 말할 수 있습니다:

读取当前浏览器打开的 Polarion 文档前 20 条需求。

Host는 현재 활성 탭 URL에서 #/project/{projectId}/...를 가져온 다음 전체 URL을 도구의 polarion_url 매개변수로 전달합니다. MCP는 URL이 구성된 Polarion 서비스와 동일 출처인지 검증하고 프로젝트 및 wiki 문서 위치를 자동으로 해석합니다.

Host에 브라우저 기능이 없거나, 판단할 수 없는 여러 탭이 동시에 존재하거나, 현재 탭이 Polarion이 아닌 경우 project_id를 명시적으로 제공하세요.

생성, 수정 및 삭제

쓰기 도구는 기본 프로젝트를 자동으로 사용할 수 없습니다. project_id 또는 polarion_url을 명시적으로 전달하고 정확한 확인 값을 제공해야 합니다:

대화 예시:

在 MY_PROJECT 创建一条 task，标题为“接口检查”。执行前先给我预览并询问确认。

Host는 먼저 프로젝트, 유형, 제목 및 설명을 표시해야 합니다. 사용자가 명시적으로 확인한 후에만 확인 문자열을 전달합니다. Polarion은 여전히 계정 권한, 유형 구성, 워크플로 및 감사 검사를 수행합니다.

수동 실행 및 기타 MCP Host

빌드:

npm ci
npm run build

Windows는 보안 launcher를 권장합니다:

$env:POLARION_BASE_URL = "https://polarion.example.com/polarion"
$env:POLARION_PROJECT_ID = "MY_PROJECT"          # 可选
$env:POLARION_NODE_PATH = (Get-Command node).Source
.\scripts\start-secure.ps1

Linux/macOS는 비밀번호 관리자 또는 프로세스 관리자에서 환경 변수를 제공한 후 다음을 실행합니다:

export POLARION_BASE_URL="https://polarion.example.com/polarion"
export POLARION_AUTH_MODE="access_token"
export POLARION_ACCESS_TOKEN="$(your-secret-manager read polarion-token)"
node dist/index.js

secret을 추적되는 .env 파일이나 MCP JSON 구성에 기록하지 마세요.

업데이트 및 제거

업데이트:

git pull --ff-only
npm ci
npm test
npm run build

암호화된 자격 증명을 유지하면서 등록만 제거:

.\scripts\uninstall.ps1

현재 Windows 사용자의 암호화된 자격 증명도 함께 삭제:

.\scripts\uninstall.ps1 -RemoveCredentials

검증 및 개발

npm test                 # 严格编译 + 单元/契约测试
npm run smoke            # MCP 协议和 8 个工具清单
npm audit --omit=dev     # 生产依赖漏洞检查

인증 통합 테스트는 비밀 대상 매개변수를 직접 설정해야 합니다:

$env:POLARION_BASE_URL = "https://polarion.example.com/polarion"
$env:POLARION_TEST_PROJECT_ID = "SANDBOX_PROJECT"
$env:POLARION_TEST_DOCUMENT_LOCATION = "Requirements/Test Document"
$env:POLARION_TEST_WORK_ITEM_ID = "REQ-1"
npm run integration:secure

실제 쓰기 자체 테스트는 기본적으로 거부됩니다. 명시적 승인을 받고 폐기 가능한 프로젝트를 선택한 경우에만 설정하세요:

$env:POLARION_TEST_PROJECT_ID = "SANDBOX_PROJECT"
$env:POLARION_CONFIRM_LIVE_WRITE_TEST = "CREATE_UPDATE_DELETE:SANDBOX_PROJECT"
npm run integration:write-self-test

이 테스트는 프로젝트 수준 임시 항목을 생성하고 수정한 후 삭제하며, LiveDoc에 자동으로 추가하지 않습니다. 공식 요구사항 문서에 대해 쓰기 자체 테스트를 실행하지 마세요.

알려진 조건 및 제한 사항

• polarion_query_work_items는 해당 SOAP 쿼리 권한이 필요합니다. 일부 계정은 알려진 ID를 직접 읽을 수 있지만 전역 Lucene 쿼리는 실행할 수 없습니다.

• 작업 항목 유형, 상태 및 워크플로는 Polarion 프로젝트마다 다르므로 생성 도구는 일반 기본 유형을 제공하지 않습니다.

• LiveDoc 생성 SOAP 요청에는 계약 테스트가 있지만, 릴리스 전 공식 문서에서 파괴적 검증은 수행되지 않았습니다.

• 현재 브라우저 자동 연결은 MCP Host가 조정하며, MCP가 브라우저를 직접 읽는 것이 아닙니다.

• Windows DPAPI 설치 스크립트는 Windows만 지원합니다. 다른 시스템은 환경 변수를 사용하거나 시스템 keychain을 직접 연동하세요.

문서

• 설치 및 문제 해결

• 아키텍처

• 기능 적용 범위 매트릭스

• 도구 매개변수 참조

• 보안 모델

• 변경 기록

• 기여 가이드

• 보안 정책

License

MIT © 2026 suzike