Communitygithub.com

ASoudy/AGS

LLMが外部サービスと連携できる高品質なMCP(Model Context Protocol)サーバーを構築するためのガイドです。Python(FastMCP)またはNode/TypeScript(MCP SDK)でMCPサーバーを作成する際に使用します。

AGS とは?

このスキルは、高品質なMCP(Model Context Protocol)サーバーを開発するための包括的なガイドを提供します。MCPサーバーは、LLMが外部APIやサービスと効率的に連携できるように設計されたツールを提供するもので、その品質は実世界のタスクをどれだけうまく達成できるかで評価されます。ガイドは4つのフェーズ(調査と計画、実装、レビューとテスト、評価の作成)で構成され、TypeScript(推奨)とPythonの両方に対応しています。特に、ツールの命名規則、入力/出力スキーマの設計、エラーメッセージの品質、評価の作成方法など、実践的なベストプラクティスを詳しく解説しています。このスキールは、MCPサーバーの開発者や、Claude Code、Cursor、CodexなどのAIエージェントがMCPサーバーを効果的に利用するためのガイドラインとして活用できます。

対応~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サーバー開発ガイド

概要

LLMが適切に設計されたツールを通じて外部サービスと連携できるMCP(Model Context Protocol)サーバーを作成します。MCPサーバーの品質は、LLMが実世界のタスクをどれだけうまく達成できるかによって評価されます。


プロセス

🚀 ハイレベルワークフロー

高品質なMCPサーバーの作成は、主に4つのフェーズで構成されます。

フェーズ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)。

確認すべき主要ページ:

  • 仕様の概要とアーキテクチャ
  • トランスポートメカニズム(ストリーミング可能HTTP、stdio)
  • ツール、リソース、プロンプトの定義

1.3 フレームワークドキュメントの学習

推奨スタック:

  • 言語:TypeScript(高品質なSDKサポート、多くの実行環境(例:MCPB)での互換性が良好。さらに、AIモデルはTypeScriptコードの生成が得意で、幅広い使用実績、静的型付け、優れたリンターツールの恩恵を受けられる)
  • トランスポート:リモートサーバーにはストリーミング可能HTTP(ステートフルなセッションやストリーミング応答とは対照的に、ステートレスなJSONの方がスケールとメンテナンスが容易)。ローカルサーバーには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/Markdown)
  • ページネーションサポート

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インスペクターでテスト:npx @modelcontextprotocol/inspector

Python:

  • 構文確認:python -m py_compile your_server.py
  • MCPインスペクターでテスト

詳細なテストアプローチと品質チェックリストについては、言語固有のガイドを参照してください。


フェーズ4:評価の作成

MCPサーバーを実装したら、包括的な評価を作成してその効果をテストします。

完全な評価ガイドラインについては、✅ 評価ガイドを読み込んでください。

4.1 評価の目的を理解する

評価を使用して、LLMがMCPサーバーを効果的に使用して、現実的で複雑な質問に回答できるかどうかをテストします。

4.2 10個の評価質問を作成する

効果的な評価を作成するには、評価ガイドに概説されているプロセスに従います:

  1. ツール検査:利用可能なツールをリストアップし、その機能を理解する
  2. コンテンツ探索:読み取り専用操作を使用して、利用可能なデータを探索する
  3. 質問生成:10個の複雑で現実的な質問を作成する
  4. 回答検証:各質問を自分で解決して回答を検証する

4.3 評価要件

各質問が以下を満たしていることを確認する:

  • 独立している:他の質問に依存しない
  • 読み取り専用:破壊的な操作が不要
  • 複雑:複数のツール呼び出しと深い探索が必要
  • 現実的:人間が気にする実際のユースケースに基づいている
  • 検証可能:文字列比較で検証できる単一の明確な回答がある
  • 安定している:回答が時間の経過とともに変わらない

4.4 出力形式

以下の構造のXMLファイルを作成する:

<evaluation>
  <qa_pair>
    <question>動物コードネームを持つAIモデルのローンチに関する議論を見つけてください。あるモデルには、ASL-X形式の特定の安全性指定が必要でした。斑点のある野生の猫にちなんで名付けられたモデルについて、どの番号Xが決定されていましたか?</question>
    <answer>3</answer>
  </qa_pair>
<!-- その他のqa_pair... -->
</evaluation>

リファレンスファイル

📚 ドキュメントライブラリ

開発中に必要に応じてこれらのリソースを読み込んでください:

コアMCPドキュメント(最初に読み込む)

  • MCPプロトコル:https://modelcontextprotocol.io/sitemap.xmlのサイトマップから始め、.mdサフィックスを付けて特定のページをフェッチする
  • 📋 MCPベストプラクティス - 普遍的なMCPガイドライン。以下を含む:
    • サーバーとツールの命名規則
    • レスポンス形式ガイドライン(JSON vs Markdown)
    • ページネーションのベストプラクティス
    • トランスポート選択(ストリーミング可能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.

関連スキル