Coding Guides MCP Server

Claude 및 GitHub Copilot과 같은 AI 어시스턴트를 위한 코딩 가이드와 모범 사례에 대한 액세스를 제공하는 Model Context Protocol(MCP) 서버입니다.

이게 무엇인가요?

이 MCP 서버는 코딩 가이드라인과 스타일 가이드를 MCP 클라이언트가 액세스할 수 있는 리소스로 노출합니다. 개발 중에 AI 어시스턴트에게 코딩 관행과 가이드라인을 제공하는 구조화된 방법을 제공하여 AGENTS.md 파일을 확장하거나 대체하도록 설계되었습니다.

Related MCP server: Code Understanding MCP Server

기능

• 리소스 기반 API: MCP 리소스를 통해 코딩 가이드를 노출합니다

• GitHub 통합: 웹을 통해 GitHub 리포지토리에서 가이드를 로드합니다

• 자동 캐싱: 다운로드한 가이드를 로컬에 캐시하여 오프라인 액세스를 지원합니다

• 폴백 지원: 네트워크를 사용할 수 없을 때 로컬 캐시 또는 디렉터리를 사용합니다

• 간단한 파일 기반 저장: 가이드를 로컬에 Markdown 파일로 저장할 수 있습니다

• 공식 MCP SDK: Python mcp SDK(MCPServer, 이전 명칭 FastMCP) 기반

• 간편한 통합: MCP 호환 클라이언트(Claude Desktop, Cline 등)와 함께 작동합니다

사용 가능한 리소스

• guides://list - 사용 가능한 모든 코딩 가이드를 나열합니다

• guides://{guide_name} - 특정 가이드의 콘텐츠를 검색합니다(예: guides://python.md)

설치

소스에서

# Clone the repository
git clone https://github.com/delian/codeguide-mcp.git
cd codeguide-mcp

# Install with uv (recommended)
uv sync

# Or with pip
pip install -e .

Docker 사용

docker build -t codeguide-mcp .
docker run -i codeguide-mcp

VS Code에서

또는 확장 프로그램 보기의 MCP 서버 목록에서 codeguide-mcp를 검색하거나(확장 프로그램 검색창에 @mcp 입력), .vscode/mcp.json에 수동으로 추가하세요:

{
  "servers": {
    "codeguide-mcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "delian/codeguide-mcp"]
    }
  }
}

구성

config.toml 파일을 만들거나 환경 변수를 설정하여 서버를 구성합니다:

GitHub 구성(권장)

GitHub 리포지토리에서 가이드를 로드하려면:

github_repo = "owner/repository"  # e.g., "delian/codeguide-mcp"
github_path = "guides"            # Path to guides directory in repo
github_branch = "main"            # Branch to fetch from
  cache_dir = ".guides-cache"       # Local cache directory
log_level = "INFO"

로컬 디렉터리 구성

로컬 가이드만 사용하려면:

guides_dir = "guides"
log_level = "INFO"

환경 변수

• GUIDES_GITHUB_REPO - GitHub 리포지토리(형식: owner/repo)

• GUIDES_GITHUB_PATH - 리포지토리의 가이드 디렉터리 경로(기본값: guides)

• GUIDES_GITHUB_BRANCH - 가져올 브랜치(기본값: main)

• GUIDES_CACHE_DIR - 로컬 캐시 디렉터리(기본값: .guides-cache)

• GUIDES_DIR - 가이드 파일이 포함된 로컬 디렉터리(기본값: guides)

• GUIDES_LOG_LEVEL - 로깅 수준(기본값: INFO)

전송(Transport)(원격 배포 참조):

• GUIDES_TRANSPORT - stdio, streamable-http 또는 auto(기본값: auto — PORT 환경 변수가 있으면 HTTP, 그렇지 않으면 stdio)

• PORT - HTTP 모드에서 수신 대기할 포트; GUIDES_PORT보다 우선합니다(Cloud Run이 이 값을 주입합니다)

• GUIDES_HOST - HTTP 모드의 바인드 주소(기본값: 0.0.0.0)

• GUIDES_HTTP_PATH - MCP 엔드포인트 경로(기본값: /mcp)

• GUIDES_STATELESS_HTTP - 각 요청을 독립적으로 처리합니다(기본값: true; 복제본이 자동 확장될 때 필요)

• GUIDES_ALLOWED_HOSTS - DNS 리바인딩 보호를 활성화하는 Host 헤더 허용 목록(기본값: 비어 있음 = Host 검증 안 함)

동작

1. 네트워크 사용 가능 + GitHub 구성됨: GitHub에서 가이드를 가져와 로컬에 캐시합니다

2. 네트워크 불가: 사용 가능한 경우 로컬 캐시를 사용합니다

3. 캐시 없음: 구성된 경우 로컬 guides_dir로 폴백합니다

원격 배포(Google Cloud Run)

동일한 이미지가 두 전송 방식을 모두 지원합니다. 기본적으로 파이프를 통해 stdio를 사용하며, PORT 환경 변수가 있으면(Cloud Run이 항상 주입) Streamable HTTP로 전환합니다. 별도의 이미지나 엔트리포인트가 필요 없습니다.

