Kurd

Python과 Rust로 구동되는 고성능 MCP(모델 컨텍스트 프로토콜) 게이트웨이입니다.

상태

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는 등록된 비동기 Python 도구로 JSON-RPC 요청을 라우팅할 수 있습니다.

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에서 데이터를 파싱한 후 Python에서 다시 파싱하기 위해 즉시 JSON으로 직렬화하는 것은 피해야 합니다.

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

비공개 네이티브 구현 세부 사항에 직접 의존하기보다는 공개 API를 사용하는 것이 좋습니다.

호환성

이 프로젝트는 현재 다음 환경에서 개발 및 테스트되고 있습니다:

Python 3.12
Windows x86-64
Rust stable

자동화된 CI/CD를 통해 추가 Python 버전, 운영 체제 및 아키텍처 지원이 추가될 예정입니다.

기여

Kurd는 현재 초기 개발 단계에 있습니다.

공개 API와 아키텍처가 안정화됨에 따라 기여 가이드라인이 추가될 예정입니다.

버그, 아이디어 및 기술 논의는 GitHub 이슈 트래커를 이용해 주세요:

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

보안

Kurd는 아직 프로덕션 준비가 완료되지 않았습니다.

보안 취약점을 발견한 경우 공개 이슈에 민감한 익스플로잇 세부 사항을 게시하지 마십시오.

프로젝트가 출시 준비에 가까워짐에 따라 전용 보안 정책과 비공개 취약점 보고 절차가 마련될 예정입니다.

라이선스

Kurd는 MIT 라이선스로 배포됩니다.

이름에 대하여

Kurd라는 이름은 쿠르드인의 정체성과 유산을 기립니다. Kurd와 Kurdistan을 기립니다.