Useful Model Context Protocol Servers (MCPS)

便利な Model Context Protocol サーバー（MCPS）

さまざまなユーティリティ機能を提供する Model Context Protocol（MCP）サーバーを実装した、スタンドアロンの Python スクリプト集です。各サーバーは、AI アシスタントや MCP プロトコルに対応する他のアプリケーションで使用できる、専門的なツールを提供します。

MCP とは？

Model Context Protocol（MCP）は、AI アシスタントが外部のツールやサービスとやり取りするための標準規格です。AI モデルは、MCP サーバーが提供する専門的な関数を呼び出すことで、機能を拡張できます。通信には、JSON メッセージを使用した標準入出力（stdio）を使用します。

利用可能なサーバー

各 MCP サーバーは、uv などの Python 環境マネージャーを使って実行するように設計されています。

YouTube データ抽出ツール（ytdlp）

yt-dlp を使って YouTube 動画から情報を抽出するサーバーです。

ツール：

• チャプターの抽出：YouTube 動画のチャプター情報を取得します。
• 字幕の抽出：指定したチャプターまたは動画全体の字幕を取得します。

MCP サーバーの設定：

"mcpServers": {
  "ytdlp": {
    "name": "youtube", // Optional friendly name for the client
    "command": "uv",
    "args": [
      "run",
      "--directory", "<path/to/repo>/useful-mcps/ytdlp", // Path to the MCP directory containing pyproject.toml
      "--", // Separator before script arguments, if any
      "ytdlp_mcp" // Match the script name defined in pyproject.toml [project.scripts]
    ]
    // 'cwd' is not needed when using --directory
  }
}

Word ドキュメント処理ツール（docx_replace）

テンプレート処理や PDF 変換など、Word ドキュメントを操作するサーバーです。

ツール：

• テンプレートの処理：Word テンプレート内のプレースホルダーを置き換え、コンテンツブロックを管理します。
• テンプレートキーの取得：Word ドキュメントテンプレートから置換キーをすべて抽出します。
• PDF への変換：Word ドキュメント（docx）を PDF 形式に変換します。

MCP サーバーの設定：

"mcpServers": {
  "docx_replace": {
    "name": "docx", // Optional friendly name
    "command": "uv",
    "args": [
      "run",
      "--directory", "<path/to/repo>/useful-mcps/docx_replace", // Path to the MCP directory
      "--",
      "docx_replace_mcp" // Match the script name defined in pyproject.toml
    ]
  }
}

PlantUML レンダラー（plantuml）

PlantUML サーバー（Docker で実行されることが多い）を使って PlantUML 図をレンダリングするサーバーです。

ツール：

• 図のレンダリング：PlantUML テキストを図の画像（例：PNG）に変換します。

MCP サーバーの設定：

"mcpServers": {
  "plantuml": {
    "name": "plantuml", // Optional friendly name
    "command": "uv",
    "args": [
      "run",
      "--directory", "<path/to/repo>/useful-mcps/plantuml", // Path to the MCP directory
      "--",
      "plantuml_server" // Match the script name defined in pyproject.toml
    ]
  }
}

(注：アクセス可能な PlantUML サーバーが実行されている必要があります。サービスに実装されているように、Docker で管理することもできます。)

Mermaid レンダラー（mermaid）

mermaidchart.com API を使って Mermaid 図をレンダリングするサーバーです。

ツール：

• Mermaid チャートのレンダリング：mermaidchart.com にドキュメントを作成し、Mermaid コードを PNG 画像に変換します。

MCP サーバーの設定：

"mcpServers": {
  "mermaid": {
    "name": "mermaid", // Optional friendly name
    "command": "uv",
    "args": [
      "run",
      "--directory", "<path/to/repo>/useful-mcps/mermaid", // Path to the MCP directory
      "--",
      "mermaid_mcp" // Match the script name defined in pyproject.toml
    ],
    "env": { // Environment variables needed by the MCP
        "MERMAID_CHART_ACCESS_TOKEN": "YOUR_API_TOKEN_HERE"
    }
  }
}

(注：環境変数に Mermaid Chart API のアクセストークンを設定する必要があります。)

RSS フィードから Markdown への変換（rss2md）

日付で絞り込みながら、RSS フィードのコンテンツを Markdown 形式に変換するサーバーです。

