Archive MCP Server

Enterprise Data Archival & Records Management System의 레코드와 보존 로직을 stdio를 통해 모든 MCP 클라이언트 — Claude Code, Claude Desktop, Cursor, 또는 자체 클라이언트 — 에 노출하는 MCP 서버입니다.

React 대시보드를 클릭해 가며 *"Finance에서 무엇을 아카이브할 수 있을까?"*를 확인하는 대신, 모델에게 질문하면 모델이 이 도구들을 호출합니다.

도구

Related MCP server: EndpointRead-MCP

리소스

요구 사항

Python 3.10+ 및 MCP SDK 2.x가 필요합니다. v2 SDK는 FastMCP를 MCPServer로 이름을 바꾸고 이를 mcp.server.mcpserver로 이동했습니다. 이 코드는 v2를 대상으로 합니다. 데이터 액세스는 SQLAlchemy 2.x이며, PostgreSQL에는 psycopg2를 사용합니다.

설정

python -m venv .venv
source .venv/bin/activate          # macOS/Linux
.venv\Scripts\activate             # Windows

python -m pip install -r requirements.txt
python seed_db.py                  # builds the local demo database
python server.py --selftest        # sanity check, no MCP client needed

그런 다음 실제 MCP 세션에서 확인합니다:

python verify_mcp.py

데이터베이스 선택

서버는 DATABASE_URL을 읽습니다(환경 변수 또는 .env 파일에서 — .env.example 참조):

archive.db에는 합성 레코드가 들어 있으므로, 이 저장소를 복제한 사람은 자격 증명 없이도 서버와 --selftest를 실행할 수 있습니다. 별도의 코드베이스가 아닙니다. seed_db.py는 프로덕션 데이터베이스가 사용하는 동일한 5개 테이블 스키마(active_records, archived_records, retention_policy, audit_logs, documents)를 구축하므로, server.py의 모든 쿼리는 어느 쪽에서든 수정 없이 실행됩니다.

실제 DATABASE_URL을 커밋하지 마세요. .env는 gitignore 처리되며, .env.example이 커밋용 템플릿입니다.

Claude Code에 연결

프로젝트 디렉터리에서:

claude mcp add --scope project archive-system -- /absolute/path/to/.venv/bin/python /absolute/path/to/server.py
claude mcp list

--scope project는 커밋 가능한 .mcp.json을 프로젝트 루트에 작성하므로 저장소를 복제하는 사람은 누구나 서버를 사용할 수 있습니다. claude를 시작하고, 프롬프트가 표시되면 프로젝트 서버를 승인한 다음 /mcp를 확인하세요. archive-system이 도구 6개와 함께 Connected로 표시되어야 합니다. 그런 다음 질문하세요:

어떤 IT 부서 레코드가 아카이브 기한을 초과했나요?

시작에 실패하면 claude --debug=mcp를 실행하고 ~/.claude/debug/ 아래의 로그를 읽어보세요.

Claude Desktop에 연결

claude_desktop_config.json에 다음을 추가하세요:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "archive-system": {
      "command": "D:\\Python\\project\\archive-mcp\\.venv\\Scripts\\python.exe",
      "args": ["D:\\Python\\project\\archive-mcp\\server.py"]
    }
  }
}

command는 단순한 python이 아니라 venv의 Python을 가리키게 하세요. 호스트는 셸의 PATH나 활성화된 virtualenv를 상속하지 않습니다. Windows에서는 두 경로 모두 백슬래시를 두 번 사용해야 합니다.

트레이 아이콘에서 재시작하세요. 창 닫기 버튼이 아니라 Quit를 선택해야 합니다. 그렇지 않으면 앱이 이전 구성으로 계속 실행됩니다.

Windows의 Microsoft Store(MSIX) 빌드 참고 사항: 해당 구성은 %APPDATA% 아래가 아니라 패키지 전용 디렉터리인 %LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude\ 아래에 있습니다. 로컬 stdio 서버는 정상적으로 실행됩니다. logs\mcp.log로 이를 확인하려고 하지 마세요. 모든 것이 정상 작동하는 동안에도 그 파일은 비어 있고 변경되지 않은 채 남아 있을 수 있습니다. 대신 프로세스를 확인하세요. 서버는 Claude Desktop의 자식 프로세스로 실행됩니다:

