Gitea MCP 서버

자체 호스팅 Gitea 플랫폼과의 원활한 통합을 위한 프로덕션급 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버는 디렉터리 구조를 유지하면서 저장소를 생성하고 파일을 업로드하는 도구를 제공합니다.

설치 및 설정 가이드

이 가이드는 일반적인 문제 해결을 포함하여 Gitea MCP 서버를 설치하고 구성하는 단계별 지침을 제공합니다.

Related MCP server: Gitea MCP Tool

기능

• 저장소 생성: 구성된 모든 Gitea 인스턴스에 새 저장소 생성

• 파일 업로드: 디렉터리 구조를 유지하면서 파일 및 폴더 업로드

• 프로젝트 동기화: 초기 커밋을 위해 전체 프로젝트 자동 동기화 (새 파일만)

• 고급 파일 업데이트: 기존 파일 수정을 위한 충돌 해결 기능이 포함된 스마트 업데이트 도구

• 다중 인스턴스 지원: 여러 Gitea 인스턴스에 동시에 연결

• 속도 제한: 인스턴스별 API 속도 제한 준수

• 일괄 처리: 구성 가능한 일괄 처리 크기로 효율적인 파일 업로드

• 포괄적인 로깅: 보안이 확보된 출력과 함께 구조화된 로깅

• 오류 처리: 재시도 로직을 포함한 강력한 오류 처리

• TypeScript: 완전한 타입 안전성 및 최신 JavaScript 기능

빠른 시작

사전 요구 사항

• Node.js 18.0.0 이상

• 하나 이상의 Gitea 인스턴스에 대한 액세스 권한

• 인증을 위한 개인 액세스 토큰

설치

1. 저장소 복제:

git clone <repository-url>
cd gitea-mcp

2. 종속성 설치:

npm install

3. 환경 변수 구성:

cp .env.example .env
# Edit .env with your Gitea instance details

4. 프로젝트 빌드:

npm run build

5. 서버 시작:

npm run start:mcp

일반적인 문제 해결

Windows 호환성

Windows에서 실행 중인 경우 빌드 스크립트와 관련된 문제가 발생할 수 있습니다. 기본 빌드 스크립트는 Windows에서 사용할 수 없는 chmod 명령을 사용합니다. package.json은 Windows 호환 빌드 스크립트를 사용하도록 업데이트되었습니다.

로깅 구성

로깅 구성에 문제가 발생하는 경우 pino-pretty 패키지가 설치되어 있는지 확인하십시오:

npm install --save-dev pino-pretty

환경 변수

.env 파일에는 다음 구성이 포함되어야 합니다:

# Server Configuration
NODE_ENV=development
LOG_LEVEL=debug

# Gitea Configuration
# Replace with your Gitea instance URL and token
GITEA_INSTANCES=[{"id":"main","name":"Main Gitea Instance","baseUrl":"https://your-gitea-instance.com","token":"your-personal-access-token","timeout":30000,"rateLimit":{"requests":100,"windowMs":60000}}]

# Upload Configuration
MAX_FILE_SIZE=10485760
MAX_FILES=100
BATCH_SIZE=10

# Gitea API Configuration
GITEA_TIMEOUT=30000
GITEA_MAX_RETRIES=3

"https://your-gitea-instance.com"을 실제 Gitea 인스턴스 URL로, "your-personal-access-token"을 Gitea 개인 액세스 토큰으로 바꾸십시오.

디버그 로깅으로 실행

디버그 로깅을 활성화하여 서버를 실행하려면 start:mcp 스크립트를 사용하십시오:

npm run start:mcp

이 스크립트는 서버를 시작하기 전에 NODE_ENV를 development로, LOG_LEVEL을 debug로 설정합니다.

개발 설정

핫 리로딩을 포함한 개발 환경:

npm run dev

구성

환경 변수

.env.example을 기반으로 .env 파일을 만듭니다:

# Server Configuration
NODE_ENV=development
LOG_LEVEL=info

# Gitea Configuration
GITEA_INSTANCES='[
  {
    "id": "main",
    "name": "Main Gitea Instance", 
    "baseUrl": "https://gitea.example.com",
    "token": "your-personal-access-token",
    "timeout": 30000,
    "rateLimit": {
      "requests": 100,
      "windowMs": 60000
    }
  }
]'

# Upload Configuration
MAX_FILE_SIZE=10485760  # 10MB
MAX_FILES=100
BATCH_SIZE=10

# API Configuration
GITEA_TIMEOUT=30000
GITEA_MAX_RETRIES=3

Gitea 인스턴스 구성

각 Gitea 인스턴스에는 다음이 필요합니다:

• id: 인스턴스에 대한 고유 식별자

