Malloy MCP Server

🚀 Malloy MCP サーバー

Malloyクエリの実行とMalloyリソースの管理を行うMCPサーバーの実装です。Malloyを使ったデータ分析や管理作業を効率的に行うことができます。

🚀 クイックスタート

このセクションでは、Malloy MCPサーバーの基本的な使い方を説明します。以下の手順に従って、サーバーを起動し、クエリを実行しましょう。

✨ 主な機能

• MCPを通じてMalloyクエリを実行します。
• Malloyプロジェクト、パッケージ、モデルのメタデータにアクセスできます。
• 詳細なコンテキストを持つ強力なエラー処理機能が備わっています。
• 包括的なテストカバレッジがあり、安定性が高いです。
• 型安全な実装がされています。

📦 インストール

以下のコマンドを使って、Malloy MCPサーバーをインストールできます。

# uvを使用してインストール（推奨）
uv pip install malloy-mcp-server

# またはpipを使用
pip install malloy-mcp-server

💻 使用例

基本的な使用法

サーバーの起動

from malloy_mcp_server import mcp

# サーバーを実行
if __name__ == "__main__":
    mcp.serve()

設定

サーバーは環境変数を使って設定できます。

例:

# パブリッシャーのURLを設定
export MALLOY_PUBLISHER_ROOT_URL="http://malloy-publisher:4000"

# カスタム設定で実行
python -m malloy_mcp_server

クエリの実行

サーバーはMalloyクエリを実行するためのMCPツールを提供しています。

from malloy_mcp_server import ExecuteMalloyQueryTool

# クエリ実行の例
result = await ExecuteMalloyQueryTool(
    query="select * from users",
    model_path="my_package/users"
)

リソースのアクセス

サーバーは以下のリソースエンドポイントを提供しています。

• malloy://project/home/metadata - プロジェクトのメタデータ
• malloy://project/home/package/{package_name} - パッケージのメタデータ
• malloy://project/home/model/{model_path} - モデルのメタデータ

高度な使用法

開発環境のセットアップ

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

git clone https://github.com/namabile/malloy-mcp-server.git
cd malloy-mcp-server

2. 依存関係をインストールします。

uv pip install -e ".[dev]"

テストの実行

# すべてのテストを実行
pytest

# カバレッジ付きで実行
pytest --cov=malloy_mcp_server

コード品質の管理

このプロジェクトでは、以下のツールを使ってコード品質を管理しています。

• black でコードを整形します。
• mypy で型チェックを行います。
• ruff でコードチェックを行います。

品質チェックを実行するには、以下のコマンドを実行します。

black .
mypy .
ruff check .

エラー処理

サーバーは詳細なエラー処理とコンテキストを提供しています。

from malloy_mcp_server.errors import QueryExecutionError

try:
    result = await ExecuteMalloyQueryTool(...)
except QueryExecutionError as e:
    print(f"エラー: {e.message}")
    print("コンテキスト:", e.context)

🔧 技術詳細

サーバーは以下の技術を基に構築されています。

• FastMCPを使ったMCPサーバーの実装
• Malloyパブリッシャークライアントを使ったMalloyとのやり取り
• Pydanticを使ったデータ検証

主要なコンポーネントは以下の通りです。

• server.py - コアサーバーの実装
• tools/query_executor.py - クエリ実行ツール
• errors.py - エラー処理ユーティリティ

🤝 貢献方法

1. リポジトリをフォークします。
2. 機能ブランチを作成します。
3. 変更を加えます。
4. 新しい機能に対するテストを追加します。
5. プルリクエストを送信します。

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。詳細は LICENSE ファイルを参照してください。