Skip to main content
Glama
deenesjakoruzh
jersonmartinez

github-project-management

by jersonmartinez
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

GitHub Project Management MCP Server

MCP CI

AI 어시스턴트가 Model Context Protocol을 통해 GitHub Project V2 보드를 프로그래밍 방식으로 관리할 수 있게 해주는 커스텀 MCP(Model Context Protocol) 서버입니다. Python 3.12 및 FastMCP로 구축되었으며, stdio 전송으로 통신하고 독립형 Docker 컨테이너 안에서 실행됩니다.

위치

project/
├── mcp/                    ← This directory (root-level, independent of the app)
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── server.py           # FastMCP entry point
│   ├── config.py
│   ├── auth.py
│   ├── capabilities.py     # Tool → permission mapping
│   ├── profiles.py         # Multi-target profile system
│   ├── tools/              # MCP tool definitions
│   ├── services/           # Business logic
│   ├── clients/            # GraphQL + gh CLI clients
│   ├── models/             # Pydantic models
│   ├── graphql/            # Query/mutation strings
│   ├── tests/              # Unit + contract tests
│   ├── scripts/            # Validation, preflight, secret scanning
│   │   ├── validate.sh     # ← Run before every push
│   │   ├── preflight.sh    # Environment prerequisites
│   │   ├── scan_secrets.sh # Token pattern detection
│   │   └── smoke_build.sh  # Minimal build verification
│   ├── profiles/           # Target config (.env files, no secrets)
│   ├── docs/               # Detailed documentation
│   ├── LICENSE             # MIT
│   ├── CONTRIBUTING.md
│   └── SECURITY.md

참고: 이 MCP 서버는 자체 Dockerfile, 종속성 및 수명 주기를 가진 독립 구성 요소입니다.

Related MCP server: GitHub Projects MCP Server

작동 방식

MCP Client → docker run --rm -i github-project-mcp:latest → stdin/stdout JSON-RPC → GitHub API

  1. MCP 클라이언트가 도구를 호출합니다(예: create_project_item).

  2. docker run --rm -i github-project-mcp:latest python server.py가 실행됩니다.

  3. 서버는 인증을 검증하고 stdin을 통해 명령을 기다립니다.

  4. 클라이언트는 JSON-RPC를 stdin으로 보내고 stdout으로 응답을 받습니다.

  5. 완료되면 컨테이너는 자동으로 제거됩니다(--rm).

Docker — 빌드 및 관리

이미지 빌드

# Desde la raíz del proyecto
docker build -t github-project-mcp:latest ./mcp

Docker Compose(로컬 개발)

로컬에서 MCP를 설정하고 실행하는 가장 간단한 방법:

# 1. Crear tu configuración local (una sola vez)
cp mcp/.env.example mcp/.env
# Editar mcp/.env con tu GITHUB_TOKEN y target (org/repo/project)

# 2. Construir y verificar
cd mcp/
make build
make verify

Makefile 타깃

모든 타깃은 Docker 내에서 실행됩니다 — 호스트 의존성 없음.

cd mcp/
make help         # Mostrar todos los targets disponibles
make build        # Construir imagen Docker
make verify       # Validar auth + scopes + config
make test         # Ejecutar unit tests
make validate     # CI completo (build + syntax + tests + tools + secrets)
make tools        # Contar herramientas registradas (>= 100)
make syntax       # Verificar sintaxis Python
make secrets      # Escanear credenciales en código
make shell        # Shell interactivo dentro del contenedor
make clean        # Eliminar imágenes

참고: 호스트에서 make를 사용할 수 없는 경우 타깃을 Docker로 직접 호출할 수 있습니다. 예: docker run --rm --env-file .env github-project-mcp:latest python3 scripts/verify_setup.py

각 기여자는 저장소를 클론하고 자신의 .env를 만들기만 하면, Docker 외에 아무것도 설치하지 않고도 MCP가 작동합니다.

이미지가 존재하는지 확인

docker images | grep github-project-mcp

수동 테스트(스모크 테스트)

docker run --rm -i \
  -e GITHUB_TOKEN="<your_token>" \
  github-project-mcp:latest \
  python server.py

서버는 stderr에 github-project-management MCP server ready. Authentication validated successfully.를 출력합니다. 그런 다음 stdin을 통해 JSON-RPC를 기다립니다. 종료하려면 Ctrl+C를 누르세요.

변경 후 재빌드

docker build -t github-project-mcp:latest ./mcp --no-cache

관리 스크립트

./scripts/dev/start.sh 스크립트는 이미지를 관리하기 위한 mcp 인자를 지원합니다:

