docagent-gw MCP 서버

Claude Code에서 그룹웨어(전자결재 문서함) 문서를 검색·조회·다운로드할 수 있는 MCP 서버.

전제조건

BE docker 기동 필수: 원본 Docagent repo(C:\Project\Docagent)에서 docker compose up -d 실행. 원격 BE(기본값 https://ai.gtp.or.kr/Docagent)를 사용하므로 별도 docker 없이 동작. 로컬 개발 시에만 DOCAGENT_BE_URL=http://127.0.0.1:8799로 변경. BE가 꺼져 있으면 도구가 복구 명령을 자동 안내합니다.
BE 계정 필요: 그룹웨어 설정을 마친 상태 (데스크톱 앱으로 1회 설정).

등록 방법 (1회만)

방법 1: install.ps1 스크립트 (권장)

Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process
C:\Project\docagent-gw-mcp\install.ps1

계정과 비밀번호를 입력하면 자동으로 등록됩니다.

방법 2: 수동 등록

Windows PowerShell에서:

claude mcp add docagent-gw --scope user `
  -e DOCAGENT_BE_URL=https://ai.gtp.or.kr/Docagent `
  -e DOCAGENT_USERNAME=<BE계정> `
  -e DOCAGENT_PASSWORD=<BE비밀번호> `
  -- node C:\Project\docagent-gw-mcp\server.mjs

로컬 개발 시에는 DOCAGENT_BE_URL=http://127.0.0.1:8799로 변경하세요.


**주의**: 위의 `<BE계정>`, `<BE비밀번호>`를 실제 값으로 바꾸세요.

## 등록 후

- 어느 Claude Code 세션에서든 `/mcp`로 MCP 상태 확인 가능.
- 자동으로 도구 7개 로드 (`gw_search`, `gw_read`, `gw_fetch`, `gw_rag_search`, `gw_sync`, `gw_sync_status`, `gw_status`).

## 도구 검색 전략

| 도구 | 용도 | 예시 |
|---|---|---|
| **`gw_search`** | 제목·기안자·기간 검색 | "2024년 보고서 찾아줘", "홍길동이 기안한 문서" |
| **`gw_rag_search`** (우선!) | 본문 내용·개념 검색 | "조직 개편 관련 규정", "출장비 청구 기준" |

→ **내용 기반 검색은 `gw_rag_search` 우선**. `gw_search`는 제목 검색.

## 보안

- **BE 비밀번호가 `~/.claude.json`에 평문 저장됨** (안전 범위: 본인 Windows 계정 홈 디렉토리).
  이는 BE 계정 비밀번호이지 그룹웨어 비밀번호가 아닙니다 (그룹웨어 creds는 BE DB에 Fernet 암호화).
- **공용 PC에서 사용 금지** — 로그아웃 후 `~/.claude.json` 확인 필수.
- 향후 Windows Credential Manager 연동 예정 (v2).

## 문제 해결

### "BE가 꺼져 있음" 오류

```powershell
cd C:\Project\Docagent  # BE가 있는 원본 repo
# 또는 원격 BE 사용 시: DOCAGENT_BE_URL을 https://ai.gtp.or.kr/Docagent 로 변경
docker compose up -d

"누락된 환경변수" 오류

install.ps1을 다시 실행하거나 수동 등록 명령어 참고.

문서 다운로드 후 파일 읽기

gw_fetch 결과의 경로를 이용해 hwp_read_pages(.hwp) 또는 local_read_files로 읽습니다.

docagent-gw