Kurd

Ein Hochleistungs-Gateway für das Model Context Protocol (MCP) für Python, unterstützt durch Rust.

Status

Kurd befindet sich derzeit in der frühen Entwicklungsphase.

Die öffentliche API und die interne Architektur können sich vor der ersten stabilen Version ändern.

Highlights

• Python-first-Entwicklererfahrung

• Nattiver Kern mit Rust

• Schnelle JSON-RPC-Vorverarbeitung

• Unterstützung für asynchrones Routing

• Native Erweiterung mit PyO3

• Paketierung und Verteilung mit Maturin

• Entwickelt für MCP-Workloads mit hohem Durchsatz

Installation

pip install kurd

Kurd befindet sich derzeit in der frühen Entwicklungsphase. Plattformspezifische Wheels sind möglicherweise noch nicht für jede Python-Version und jedes Betriebssystem verfügbar.

Schnellstart

from kurd import Router

router = Router()


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

JSON-RPC-Dispatch

Kurd kann JSON-RPC-Anfragen an registrierte asynchrone Python-Tools weiterleiten.

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())

Beispielantwort:

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

Architektur

Kurd verwendet eine hybride Python- und Rust-Architektur.

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

Python stellt die entwicklerorientierte API bereit, während leistungskritische Parsing- und Vorverarbeitungsaufgaben vom Rust-Kern übernommen werden.

Leistung

Frühe lokale Mikrobenchmarks zeigen, dass Kurds Rust-JSON-RPC-Vorverarbeitungspfad eine äquivalente reine Python-Implementierung übertreffen kann.

Die aktuellen Messungen sind experimentell und sollten noch nicht als Produktionsleistungsgarantien interpretiert werden.

Benchmarks werden mit Tools wie pyperf durchgeführt, um Folgendes zu messen:

• Durchsatz

• durchschnittliche Latenz

• p50-Latenz

• p95-Latenz

• p99-Latenz

• Python- vs. Rust-Vorverarbeitungsleistung

Reproduzierbare Benchmark-Ergebnisse werden veröffentlicht, sobald das Projekt ausgereift ist.

Entwicklung

Kurd erfordert Python und Rust.

Empfohlene Entwicklungsumgebung:

Python 3.12+
Rust stable
Maturin
PyO3

Erstellen Sie eine virtuelle Umgebung:

python -m venv .venv

Aktivieren Sie sie in Windows PowerShell:

.\.venv\Scripts\Activate.ps1

Installieren Sie Maturin:

python -m pip install maturin

Erstellen und installieren Sie Kurd im Entwicklungsmodus:

maturin develop --release

Führen Sie die Testsuite aus:

python -m pytest -q

Erstellen Sie ein Release-Wheel:

maturin build --release

Projektstruktur

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

Benchmarking

Kurd enthält Benchmark-Arbeiten, die sich auf den Vergleich des Rust-Vorverarbeitungspfads mit äquivalenter reiner Python-Verarbeitung konzentrieren.

Beispiel für lokale pyperf-Messungen:

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

Diese Zahlen sind vorläufige lokale Mikrobenchmarks und keine Produktionsleistungsgarantien.

Die Leistung kann je nach Folgendem variieren:

• CPU-Architektur

• Python-Version

• Betriebssystem

• Payload-Größe

• Batch-Größe

• Systemlast

• Compiler-Konfiguration

• Rust-Optimierungsstufe

Zukünftige Benchmarks werden reproduzierbare plattformübergreifende Messungen enthalten.

Roadmap

Geplante Entwicklungsbereiche umfassen:

• MCP-natives Routing

• Streamable-HTTP-Transport

• Verbindungsverwaltung

• Anforderungsrouting

• Parallelitätssteuerung

• Backpressure

• Timeouts und Abbruch

• Upstream-Health-Checks

• Beobachtbarkeit

• Strukturierte Fehlerbehandlung

• Verbesserte Python-Typunterstützung

• Plattformübergreifende Wheels

• Automatisierte CI/CD-Releases

• Benchmark-Automatisierung

• Leistungstests für Linux, macOS und Windows

Designziele

Kurd wird um mehrere Kernprinzipien herum entwickelt:

Python-Ergonomie

Entwickler sollten über eine einfache und vertraute Python-API mit Kurd interagieren.

Rust-Leistung