./scripts/dev/start.sh mcp build      # Construir/reconstruir la imagen
./scripts/dev/start.sh mcp test       # Ejecutar smoke test
./scripts/dev/start.sh mcp status     # Verificar si la imagen existe

참고: MCP는 지속적인 서비스가 아닙니다. up/down/restart가 필요하지 않습니다. 클라이언트가 도구를 사용할 때마다 요청 시 실행됩니다.

IDE 통합

MCP는 stdio를 통한 MCP 프로토콜을 지원하는 모든 클라이언트와 호환됩니다. 구성은 IDE에 따라 다릅니다 — 일반적인 패턴은 다음과 같습니다:

{
  "mcpServers": {
    "github-project-management": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "GITHUB_TOKEN",
        "--env-file", "mcp/.env",
        "github-project-mcp:latest",
        "python", "server.py"
      ]
    }
  }
}

IDE별 특정 구성은 docs/SETUP.md를 참조하세요.

등록된 도구(100개)

핵심 작업

도구

설명

discover_ids

프로젝트/필드 ID 찾기

list_project_items

필터로 항목 나열

create_project_item

이슈 생성 + 프로젝트에 추가

update_project_item_fields

상태, 우선순위, 마감일 업데이트

set_estimate

스토리 포인트 추정치 설정

archive_project_item

보드에서 항목 보관

이슈 관리

도구

설명

close_issue

이슈 닫기

reopen_issue

닫힌 이슈 다시 열기

comment_issue

이슈에 댓글 추가

edit_issue

제목, 본문, 라벨, 마일스톤, 담당자 편집

add_sub_issue

하위 이슈로 연결

remove_sub_issue

하위 이슈 연결 해제

get_issue_detail

전체 이슈 상세 정보

search_issues

쿼리로 검색

보드 작업

도구

설명

move_to_status

항목을 모든 상태 열로 이동

move_to_done

Done으로 표시

move_to_trash

휴지통으로 이동

bulk_update_items

여러 항목 일괄 업데이트

bulk_close_issues

여러 이슈 일괄 닫기

bulk_assign

여러 이슈 담당자 지정

계획 및 워크플로

도구

설명

sprint_planning

스프린트 계획 생성

generate_release_notes

릴리스 노트 자동 생성

complete_issue

전체 완료 워크플로

daily_standup

스탠드업 보고서 생성

sprint_review

스프린트 리뷰 요약

triage_new_issues

제안 자동 트리아지

escalate_overdue

기한 초과 항목에 플래그 지정

create_epic

상위 + 하위 이슈 생성

close_sprint

스프린트 종료 및 항목 이동

메타데이터

도구

설명

create_milestone

GitHub 마일스톤 생성

close_milestone

마일스톤 닫기

list_milestones

마일스톤 목록 표시

create_label

라벨 생성

list_labels

라벨 목록 표시

get_project_stats

보드 통계

get_sprint_summary

현재 스프린트 지표

아키텍처

Tool Layer (FastMCP tool definitions)
    ↓
Service Layer (business logic, orchestration)
    ↓
Client Layer (GraphQL + gh CLI + caching)
    ↓
GitHub APIs (GraphQL v4 + REST v3)

위임 전략

메서드

사용 시기

gh CLI

이슈 CRUD, 댓글, 프로젝트 항목 추가, 닫기

Custom GraphQL

필드 업데이트, 보관, 검색, 하위 이슈

환경 변수

변수

필수

설명

GITHUB_TOKEN

예

GitHub PAT(세분화된 또는 클래식)

GH_PROJECT_ORG_NAME

예

GitHub 소유자(조직 또는 사용자 로그인)

GH_PROJECT_REPO_NAME

예

저장소 이름

GH_PROJECT_PROJECT_NUMBER

예

Project V2 보드 번호(1–100000)

문제 해결

MCP가 연결되지 않음

# Verificar que la imagen existe
docker images | grep github-project-mcp

# Si no existe, construir
docker build -t github-project-mcp:latest ./mcp

# Verificar token
echo $GITHUB_TOKEN | head -c 20

MCP 다시 연결

MCP가 IDE에서 연결 해제되면 해당 MCP 클라이언트의 다시 연결 옵션을 사용하세요.

인증 오류

  • GITHUB_TOKEN이 컨테이너 환경에서 사용 가능한지 확인하세요.

  • github_pat_*(세분화된) 토큰에는 권한이 필요합니다: Issues(RW), Projects(RW), Metadata(R)

  • 클래식 토큰에는 scopes가 필요합니다: repo, project, read:org

관련 문서

문서

용도

docs/SETUP.md

