관리자 가이드

어떻게 구성되어 있나요?

Go 서버 하나가 웹 콘솔(React), MCP 엔드포인트(/mcp, Streamable HTTP), OAuth 인가 서버(/oauth/*, /.well-known/*), 콘솔 API(/api/*)를 함께 제공합니다. 설정·감사·승인·토큰 해시는 PostgreSQL 에 저장하고, 비밀값은 ENCRYPTION_KEY 로 AES-256-GCM 암호화합니다.

설계 원칙: 정책과 역할은 권한을 줄이기만 하고, 관리자 역할도 문서 권한을 우회하지 않습니다. 볼 수 없는 문서와 없는 문서는 같은 응답(PERMISSION_DENIED, "대상을 찾을 수 없거나 접근 권한이 없습니다")으로 돌려줍니다.

어떻게 설치하나요?

요구사항

• Linux 서버와 Docker, Docker Compose v2 (또는 docker-compose)
• PostgreSQL: 동봉 compose 는 postgres:17-alpine 이미지를 씁니다. 기존 데이터베이스를 써도 됩니다.
• Keycloak (OIDC). Keycloak 26.4 에서 확인했습니다. SSO 없이 로컬 계정만으로도 시작할 수 있습니다.
• Confluence Server 7.2.0, REST 전용 서비스 계정, (권장) confmcp 권한 플러그인
• 게이트웨이와 Confluence 의 시계 동기화(NTP): 플러그인은 ±5분을 넘는 서명 요청을 거부합니다.
• 외부 접속 주소(HTTPS 권장). 리버스 프록시 뒤에 둘 수 있습니다.

1. 이미지 적재

GitHub 릴리스에서 confmcp-v0.1.2.tar.gz 를 받아 서버로 옮깁니다. 웹 콘솔·글꼴·마이그레이션이 모두 이미지에 들어 있어 실행 중 외부 다운로드가 없습니다.

docker load -i confmcp-v0.1.2.tar.gz      # → confmcp:v0.1.2

2. PostgreSQL 이미지 반입

confmcp 릴리스에는 PostgreSQL 이미지가 들어 있지 않습니다. 인터넷이 되는 곳에서 저장해 함께 옮기거나, 기존 PostgreSQL 을 DATABASE_URL 로 지정하십시오.

# 인터넷이 되는 PC
docker pull postgres:17-alpine
docker save postgres:17-alpine | gzip > postgres-17-alpine.tar.gz
# 오프라인 서버
docker load -i postgres-17-alpine.tar.gz

3. 환경변수

confmcp 가 읽는 환경변수는 네 개뿐입니다(수신 주소 CONFMCP_ADDR 는 선택, 기본 :8080). 나머지 설정은 모두 관리 콘솔에서 입력합니다.

동봉 compose 를 쓸 때는 deploy/.env 에 값을 채웁니다. CONFMCP_VERSION, CONFMCP_PORT, POSTGRES_USER/PASSWORD/DB 는 compose 가 쓰는 값이며, compose 가 이 값으로 DATABASE_URL 을 만듭니다.

cp deploy/.env.example deploy/.env
$EDITOR deploy/.env     # POSTGRES_PASSWORD, BOOTSTRAP_ADMIN_PASSWORD, ENCRYPTION_KEY

4. 기동

docker compose -f deploy/docker-compose.yml --env-file deploy/.env up -d

compose 없이 기존 PostgreSQL 에 붙일 때:

docker run -d --name confmcp -p 8080:8080 \
  -e DATABASE_URL='postgres://confmcp:<비밀번호>@<DB 호스트>:5432/confmcp?sslmode=disable' \
  -e BOOTSTRAP_ADMIN=admin -e BOOTSTRAP_ADMIN_PASSWORD='<관리자 비밀번호>' \
  -e ENCRYPTION_KEY='<openssl rand -base64 32 로 만든 값>' \
  confmcp:v0.1.2

데이터베이스 마이그레이션은 시작할 때 자동으로 적용됩니다.

5. 상태 확인

curl -fsS http://localhost:8080/healthz    # {"status":"ok","service":"confmcp","version":"0.1.2",…}
curl -fsS http://localhost:8080/readyz     # 데이터베이스·설정이 준비되면 200, 아니면 503
curl -s   http://localhost:8080/api/version

/readyz 응답의 confluenceConfigured 로 Confluence 연결 설정 여부도 볼 수 있습니다. 이제 http://<호스트>:8080 에 BOOTSTRAP_ADMIN 계정으로 로그인해 초기 설정을 진행합니다.

업그레이드·백업·복구는 어떻게 하나요?

업그레이드

bash deploy/upgrade.sh /path/to/confmcp-v<새 버전>.tar.gz

스크립트는 같은 위치에 .sha256 파일이 있으면 무결성을 확인하고, 이미지를 적재한 뒤 deploy/.env 의 CONFMCP_VERSION 만 새 버전으로 바꾸고(다른 값은 읽거나 출력하지 않음) 재기동하며, 컨테이너가 실제로 새 버전으로 떴는지 확인한 뒤에만 성공으로 끝납니다.

백업

docker exec confmcp-postgres pg_dump -U confmcp -d confmcp -Fc > confmcp-$(date +%F).dump

ENCRYPTION_KEY(deploy/.env)는 덤프와 다른 곳에 따로 보관합니다. 덤프만으로는 저장된 비밀값을 읽을 수 없고, 키 없이는 덤프의 비밀값을 복구할 수 없습니다.

복구

docker compose -f deploy/docker-compose.yml --env-file deploy/.env stop confmcp
docker exec -i confmcp-postgres pg_restore -U confmcp -d confmcp --clean --if-exists < confmcp-2026-10-08.dump
docker compose -f deploy/docker-compose.yml --env-file deploy/.env start confmcp

복구할 때는 백업 당시와 같은 ENCRYPTION_KEY 로 기동해야 합니다.

v0.1.1 업그레이드·롤백 주의: replace_text 는 검색 문자열의 앞뒤 공백을 보존하며, find·body 의 공백도 승인 해시에 반영합니다. 공백이 포함된 기존 변경안은 재승인이 필요할 수 있습니다. 버전을 바꾸면 같은 재시도 키로 이전 성공 결과를 조회하는 대신 충돌 또는 APPROVAL_STALE 응답을 받을 수 있으므로, 현재 문서와 실행 이력을 확인한 뒤 변경안을 다시 작성하십시오. 데이터베이스 스키마 변경은 없으며 권한 플러그인은 v0.1.0 을 그대로 사용합니다.

v0.1.2 업그레이드·롤백 주의: DELETE /mcp 세션 종료가 이제 GET /mcp·initialize 와 같은 인증을 요구합니다. 인증 헤더 없이 세션을 닫던 클라이언트·스크립트는 401 과 WWW-Authenticate 챌린지를 받으므로 자격 증명을 함께 보내도록 고쳐야 합니다. 세션은 소유자 본인만 닫을 수 있고, 없는 세션과 타인의 세션은 구분 없이 204 로 응답합니다. 인증을 보내지 않아 닫히지 못한 세션은 closed_at 이 비어 있는 채로 남지만, 관리 콘솔의 활성 세션 집계는 마지막 활동에서 1시간이 지나면 그 세션을 빼므로 수치가 한동안 커 보일 수 있습니다. 데이터베이스 스키마 변경은 없으며 권한 플러그인은 v0.1.0 을 그대로 사용합니다.

처음 기동한 뒤 무엇부터 설정하나요?

관리 대시보드의 "설정 경고"가 빠진 항목을 알려 줍니다. 아래 순서를 권장합니다.

1. 보안 → MCP 게이트웨이 → 공개 URL: 사용자가 접속하는 외부 주소. OAuth 발급자와 링크 생성에 쓰입니다.
2. 인증 · SSO: Keycloak 클라이언트 값 입력 → 연결 시험 → MCP OAuth 점검.
3. Confluence 연결: 기본 URL(컨텍스트 경로 포함), 서비스 계정 → 연결 시험으로 버전 확인.
4. 권한 판정: 플러그인 설치, 공유 비밀 생성·저장, Confluence 쪽에 같은 비밀 설정 → 상태 확인.
5. 사용자 매핑 방식 결정: 같은 디렉터리라면 Confluence 연결의 "같은 사용자 디렉터리 신뢰"를 켭니다.
6. 접근 정책: 공간 허용 규칙을 최소 하나 만듭니다. 규칙이 없으면 MCP 는 어떤 공간에도 접근할 수 없습니다.
7. MCP 도구와 보안(본인 승인 허용, 승인 유효 시간, IP 허용 목록) 검토.
8. (선택) AI 설정, 화면 설정.
9. 일반 사용자 계정으로 로그인해 [내 Confluence] 매핑, [내 권한 확인], [MCP 연결]을 확인합니다.

Keycloak 에는 무엇을 설정하나요?

클라이언트 하나와 realm 역할 네 개면 됩니다. 이 클라이언트 하나로 콘솔 로그인과 MCP OAuth 로그인을 모두 처리합니다. 예시는 저장소의 deploy/keycloak/ 에 있습니다.

1. 클라이언트 confmcp Keycloak 관리 콘솔의 Clients → Import client 로 deploy/keycloak/confmcp-client.json 을 가져오고 주소를 실제 값으로 바꿉니다. OpenID Connect, Client authentication ON(confidential), Standard flow, PKCE S256, Valid redirect URI https://<confmcp 주소>/auth/oidc/callback, Valid post logout redirect URI https://<confmcp 주소>/login, Web origins https://<confmcp 주소>.
2. Realm 역할 네 개 deploy/keycloak/confmcp-roles.json 에 정리된 역할을 만들고 사용자·그룹에 부여합니다.

   역할	화면 이름	범위
   confluence-mcp-reader	조회자	조회 도구
   confluence-mcp-writer	작성자	조회 + 변경안 작성(본인 승인)
   confluence-mcp-approver	승인자	작성 + 이동·휴지통 및 다른 사람의 변경 승인
   confluence-mcp-admin	관리자	설정 관리 (문서 권한 우회 없음)

3. 콘솔 → 인증 · SSO Keycloak SSO 사용을 켜고 Issuer URL(realm 의 issuer), Client ID, Client Secret 을 입력해 저장한 뒤 연결 시험을 누릅니다. 연결 시험은 Issuer 디스커버리를 확인하고, Keycloak 클라이언트에 등록할 값(클라이언트 유형, Valid redirect URIs, Web origins, Valid post logout redirect URIs, Realm 역할)을 그대로 보여 주므로 Keycloak 화면과 하나씩 맞춰 보면 됩니다.

그 밖의 SSO 옵션

Keycloak SSO 를 끄면 로컬 계정으로만 로그인합니다. 최초 관리자 계정은 SSO 장애 시 비상 계정으로 남겨 두십시오.

MCP 클라이언트 인증은 어떻게 동작하나요?

confmcp 자체가 MCP 클라이언트의 OAuth 2.1 인가 서버입니다. 사용자는 위의 같은 Keycloak 클라이언트로 로그인하므로 Keycloak 에 MCP 용 클라이언트·루프백 redirect·audience 매퍼를 추가로 만들 필요가 없습니다.

• 엔드포인트: /.well-known/oauth-protected-resource/mcp, /.well-known/oauth-authorization-server, /oauth/register(RFC 7591 동적 등록), /oauth/authorize(PKCE S256), /oauth/token, /oauth/revoke
• 등록 제한: redirect URI 는 10개 이하, 루프백 http(포트 무관), https, 역도메인 형식 전용 스킴만 허용합니다.
• 토큰: 액세스 토큰은 불투명 값으로 해시만 저장하고 1시간 유효하며 MCP 리소스에 바인딩됩니다. refresh 토큰은 30일, 쓸 때마다 교체되고 이미 교체된 refresh 토큰이 다시 쓰이면 그 연결(grant) 전체를 폐기합니다.
• 권한 범위: 사용자의 Keycloak 역할에서 스코프를 계산하므로 OAuth 호출과 API 키 호출이 같은 스코프 검사를 거칩니다.

MCP OAuth 점검은 MCP 주소, 보호 리소스·인가 서버 메타데이터 URL, Claude Code 연결 명령을 보여 줍니다. 클라이언트가 연결되지 않으면 같은 화면의 최근 OAuth 탐색 기록에서 어느 단계(401 응답, 메타데이터, 등록, 인가, 토큰)에서 멈췄는지 확인하십시오. /mcp 응답에는 버전 헤더가 붙어 어느 빌드가 응답하는지 알 수 있습니다.

Confluence 는 어떻게 연결하나요?

저장한 뒤 연결 시험을 누르면 서비스 계정으로 로그인해 Confluence 버전과 빌드 번호를 감지하고, "감지된 서버 정보"에 기록합니다(직접 수정 불가). REST 호출은 리다이렉트를 따라가지 않으며, Confluence 가 로그인 화면(HTML)이나 SSO 리다이렉트로 답하면 성공으로 처리하지 않고 오류로 돌려줍니다.

요청자 권한은 어떻게 판정하나요?

모든 도구 호출은 이 판정을 통과해야 합니다. 판정 모드는 두 가지이며, 서비스 계정이 본 REST 제한 정보로 요청자 권한을 추정하는 모드는 없습니다. 서비스 계정이 보는 제한은 요청자의 것이 아니기 때문입니다.

권한 플러그인 모드 (기본, 권장)

Confluence 안에 설치하는 읽기 전용 플러그인 confmcp Permission Resolver 가 요청 본문의 userKey 사용자에 대해 Confluence 의 PermissionManager·SpacePermissionManager 판정을 그대로 돌려줍니다. 열람 제한은 하위로 상속되고 편집 제한은 상속되지 않는 Confluence 의미, 그룹 권한, 익명·관리자 예외가 화면과 똑같이 적용됩니다.

1. 빌드 저장소의 plugin/ 에서 JDK 8 · Maven 3.6+ 로 빌드합니다(Atlassian 공개 Maven 저장소 접근 필요). 결과물은 target/confmcp-permission-plugin-0.1.0.jar 입니다.

   cd plugin && mvn package
   # 로컬에 Maven 이 없으면
   docker run --rm -v "$PWD/plugin":/src -v confmcp-m2:/root/.m2 -w /src \
     maven:3.9-eclipse-temurin-8 mvn -B package

2. 설치 (UPM) Confluence 시스템 관리자로 설정 → 앱 관리 → 앱 업로드에서 JAR 를 올립니다. "confmcp Permission Resolver" 가 사용 상태면 완료입니다. 재시작은 필요 없고, Data Center 는 UPM 이 모든 노드에 설치합니다.
3. 공유 비밀 생성 콘솔 → 권한 판정에서 플러그인 공유 비밀(16–512자)을 입력하거나 생성으로 만들고 저장합니다. 생성한 값은 저장 직후 한 번만 보이므로 바로 복사합니다. 플러그인 URL 은 비우면 Confluence 기본 URL 을 씁니다.
4. Confluence 에 같은 비밀 저장

   curl -u admin:관리자비밀번호 -X PUT \
     'https://wiki.example.com/confluence/rest/confmcp/1.0/config' \
     -H 'Content-Type: application/json' -H 'X-Atlassian-Token: no-check' \
     -d '{"secret":"<콘솔에 넣은 것과 같은 값>"}'
   # → {"configured":true,"source":"pluginSettings"}

   값은 Confluence 전역 플러그인 설정에 저장되어 Data Center 의 모든 노드가 같은 값을 씁니다. 없으면 JVM 속성 -Dconfmcp.secret=… 을 대신 쓰고, 둘 다 없으면 서명 엔드포인트는 503 secret not configured 로 닫혀 있습니다. 값을 돌려주는 API 는 없습니다.
5. 상태 확인 콘솔의 플러그인 상태 확인이 서명된 GET /rest/confmcp/1.0/health 를 보내 {"status":"ok","pluginVersion":"0.1.0","confluenceVersion":"7.2.0",…} 를 보여 줍니다. 서명 없이 직접 호출하면 401 missing signature headers 가 정상입니다.

서명 방식

판정·사용자·상태 API 는 모두 HMAC-SHA256(secret, METHOD \n 요청 경로(컨텍스트 경로 포함) \n sha256(본문) \n timestamp \n nonce) 서명이 맞아야 응답합니다(헤더 X-Confmcp-Timestamp, X-Confmcp-Nonce, X-Confmcp-Signature). 타임스탬프가 ±5분을 벗어나면 거부하고, 한 번 쓴 nonce 는 10분간 기억해 재전송을 막습니다. 그래서 일반 Confluence 사용자는 다른 사람의 권한을 물어볼 수 없습니다. nonce 캐시는 노드별이므로 게이트웨이와 Confluence 사이 구간은 TLS 로 보호하십시오.

플러그인 API

결과는 연산별 allow / deny / unknown 과 사유 코드(NOT_VISIBLE, PAGE_EDIT_RESTRICTED 등)입니다. 볼 수 없는 콘텐츠와 없는 콘텐츠는 똑같이 deny / NOT_VISIBLE 이고, 비활성 사용자는 모든 연산이 deny, 휴지통·초안 콘텐츠는 열람 외 연산이 deny 입니다.

롤백: 플러그인을 비활성화·제거하기 전에 콘솔에서 판정 모드를 먼저 사용자 위임으로 바꾸십시오. 그렇지 않으면 fail-closed 에 따라 도구 호출이 거부됩니다.

사용자 위임 모드

요청자 본인의 Confluence 자격증명으로 대상을 조회하고(보이지 않으면 거부), Confluence 의 operations 정보로 작성·편집·댓글·첨부·삭제 가능 여부를 판정합니다. Confluence 가 알려 주지 않는 연산은 unknown 으로 거부합니다. 이 모드를 쓰려면 Confluence 연결에서 "사용자 본인 자격증명 연결 허용"을 켜고, 사용자마다 [내 Confluence]에서 자격증명을 연결해야 합니다. 연결된 자격증명의 userKey 가 매핑과 다르면 호출을 거부합니다.

권한 판정 화면 아래의 판정 시험에 사용자명과 공간 키 또는 콘텐츠 ID 를 넣으면, 그 사용자의 Confluence 권한 결과(정책 미반영)를 작업별로 볼 수 있습니다.

사용자 매핑은 어떻게 관리하나요?

영구 식별자는 (Keycloak issuer, sub) ↔ (인스턴스, Confluence userKey) 입니다. 사용자명은 후보를 찾는 데만 쓰고, 이름·이메일을 느슨하게 비교하지 않습니다. 매핑이 없는 사용자는 MCP 도구를 쓸 수 없습니다(IDENTITY_UNMAPPED).

• 재확인: 저장된 userKey 가 아직 있고 활성인지 확인합니다. 계정이 삭제되었거나 비활성이면 매핑을 비활성으로 바꿉니다.
• 재생성 계정 비승계: 같은 사용자명이 이제 다른 userKey 를 가리키면(계정을 지우고 다시 만든 경우) 매핑을 옮기지 않고 비활성화합니다. 새 계정과는 관리자가 다시 연결해야 합니다.
• Confluence 계정 하나는 Keycloak 주체 하나에만 매핑되고, 자동 매핑은 기존 매핑을 다른 계정으로 바꾸지 않습니다.
• 매핑 실패 기록: 로그인이나 도구 호출 중 계정을 찾지 못한 사유와 횟수가 쌓입니다. 원인을 해결한 뒤 비우십시오.
• 변경 이력: 매핑 생성·재확인·활성 변경·삭제를 기록합니다(최근 100건).

접근 정책은 어떻게 동작하나요?

접근 정책은 MCP 가 닿을 수 있는 범위를 Confluence 권한 위에서 더 좁히기만 합니다. 판정은 요청자가 보낸 공간 키가 아니라 Confluence 에서 다시 읽은 실제 공간과 상위 경로로 합니다.

• 위험도 상한: 허용 규칙에 상한(READ / WRITE / EXECUTE)을 걸면 그 대상에서는 그 등급까지만 쓸 수 있습니다. 여러 규칙이 걸리면 가장 낮은 상한이 적용됩니다. 예: 운영 공간은 READ 상한으로 조회만 허용.
• 우선순위: 숫자가 작을수록 먼저 평가합니다.
• 정책 세대: 규칙을 바꿀 때마다 세대가 올라가고, 이전 세대에서 받은 승인은 APPROVAL_STALE 로 무효가 됩니다.
• 라벨은 일반 편집자가 바꿀 수 있어 보안 경계가 될 수 없으므로 정책 대상이 아닙니다.
• 규칙이 하나도 없으면 MCP 는 어떤 공간에도 접근할 수 없습니다.

판정 미리보기에 공간 키나 콘텐츠 ID 를 넣으면 정책 결과를 미리 봅니다. 콘텐츠 ID 를 넣으면 실제 공간과 상위 페이지를 Confluence 에서 읽어 판정하고, 사용자명을 넣으면 그 사용자의 Confluence 권한도 함께 확인합니다.

MCP 도구는 어떻게 관리하나요?

도구 28종(P0 조회 17 · P1 작성·첨부 7 · P2 고위험 4) 각각에 대해 세 가지를 바꿀 수 있습니다. 도구 목록과 설명은 사용자 가이드의 도구 표를 보십시오.

• 활성화: 끄면 목록에서 사라지고 호출은 TOOL_DISABLED. P2(블로그 작성, 라벨 제거, 페이지 이동, 휴지통)는 기본 비활성입니다.
• 승인 필요: 쓰기 도구는 기본으로 켜져 있습니다. 위험도 EXECUTE 도구(이동·휴지통)는 승인을 끌 수 없고 항상 별도 승인자가 필요합니다.
• 최소 역할: 기본은 위험도에 따라 READ → 조회자, WRITE → 작성자, EXECUTE → 승인자. confluence_prepare_change 는 작성자입니다.

여러 단계를 묶은 고수준 도구(confluence_page_context, confluence_space_context)의 노출 여부는 보안 → MCP 게이트웨이에서 정합니다. 도구 행을 펼치면 입력 스키마를 볼 수 있습니다.

변경 승인은 누가 할 수 있나요?

• 본인 승인: 보안 설정 "본인 승인 허용"(기본 켜짐)이면 요청자가 자신의 WRITE 등급 변경을 승인할 수 있습니다. 끄면 모든 변경에 승인자가 필요합니다.
• 별도 승인자가 필요한 작업: EXECUTE 등급(페이지 이동, 휴지통)은 본인 승인 설정과 관계없이 요청자가 아닌 승인자(confluence-mcp-approver 이상)가 승인해야 합니다.
• 승인자는 대상 문서를 볼 수 있어야 합니다: 다른 사람의 변경안은 승인자 본인이 Confluence 에서 그 문서를 열람할 수 있을 때만 상세를 보고 승인할 수 있습니다. 관리자도 예외가 아닙니다.
• 승인 유효 시간은 보안 설정(기본 30분)입니다. 승인은 인자, 대상 버전, 원문 해시, 정책 세대에 묶이며 한 번만 소비됩니다.

[변경 승인] 관리 화면은 모든 사용자의 승인 요청을 상태별로 보여 주고, 행을 누르면 diff 를 확인해 승인·거절할 수 있습니다(위 규칙 동일 적용).

쓰기 결과가 불명확하면 어떻게 정리하나요?

[쓰기 작업 기록]은 승인된 변경이 Confluence 에 실제로 적용된 기록입니다. 같은 요청은 멱등 키로 한 번만 실행됩니다. 쓰기 요청을 보냈는데 응답을 받지 못했거나(타임아웃, 연결 끊김), 응답 후 재조회 검증에 실패했거나, 실행 중 서비스가 재시작되면 상태가 결과 불명확(outcome_unknown)이 되고 사용자는 OUTCOME_UNKNOWN 을 받습니다. confmcp 는 이런 쓰기를 자동으로 다시 보내지 않습니다.

1. 대상 확인 기록의 대상 ID 로 Confluence 페이지 기록(버전 이력)이나 첨부·댓글을 열어 실제로 반영되었는지 봅니다.
2. 정리 "결과 불명확 작업"에서 해당 기록을 성공 또는 실패로 정리하고, 확인한 내용(예: "버전 14 로 반영 확인")을 메모로 남깁니다. 정리 내용은 감사 로그에 남습니다.
3. 사용자 안내 실패로 정리했다면 사용자에게 새 변경안을 만들도록 알립니다. 같은 승인으로는 다시 실행되지 않습니다.

대기 중인 결과 불명확 건수는 대시보드 경고와 confmcp_operation_outcome_unknown 지표로도 보입니다.

MCP 연결 현황에서는 무엇을 관리하나요?

• OAuth 클라이언트: MCP 클라이언트가 동적 등록으로 만든 클라이언트입니다. 차단하면 그 클라이언트로 맺은 모든 사용자 연결이 철회됩니다.
• 사용자 연결(grant): 사용자가 클라이언트에 허락한 연결입니다. 철회하면 해당 연결의 토큰이 즉시 무효가 됩니다.
• MCP 세션: 최근 MCP 세션 기록입니다.

API 키와 권한 체계는 어떻게 관리하나요?

• 권한 체계(역할 → 스코프): 키 역할은 스코프 묶음이며 콘솔에서 편집합니다. 기본 역할도 스코프는 바꿀 수 있지만 삭제할 수는 없습니다. 스코프: confluence:read, confluence:attachment:read, confluence:write, confluence:attachment:write, confluence:execute, ai:invoke, admin:read, admin:write.
• 실제 허용 범위 = 키 스코프 ∩ 소유자의 현재 역할이 허용하는 범위. 그 위에 소유자의 Confluence 권한이 다시 적용됩니다.
• 키 정책 (기본값): 기본 역할 reader, 회전 주기 90일, 유효 기간 365일, 사용자당 최대 5개, 본인 발급 허용, 회전 유예 24시간.
• 관리자 회전·폐기: 모든 사용자의 키를 회전하거나 사유를 남기고 폐기할 수 있습니다. 키 비밀값은 저장하지 않으므로 회전하면 새 값을 한 번만 보여 줍니다.

사용자는 어떻게 관리하나요?

콘솔 사용자(Keycloak 과 로컬 계정)와 MCP 역할을 관리합니다. 로컬 계정을 만들고(비밀번호 10자 이상), 표시 이름·이메일·역할·서비스 관리자 여부를 바꿀 수 있습니다.

• Keycloak 사용자의 역할은 로그인할 때마다 토큰의 역할로 갱신되므로, 여기서 바꾼 역할은 다음 로그인 때 덮어써질 수 있습니다. 역할은 Keycloak 에서 관리하십시오.
• 사용자를 비활성화하면 로그인 세션과 MCP OAuth 연결이 즉시 종료됩니다.
• 서비스 관리자는 관리 화면 접근 권한일 뿐 문서 권한을 우회하지 않습니다.

운영 한도의 기본값은 무엇인가요?

도구 호출 하나가 읽거나 돌려줄 수 있는 양입니다. 범위를 벗어난 값은 저장할 때 안전한 범위로 조정됩니다.

AI 도우미는 어떻게 설정하나요?

콘솔 [AI 도우미]가 쓰는 모델입니다. 끄면 AI 도우미와 AI 호출 스코프가 모두 비활성화됩니다.

• 제공자: Anthropic Messages API 또는 OpenAI 호환(vLLM, Ollama, 사내 게이트웨이 등). 오프라인망에서는 Base URL 에 사내 추론 게이트웨이 주소를 넣습니다. API 키는 암호화해 저장합니다.
• 스트리밍: 기본 켜짐. 응답을 SSE 로 중계합니다.
• 최대 출력 토큰: 기본 16,384, 최대 524,288(512k)까지 설정할 수 있습니다. 긴 출력을 고려해 응답 제한 시간(기본 600초)을 넉넉히 두십시오.
• 허용 모델 목록: 사용자에게 보여 줄 모델들입니다. 기본 모델은 사용자가 고르지 않을 때 씁니다.
• 시스템 프롬프트: 문서 내용을 신뢰할 수 없는 데이터로 다루도록 지시하는 문장을 유지하십시오.

저장한 뒤 연결 시험을 누르면 저장된 설정으로 짧은 요청을 보냅니다.

보안 설정에는 무엇이 있나요?

MCP 게이트웨이

화면 설정으로 무엇을 바꾸나요?

모든 사용자에게 적용되는 표시 설정입니다: 서비스 이름(머리글·브라우저 제목), 부제, 대표 색상(기본 남색 외 파랑·하늘·초록·자주·주황 등), 기본 글자 크기(0.85–1.4, 사용자가 개인 설정에서 따로 바꿀 수 있음), 기본 테마, 로그인 화면 안내문(사용 목적·문의처, 텍스트로만 표시). 저장 전 미리보기가 함께 보입니다.

감사 로그와 지표는 어디서 보나요?

[감사 로그]에는 로그인, 도구 호출, 쓰기, 거부, 승인, 관리 변경이 모두 남습니다. 각 기록에는 Keycloak 사용자, 매핑된 Confluence 사용자, 실제 실행 계정, MCP 클라이언트, 인증 방식, 도구, 공간·콘텐츠 ID·버전, 판정, 승인 ID, 결과 코드, 지연, IP 가 들어가며 비밀값과 문서 본문은 기록하지 않습니다. 분류·사용자·결과 코드·콘텐츠 ID 로 거르고, 행을 누르면 상세를 봅니다. 보존 기간이 지난 기록은 정리할 수 있습니다.

[관리 대시보드]는 연결 상태, 설정 경고, 최근 24시간 호출 수·오류율·권한·정책 거부·응답 시간 p95, 시간대별 호출 추이, 최근 7일 상위 도구를 30초마다 갱신해 보여 줍니다.

Prometheus 지표 (/metrics)

/metrics, /healthz, /readyz 는 로그인 없이 응답합니다(IP 허용 목록은 적용). 외부에 노출하지 않도록 네트워크나 프록시에서 제한하십시오.

시스템 화면에서는 무엇을 확인하나요?

버전(버전·커밋·빌드 날짜), 의존 서비스 상태(PostgreSQL, Keycloak, Confluence, 권한 판정), 데이터베이스와 적용된 마이그레이션(스키마 버전), MCP 도구 호출 통계(호출 수, 오류율, 평균·p50·p95 지연, 기간별 막대 그래프), confmcp 가 읽는 환경변수 네 가지를 봅니다. 통계의 실패에는 거부와 승인 대기가 포함되지 않습니다.

문제가 생기면 어디부터 보나요?

무엇이 어디까지 검증되었나요?

v0.1.0 의 인수 시나리오(AC-01 ~ AC-20)를 어떻게 검증했는지 정리했습니다. 자동 검증은 모의 Confluence(hack/mockconfluence: 제한 페이지·충돌 시나리오를 재현하는 7.2 REST 와 권한 플러그인 모의)를 상대로 한 것이며, 모든 항목은 실제 Confluence Server 7.2.0 에서 다시 확인해야 합니다.

# 모의 환경 자동 점검
scripts/dev.sh up         # PostgreSQL + 모의 Confluence 7.2 + confmcp + 샘플 데이터
hack/e2e.sh               # go test -tags e2e ./hack/e2e
scripts/go.sh test ./...  # 단위 테스트 (internal/confluence/client_test.go 등)

이 밖에 e2e 의 TestPolicyDeniesHR 는 정책으로 차단한 공간이 공간 목록에 나오지 않음을, 단위 테스트 TestBodyViewIsNeverRequested 는 매크로를 실행하는 body.view 를 요청하지 않음을 확인합니다.

실제 Confluence 7.2.0 에서 확인할 때

• 열람 제한이 걸린 상위 페이지와 하위 페이지, 편집 제한만 걸린 페이지, 그룹 권한만 있는 공간을 준비합니다.
• 권한이 다른 사용자 두 명(예: 일반 직원, 보안팀)으로 같은 검색·조회·수정 요청을 보내 결과를 비교합니다.
• [내 권한 확인] 결과가 Confluence 화면의 권한(페이지 제한, 공간 권한)과 같은지 대조합니다.
• Confluence 앞의 SSO·프록시 구성에서 REST 와 플러그인 경로가 로그인 화면으로 돌지 않는지 확인합니다.