MCP 서버 보일러플레이트

사용자 지정 MCP 서버를 구축하기 위한 재사용 가능한 기준 역할을 하도록 설계된 최소한의 잘 문서화된 MCP(Model Context Protocol) 서버 구현입니다.

MCP란 무엇인가요?

MCP(Model Context Protocol)는 AI 어시스턴트가 외부 서버와 상호 작용할 수 있도록 하는 표준화된 프로토콜입니다. MCP 서버는 다음을 제공할 수 있습니다:

• 도구(Tools): AI가 작업을 수행하기 위해 호출할 수 있는 함수

• 리소스(Resources): AI가 읽을 수 있는 정적 또는 동적 데이터

• 프롬프트(Prompts): 일관된 AI 상호 작용을 위한 재사용 가능한 프롬프트 템플릿

Related MCP server: MCP Mingdao

기능

이 보일러플레이트는 다음을 제공합니다:

• 최소한의 구조: 쉽게 확장할 수 있는 깔끔한 기준

• 광범위한 문서: 인라인 주석 및 별도의 문서 파일

• 아키텍처 다이어그램: 구성 요소 상호 작용을 보여주는 Mermaid 다이어그램

• 확장 가이드: 서버 성장을 위한 모범 사례

• 타입 힌트: 더 나은 IDE 지원을 위한 전체 타입 주석

• Async/await: 동시 작업을 위한 비차단 I/O

재사용 가능한 프롬프트 템플릿

프롬프트는 자리 표시자를 사용하여 구조화된 프롬프트를 정의할 수 있는 재사용 가능한 프롬프트 템플릿입니다. 이를 통해 다음이 가능합니다:

• 일관성: 다양한 AI 상호 작용 전반에 걸친 표준화된 프롬프트 형식

• 매개변수화: 인수를 통한 동적 콘텐츠 삽입

• 재사용성: 한 번 정의하고 다양한 입력으로 여러 번 사용

• 타입 안전성: 유효성 검사가 포함된 정의된 인수 스키마

프롬프트 템플릿은 다음으로 구성됩니다:

• 이름: 프롬프트의 고유 식별자

• 설명: 프롬프트가 수행하는 작업

• 인수: 프롬프트 사용 시 채울 수 있는 선택적 매개변수

예시 사용 사례:

• 구성 가능한 심각도 수준을 갖춘 코드 리뷰 템플릿

• 사용자 지정 가능한 어조를 갖춘 문서 생성

• 가변적인 초점 영역을 갖춘 분석 프롬프트

• 다양한 출력 형식을 갖춘 보고서 생성

프로젝트 구조

windsurf-project-3/
├── mcp_server.py          # Main server implementation with extensive comments
├── pyproject.toml         # Project configuration for uv
├── ARCHITECTURE.md        # Architecture documentation with Mermaid diagrams
├── SCALING_GUIDE.md       # Scaling patterns and best practices
├── README.md              # This file
├── tools/                 # Placeholder for tool modules (create as needed)
├── resources/             # Placeholder for resource modules (create as needed)
├── prompts/               # Placeholder for prompt modules (create as needed)
└── utils/                 # Placeholder for utility modules (create as needed)

설치

이 프로젝트는 빠른 Python 패키지 관리를 위해 uv를 사용합니다.

1. Python 3.10 이상 설치

2. uv 설치 (아직 설치되지 않은 경우):

curl -LsSf https://astral.sh/uv/install.sh | sh

3. 종속성 설치:

uv sync

빠른 시작

1. 첫 번째 도구 추가

mcp_server.py를 편집하고 list_tools() 함수에 도구를 추가합니다:

@app.list_tools()
async def list_tools() -> list[Tool]:
    return [
        Tool(
            name="echo",
            description="Echo back the input text",
            inputSchema={
                "type": "object",
                "properties": {
                    "text": {"type": "string", "description": "Text to echo"}
                },
                "required": ["text"]
            }
        )
    ]

2. 도구 핸들러 구현

call_tool() 함수에 도구 로직을 추가합니다:

@app.call_tool()
async def call_tool(name: str, arguments: Any) -> str:
    if name == "echo":
        text = arguments.get("text", "")
        return f"Echo: {text}"
    raise ValueError(f"Unknown tool: {name}")

3. 프롬프트 추가 (선택 사항)

list_prompts() 함수에 프롬프트를 추가합니다:

@app.list_prompts()
async def list_prompts() -> list[Prompt]:
    return [
        Prompt(
            name="example_prompt",
            description="An example prompt template",
            arguments=[
                PromptArgument(
                    name="topic",
                    description="The topic to write about",
                    required=True
                )
            ]
        )
    ]

그런 다음 get_prompt()에서 핸들러를 구현합니다:

