MCP Server Python

🚀 MCPサーバー: ドキュメント検索とウェブスクレイピング (uv + FastMCP)

このプロジェクトは、人気のあるAI / Pythonエコシステムライブラリの公式ドキュメントコンテンツを検索し、クリーニングするツールを提供する最小限の非同期MCP（Model Context Protocol）サーバーを提供します。以下の技術を使用しています。

• fastmcpを使用して、stdio経由でMCPサーバーを定義および実行します。
• httpxを使用して非同期HTTP呼び出しを行います。
• serper.devを使用してGoogleライクな検索（API経由）を行います。
• groq API（LLM）を使用して、生のHTMLを読みやすいテキストチャンクに変換します。
• python-dotenvを使用して環境変数を管理します。
• uvをパッケージマネージャー兼ランナーとして使用します（高速、ロックファイルベース、Python 3.11以上）。

✨ 主な機能

• 検索は公式ドキュメントのドメイン（uv、langchain、openai、llama-index）に限定されます。
• ツール: get_docs(query, library)は、SOURCE:ラベル付きのクリーニングされたセクションを連結して返します。
• ストリーミングに対応した非同期設計（LLMでクリーニングする前に大きなHTMLページをチャンクに分割）。
• client.pyは、MCPクライアントとして接続してツールを呼び出し、その後LLMで後処理する方法を示しています。

🚀 クイックスタート

前提条件:

• Python 3.11以上
• uvがインストールされていること（https://docs.astral.sh/uv/）
• SERPER_API_KEYとGROQ_API_KEYのAPIキー

1. クローンとインストール

git clone <your-repo-url> mcp-server-python
cd mcp-server-python
uv sync

これにより、pyproject.tomlとuv.lockに基づいて.venvが作成または更新されます。

2. 環境変数

プロジェクトのルートに.envファイルを作成します。

SERPER_API_KEY=your_serper_api_key_here
GROQ_API_KEY=your_groq_api_key_here

オプション: 後で機能を拡張する場合は、他のモデル設定を追加できます。

3. MCPサーバーを直接実行

uv run mcp_server.py

サーバーが起動し、stdioで待機します（ログを追加しない限り、追加の出力はありません）。get_docsツールが登録されます。

4. 提供されているクライアントを使用

uv run client.py

次のような出力が表示されるはずです。

Available tools: ['get_docs']
ANSWER: <model-produced answer referencing SOURCE lines>

リストが空の場合は、サーバーが正しく起動し、例外が発生していないことを確認してください（ログを追加してください—以下を参照）。

💻 使用例

基本的な使用法

from mcp.client.stdio import stdio_client
from mcp import ClientSession, StdioServerParameters
import asyncio

async def demo():
    params = StdioServerParameters(command="uv", args=["run", "mcp_server.py"])
    async with stdio_client(params) as (r, w):
        async with ClientSession(r, w) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])
            docs = await session.call_tool("get_docs", {"query": "install", "library": "uv"})
            print(docs.content[:500])

asyncio.run(demo())

高度な使用法

# 独自のPythonスクリプトでツールを直接呼び出す場合の例
from mcp.client.stdio import stdio_client
from mcp import ClientSession, StdioServerParameters
import asyncio

async def custom_demo():
    # 独自のパラメータ設定
    custom_params = StdioServerParameters(command="uv", args=["run", "mcp_server.py"])
    async with stdio_client(custom_params) as (r, w):
        async with ClientSession(r, w) as session:
            await session.initialize()
            # ツールの一覧を取得
            tools = await session.list_tools()
            print([t.name for t in tools.tools])
            # 特定のクエリとライブラリでツールを呼び出す
            docs = await session.call_tool("get_docs", {"query": "advanced_search", "library": "langchain"})
            # 取得したドキュメントの一部を表示
            print(docs.content[:500])

asyncio.run(custom_demo())

📚 ドキュメント

ツール: get_docs

シグネチャ:

get_docs(query: str, library: str) -> str

サポートされているライブラリ（キー）: uv、langchain、openai、llama-index。

処理の流れ:

1. サイト限定のクエリを構築: site:<docs-domain> <query>。
2. Serper APIを呼び出して有機的な検索結果を取得。
3. httpxを使用して各結果のURLを非同期で取得。
4. HTMLを約4000文字のチャンクに分割（メモリ安全性とLLMの制限）。
5. Groq LLM（openai/gpt-oss-20b）を使用して、システムプロンプトで各チャンクをクリーニング。
6. 各ブロックを連結し、トレーサビリティのためにSOURCE: <url>でラベル付け。

返される値: 検索強化プロンプトに適した大きなテキストブロブで、ソースの帰属行が保持されます。

アーキテクチャ

ファイルの概要:

依存関係の注意事項

コアランタイムの依存関係（pyproject.tomlから）:

• fastmcp – MCPサーバーヘルパー。
• httpx – 非同期HTTPクライアント。
• groq – Groq APIクライアント。
• python-dotenv – .envから変数を読み込む。
• trafilatura – ヒューリスティックなコンテンツ抽出（現在は部分的に使用されており、拡張可能）。

💡 使用アドバイス

スクレイピングツールを追加する場合は、パフォーマンスのために単一のhttpx.AsyncClientを再利用してください。

ロギングとデバッグ

サーバーの動作を確認するには、一時的に以下のコードを追加できます。

import logging, sys
logging.basicConfig(level=logging.INFO, stream=sys.stderr)

これをmcp_server.pyのインポートの直後に配置します。プロトコルはstdoutをJSON-RPCに使用するため、ログはstderrにのみ送信します。

拡張

拡張のアイデア:

• キャッシュ層（例: sqliteまたはメモリ内辞書）を追加して、同じURLの再取得を避けます。
• asyncio.gather()を使用してURLの取得とクリーニングを並列化します（レート制限とLLMのコストに注意）。
• 別のツール（例: summarize_diff、list_endpoints）を追加します。
• 連結された文字列の代わりに、構造化されたJSON出力（ソースのリスト + クリーニングされたテキスト）を提供します。
• pytest + pytest-asyncioを使用してテストを追加します（Serper + LLM APIをモック）。

仮想環境を使用して実行

すでにアクティブな仮想環境があり、プロジェクトの固定環境の代わりにそれを使用したい場合は、uvにそれを指定できます。

uv run --active client.py

そうでない場合、uvはアクティブな$VIRTUAL_ENVがプロジェクトの.venvと異なることを警告しますが、プロジェクトの環境を引き続き使用します。

トラブルシューティングチートシート

貢献

1. フォークしてブランチを作成します。
2. uv syncを実行します。
3. 新しいツールのテストを追加します（追加した場合）。
4. 明確な説明付きでPRを開きます。

ロードマップ（オプション）

• [] ツールパラメータのJSONスキーマメタデータを追加します。
• [] 構造化されたレスポンス形式（{ソース, テキスト}のリスト）を追加します。
• [] キャッシュ層を追加します。
• [] レート制限/バックオフを追加します。
• [] CIワークフロー（リント + テスト）を追加します。

謝辞

• Serper.devの検索API
• Groqの高速OSSモデルサービング
• Astralのuv
• MCPエコシステムのプロトコル基盤

📄 ライセンス

配布する場合は、ここにライセンスセクション（例: MIT）を追加してください。