Kurd

Python向けの高性能Model Context Protocol (MCP)ゲートウェイで、Rustを採用しています。

ステータス

Kurdは現在、開発初期段階にあります。

公開APIと内部アーキテクチャは、最初の安定版リリース前に変更される可能性があります。

ハイライト

• Pythonファーストの開発者体験

• Rustを採用したネイティブコア

• 高速なJSON-RPC前処理

• 非同期ルーティングのサポート

• PyO3で構築されたネイティブ拡張

• Maturinによるパッケージングと配布

• 高スループットなMCPワークロード向けに設計

インストール

pip install kurd

Kurdは現在、開発初期段階にあります。すべてのPythonバージョンとオペレーティングシステムで、プラットフォーム固有のホイールがまだ利用できない場合があります。

クイックスタート

from kurd import Router

router = Router()


@router.tool(name="ping")
async def ping(value: int):
    return value + 1

JSON-RPCディスパッチ

KurdはJSON-RPCリクエストを、登録された非同期Pythonツールにルーティングできます。

import asyncio

from kurd import Router


router = Router()


@router.tool(name="add")
async def add(a: int, b: int):
    return a + b


async def main():
    response = await router.dispatch(
        '{"jsonrpc":"2.0","id":1,"method":"add","params":{"a":2,"b":3}}'
    )

    print(response)


asyncio.run(main())

応答の例:

{
  "jsonrpc": "2.0",
  "result": 5,
  "id": "1"
}

アーキテクチャ

KurdはPythonとRustのハイブリッドアーキテクチャを採用しています。

Python API
    |
    v
Kurd Router
    |
    v
PyO3
    |
    v
Rust Core
    |
    v
JSON-RPC Processing

Pythonは開発者向けAPIを提供し、パフォーマンスが重要な解析と前処理はRustコアが処理します。

パフォーマンス

初期のローカルマイクロベンチマークでは、KurdのRust JSON-RPC前処理パスが、同等の純Python実装よりも優れたパフォーマンスを発揮できることが示されています。

現在の測定値は実験的なものであり、本番環境でのパフォーマンスを保証するものとして解釈すべきではありません。

ベンチマークは、pyperfなどのツールを使用して実行されています:

• スループット

• 平均レイテンシ

• p50レイテンシ

• p95レイテンシ

• p99レイテンシ

• PythonとRustの前処理パフォーマンス

再現可能なベンチマーク結果は、プロジェクトが成熟するにつれて公開される予定です。

開発

KurdにはPythonとRustが必要です。

推奨される開発環境:

Python 3.12+
Rust stable
Maturin
PyO3

仮想環境を作成します:

python -m venv .venv

Windows PowerShellでアクティブにします:

.\.venv\Scripts\Activate.ps1

Maturinをインストールします:

python -m pip install maturin

Kurdを開発モードでビルドしてインストールします:

maturin develop --release

テストスイートを実行します:

python -m pytest -q

リリースホイールをビルドします:

maturin build --release

プロジェクト構造

kurd-mcp/
├── kurd/
│   ├── __init__.py
│   ├── router.py
│   └── _kurd.*
│
├── src/
│   └── lib.rs
│
├── tests/
│
├── benchmarks/
│
├── Cargo.toml
├── pyproject.toml
├── README.md
└── LICENSE

ベンチマーク

Kurdには、Rustの前処理パスを同等の純Python処理と比較することに焦点を当てたベンチマーク作業が含まれています。

ローカルでのpyperf測定の例:

Python: 5.92 us
Rust:   2.26 us
Speedup: 2.62x

これらの数値は予備的なローカルマイクロベンチマークであり、本番環境でのパフォーマンスを保証するものではありません。

パフォーマンスは、以下によって異なる場合があります:

• CPUアーキテクチャ

• Pythonのバージョン

• オペレーティングシステム

• ペイロードサイズ

• バッチサイズ

• システム負荷

• コンパイラ設定

• Rustの最適化レベル

将来のベンチマークには、再現可能なクロスプラットフォーム測定が含まれる予定です。

ロードマップ

計画されている開発分野は次のとおりです:

• MCPネイティブルーティング

• ストリーミング可能なHTTPトランスポート

• 接続管理

• リクエストルーティング

• 並行性制御

• バックプレッシャー

• タイムアウトとキャンセル

• アップストリームのヘルスチェック

• 可観測性

• 構造化エラー処理

• 改善されたPython型サポート

• クロスプラットフォームホイール

• 自動化されたCI/CDリリース

• ベンチマークの自動化

• Linux、macOS、Windowsでのパフォーマンステスト