Get-CimInstance Win32_Process -Filter "Name like '%python%'" |
  Where-Object { $_.CommandLine -like "*archive-mcp*" }

설계 노트

• stdio 전송 — 클라이언트가 같은 머신에서 서버를 하위 프로세스로 실행하기 때문입니다. 서버가 원격으로 실행되고 여러 클라이언트를 처리한다면 HTTP 전송이 합리적일 것입니다.

• 스토리지와의 단일 접점. _connect()는 SQLAlchemy Engine을 반환하며 데이터베이스가 무엇인지 아는 유일한 곳입니다. 쿼리는 방언에 중립적인 명명된 바인드 매개변수(:department)를 사용하므로 SQLite와 PostgreSQL은 두 개가 아니라 하나의 쿼리 세트를 공유합니다.

• pool_pre_ping=True — 서버리스 PostgreSQL(Neon 등)은 유휴 컴퓨팅을 일시 중단하고 MCP 서버는 질문 사이에 유휴 상태로 대기하기 때문입니다. 이 옵션이 없으면 한동안 질문이 없다가 오는 첫 질문이 오래된 풀 연결에서 실패합니다.

• 대상 여부는 SQL이 아닌 Python에서 계산합니다. PostgreSQL INTERVAL 연산에는 SQLite에 해당하는 기능이 없으며, 비교를 한 곳에 유지하면 두 백엔드가 일관성을 유지합니다. 활성 행이 수천 개 수준이면 이 비용은 최적화할 가치가 없습니다.

• 경과 기간은 joining_date 기준으로 측정합니다. created_at은 대량 적재 타임스탬프로 모든 행에서 동일하므로, 이를 기준으로 보존 기간을 계산하면 대상 항목을 결코 찾지 못합니다. joining_date는 문서 날짜를 대신하는 직원 수준의 날짜입니다. 스키마에는 문서 날짜가 없는데, 이는 업스트림에서 해결할 가치가 있는 실제 공백입니다.

• 아카이브 상태는 플래그가 아니라 테이블입니다. 레코드는 active_records 또는 archived_records에 존재하며, 이동 후에도 id는 안정적이므로 get_record는 둘 다 확인합니다. status 열은 고용 상태이며 관련이 없습니다.

• 도구는 읽기 전용으로 표시됩니다. 각 도구는 ToolAnnotations(read_only_hint=True, destructive_hint=False)를 가지므로 클라이언트는 실행 전에 안전한 호출과 상태를 변경하는 호출을 구분할 수 있습니다.

• 도구는 실제로도 읽기 전용입니다. 아카이빙은 파괴적이며 정책의 적용을 받습니다. archival_candidates는 의도적으로 아카이브 가능한 항목만 보고하고 결정은 기존 예약 작업에 맡깁니다. 모델에게 파괴적인 도구를 노출하는 것은 먼저 확인 절차가 필요한 선택입니다.

• Docstring이 API입니다. 모델은 docstring과 타입 힌트에서 도구를 선택하므로 유효한 부서와 문서 유형이 여기에 열거됩니다. 오래된 열거형은 없는 것보다 나쁩니다. 모델이 Legal처럼 그럴듯한 값을 전달하고 빈 결과를 받은 다음 아카이브할 것이 없다고 보고하기 때문입니다.

• '대상'의 단일 정의, 양방향으로 사용. _verdict는 레코드의 경과 기간을 보존 기간과 대조하고, _eligible_on은 이를 반전시켜 레코드가 해당 기간을 넘어서는 날짜를 제공하며, retention_forecast는 그 날짜를 기준으로 버킷을 나눕니다. 두 함수는 정확히 일치해야 합니다. 그렇지 않으면 같은 날 한 레코드가 예측에서는 예정됨으로, archival_candidates에서는 기한 초과로 나타날 수 있습니다. 역함수를 당연한 방식(joining + timedelta(days=years * 365.25))으로 작성하면 이 일치가 깨집니다. date + timedelta는 정수 일수만 유지하고 .75를 조용히 버리기 때문입니다.

• 출력은 형식이 지정된 텍스트이며 원시 JSON 덤프가 아닙니다. 모델이 재포맷 없이 사용자에게 그대로 인용할 수 있기 때문입니다.