Leistungskritische Protokollverarbeitung sollte von nativem Rust-Code übernommen werden, wann immer dies einen messbaren Vorteil bietet.

Minimale Python/Rust-Grenzüberhead

Daten sollten die Python/Rust-Grenze nur dann überschreiten, wenn es notwendig ist.

Das Parsen von Daten in Rust und das sofortige Zurückserialisieren in JSON, damit Python sie erneut parsen kann, sollte vermieden werden.

MCP-native Architektur

Kurd soll sich zu einem MCP-bewussten Gateway entwickeln und nicht nur ein generischer JSON-RPC-Router bleiben.

Messbare Leistung

Leistungsbehauptungen sollten durch reproduzierbare Benchmarks gestützt werden und nicht durch theoretische Annahmen.

Technologie-Stack

Kurd verwendet derzeit:

• Python

• Rust

• PyO3

• Maturin

• Tokio

• Serde

• serde_json

• pytest

• pyperf

Python-API

Die öffentliche API soll Python-freundlich bleiben.

Beispiel:

from kurd import Router

router = Router()


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

Anfragen können dann über den Router weitergeleitet werden:

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

Fehlerbehandlung

Kurd unterstützt derzeit grundlegende JSON-RPC-Fehlerantworten, einschließlich:

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

Die Fehlerbehandlung wird sich weiterentwickeln, wenn die MCP-Protokollunterstützung vollständiger wird.

Erstellen aus dem Quellcode

Klonen Sie das Repository:

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

Erstellen Sie eine virtuelle Umgebung:

python -m venv .venv

Aktivieren Sie sie:

.\.venv\Scripts\Activate.ps1

Installieren Sie Entwicklungsabhängigkeiten:

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

Erstellen Sie die Rust-Erweiterung:

maturin develop --release

Führen Sie Tests aus:

python -m pytest -q

Erstellen Sie ein verteilbares Wheel:

maturin build --release

Generierte Wheels werden unter folgendem Pfad abgelegt:

target/wheels/

Testen

Führen Sie die vollständige Testsuite mit folgendem Befehl aus:

python -m pytest -q

Aktuelle Tests decken Bereiche ab wie:

• Paketimport

• Verfügbarkeit der Rust-Erweiterung

• Parsen von gültigem JSON

• Parsen von ungültigem JSON

• Parameterextraktion

• Router-Dispatch

• Behandlung von "Methode nicht gefunden"

• Ungültige Parameter

• Interne Fehler

Zusätzliche Integrations- und Transporttests werden hinzugefügt, sobald sich das Projekt entwickelt.

Paketlayout

Kurd ist ein gemischtes Python/Rust-Paket.

Das Python-Paket stellt die entwicklerorientierte API bereit:

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

Die native Erweiterung ist in Rust implementiert:

src/
└── lib.rs

Das private native Modul wird intern wie folgt bereitgestellt:

kurd._kurd

Benutzer sollten im Allgemeinen mit der öffentlichen API interagieren, die von Folgendem bereitgestellt wird:

import kurd

anstatt direkt von privaten nativen Implementierungsdetails abhängig zu sein.

Kompatibilität

Das Projekt wird derzeit hauptsächlich mit Folgendem entwickelt und getestet:

Python 3.12
Windows x86-64
Rust stable

Unterstützung für zusätzliche Python-Versionen, Betriebssysteme und Architekturen wird durch automatisierte Wheel-Builds hinzugefügt.

Mitwirken

Kurd befindet sich derzeit in einer frühen Entwicklungsphase.

Richtlinien für Beiträge werden hinzugefügt, sobald sich die öffentliche API und die Architektur stabilisieren.

Für Fehler, Ideen und technische Diskussionen verwenden Sie den GitHub-Issue-Tracker:

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

Sicherheit

Kurd ist noch nicht als produktionsreif anzusehen.

Wenn Sie ein Sicherheitsproblem entdecken, vermeiden Sie es, sensible Exploit-Details in einem öffentlichen Issue zu veröffentlichen.

Eine dedizierte Sicherheitsrichtlinie und ein privater Prozess zur Meldung von Schwachstellen werden hinzugefügt, sobald sich das Projekt der Produktionsreife nähert.

Lizenz

Kurd wird unter der MIT-Lizenz veröffentlicht.

Name

Der Name Kurd würdigt die kurdische Identität und das kurdische Erbe. Bezhi Kurd u Kurdistan