1. 이미지 게시

docker build -t delian/codeguide-mcp:0.1.0 -t delian/codeguide-mcp:latest .
docker push delian/codeguide-mcp:0.1.0
docker push delian/codeguide-mcp:latest

2. 배포

gcloud run deploy codeguide-mcp \
  --image=docker.io/delian/codeguide-mcp:0.1.0 \
  --region=europe-west1 \
  --allow-unauthenticated \
  --port=8080 \
  --set-env-vars=GUIDES_TRANSPORT=streamable-http,GUIDES_GITHUB_REPO= \
  --memory=512Mi --cpu=1 \
  --min-instances=0 --max-instances=4 --concurrency=40

GUIDES_GITHUB_REPO=(비어 있음)로 설정하면 서비스가 이미지에 포함된 가이드를 제공합니다. GitHub를 활성화된 상태로 두면 가이드마다 네트워크 왕복이 추가되고, 송신 IP당 시간당 60회의 인증되지 않은 GitHub API 제한에 도달하게 되며, 이후 서버는 조용히 동일한 포함 파일로 폴백합니다.

그러면 MCP 엔드포인트는 https://<service-url>/mcp가 됩니다:

gcloud run services describe codeguide-mcp --region=europe-west1 \
  --format='value(status.url)'

Cloud Run은 동일한 서비스에 대해 두 개의 호스트 이름으로 응답합니다. gcloud run deploy가 출력하는 SERVICE-PROJECTNUMBER.REGION.run.app 형식과 status.url이 보고하는 이전 형식인 SERVICE-HASH-REGIONCODE.a.run.app 형식입니다. 둘 다 동일하며, 클라이언트 구성에서 어느 것을 사용해도 작동합니다.

3. 클라이언트 연결 설정

클라이언트별 구성은 아래의 원격 서버에 연결을 참조하세요.

Docker Hub에서 가져오기

Cloud Run은 공개 Docker Hub 이미지를 직접 배포하지만, 이미지를 1시간 동안만 캐시하고 이후에는 익명으로 다시 가져오므로, 스케일 업 시 Docker Hub의 익명 풀 제한에 도달하여 인스턴스 시작에 실패할 수 있습니다. 단순한 사용을 넘어서는 경우 Artifact Registry 원격 리포지토리를 통해 미러링하세요:

gcloud artifacts repositories create dockerhub \
  --repository-format=docker --location=europe-west1 \
  --mode=remote-repository --remote-docker-repo=DOCKER-HUB

gcloud run deploy codeguide-mcp \
  --image=europe-west1-docker.pkg.dev/PROJECT_ID/dockerhub/delian/codeguide-mcp:0.1.0 \
  ...

공개 실행 시 참고 사항

• --allow-unauthenticated는 엔드포인트를 전 세계에서 호출 가능하게 만듭니다. 서버는 읽기 전용이지만 clear_cache 프롬프트는 모든 호출자가 접근할 수 있으며 인메모리 캐시를 삭제하고, 트래픽은 자동 확장 비용을 발생시킵니다. --max-instances를 상한으로 유지하세요. 액세스를 제한하려면 이 플래그를 생략하고 클라이언트가 ID 토큰을 보내도록 하거나, Cloud Armor / API Gateway로 서비스를 보호하세요.

• Cloud Run은 세션의 요청을 서로 다른 인스턴스로 라우팅할 수 있으므로, 세션 선호도를 활성화하지 않는 한 GUIDES_STATELESS_HTTP는 true로 유지해야 합니다.

• GET /는 설계상 404를 반환하며, /mcp만 제공됩니다. Cloud Run의 기본 시작 프로브는 $PORT에 대한 TCP 검사이므로 문제없습니다. /에 HTTP 상태 확인(health check)을 구성하지 마세요.

• 사용자 지정 도메인에서 서비스를 노출하는 경우 GUIDES_ALLOWED_HOSTS를 서비스 호스트 이름으로 설정하여 Host 헤더 검증을 활성화하세요.

MCP 레지스트리에 게시

VS Code 확장 프로그램 보기의 MCP 서버 목록(검색창에 @mcp 입력)은 공식 MCP Registry에서 데이터를 가져오는 GitHub MCP Registry에서 제공됩니다. 따라서 이 서버가 VS Code에서 검색 가능해지려면 해당 레지스트리에 게시해야 합니다. 자체 VS Code 확장 프로그램은 필요하지 않습니다.

server.json에는 레지스트리 메타데이터가 들어 있습니다. 로컬에서 실행하려는 클라이언트를 위한 Docker 이미지와, 그렇지 않은 클라이언트를 위한 호스팅 URL입니다. 이미지 소유권은 Dockerfile의 io.modelcontextprotocol.server.name 레이블로 입증되며, 그 값은 server.json의 .name과 반드시 같아야 합니다.

한 번 인증하고(대화형 기기 코드 흐름), 게시 스크립트를 실행하세요:

mcp-publisher login github     # namespace io.github.<your-username>/*
tools/publish.sh