토큰 설정 및 권한

docs/USAGE.md

도구 입력/출력 예시

docs/PARAMETERS.md

매개변수 참조

docs/TROUBLESHOOTING.md

일반적인 오류

소스 위치 및 동기화

이 디렉터리(mcp/)는 MCP 패키지의 캐노니컬 소스(공식 원본) 입니다.

저장소에는 동기화된 사본이 다음 위치에 있습니다:

  • app/backend/app/mcp/github_project/ — Docker 빌드를 위해 백엔드에 포함됨

동기화 워크플로

  1. 먼저 mcp/에서 모든 변경을 수행합니다.

  2. 수정된 파일을 포함 경로로 복사합니다:

cp mcp/<file> app/backend/app/mcp/github_project/<file>

  1. 자동화된 검사로 검증합니다:

./mcp/scripts/check_sync.sh

동기화 스크립트는 모든 공유 .py 파일을 비교합니다(백엔드 사본에서 의도적으로 다른 __init__.py와 Dockerfile, requirements.txt 같은 인프라 전용 파일은 제외). CI는 모든 푸시에서 이 검사를 실행하며, 차이가 발생하면 빌드가 실패합니다.

백엔드 사본에서 의도적으로 다른 파일

파일

이유

__init__.py

백엔드 전용 임포트 + 동기화 소스 문서

README.md

이곳을 가리키며 복사 정책을 문서화

백엔드 테스트 스위트는 포함된 사본을 대상으로 실행됩니다. 구문 검증은 두 트리를 모두 컴파일해야 합니다.

강화된 런타임 동작

모든 설정은 GH_PROJECT_ 접두사를 사용하며 시작 시 검증됩니다:

설정

기본값

범위 / 동작

GH_PROJECT_TIMEOUT_SECONDS

10

1–120초

GH_PROJECT_RETRY_ATTEMPTS

1

0–5; 읽기 전용, 변경 작업은 재시도하지 않음

GH_PROJECT_RETRY_DELAY_SECONDS

2.0

0–60초, 지수 백오프

GH_PROJECT_CACHE_TTL_HOURS

24

1–720시간

GH_PROJECT_CACHE_PATH

.github_project_cache.json

구성 가능한 로컬 경로

GH_PROJECT_PAGE_SIZE

100

1–100

GH_PROJECT_MAX_ITEMS

200

1–1,000

GH_PROJECT_MAX_CLI_OUTPUT_CHARS

1,000,000

10,000–10,000,000

메타데이터 캐시는 원자적으로 기록되며, 소유자 전용 권한(0600)을 사용하고, 미래 타임스탬프를 거부하며, 조직이나 프로젝트 번호가 다르면 재사용되지 않습니다. CLI 및 GraphQL 진단은 토큰 형태의 값을 마스킹하고 MCP 클라이언트에 반환하기 전에 크기를 제한합니다.

Docker 전용 검증

호스트 Python 도구 없이 검증을 실행합니다:

# Compile both source copies through a Python container
tar -C . -cf - mcp app/backend/app/mcp \
  | docker run --rm -i python:3.12-slim sh -c \
    'mkdir -p /tmp/factib && tar -xf - -C /tmp/factib && \
     python -m compileall -q /tmp/factib/mcp /tmp/factib/app/backend/app/mcp'

# Run the backend MCP tests using the existing backend image
tar -C . -cf - app/backend/app app/backend/tests/mcp \
  | docker run --rm -i -e PYTHONPATH=/tmp/factib/app/backend backend:latest sh -c \
    'mkdir -p /tmp/factib && tar -xf - -C /tmp/factib && cd /tmp/factib/app/backend && \
     pytest -q --confcutdir=/tmp/factib/app/backend/tests/mcp tests/mcp'

로컬 검증(푸시 전)

PR을 생성하거나 변경 사항을 푸시하기 전에 항상 실행하세요. 이는 CI 파이프라인을 로컬에서 미러링하여 문제가 GitHub Actions에 도달하기 전에 잡아냅니다.

빠른 시작

# Full validation (builds image + runs all checks):
./mcp/scripts/validate.sh

# Quick mode (reuses cached image, skips rebuild):
./mcp/scripts/validate.sh --quick

# Auto-fix known issues (e.g., BOM characters):
./mcp/scripts/validate.sh --fix

검사 내용

단계

내용

CI 단계와 동일

1. BOM

Python 파일에서 UTF-8 BOM 바이트 감지

해당 없음(구문 오류 방지)

2. 빌드

docker build -t github-project-mcp:validate ./mcp

"MCP 이미지 빌드"

3. 구문