• name: 로깅을 위한 사람이 읽을 수 있는 이름

• baseUrl: Gitea 인스턴스의 기본 URL

• token: 적절한 권한이 있는 개인 액세스 토큰

• timeout: 요청 시간 제한(밀리초 단위, 선택 사항)

• rateLimit: 속도 제한 구성(선택 사항)

개인 액세스 토큰 설정

1. Gitea 인스턴스에 로그인

2. 설정(Settings) → 애플리케이션(Applications) → 개인 액세스 토큰(Personal Access Tokens)으로 이동

3. 다음 권한으로 새 토큰 생성:

   • repo: 전체 저장소 액세스

   • write:repository: 저장소 생성

   • read:user: 사용자 정보 읽기

MCP 클라이언트 구성

Claude Desktop

Claude Desktop 구성에 추가:

{
  "mcpServers": {
    "gitea-mcp": {
      "command": "node",
      "args": ["./build/index.js"],
      "cwd": "/path/to/gitea-mcp",
      "env": {
        "NODE_ENV": "production",
        "LOG_LEVEL": "info"
      }
    }
  }
}

기타 MCP 클라이언트

서버는 stdio를 통해 통신하며 MCP 프로토콜 사양을 따릅니다. 구성 세부 정보는 클라이언트 설명서를 참조하십시오.

사용 가능한 도구

create_repository

지정된 Gitea 인스턴스에 새 저장소를 생성합니다.

매개변수:

• instanceId (문자열, 필수): Gitea 인스턴스 식별자

• name (문자열, 필수): 저장소 이름

• description (문자열, 선택 사항): 저장소 설명

• private (불리언, 기본값: true): 저장소를 비공개로 설정

• autoInit (불리언, 기본값: true): README로 초기화

• defaultBranch (문자열, 기본값: "main"): 기본 브랜치 이름

예시:

{
  "instanceId": "main",
  "name": "my-new-repo",
  "description": "A test repository",
  "private": true,
  "autoInit": true,
  "defaultBranch": "main"
}

upload_files

디렉터리 구조를 유지하면서 저장소에 여러 파일을 업로드합니다.

매개변수:

• instanceId (문자열, 필수): Gitea 인스턴스 식별자

• owner (문자열, 필수): 저장소 소유자 사용자 이름

• repository (문자열, 필수): 저장소 이름

• files (배열, 필수): path와 content를 포함하는 파일 객체 배열

• message (문자열, 필수): 커밋 메시지

• branch (문자열, 기본값: "main"): 대상 브랜치

• batchSize (숫자, 기본값: 10): 배치당 파일 수

예시:

{
  "instanceId": "main",
  "owner": "username",
  "repository": "my-repo",
  "files": [
    {
      "path": "README.md",
      "content": "# My Project\n\nProject description here."
    },
    {
      "path": "src/index.js", 
      "content": "console.log('Hello, World!');"
    }
  ],
  "message": "Initial commit",
  "branch": "main",
  "batchSize": 5
}

sync_project ⚠️ 초기 커밋 전용

.gitignore 규칙을 준수하면서 전체 프로젝트 디렉터리를 Gitea 저장소에 자동으로 검색하고 동기화합니다.

중요: 이 도구는 초기 프로젝트 업로드를 위해 설계되었으며 새 파일만 생성할 수 있습니다. 저장소에 이미 존재하는 파일은 업데이트할 수 없습니다. 기존 파일을 업데이트하려면 sync_update 도구를 대신 사용하십시오.

매개변수:

• instanceId (문자열, 필수): Gitea 인스턴스 식별자

• owner (문자열, 필수): 저장소 소유자 사용자 이름

• repository (문자열, 필수): 저장소 이름

• message (문자열, 필수): 동기화를 위한 커밋 메시지

• branch (문자열, 기본값: "main"): 대상 브랜치

• projectPath (문자열, 기본값: "."): 동기화할 프로젝트 디렉터리 경로

• dryRun (불리언, 기본값: false): 실제로 업로드하지 않고 업로드될 내용을 미리 보기

• includeHidden (불리언, 기본값: false): 숨김 파일 포함 ( . 으로 시작하는 파일)

• maxFileSize (숫자, 기본값: 1048576): 최대 파일 크기(바이트 단위, 1MB)

• textOnly (불리언, 기본값: true): 텍스트 파일만 업로드 (바이너리 파일 건너뛰기)

기능:

• .gitignore 규칙을 자동으로 읽고 적용

• 일반적인 무시 패턴(node_modules/, .git/ 등)에 대한 합리적인 기본값 포함

• 프로젝트 디렉터리를 재귀적으로 스캔하여 적격 파일 찾기