ツール：

• fetch_rss_to_markdown：RSS フィードを取得し、日付で記事を絞り込み、該当する記事を Markdown のリスト形式で返します。。

MCP サーバーの設定：

"mcpServers": {
  "mermaid": {
    "name": "rss2md", // Optional friendly name
    "command": "uv",
    "args": [
      "run",
      "--directory", "<path/to/repo>/useful-mcps/rss2md", // Path to the MCP directory
      "--",
      "rss2md_mcp" // Match the script name defined in pyproject.toml
    ],
    "env": { // Environment variables needed by the MCP
    }
  }
}

インストール

1. リポジトリをクローンします：

   git clone https://github.com/daltonnyx/useful-mcps.git # Replace with the actual repo URL if different
   cd useful-mcps
   

2. uv をインストールします： uv がインストールされていない場合は、インストールしてください：

   pip install uv
   # or follow instructions at https://github.com/astral-sh/uv
   

3. 依存関係： 依存関係は pyproject.toml を使って MCP ごとに管理されます。初めて --directory を指定して MCP を実行すると、通常は uv run が仮想環境内に依存関係を自動的にインストールします。

使用方法

サーバーの実行

各 MCP サーバーは、対象の MCP のディレクトリを指定する uv run --directory <path> を使って実行することをおすすめします。uv は、そのディレクトリにある pyproject.toml に基づいて仮想環境と依存関係を管理します。

例（ルートの useful-mcps ディレクトリから実行する場合）：

# Run the YouTube MCP
uv run --directory ./ytdlp ytdlp_mcp

# Run the Mermaid MCP (ensure token is set in environment)
uv run --directory ./mermaid mermaid_mcp

または、上記の JSON 設定例のように、MCP クライアントで uv run --directory ... コマンドを直接実行するように設定できます。

サーバーへの接続

MCP クライアントアプリケーションで、各サーバーの「MCP サーバーの設定」例に示す command と args の構成を使って、目的のサーバーを起動するように設定します。command が uv の実行ファイルを指し、args で MCP のフォルダーへのパスを指定する --directory と、実行するスクリプト名が正しく指定されていることを確認してください。必要な環境変数（API トークンなど）は、env プロパティを使って渡します。

ツール固有の使用例

各 MCP サーバーの call_tool 関数に渡す arguments の例を示します。

YouTube Data Extractor

チャプターを抽出する

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}

字幕を抽出する

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "language": "en",
  "chapters": [
    {
      "title": "Introduction",
      "start_time": "00:00:00",
      "end_time": "00:01:30"
    }
  ]
}

Word Document Processor

テンプレートを処理する

{
  "template_file": "/path/to/template.docx",
  "replacements": {
    "name": "John Doe",
    "date": "2023-05-15"
  },
  "blocks": {
    "optional_section": true,
    "alternative_section": false
  },
  "output_filename": "/path/to/output.docx"
}

(注：template_file と docx_file には、パスの代わりに Base64 エンコードされた文字列も指定できます。)

テンプレートキーを取得する

{
  "template_file": "/path/to/template.docx"
}

PDF に変換する

{
  "docx_file": "/path/to/document.docx",
  "pdf_output": "/path/to/output.pdf"
}

PlantUML Renderer

図をレンダリングする

{
  "input": "participant User\nUser -> Server: Request\nServer --> User: Response",
  "output_path": "/path/to/save/diagram.png"
}

(注：input には .puml ファイルへのパスも指定できます。)

Mermaid Renderer

Mermaid チャートをレンダリングする

{
  "mermaid_code": "graph TD;\n    A-->B;\n    A-->C;\n    B-->D;\n    C-->D;",
  "output_path": "/path/to/save/mermaid.png",
  "theme": "default" // Optional, e.g., "default", "dark", "neutral", "forest"
}

開発

新しい MCP サーバーの追加

1. MCP 用の新しいディレクトリを作成します（例：my_new_mcp）。
2. ディレクトリ内に、次のファイルを作成します。
   • pyproject.toml：プロジェクトのメタデータ、依存関係、スクリプトのエントリーポイントを定義します（例：[project.scripts] セクションで my_new_mcp = "my_new_mcp:main" をマッピングします）。
   • pyrightconfig.json：（任意）型チェックに使用します。
   • メインの Python ファイル（例：my_new_mcp.py）：mcp ライブラリを使って MCP のロジックを実装します（以下のテンプレートを参照）。