設計目標

Kurdは、いくつかの中核となる原則に基づいて設計されています:

Pythonの人間工学

開発者は、シンプルで使い慣れたPython APIを通じてKurdを操作できる必要があります。

Rustのパフォーマンス

パフォーマンスが重要なプロトコル処理は、測定可能なメリットがある場合は常に、ネイティブのRustコードで処理する必要があります。

Python/Rust境界のオーバーヘッドを最小限に

データは、必要な場合にのみPython/Rust境界を越える必要があります。

Rustでデータを解析し、それをすぐにJSONにシリアライズしてPythonに再度解析させることは避ける必要があります。

MCPネイティブアーキテクチャ

Kurdは、単なる汎用JSON-RPCルーターに留まらず、MCP対応ゲートウェイへと進化することを目的としています。

測定可能なパフォーマンス

パフォーマンスの主張は、理論上の仮定ではなく、再現可能なベンチマークによって裏付けられる必要があります。

技術スタック

Kurdは現在、以下を使用しています:

• Python

• Rust

• PyO3

• Maturin

• Tokio

• Serde

• serde_json

• pytest

• pyperf

Python API

公開APIは、Pythonフレンドリーなままであることを目的としています。

例:

from kurd import Router

router = Router()


@router.tool()
async def multiply(a: int, b: int):
    return a * b

リクエストは、ルーターを介してディスパッチできます:

response = await router.dispatch(
    """
    {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "multiply",
        "params": {
            "a": 4,
            "b": 5
        }
    }
    """
)

エラー処理

Kurdは現在、基本的なJSON-RPCエラー応答をサポートしています:

-32700  Parse error
-32601  Method not found
-32602  Invalid params
-32603  Internal error

MCPプロトコルのサポートがより完全になるにつれて、エラー処理も進化し続けます。

ソースからのビルド

リポジトリをクローンします:

git clone https://github.com/sn391/kurd.git
cd kurd

仮想環境を作成します:

python -m venv .venv

アクティブにします:

.\.venv\Scripts\Activate.ps1

開発用依存関係をインストールします:

python -m pip install --upgrade pip
python -m pip install maturin pytest pyperf

Rust拡張機能をビルドします:

maturin develop --release

テストを実行します:

python -m pytest -q

配布可能なホイールをビルドします:

maturin build --release

生成されたホイールは、次の場所に配置されます:

target/wheels/

テスト

次のコマンドで完全なテストスイートを実行します:

python -m pytest -q

現在のテストでは、次のような領域をカバーしています:

• パッケージのインポート

• Rust拡張機能の利用可能性

• 有効なJSON解析

• 無効なJSON解析

• パラメータ抽出

• ルーターディスパッチ

• メソッドが見つからない場合の処理

• 無効なパラメータ

• 内部エラー

プロジェクトの開発に伴い、追加の統合テストとトランスポートテストが追加される予定です。

パッケージレイアウト

Kurdは、PythonとRustのハイブリッドパッケージです。

Pythonパッケージは、開発者向けAPIを公開します:

kurd/
├── __init__.py
├── router.py
└── _kurd.*

ネイティブ拡張機能はRustで実装されています:

src/
└── lib.rs

プライベートなネイティブモジュールは、内部的に次のように公開されます:

kurd._kurd

ユーザーは通常、以下で公開されている公開APIを介して操作する必要があります:

import kurd

プライベートなネイティブ実装の詳細に直接依存するのではなく。

互換性

このプロジェクトは現在、主に以下を使用して開発およびテストされています:

Python 3.12
Windows x86-64
Rust stable

追加のPythonバージョン、オペレーティングシステム、アーキテクチャのサポートは、自動化されたホイールビルドを通じて追加される予定です。

貢献

Kurdは現在、開発の初期段階にあります。

公開APIとアーキテクチャが安定化するにつれて、貢献ガイドラインが追加される予定です。

バグ、アイデア、技術的な議論については、GitHubのイシュートラッカーを使用してください:

https://github.com/sn391/kurd/issues

セキュリティ

Kurdはまだ本番環境に対応しているとは見なされていません。

セキュリティの問題を発見した場合は、公開イシューに機密性の高いエクスプロイトの詳細を公開しないでください。

専用のセキュリティポリシーと非公開の脆弱性報告プロセスは、プロジェクトが本番環境への準備が整うにつれて追加される予定です。

ライセンス

KurdはMITライセンスの下でリリースされています。

名前

Kurdという名前は、クルド人のアイデンティティと遺産に敬意を表しています。 Bezhi Kurd u Kurdistan