• 바이너리 파일을 감지하고 선택적으로 건너뛰는 간단한 휴리스틱

• 대용량 파일에 대한 크기 필터링

• 변경 사항 미리 보기를 위한 드라이 런(Dry run) 모드

• 발견, 필터링, 업로드 및 실패한 파일에 대한 상세 보고

사용 사례:

• 초기 프로젝트 설정 및 첫 커밋

• 빈 저장소에 새 프로젝트 업로드

• 새 저장소에 대량 파일 업로드

예시:

{
  "instanceId": "main",
  "owner": "username",
  "repository": "my-project",
  "message": "Initial project sync",
  "branch": "main",
  "projectPath": "./my-app",
  "dryRun": false,
  "includeHidden": false,
  "maxFileSize": 2097152,
  "textOnly": true
}

sync_update ✨ 고급 파일 업데이트

지능적인 충돌 해결 및 변경 사항 감지 기능을 갖춘 Gitea 저장소의 기존 파일 업데이트를 위한 고급 도구입니다.

매개변수:

• instanceId (문자열, 필수): Gitea 인스턴스 식별자

• owner (문자열, 필수): 저장소 소유자 사용자 이름

• repository (문자열, 필수): 저장소 이름

• files (배열, 필수): 파일 작업 객체 배열

• files[].path (문자열, 필수): 저장소 내 파일 경로 (슬래시 사용)

• files[].content (문자열, 조건부): 파일 내용 (추가/수정 작업에 필수)

• files[].operation (문자열, 필수): 작업 유형: 'add', 'modify', 또는 'delete'

• files[].sha (문자열, 선택 사항): 현재 파일 SHA (제공되지 않으면 자동 감지)

• message (문자열, 필수): 모든 작업에 대한 커밋 메시지

• branch (문자열, 기본값: "main"): 대상 브랜치

• strategy (문자열, 기본값: "auto"): 업데이트 전략: 'auto', 'batch', 또는 'individual'

• conflictResolution (문자열, 기본값: "fail"): 충돌 처리: 'fail', 'overwrite', 또는 'skip'

• detectChanges (불리언, 기본값: true): 불필요한 업데이트를 방지하기 위해 원격 파일과 비교

• dryRun (불리언, 기본값: false): 변경 사항을 적용하지 않고 작업 미리 보기

주요 기능:

• 스마트 API 사용: 업데이트에는 PUT, 생성에는 POST, 삭제에는 DELETE 사용

• 변경 사항 감지: 로컬과 원격 콘텐츠를 비교하여 불필요한 업데이트 건너뛰기

• 자동 SHA 확인: 업데이트 작업에 필요한 SHA 값을 자동으로 가져오기

• 다중 전략: 자동, 일괄(단일 커밋), 또는 개별(별도 커밋)

• 충돌 해결: 마지막 동기화 이후 원격 파일이 변경된 경우 처리

• 혼합 작업: 단일 호출로 생성, 업데이트 및 삭제 작업 처리 가능

• 드라이 런 모드: 변경 사항을 적용하지 않고 수행될 작업 미리 보기

작업 유형:

• add: 새 파일 생성 (POST API와 동일)

• modify: 기존 파일 업데이트 (충돌 해결을 위해 SHA와 함께 PUT API 사용)

• delete: 기존 파일 제거 (SHA와 함께 DELETE API 사용)

전략 옵션:

• auto: 파일 수와 작업 유형에 따라 최적의 접근 방식을 지능적으로 선택

• batch: Gitea의 배치 API를 사용하여 단일 커밋으로 모든 작업 수행

• individual: 각 작업을 별도의 커밋으로 수행

사용 사례:

• 기존 프로젝트 파일 업데이트

• 선택적 파일 수정

• 대량 파일 작업 (생성, 업데이트, 삭제)

• 점진적 프로젝트 업데이트

• 자동화된 파일 유지 관리

예시:

{
  "instanceId": "main",
  "owner": "username",
  "repository": "my-project",
  "files": [
    {
      "path": "README.md",
      "content": "# Updated Project\n\nThis is an updated version of the project.",
      "operation": "modify"
    },
    {
      "path": "src/new-feature.js",
      "content": "// New feature implementation\nfunction newFeature() {\n  return 'Hello, World!';\n}",
      "operation": "add"
    },
    {
      "path": "old-file.txt",
      "operation": "delete"
    }
  ],
  "message": "Update documentation and add new feature",
  "branch": "main",
  "strategy": "auto",
  "detectChanges": true,
  "dryRun": false
}

드라이 런 예시 응답:

{
  "dryRun": true,
  "strategy": "individual",
  "summary": {
    "discovered": 3,
    "analyzed": 3,
    "needsUpdate": 2,
    "processed": 0,
    "succeeded": 0,
    "failed": 0,
    "skipped": 0
  },
  "filesNeedingUpdate": [
    {
      "path": "README.md",
      "operation": "modify",
      "hasRemoteSha": true
    },
    {
      "path": "src/new-feature.js",
      "operation": "add",
      "hasRemoteSha": false
    }
  ]
}

도구 선택 가이드

각 도구 사용 시기:

1. create_repository: 새 저장소 생성

2. sync_project: 빈/새 저장소에 초기 프로젝트 업로드

3. upload_files: 프로세스를 완전히 제어하면서 특정 파일 업로드

4. sync_update: 기존 저장소에서 기존 파일 업데이트, 새 파일 생성 또는 파일 삭제

워크플로우 예시:

# 1. Create a new repository
create_repository → "my-new-project"

# 2. Initial upload of all project files
sync_project → Upload entire project structure

# 3. Later updates to specific files
sync_update → Modify README.md, add new features, delete old files

개발

스크립트

• npm run build - 프로덕션용 빌드

• npm run dev - 핫 리로딩을 포함한 개발

• npm start - 프로덕션 서버 시작

• npm test - 테스트 실행

• npm run lint - 코드 린트

• npm run format - 코드 포맷팅

• npm run type-check - TypeScript 타입 검사

프로젝트 구조

gitea-mcp/
├── src/
│   ├── index.ts              # Main server entry point
│   ├── config/               # Configuration management
│   ├── gitea/                # Gitea API client
│   ├── tools/                # MCP tool implementations
│   ├── services/             # Business logic services
│   ├── utils/                # Utilities (logging, errors, etc.)
│   └── types/                # TypeScript type definitions
├── build/                    # Compiled JavaScript
├── docs/                     # Documentation
└── package.json

새 도구 추가

1. src/tools/에 도구 구현 생성

2. src/tools/schemas.ts에 스키마 유효성 검사 추가

3. src/tools/index.ts에 도구 등록

4. tests/unit/tools/에 테스트 추가

배포

Docker

Docker로 빌드 및 실행:

# Build image
docker build -t gitea-mcp .

# Run container
docker run -d \
  --name gitea-mcp \
  --env-file .env \
  gitea-mcp

프로덕션 고려 사항

• 토큰에는 환경 변수 또는 비밀 관리 사용

• 적절한 로그 수준 구성

• 모니터링 및 상태 확인 설정

• Node.js 애플리케이션에는 PM2와 같은 프로세스 관리자 사용

• 오케스트레이션을 위해 Docker 또는 Kubernetes 사용 고려

보안

모범 사례

• 환경 변수 또는 비밀 관리를 사용하여 토큰을 안전하게 저장

• 액세스 토큰에 필요한 최소한의 권한만 사용

• 모든 입력 매개변수 유효성 검사

• 민감한 데이터를 노출하지 않고 보안 이벤트 로깅

• 모든 Gitea API 통신에 HTTPS 사용

• 정기적으로 액세스 토큰 교체

속도 제한

서버는 API 제한을 준수하기 위해 Gitea 인스턴스별로 속도 제한을 구현합니다:

• 기본값: 인스턴스당 분당 100회 요청

• 인스턴스 구성에서 rateLimit을 통해 구성 가능

• 지수 백오프를 통한 자동 재시도

문제 해결

일반적인 문제

인증 실패

• 액세스 토큰이 올바르고 필요한 권한이 있는지 확인

• 토큰이 만료되지 않았는지 확인

• 기본 URL이 올바른지 확인

속도 제한 초과

• 파일 업로드 배치 크기 줄이기

• 속도 제한 구성 조정

• 요청 재시도 전 대기

파일 업로드 실패

• 파일 내용이 유효한지 확인

• 파일 경로에 잘못된 문자가 포함되어 있지 않은지 확인

• 저장소가 존재하고 쓰기 권한이 있는지 확인

로깅

문제 해결을 위해 디버그 로깅 활성화:

LOG_LEVEL=debug npm start

상태 확인

서버 상태 확인:

curl -f http://localhost:8080/health || exit 1

기여

1. 저장소 포크

2. 기능 브랜치 생성

3. 테스트와 함께 변경 사항 적용

4. 린트 및 타입 검사 실행

5. 풀 리퀘스트 제출

라이선스

MIT 라이선스 - 자세한 내용은 LICENSE 파일을 참조하십시오.

지원

• GitHub Issues: 버그 및 기능 요청 보고

• 문서: docs/ 디렉터리 확인

• 예시: examples/ 디렉터리 확인

Gitea 및 MCP 커뮤니티를 위해 ❤️로 제작되었습니다.

참고 항목