3. 必要なクラスと関数（serve、list_tools、call_tool）を実装します。

基本テンプレート（my_new_mcp.py）：

import json
import logging
import asyncio
from typing import List, Dict, Any, Optional
# Assuming mcp library is installed or available
# from mcp import Server, Tool, TextContent, stdio_server
# Placeholder imports if mcp library structure is different
from typing import Protocol # Using Protocol as placeholder

# Placeholder definitions if mcp library isn't directly importable here
class Tool(Protocol):
    name: str
    description: str
    inputSchema: dict

class TextContent(Protocol):
    type: str
    text: str

class Server:
    def __init__(self, name: str): pass
    def list_tools(self): pass # Decorator
    def call_tool(self): pass # Decorator
    def create_initialization_options(self): pass
    async def run(self, read_stream, write_stream, options): pass

# Placeholder context manager
class stdio_server:
    async def __aenter__(self): return (None, None) # Dummy streams
    async def __aexit__(self, exc_type, exc, tb): pass


# Pydantic is often used for schema definition
# from pydantic import BaseModel
# class MyInput(BaseModel):
#     param1: str
#     param2: int

class MyInputSchema: # Placeholder if not using Pydantic
    @staticmethod
    def model_json_schema():
      return {"type": "object", "properties": {"param1": {"type": "string"}, "param2": {"type": "integer"}}, "required": ["param1", "param2"]}


class MyTools:
    TOOL_NAME = "my.tool"

class MyService:
    def __init__(self):
        # Initialize resources if needed
        pass

    def my_function(self, param1: str, param2: int) -> dict:
        # Implement your tool functionality
        logging.info(f"Running my_function with {param1=}, {param2=}")
        # Replace with actual logic
        result_content = f"Result: processed {param1} and {param2}"
        return {"content": result_content}

async def serve() -> None:
    logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
    server = Server("mcp-my-service")
    service = MyService()

    @server.list_tools()
    async def list_tools() -> list[Tool]:
        logging.info("list_tools called")
        return [
            Tool(
                name=MyTools.TOOL_NAME,
                description="Description of my tool",
                # Use Pydantic's schema or manually define
                inputSchema=MyInputSchema.model_json_schema(),
            ),
        ]

    @server.call_tool()
    async def call_tool(name: str, arguments: dict) -> list[TextContent]:
        logging.info(f"call_tool called with {name=}, {arguments=}")
        try:
            if name == MyTools.TOOL_NAME:
                # Add validation here if not using Pydantic
                param1 = arguments.get("param1")
                param2 = arguments.get("param2")
                if param1 is None or param2 is None:
                     raise ValueError("Missing required arguments")

                result = service.my_function(param1, int(param2)) # Ensure type conversion if needed
                logging.info(f"Tool executed successfully: {result=}")
                return [TextContent(type="text", text=json.dumps(result))] # Return JSON string
            else:
                logging.warning(f"Unknown tool requested: {name}")
                raise ValueError(f"Unknown tool: {name}")
        except Exception as e:
            logging.error(f"Error executing tool {name}: {e}", exc_info=True)
            # Return error as JSON
            error_payload = json.dumps({"error": str(e)})
            return [TextContent(type="text", text=error_payload)]

    options = server.create_initialization_options()
    logging.info("Starting MCP server...")
    async with stdio_server() as (read_stream, write_stream):
        await server.run(read_stream, write_stream, options)
    logging.info("MCP server stopped.")

def main():
    # Entry point defined in pyproject.toml `[project.scripts]`
    try:
        asyncio.run(serve())
    except KeyboardInterrupt:
        logging.info("Server interrupted by user.")

if __name__ == "__main__":
    # Allows running directly via `python my_new_mcp.py` for debugging
    main()

テスト

ルートディレクトリから pytest を使ってテストを実行します。

pytest tests/

(テスト用の依存関係がインストールされていることを確認してください。必要に応じて uv pip install pytest を実行するか、いずれかの pyproject.toml ファイルの開発用依存関係に pytest を追加してください。)

ライセンス

MIT ライセンス

コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。