Kurd

Высокопроизводительный шлюз Model Context Protocol (MCP) для Python на базе Rust.

Статус

Kurd в настоящее время находится на ранней стадии разработки.

Публичный API и внутренняя архитектура могут измениться до первого стабильного релиза.

Основные возможности

• Ориентированный на Python опыт разработчика

• Нативное ядро на базе Rust

• Быстрая предобработка JSON-RPC

• Поддержка асинхронной маршрутизации

• Нативное расширение, созданное с помощью PyO3

• Упаковка и распространение с помощью Maturin

• Спроектирован для высоконагруженных MCP-задач

Установка

pip install kurd

Kurd в настоящее время находится на ранней стадии разработки. Платформенные wheel-файлы могут быть ещё недоступны для каждой версии 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.

Производительность

Ранние локальные микробенчмарки показывают, что путь предобработки JSON-RPC на Rust в Kurd может превзойти эквивалентную реализацию на чистом 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

Соберите релизный wheel-файл:

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

Эти цифры являются предварительными локальными микробенчмарками и не являются гарантиями производительности в продакшене.

Производительность может изменяться в зависимости от:

• архитектуры процессора

• версии Python

• операционной системы

• размера полезной нагрузки

• размера пакета

• загрузки системы

• конфигурации компилятора

• уровня оптимизации Rust

Будущие бенчмарки будут включать воспроизводимые кроссплатформенные измерения.

Дорожная карта

Планируемые направления разработки включают:

• MCP-нативная маршрутизация

• Потоковый HTTP-транспорт

• управление соединениями

• маршрутизация запросов

• контроль конкурентности

• противодавление

• таймауты и отмена

• проверки работоспособности вышестоящих сервисов

• наблюдаемость

• структурированная обработка ошибок

• улучшенная поддержка типов Python

• кроссплатформенные wheel-файлы

• автоматизированные CI/CD-релизы

• автоматизация бенчмарков

• тестирование производительности на Linux, macOS и Windows

Цели проектирования

Kurd проектируется на основе нескольких ключевых принципов:

Эргономика Python

Разработчики должны взаимодействовать с Kurd через простой и знакомый Python API.

Производительность Rust

Чувствительная к производительности обработка протокола должна выполняться нативным кодом Rust всякий раз, когда это даёт измеримое преимущество.

Минимальные накладные расходы на границе Python/Rust

Данные должны пересекать границу Python/Rust только при необходимости.

Следует избегать разбора данных в Rust с последующей немедленной сериализацией обратно в JSON для повторного разбора в Python.

MCP-нативная архитектура

Kurd предназначен для развития в MCP-ориентированный шлюз, а не для того, чтобы оставаться лишь универсальным маршрутизатором JSON-RPC.

Измеримая производительность

Заявления о производительности должны подтверждаться воспроизводимыми бенчмарками, а не теоретическими предположениями.

Технологический стек

Kurd в настоящее время использует:

• Python

• Rust

• PyO3

• Maturin

• Tokio

• Serde

• serde_json

• pytest

• pyperf

API Python

Публичный 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

Соберите распространяемый wheel-файл:

maturin build --release

Сгенерированные wheel-файлы помещаются в:

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, операционных систем и архитектур будет добавлена с помощью автоматизированной сборки wheel-файлов.

Участие в разработке

Kurd в настоящее время находится на раннем этапе разработки.

Рекомендации по участию будут добавлены по мере стабилизации публичного API и архитектуры.

Для сообщений об ошибках, обмена идеями и технических обсуждений используйте трекер задач GitHub:

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

Безопасность

Kurd ещё не считается готовым к продакшену.

Если вы обнаружили проблему безопасности, не публикуйте чувствительные детали эксплуатации уязвимости в публичном issue.

Специальная политика безопасности и закрытый процесс сообщения об уязвимостях будут добавлены по мере приближения проекта к готовности к продакшену.

Лицензия

Kurd выпущен под лицензией MIT.

Название

Название Kurd отдаёт дань уважения курдской идентичности и наследию. Bezhi Kurd u Kurdistan