Communitygithub.com

ASoudy/AGS

고품질 MCP(Model Context Protocol) 서버 구축 가이드입니다. Python(FastMCP) 또는 Node/TypeScript(MCP SDK)로 외부 API 및 서비스를 통합할 때 사용합니다.

AGS란 무엇인가요?

이 스킬은 LLM이 외부 서비스와 상호작용할 수 있도록 잘 설계된 도구를 제공하는 MCP 서버를 개발하기 위한 포괄적인 가이드입니다. MCP 서버의 품질은 LLM이 실제 작업을 얼마나 잘 수행할 수 있게 하는지로 측정됩니다. 이 가이드는 깊이 있는 연구 및 계획, 구현, 검토 및 테스트, 평가 생성의 4단계 프로세스를 따릅니다. TypeScript(MCP SDK) 또는 Python(FastMCP)을 사용하여 MCP 서버를 구축하는 방법을 상세히 다루며, 도구 명명 규칙, 입력/출력 스키마 설계, 오류 처리, 페이지네이션 모범 사례 등을 포함합니다. 또한 MCP Inspector를 사용한 테스트 방법과 10개의 평가 질문을 생성하여 서버의 효과성을 검증하는 방법까지 안내합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ASoudy/AGS/tree/HEAD/claude_skills_libraries/landing-page-mastery/skills/mcp-builder

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

MCP 서버 개발 가이드

개요

MCP(Model Context Protocol) 서버를 생성하여 LLM이 잘 설계된 도구를 통해 외부 서비스와 상호작용할 수 있도록 합니다. MCP 서버의 품질은 LLM이 실제 작업을 얼마나 잘 수행할 수 있게 하는지로 측정됩니다.


프로세스

🚀 상위 수준 워크플로우

고품질 MCP 서버를 만드는 데는 네 가지 주요 단계가 있습니다:

1단계: 깊이 있는 연구 및 계획

1.1 최신 MCP 설계 이해

API 범위 대 워크플로 도구: 포괄적인 API 엔드포인트 범위와 특수 워크플로 도구 간의 균형을 맞추세요. 워크플로 도구는 특정 작업에 더 편리할 수 있지만, 포괄적인 범위는 에이전트가 작업을 구성할 수 있는 유연성을 제공합니다. 성능은 클라이언트에 따라 다릅니다. 일부 클라이언트는 기본 도구를 결합한 코드 실행의 이점을 얻는 반면, 다른 클라이언트는 상위 수준 워크플로와 더 잘 작동합니다. 확실하지 않은 경우 포괄적인 API 범위를 우선시하세요.

도구 명명 및 검색 가능성: 명확하고 설명적인 도구 이름은 에이전트가 필요한 도구를 빠르게 찾는 데 도움이 됩니다. 일관된 접두사(예: github_create_issue, github_list_repos)와 작업 지향적인 명명을 사용하세요.

컨텍스트 관리: 에이전트는 간결한 도구 설명과 결과를 필터링/페이지 매김할 수 있는 기능의 이점을 얻습니다. 집중되고 관련성 높은 데이터를 반환하는 도구를 설계하세요. 일부 클라이언트는 코드 실행을 지원하여 에이전트가 데이터를 효율적으로 필터링하고 처리할 수 있도록 합니다.

실행 가능한 오류 메시지: 오류 메시지는 구체적인 제안과 다음 단계를 통해 해결 방법을 안내해야 합니다.

1.2 MCP 프로토콜 문서 학습

MCP 사양 탐색:

사이트맵에서 관련 페이지를 찾습니다: https://modelcontextprotocol.io/sitemap.xml

