gramps-web-mcp

오픈소스 족보 플랫폼 Gramps Web을 위한 MCP 보조 서버입니다. AI 에이전트가 Model Context Protocol을 통해 가계도에 접근할 수 있도록 구조화된 도구 기반 인터페이스를 제공합니다.

이 프로젝트는 독립형 족보 UI나 Gramps Web을 대체하는 것이 아닙니다. 기존 Gramps Web 인스턴스와 함께 실행하세요. 사용자, 가계도, 미디어, 권한, 족보 편집 UI는 Gramps Web에 그대로 유지됩니다.

기능

• 57개의 MCP 도구 — 사람, 가족, 사건, 장소, 출처, 인용, 메모, 미디어, 저장소, 태그의 읽기/생성/수정/삭제 지원

• 검색 및 탐색 — 전체 텍스트 검색 및 페이지별 객체 목록 보기

• 친족 도구 — 조상, 후손, 관계, 타임라인

• 복합 워크플로우 — 빠른 사람 추가, 사람에 사건 추가, Gramps ID로 찾기

• 6개의 MCP 리소스 — 유형 어휘, 입력 가이드, 가계도 메타데이터, 이름 설정, 시각 인식 에이전트를 위한 옵트인 미디어 썸네일/파일

• 미디어 보호 장치 — 크기 제한, MIME 허용 목록, 비공개 레코드 기본값

• MCP 프롬프트 — 연구, 사람/가족 추가, 가져오기를 위한 안내 워크플로우

• 다중 전송 방식 — stdio (로컬 클라이언트), Streamable HTTP, 레거시 SSE

• 읽기 전용 모드 — 모든 도구를 표시하면서 생성/수정/삭제 호출 차단

전체 목록은 도구 카탈로그를 참조하세요.

Related MCP server: ASPNET Core Debugging MCP Server

사전 요구 사항

• .NET 8 SDK (로컬 개발용)

• API 접근이 가능한 실행 중인 Gramps Web 인스턴스

• Docker (선택 사항, 컨테이너 배포용)

빠른 시작

로컬 개발 (데모 서버)

run-local-server.sh는 공개 demo.grampsweb.org 인스턴스에 잘 알려진 데모 자격 증명(owner / owner)을 사용하여 연결합니다:

./run-local-server.sh

서버는 HTTP 전송 방식으로 http://127.0.0.1:8080/mcp에서 시작됩니다. 루프백 전용으로 바인딩할 때는 API 키가 필요하지 않습니다.

Docker

사전 빌드된 멀티 아키텍처 이미지(linux/amd64, linux/arm64)가 GitHub Container Registry에 게시됩니다. Docker가 자동으로 일치하는 아키텍처를 선택합니다. amd64는 대부분의 Unraid 및 x86 호스트를, arm64는 Apple Silicon 및 ARM SBC를 지원합니다:

docker pull ghcr.io/scormave/gramps-web-mcp:latest

docker run -p 8080:8080 \
  -e GRAMPS_API_URL=https://your-gramps.example.com \
  -e GRAMPS_USERNAME=your-user \
  -e GRAMPS_PASSWORD=your-password \
  -e GRAMPS_TREE_ID=your-tree-uuid \
  -e MCP_API_KEY=your-secret-api-key \
  ghcr.io/scormave/gramps-web-mcp:latest

이미지는 Docker HEALTHCHECK, Unraid 컨테이너 상태 확인 및 기타 가동 시간 모니터를 위한 GET /health 엔드포인트를 노출합니다. MCP 서버가 Gramps Web에 대해 인증할 수 있으면 HTTP 200을 반환하고, 그렇지 않으면 HTTP 503을 반환합니다. 기본 공개 응답은 최소화되어 있습니다: { "status": "healthy" } 또는 { "status": "unhealthy" }. 시작 로그에는 API에 연결할 수 있게 되면 Connected to Gramps Web at …과 같은 줄이 포함됩니다.

이미지는 기본적으로 포트 8080에서 Streamable HTTP(MCP_TRANSPORT=http)를 사용하며, 위 명령어에서 사용된 방식입니다. 컨테이너를 직접 실행하는 클라이언트(예: MCP Registry 설치)는 대신 -e MCP_TRANSPORT=stdio와 함께 stdin을 열린 상태로 유지하여(docker run -i) stdio로 실행합니다. 이는 server.json에 선언된 모드입니다.

읽기 전용 모드의 경우 -e GRAMPS_READ_ONLY=true를 추가하세요:

docker run -p 8080:8080 \
  -e GRAMPS_API_URL=https://your-gramps.example.com \
  -e GRAMPS_USERNAME=your-user \
  -e GRAMPS_PASSWORD=your-password \
  -e GRAMPS_TREE_ID=your-tree-uuid \
  -e MCP_API_KEY=your-secret-api-key \
  -e GRAMPS_READ_ONLY=true \
  ghcr.io/scormave/gramps-web-mcp:latest

Unraid 설치