이미지 내 모든 .py 파일에 대해 ast.parse

"구문 검사"

4. 테스트

tests/에서 테스트 모듈 실행

"단위 테스트 실행"

5. 도구

등록된 도구 수 계산(100개 이상이어야 함)

"도구 수 검증"

6. 시크릿

추적된 파일에서 토큰 패턴 스캔

해당 없음(공개 전)

사용 가능한 스크립트

스크립트

용도

사용 시기

scripts/validate.sh

전체 CI 미러

모든 푸시/PR 전

scripts/preflight.sh

사전 요구사항 확인(Docker, 토큰, 구성)

초기 설정 또는 환경 변경 시

scripts/scan_secrets.sh

시크릿 패턴 감지

저장소 공개 전

scripts/smoke_build.sh

최소 빌드 + 도구 수

빠른 정상 확인

scripts/run_contract_tests.sh

다중 타깃 계약 테스트 스위트

구조 변경 후

일반적인 문제 및 해결 방법

문제

증상

해결 방법

BOM 문자

SyntaxError: invalid non-printable character U+FEFF

./mcp/scripts/validate.sh --fix

이미지가 빌드되지 않음

Docker 명령에서 "Image not found"

docker build -t github-project-mcp:latest ./mcp

토큰 미설정

사전 점검에서 "No GitHub token found"

export GITHUB_TOKEN=ghp_...

도구 수 < 100

새 도구가 server.py에 등록되지 않음

server.py에서 mcp.tool()(your_tool) 추가

구현된 작업과 계획된 작업을 포함한 전체 200개 항목 목록은 docs/HARDENING_200.md에 있습니다.

확장 기능 모음: 추가 도구 60개

이 서버는 총 100개 이상의 도구를 제공합니다. 즉, 원래의 운영 도구 40개와 tools/capability_suite.py의 특화 기능 60개로 구성됩니다.

그룹

목적

예시

이슈 및 Markdown 품질

이슈 검증, 정규화, 요약, 템플릿화, 번들 및 검토

validate_issue_markdown, build_issue_template, build_issue_review_checklist

댓글 시스템

진행, 계획, 차단, 해결 댓글 생성; 댓글 목록/검색/편집

comment_issue_progress, comment_issue_blocker, list_issue_comments

프로젝트 보고

건강도, 상태, 우선순위, 담당자, 마감일 및 필드 보고서

project_health_report, project_due_date_risk, project_field_options_report

프로젝트 계획

Markdown 내보내기/가져오기, 메타데이터 동기화 계획 및 필터링된 일괄 계획

project_export_markdown, project_sync_issue_metadata, project_bulk_status_by_filter

전략적 자동화

스프린트 계획, 백로그 순위, 리스크/의존성 보고서 및 이해관계자 업데이트

plan_next_sprint, prioritize_backlog, generate_risk_register

로드맵 및 의사결정

변경 로그, 릴리스 체크리스트, 로드맵, 회고 및 자동화 의사결정

generate_changelog_from_issues, build_roadmap_markdown, build_sprint_retrospective

광범위한 변경을 유발할 수 있는 도구는 기본적으로 dry_run 계획을 반환합니다. 직접 댓글 도구는 호출당 하나의 실제 댓글 작업을 수행합니다. 기능 카탈로그는 가져오기 시점에 60개의 고유 추가 항목을 검증하며, Docker 검증은 두 소스 사본 모두에서 등록된 FastMCP 도구 100개를 확인합니다.

배포

Docker 이미지

MCP 서버는 독립형 Docker 이미지로 배포됩니다. 로컬 빌드:

docker build -t github-project-mcp:latest ./mcp

CI/CD 파이프라인

mcp-ci.yaml 워크플로는 다음 경우에 자동으로 실행됩니다:

  • mcp/ 아래 파일이 변경될 때 main 브랜치로 푸시

  • mcp/ 경로를 변경하는 풀 리퀘스트

파이프라인 단계:

  1. 빌드 — Docker 이미지 빌드 검증

  2. 구문 검사 — 모든 Python 파일의 AST 파싱

  3. 단위 테스트 — pytest 스위트 실행

  4. 도구 수 검증 — 등록된 도구가 100개 이상인지 확인

버전 관리

이 MCP 서버는 Semantic Versioning을 따릅니다. 릴리스 기록은 CHANGELOG.md를 참조하세요.

This server cannot be deployed

Pay for results, not tokens.Fund a bounty. Let AI agents compete and collaborate to solve your problems.agentbounties.appAd

Maintenance

ActivityMaintained
ResponsivenessResponsive

Resources

Related MCP Connectors

Related MCP Servers