Kurd

Una puerta de enlace de alto rendimiento para el Protocolo de Contexto de Modelo (MCP) para Python, impulsada por Rust.

Estado

Kurd se encuentra actualmente en desarrollo temprano.

La API pública y la arquitectura interna pueden cambiar antes de la primera versión estable.

Características principales

• Experiencia de desarrollo centrada en Python

• Núcleo nativo impulsado por Rust

• Preprocesamiento JSON-RPC rápido

• Soporte de enrutamiento asíncrono

• Extensión nativa construida con PyO3

• Empaquetado y distribución con Maturin

• Diseñado para cargas de trabajo MCP de alto rendimiento

Instalación

pip install kurd

Kurd se encuentra actualmente en desarrollo temprano. Es posible que las wheels específicas de plataforma aún no estén disponibles para todas las versiones de Python y sistemas operativos.

Inicio rápido

from kurd import Router

router = Router()


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

Despacho JSON-RPC

Kurd puede enrutar solicitudes JSON-RPC a herramientas asíncronas de Python registradas.

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

Ejemplo de respuesta:

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

Arquitectura

Kurd utiliza una arquitectura híbrida de Python y Rust.

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

Python proporciona la API orientada al desarrollador, mientras que el análisis y el preprocesamiento sensibles al rendimiento son manejados por el núcleo de Rust.

Rendimiento

Los primeros microbenchmarks locales muestran que la ruta de preprocesamiento JSON-RPC en Rust de Kurd puede superar a una implementación equivalente en Python puro.

Las mediciones actuales son experimentales y no deben interpretarse todavía como garantías de rendimiento en producción.

Se están realizando benchmarks con herramientas como pyperf para medir:

• capacidad de procesamiento

• latencia media

• latencia p50

• latencia p95

• latencia p99

• rendimiento del preprocesamiento en Python vs. Rust

Los resultados de benchmark reproducibles se publicarán a medida que el proyecto madure.

Desarrollo

Kurd requiere Python y Rust.

Entorno de desarrollo recomendado:

Python 3.12+
Rust stable
Maturin
PyO3

Crea un entorno virtual:

python -m venv .venv

Actívalo en Windows PowerShell:

.\.venv\Scripts\Activate.ps1

Instala Maturin:

python -m pip install maturin

Compila e instala Kurd en modo de desarrollo:

maturin develop --release

Ejecuta la suite de pruebas:

python -m pytest -q

Compila una wheel de distribución:

maturin build --release

Estructura del proyecto

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

Benchmarking

Kurd incluye trabajo de benchmark centrado en comparar la ruta de preprocesamiento en Rust con el procesamiento equivalente en Python puro.

Ejemplo de mediciones locales con pyperf:

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

Estos números son microbenchmarks locales preliminares y no son garantías de rendimiento en producción.

El rendimiento puede variar según:

• arquitectura de la CPU

• versión de Python

• sistema operativo

• tamaño de la carga útil

• tamaño del lote

• carga del sistema

• configuración del compilador

• nivel de optimización de Rust

Los benchmarks futuros incluirán mediciones reproducibles entre plataformas.

Hoja de ruta

Las áreas de desarrollo planificadas incluyen:

• enrutamiento nativo de MCP

• transporte HTTP transmisible

• gestión de conexiones

• enrutamiento de solicitudes

• control de concurrencia

• contrapresión

• tiempos de espera y cancelación

• comprobaciones de salud de los servicios upstream

• observabilidad

• manejo estructurado de errores

• soporte mejorado de tipos de Python

• wheels multiplataforma

• lanzamientos automatizados de CI/CD

• automatización de benchmarks

• pruebas de rendimiento en Linux, macOS y Windows

Objetivos de diseño

Kurd se está diseñando en torno a varios principios fundamentales:

Ergonomía de Python

Los desarrolladores deberían interactuar con Kurd a través de una API de Python simple y familiar.

Rendimiento de Rust

El procesamiento de protocolo sensible al rendimiento debería ser manejado por código nativo de Rust siempre que esto proporcione un beneficio medible.

Sobrecarga mínima en el límite entre Python y Rust

Los datos deberían cruzar el límite entre Python y Rust solo cuando sea necesario.

Se debe evitar analizar datos en Rust y serializarlos inmediatamente de vuelta a JSON para que Python los analice de nuevo.

Arquitectura nativa de MCP

Kurd tiene la intención de evolucionar hacia una puerta de enlace consciente de MCP en lugar de seguir siendo solo un enrutador JSON-RPC genérico.

Rendimiento medible

Las afirmaciones de rendimiento deberían estar respaldadas por benchmarks reproducibles en lugar de suposiciones teóricas.

Pila tecnológica

Kurd utiliza actualmente:

• Python

• Rust

• PyO3

• Maturin

• Tokio

• Serde

• serde_json

• pytest

• pyperf

API de Python

La API pública tiene la intención de seguir siendo amigable con Python.

Ejemplo:

from kurd import Router

router = Router()


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

Las solicitudes pueden entonces enviarse a través del enrutador:

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

Manejo de errores

Kurd actualmente admite respuestas de error JSON-RPC básicas, incluyendo:

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

El manejo de errores continuará evolucionando a medida que el soporte del protocolo MCP se vuelva más completo.

Compilación desde el código fuente

Clona el repositorio:

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

Crea un entorno virtual:

python -m venv .venv

Actívalo:

.\.venv\Scripts\Activate.ps1

Instala las dependencias de desarrollo:

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

Compila la extensión de Rust:

maturin develop --release

Ejecuta las pruebas:

python -m pytest -q

Compila una wheel distribuible:

maturin build --release

Las wheels generadas se colocan en:

target/wheels/

Pruebas

Ejecuta la suite de pruebas completa con:

python -m pytest -q

Las pruebas actuales cubren áreas como:

• importación del paquete

• disponibilidad de la extensión de Rust

• análisis de JSON válido

• análisis de JSON no válido

• extracción de parámetros

• envío del enrutador

• manejo de método no encontrado

• parámetros no válidos

• errores internos

Se añadirán pruebas adicionales de integración y transporte a medida que el proyecto se desarrolle.

Estructura del paquete

Kurd es un paquete mixto de Python/Rust.

El paquete de Python expone la API orientada al desarrollador:

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

La extensión nativa está implementada en Rust:

src/
└── lib.rs

El módulo nativo privado se expone internamente como:

kurd._kurd

Los usuarios deberían generalmente interactuar con la API pública expuesta por:

import kurd

en lugar de depender directamente de los detalles de implementación nativa privados.

Compatibilidad

El proyecto se está desarrollando y probando actualmente principalmente con:

Python 3.12
Windows x86-64
Rust stable

El soporte para versiones adicionales de Python, sistemas operativos y arquitecturas se añadirá mediante compilaciones automatizadas de wheels.

Contribuciones

Kurd se encuentra actualmente en una fase temprana de desarrollo.

Las guías de contribución se añadirán a medida que la API pública y la arquitectura se estabilicen.

Para errores, ideas y discusiones técnicas, utiliza el rastreador de incidencias de GitHub:

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

Seguridad

Kurd aún no se considera listo para producción.

Si descubres un problema de seguridad, evita publicar detalles sensibles de explotación en una incidencia pública.

Se añadirá una política de seguridad dedicada y un proceso privado de notificación de vulnerabilidades a medida que el proyecto se acerque a estar listo para producción.

Licencia

Kurd se publica bajo la Licencia MIT.

Nombre

El nombre Kurd honra la identidad y el patrimonio kurdo. Bezhi Kurd u Kurdistan