Unraid 사용자는 Community Applications에서 gramps-web-mcp를 설치할 수 있습니다. 템플릿 소스는 Scormave/gramps-web-mcp-unraid에서 관리됩니다. Unraid 관련 도움말은 Unraid 포럼 지원 스레드를 참조하세요.

기본 설정:

1. Unraid에서 Apps / Community Applications를 엽니다.

2. gramps-web-mcp를 검색하고 템플릿을 설치합니다.

3. Gramps Web 인스턴스에 맞게 GRAMPS_API_URL, GRAMPS_USERNAME, GRAMPS_PASSWORD, GRAMPS_TREE_ID를 설정합니다. MCP 포트가 네트워크의 다른 머신에서 접근 가능한 경우 MCP_API_KEY를 설정합니다.

4. 기본 컨테이너 포트 8080을 유지하거나 다른 호스트 포트로 매핑합니다.

5. 컨테이너를 시작하고 /health를 확인합니다. 서비스가 Gramps Web에 인증할 수 있으면 HTTP 200을 반환하며, 기본적으로 최소 JSON 응답이 반환됩니다.

가장 쉬운 연결을 위해 Gramps Web과 gramps-web-mcp를 동일한 Unraid Docker 네트워크에서 실행하고 GRAMPS_API_URL을 Gramps Web 컨테이너 URL로 설정하세요. 클라이언트를 위한 MCP 엔드포인트는 http://<unraid-host>:<mapped-port>/mcp입니다.

Gramps Web + MCP (Docker Compose)

동일한 호스트 및 Docker 네트워크에서 Gramps Web과 MCP 서버를 실행하려면 docker-compose.example.yml을 시작점으로 사용하세요:

cp docker-compose.example.yml docker-compose.yml
cp .env.example .env
# Complete the Gramps Web setup wizard, then set credentials in .env
docker compose up -d

Gramps Web은 포트 5055에, MCP는 포트 8080에 게시됩니다(/mcp 및 /health). Compose 네트워크 내에서 MCP 컨테이너는 http://grampsweb:5000에서 Gramps Web에 접근합니다.

Claude Desktop (MCPB 확장)

Claude Desktop용 원클릭 설치는 GitHub Releases에서 MCP Bundle (.mcpb)로 제공됩니다. 플랫폼에 맞는 번들을 다운로드하세요:

1. 최신 릴리스에서 해당 OS의 .mcpb 파일을 다운로드합니다.

2. 더블 클릭하거나 Claude Desktop 창으로 드래그합니다.

3. Gramps Web URL, 사용자 이름, 비밀번호/토큰, 가계도 UUID를 입력합니다.

4. 첫 번째 세션에서는 읽기 전용 모드를 활성화한 상태로 유지합니다. Claude가 레코드를 생성하거나 편집하도록 하려는 경우에만 비활성화합니다.

5. 설치를 완료하고 새 채팅을 시작합니다.

확장은 로컬에서 stdio를 통해 실행되며, 머신에 .NET SDK가 필요하지 않습니다. 패키징 세부 사항은 mcpb/README.md를, 개인정보 보호 정책은 PRIVACY.md를 참조하세요.

로컬에서 번들을 빌드하려면:

./scripts/pack-mcpb.sh osx-arm64   # or osx-x64, win-x64, linux-x64, linux-arm64

MCP 클라이언트 구성 (수동)

stdio (예: Claude Desktop, Cursor):

{
  "mcpServers": {
    "gramps-web": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/gramps-web-mcp/GrampsWeb.Mcp/GrampsWeb.Mcp.csproj"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "GRAMPS_API_URL": "https://your-gramps.example.com",
        "GRAMPS_USERNAME": "your-user",
        "GRAMPS_PASSWORD": "your-password",
        "GRAMPS_TREE_ID": "your-tree-uuid"
      }
    }
  }
}

읽기 전용 모드로 stdio 서버를 실행하려면 env에 "GRAMPS_READ_ONLY": "true"를 추가하세요.

HTTP (원격 / Docker):

MCP 클라이언트를 http://host:8080/mcp로 Streamable HTTP 전송 방식으로 지정하세요. MCP_API_KEY가 설정된 경우, 모든 MCP 요청에 Authorization: Bearer <key> 또는 X-Api-Key: <key>로 전송하세요.

curl -X POST http://host:8080/mcp \
  -H "Authorization: Bearer $MCP_API_KEY" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}},"id":1}'