그런 다음 마크다운 형식의 특정 페이지를 .md 접미사로 가져옵니다(예: https://modelcontextprotocol.io/specification/draft.md).

검토할 주요 페이지:

  • 사양 개요 및 아키텍처
  • 전송 메커니즘(streamable HTTP, stdio)
  • 도구, 리소스 및 프롬프트 정의

1.3 프레임워크 문서 학습

권장 스택:

  • 언어: TypeScript(고품질 SDK 지원 및 MCPB와 같은 여러 실행 환경에서의 우수한 호환성. 또한 AI 모델은 TypeScript 코드 생성에 능숙하며, 광범위한 사용, 정적 타이핑 및 우수한 린팅 도구의 이점을 누립니다)
  • 전송: 원격 서버의 경우 stateless JSON을 사용하는 Streamable HTTP(상태 저장 세션 및 스트리밍 응답보다 확장 및 유지 관리가 더 간단). 로컬 서버의 경우 stdio.

프레임워크 문서 로드:

TypeScript(권장)의 경우:

  • TypeScript SDK: WebFetch를 사용하여 https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md 로드
  • ⚡ TypeScript 가이드 - TypeScript 패턴 및 예제

Python의 경우:

  • Python SDK: WebFetch를 사용하여 https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md 로드
  • 🐍 Python 가이드 - Python 패턴 및 예제

1.4 구현 계획

API 이해: 서비스의 API 문서를 검토하여 주요 엔드포인트, 인증 요구 사항 및 데이터 모델을 식별합니다. 필요에 따라 웹 검색 및 WebFetch를 사용하세요.

도구 선택: 포괄적인 API 범위를 우선시하세요. 가장 일반적인 작업부터 시작하여 구현할 엔드포인트를 나열합니다.


2단계: 구현

2.1 프로젝트 구조 설정

프로젝트 설정에 대한 언어별 가이드를 참조하세요:

2.2 핵심 인프라 구현

공유 유틸리티 생성:

  • 인증을 포함한 API 클라이언트
  • 오류 처리 도우미
  • 응답 형식 지정(JSON/마크다운)
  • 페이지네이션 지원

2.3 도구 구현

각 도구에 대해:

입력 스키마:

  • Zod(TypeScript) 또는 Pydantic(Python) 사용
  • 제약 조건과 명확한 설명 포함
  • 필드 설명에 예제 추가

출력 스키마:

  • 구조화된 데이터가 가능한 경우 outputSchema 정의
  • 도구 응답에 structuredContent 사용(TypeScript SDK 기능)
  • 클라이언트가 도구 출력을 이해하고 처리하는 데 도움

도구 설명:

  • 기능에 대한 간결한 요약
  • 매개변수 설명
  • 반환 유형 스키마

구현:

  • I/O 작업에 async/await 사용
  • 실행 가능한 메시지와 함께 적절한 오류 처리
  • 해당되는 경우 페이지네이션 지원
  • 최신 SDK 사용 시 텍스트 콘텐츠와 구조화된 데이터 모두 반환

주석:

  • readOnlyHint: true/false
  • destructiveHint: true/false
  • idempotentHint: true/false
  • openWorldHint: true/false

3단계: 검토 및 테스트

3.1 코드 품질

다음 사항을 검토합니다:

  • 중복 코드 없음(DRY 원칙)
  • 일관된 오류 처리
  • 전체 유형 범위
  • 명확한 도구 설명

3.2 빌드 및 테스트

TypeScript:

  • npm run build 실행하여 컴파일 확인
  • MCP Inspector로 테스트: npx @modelcontextprotocol/inspector

Python:

  • 구문 확인: python -m py_compile your_server.py
  • MCP Inspector로 테스트

자세한 테스트 방법과 품질 체크리스트는 언어별 가이드를 참조하세요.


4단계: 평가 생성

MCP 서버를 구현한 후 포괄적인 평가를 생성하여 효과성을 테스트합니다.

전체 평가 지침을 보려면 ✅ 평가 가이드를 로드하세요.

4.1 평가 목적 이해

평가를 사용하여 LLM이 MCP 서버를 효과적으로 사용하여 현실적이고 복잡한 질문에 답할 수 있는지 테스트합니다.

4.2 평가 질문 10개 생성

효과적인 평가를 생성하려면 평가 가이드에 설명된 프로세스를 따르세요:

  1. 도구 검사: 사용 가능한 도구를 나열하고 기능 이해
  2. 콘텐츠 탐색: READ-ONLY 작업을 사용하여 사용 가능한 데이터 탐색
  3. 질문 생성: 복잡하고 현실적인 질문 10개 생성
  4. 답변 확인: 각 질문을 직접 해결하여 답변 확인

4.3 평가 요구 사항

각 질문이 다음 요구 사항을 충족하는지 확인하세요:

  • 독립적: 다른 질문에 의존하지 않음
  • 읽기 전용: 비파괴적 작업만 필요
  • 복잡성: 여러 도구 호출과 깊은 탐색 필요
  • 현실성: 사람들이 관심을 가질 실제 사용 사례 기반
  • 검증 가능: 문자열 비교로 확인할 수 있는 단일하고 명확한 답변
  • 안정성: 시간이 지나도 답변이 변경되지 않음

4.4 출력 형식

다음 구조의 XML 파일을 생성합니다:

<evaluation>
  <qa_pair>
    <question>Find discussions about AI model launches with animal codenames. One model needed a specific safety designation that uses the format ASL-X. What number X was being determined for the model named after a spotted wild cat?</question>
    <answer>3</answer>
  </qa_pair>
<!-- More qa_pairs... -->
</evaluation>

참조 파일

📚 문서 라이브러리

개발 중 필요에 따라 다음 리소스를 로드하세요:

핵심 MCP 문서(먼저 로드)

  • MCP 프로토콜: https://modelcontextprotocol.io/sitemap.xml의 사이트맵에서 시작하여 .md 접미사로 특정 페이지 가져오기
  • 📋 MCP 모범 사례 - 보편적인 MCP 지침:
    • 서버 및 도구 명명 규칙
    • 응답 형식 지침(JSON vs 마크다운)
    • 페이지네이션 모범 사례
    • 전송 선택(streamable HTTP vs stdio)
    • 보안 및 오류 처리 표준

SDK 문서(1/2단계에서 로드)

  • Python SDK: https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md에서 가져오기
  • TypeScript SDK: https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md에서 가져오기

언어별 구현 가이드(2단계에서 로드)

  • 🐍 Python 구현 가이드 - 완전한 Python/FastMCP 가이드:

    • 서버 초기화 패턴
    • Pydantic 모델 예제
    • @mcp.tool을 사용한 도구 등록
    • 완전한 작동 예제
    • 품질 체크리스트
  • ⚡ TypeScript 구현 가이드 - 완전한 TypeScript 가이드:

    • 프로젝트 구조
    • Zod 스키마 패턴
    • server.registerTool을 사용한 도구 등록
    • 완전한 작동 예제
    • 품질 체크리스트

평가 가이드(4단계에서 로드)

  • ✅ 평가 가이드 - 완전한 평가 생성 가이드:
    • 질문 생성 지침
    • 답변 확인 전략
    • XML 형식 사양
    • 예제 질문 및 답변
    • 제공된 스크립트로 평가 실행

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ASoudy/AGS

Advanced JavaScript animation library skill for creating complex, high-performance web animations.

ASoudy/AGS

Astropy is the core Python package for astronomy, providing essential functionality for astronomical research and data analysis.

ASoudy/AGS

Build content-focused websites with Astro — zero JS by default, islands architecture, multi-framework components, and Markdown/MDX support.

ASoudy/AGS

One sentence - what this skill does and when to invoke it

ASoudy/AGS

Audit and fix animation performance issues including layout thrashing, compositor properties, scroll-linked motion, and blur effects. Use when animations stutter, transitions jank, or reviewing CSS/JS animation performance.

ASoudy/AGS

Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.

ASoudy/AGS

Pull a YouTube video transcript into a queryable markdown vault with yt-dlp subtitle discovery, VTT cleanup, metadata frontmatter, and capture-seed stubs.

ASoudy/AGS

Expert in building portfolios that actually land jobs and clients - not just showing work, but creating memorable experiences. Covers developer portfolios, designer portfolios, creative portfolios, and portfolios that convert visitors into opportunities.

ASoudy/AGS

Generates high-converting Next.js/React landing pages with Tailwind CSS. Uses PAS, AIDA, and BAB frameworks for optimized copy/components (Heroes, Features, Pricing). Focuses on Core Web Vitals/SEO.

ASoudy/AGS

AI-powered animation tool for creating motion in logos, UI, icons, and social media assets.

ASoudy/AGS

CRITICAL: Use for Makepad animation system. Triggers on: makepad animation, makepad animator, makepad hover, makepad state, makepad transition, "from: { all: Forward", makepad pressed, makepad 动画, makepad 状态, makepad 过渡, makepad 悬停效果

ASoudy/AGS

Comprehensive patterns for Next.js 14+ App Router architecture, Server Components, and modern full-stack React development.

ASoudy/AGS

Next.js App Router principles. Server Components, data fetching, routing patterns.

ASoudy/AGS

Expert integration of Supabase Auth with Next.js App Router

ASoudy/AGS

React and Next.js 14+ application development with App Router, Server Components, TypeScript, Tailwind CSS, and modern frontend patterns.

ASoudy/AGS

Best practices for Remotion - Video creation in React

ASoudy/AGS

Generate walkthrough videos from Stitch projects using Remotion with smooth transitions, zooming, and text overlays

ASoudy/AGS

Seek and analyze video content using Memories.ai Large Visual Memory Model for persistent video intelligence

ASoudy/AGS

Writes complete, structured landing pages optimized for SEO ranking, AEO citation, and visitor conversion. Activate when the user wants to write or generate a landing page for a product, service, or offer.

ASoudy/AGS

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

관련 스킬