@app.get_prompt()
async def get_prompt(name: str, arguments: dict[str, str] | None) -> str:
    if name == "example_prompt":
        topic = arguments.get("topic") if arguments else None
        if not topic:
            raise ValueError("Argument 'topic' is required")
        return f"Write a detailed explanation about {topic}."
    raise ValueError(f"Unknown prompt: {name}")

3. 서버 실행

uv run python mcp_server.py

4. MCP 클라이언트 구성

MCP 클라이언트 구성에 다음을 추가합니다:

{
  "mcpServers": {
    "your-server-name": {
      "command": "uv",
      "args": ["run", "python", "/path/to/mcp_server.py"]
    }
  }
}

문서

• ARCHITECTURE.md: 다음을 보여주는 Mermaid 다이어그램이 포함된 상세 아키텍처 문서:

  • Python 모듈 및 목적

  • 구성 요소 상호 작용

  • 요청 흐름 (도구 호출, 리소스 읽기)

  • 사용된 디자인 패턴

• SCALING_GUIDE.md: 서버 확장을 위한 모범 사례:

  • 모듈화 패턴

  • 상태 관리 전략

  • 오류 처리 패턴

  • 로깅 및 모니터링

  • 구성 관리

  • 테스트 전략

  • 성능 최적화

  • 보안 고려 사항

코드 구조

메인 서버 파일(mcp_server.py)은 다음 섹션으로 구성됩니다:

1. 서버 초기화: MCP 서버 인스턴스 생성

2. 도구 등록: 사용 가능한 도구 정의

3. 도구 핸들러: 도구 실행 로직 구현

4. 리소스 등록: 사용 가능한 리소스 정의

5. 리소스 핸들러: 리소스 읽기 로직 구현

6. 진입점: stdio 통신으로 서버 시작

각 섹션에는 각 구성 요소의 목적과 사용법을 설명하는 광범위한 인라인 주석이 포함되어 있습니다.

확장 지점

도구 추가

1. list_tools()에서 스키마와 함께 도구 정의

2. call_tool()에서 핸들러 구현

3. 더 큰 프로젝트의 경우 tools/ 디렉토리의 별도 모듈로 이동

프롬프트 추가

1. list_prompts()에서 인수와 함께 프롬프트 정의

2. get_prompt()에서 핸들러 구현

3. 더 큰 프로젝트의 경우 prompts/ 디렉토리의 별도 모듈로 이동

리소스 추가

1. list_resources()에서 메타데이터와 함께 리소스 정의

2. read_resource()에서 핸들러 구현

3. 더 큰 프로젝트의 경우 resources/ 디렉토리의 별도 모듈로 이동

유틸리티 추가

공유 코드를 utils/ 디렉토리로 추출:

• 유효성 검사 함수

• 로깅 도우미

• 구성 관리

• 오류 처리 유틸리티

기준으로 사용하기

이 보일러플레이트는 새 프로젝트를 위해 복사 및 수정되도록 설계되었습니다:

1. 전체 프로젝트 디렉토리 복사

2. pyproject.toml에서 프로젝트 이름 변경

3. mcp_server.py에서 서버 이름 업데이트

4. 도구, 리소스 및 프롬프트 추가

5. 필요에 따라 문서 사용자 지정

사용된 Python 모듈

• mcp.server.Server: 메인 MCP 서버 클래스

• mcp.types.Tool: 도구 타입 정의

• mcp.types.Resource: 리소스 타입 정의

• mcp.types.Prompt: 프롬프트 타입 정의

• mcp.types.PromptArgument: 프롬프트 인수 타입 정의

• mcp.server.stdio: Stdio 통신 스트림

• asyncio: 동시 작업을 위한 Async/await

• typing: 코드 명확성을 위한 타입 힌트

각 모듈에 대한 자세한 설명은 ARCHITECTURE.md를 참조하세요.

개발

테스트 실행

# Run with pytest (add tests first)
uv run pytest

코드 스타일

이 프로젝트는 Python 타입 힌트를 사용하며 PEP 8 규칙을 따릅니다. 다음 사용을 고려하세요:

• 린팅을 위한 ruff

• 타입 검사를 위한 mypy

종속성 추가

uv add <package-name>

문제 해결

• 가져오기 오류: uv sync를 실행하여 종속성 설치

• 서버 응답 없음: MCP 클라이언트 구성 확인

• 타입 오류: Python 3.10+가 설치되어 있는지 확인

• uv 명령을 찾을 수 없음: https://github.com/astral-sh/uv 에서 uv 설치

리소스

• MCP 사양

• MCP Python SDK

• uv 문서

라이선스

이 보일러플레이트는 교육 및 개발 목적으로 있는 그대로 제공됩니다. 자유롭게 프로젝트에 사용하고 수정하세요.