tools/publish.sh가 전체 릴리스를 처리합니다: 필요한 도구와 Docker 로그인을 확인하고, server.json과 pyproject.toml이 버전에서 일치하는지 및 Dockerfile 레이블이 서버 이름과 일치하는지 검증하며, :VERSION과 :latest를 빌드 및 푸시하고, server.json을 라이브 레지스트리와 대조하여 검증한 후 게시하고, 엔트리를 다시 읽어 확인합니다.

tools/publish.sh --dry-run          # everything except push and publish
tools/publish.sh --version 0.2.0    # bump server.json + pyproject + image tag, then release
tools/publish.sh --skip-build       # reuse images already on Docker Hub

mcp-publisher가 없다면 registry quickstart에서 설치하세요. 게시 후 GitHub의 큐레이션 목록에 포함되려면 partnerships@github.com에 요청해야 할 수 있습니다.

가이드 추가

GitHub 사용(권장)

github_repo를 구성했다면 GitHub 리포지토리의 지정된 디렉터리에 Markdown 파일을 추가하기만 하면 됩니다. 서버가 자동으로 가져와 캐시합니다.

로컬 디렉터리 사용

guides/ 디렉터리에 Markdown 파일을 추가하세요. 각 파일은 자동으로 리소스로 사용할 수 있게 됩니다.

예시:

echo "# Python Style Guide\n\nUse PEP 8..." > guides/python.md

MCP 클라이언트와 함께 사용

서버는 두 가지 방식으로 사용할 수 있습니다:

로컬 모드는 네트워크와 호스팅이 필요 없으며, 원격 모드는 팀이 하나의 배포를 공유하고 모든 사람에게 동일한 가이드를 유지할 수 있게 합니다.

원격 서버에 연결

배포된 인스턴스는 /mcp에서 MCP 엔드포인트를 노출합니다. 아래 스니펫은 참조 배포를 사용합니다:

https://codeguide-mcp-86057491046.europe-west1.run.app/mcp

공개되어 있으며 자격 증명이 필요 없습니다. 직접 서비스를 실행하는 경우 자신의 URL로 대체하세요. 원격 배포를 참조하세요.

VS Code — 단일 작업 영역용 .vscode/mcp.json, 또는 모든 작업 영역용 사용자 mcp.json:

{
  "servers": {
    "codeguide-mcp": {
      "type": "http",
      "url": "https://codeguide-mcp-86057491046.europe-west1.run.app/mcp"
    }
  }
}

Claude Code:

claude mcp add --transport http codeguide-mcp \
  https://codeguide-mcp-86057491046.europe-west1.run.app/mcp

Cursor — ~/.cursor/mcp.json(전역) 또는 .cursor/mcp.json(프로젝트별):

{
  "mcpServers": {
    "codeguide-mcp": {
      "url": "https://codeguide-mcp-86057491046.europe-west1.run.app/mcp"
    }
  }
}

Claude Desktop — 설정에서 사용자 지정 커넥터로 추가하거나, mcp-remote로 원격 엔드포인트를 stdio 클라이언트에 연결하세요:

{
  "mcpServers": {
    "codeguide-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://codeguide-mcp-86057491046.europe-west1.run.app/mcp"]
    }
  }
}

Streamable HTTP를 지원하는 모든 클라이언트가 작동합니다. /mcp URL을 가리키면 됩니다. 인증이 필요한 서버의 경우 --header "Authorization: Bearer $(gcloud auth print-identity-token)"(Claude Code) 또는 클라이언트에 해당하는 headers 블록으로 토큰을 전달하세요.

원격 엔드포인트 확인

curl 한 번으로 배포가 활성 상태이고 공개되었는지 확인할 수 있습니다:

curl -s -X POST https://codeguide-mcp-86057491046.europe-west1.run.app/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
       "protocolVersion":"2025-06-18","capabilities":{},
       "clientInfo":{"name":"curl","version":"1"}}}'

정상 서버는 기능과 지침이 포함된 SSE event: message 프레임으로 응답합니다. GET /는 설계상 404를 반환하며 /mcp만 제공됩니다.

대신 HTTP를 통해 모든 리소스, 도구, 프롬프트를 테스트하려면:

uv run python verify_server.py --http https://codeguide-mcp-86057491046.europe-west1.run.app/mcp

로컬 사용

Claude Desktop

mcp.json에 추가하세요:

{
  "mcpServers": {
    "coding-guides": {
      "command": "python",
      "args": ["-m", "main"]
    }
  }
}

또는

{
  "mcpServers": {
    "coding-guides": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "docker.io/delian/codeguide-mcp"]
    }
  }
}

기타 MCP 클라이언트

서버를 실행하고 stdio로 연결하세요:

python main.py

개발

# Install development dependencies
uv pip install -e ".[dev]"

# Run pre-commit hooks
pre-commit install
pre-commit run --all-files

# Run the server
python main.py

라이선스

MIT

기여

기여를 환영합니다! 이슈(issue) 또는 풀 리퀘스트(pull request)를 열어 주세요.