시각 인식 에이전트는 도구(GetMediaThumbnail, GetMediaFile) 또는 바이너리 MCP 리소스(예: gramps://media/{handle}/thumbnail/{size}, gramps://media/{handle}/file)를 통해 옵트인 미디어를 읽을 수 있습니다. GetMediaFile은 MIME 유형에 따라 이미지, 오디오 또는 임베디드 blob 리소스 콘텐츠를 반환합니다. 종단 간 분석은 MCP 클라이언트가 입력된 도구 콘텐츠 또는 바이너리 리소스 콘텐츠를 적절한 모델에 전달하는지에 따라 달라집니다.

구성

필수 (Gramps 연결)

런타임 모드

• GRAMPS_READ_ONLY: true로 설정하면 도구는 표시되지만 생성/수정/삭제 호출을 차단합니다.

• GRAMPS_MUTATION_SERIALIZE: 이 프로세스에서 생성/수정/삭제 HTTP 호출을 한 번에 하나씩 실행합니다.

• GRAMPS_MUTATION_MIN_INTERVAL_MS: 복합 도구 내 단계를 포함한 변경 HTTP 호출 간 최소 대기 시간입니다.

런타임 참고 사항:

• GRAMPS_READ_ONLY=false는 서버가 읽기/쓰기 모드로 시작됨을 의미합니다.

• Claude Desktop MCPB 확장은 예외입니다. 설정 폼이 기본적으로 읽기 전용으로 설정되어 더 안전하게 처음 사용할 수 있습니다.

• 쓰기 직렬화와 선택적 간격은 일반적인 Gramps Web SQLite 가계도를 에이전트의 쓰기 폭주로부터 보호합니다.

• 쓰기 게이트는 프로세스 내에서만 작동합니다. 여러 MCP 복제본, Gramps Web UI 또는 다른 API 클라이언트와 조정하지 않습니다.

• 순차 편집 시에도 database is locked 오류가 발생하는 SQLite 배포의 경우 GRAMPS_MUTATION_MIN_INTERVAL_MS=250 또는 500으로 설정하세요.

• SQLite 잠금 오류 또는 상위 HTTP 429 발생 시, 변경 도구는 일반 500 대신 짧은 백오프 힌트와 함께 재시도 가능한 MCP 오류를 반환합니다.

• Gramps Web이 PostgreSQL을 사용하고 병렬 쓰기를 원하는 경우 GRAMPS_MUTATION_SERIALIZE=false로 설정하세요.

미디어 파일 접근

미디어 바이트 도구/리소스는 기본적으로 비활성화되어 있습니다. get_media는 파일 다운로드 없이 메타데이터에 계속 사용할 수 있습니다.

AI 분석에는 GetMediaThumbnail 또는 gramps://media/{handle}/thumbnail/{size}를 선호하세요. 전체 파일은 크고 민감할 수 있으며, 동일한 크기, MIME, 비공개 레코드 검사가 적용됩니다.

정확한 유형과 type/* 와일드카드가 지원됩니다. 기본 미디어 허용 목록은 image/jpeg,image/png,image/webp,image/avif,application/pdf입니다.

전송 방식

GRAMPS_API_URL, GRAMPS_USERNAME, GRAMPS_PASSWORD, GRAMPS_TREE_ID는 평소와 같이 설정하세요.

HTTP 전송 방식의 경우 응답이 SSE를 통해 스트리밍됩니다. 프로토콜 세부 사항은 Streamable HTTP 명세를 참조하세요. ASPNETCORE_URLS를 설정하여 수신 주소를 선택하세요. 예: http://127.0.0.1:8080.

선택 사항 (MCP 전송)

HTTP 인증

MCP_API_KEY가 설정되면 모든 MCP HTTP/SSE 엔드포인트는 모든 요청에서 키를 요구합니다. GET /health는 Docker 및 로드 밸런서 프로브를 위해 익명으로 유지됩니다.

키 생성:

openssl rand -base64 32

키가 없어도 서버는 계속 시작됩니다(하위 호환). 수신 대기 주소가 루프백 전용이 아닌 경우 MCP_API_KEY를 설정하거나, 자체 인증이 있는 역방향 프록시를 사용하거나, 로컬 전용으로 127.0.0.1에 바인딩할 것을 권장하는 경고가 기록됩니다.

Docker 내부에서 ASPNETCORE_URLS는 일반적으로 http://0.0.0.0:8080이므로 호스트가 127.0.0.1에서만 포트를 게시하더라도 경고가 표시됩니다. 외부 접근이 이미 제한된 경우에는 예상되는 동작입니다.

개발

dotnet test

CONTRIBUTING.md 및 개발자 가이드를 참조하세요.

문서

기여

기여를 환영합니다. CONTRIBUTING.md를 참조하세요.

보안

취약점을 신고하려면 SECURITY.md를 참조하세요.

개인정보 처리방침

Claude Desktop 확장 프로그램은 로컬 MCP 서버입니다. 사용자가 구성한 Gramps Web 인스턴스에만 데이터를 전송하며 분석 데이터나 대화 데이터를 수집하지 않습니다. 자세한 내용은 PRIVACY.md를 참조하세요.

라이선스

Copyright (c) Scormave

이 프로젝트는 GNU Affero General Public License v3.0 (AGPL-3.0-or-later)에 따라 라이선스가 부여됩니다. 이 소프트웨어는 네트워크 서버 소프트웨어이므로, 수정된 버전을 호스팅하는 경우 네트워크를 통해 상호작용하는 사용자에게 해당 소스 코드를 제공해야 합니다.