Kurd

一个由 Rust 驱动、面向 Python 的高性能模型上下文协议（MCP）网关。

状态

Kurd 目前处于早期开发阶段。

在首个稳定版本发布之前，公共 API 和内部架构可能会发生变化。

亮点

• Python 优先的开发者体验

• Rust 驱动的原生核心

• 快速的 JSON-RPC 预处理

• 异步路由支持

• 使用 PyO3 构建的原生扩展

• 使用 Maturin 进行打包和分发

• 专为高吞吐量 MCP 工作负载设计

安装

pip install kurd

Kurd 目前处于早期开发阶段。可能尚未为所有 Python 版本和操作系统提供特定平台的 wheel 包。

快速开始

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

构建发布版 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

这些数字是初步的本地微基准测试结果，并非生产环境的性能保证。

性能可能因以下因素而异：

• CPU 架构

• Python 版本

• 操作系统

• 负载大小

• 批量大小

• 系统负载

• 编译器配置

• Rust 优化级别

未来的基准测试将包含可复现的跨平台测量结果。

路线图

计划中的开发领域包括：

• MCP 原生路由

• 可流式 HTTP 传输

• 连接管理

• 请求路由

• 并发控制

• 背压

• 超时与取消

• 上游健康检查

• 可观测性

• 结构化错误处理

• 改进的 Python 类型支持

• 跨平台 wheel 包

• 自动化 CI/CD 发布

• 基准测试自动化

• Linux、macOS 和 Windows 性能测试

设计目标

Kurd 的设计围绕以下几个核心原则：

Python 易用性

开发者应通过简单且熟悉的 Python API 与 Kurd 交互。

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

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

构建可分发的 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

将通过自动化 wheel 构建来增加对更多 Python 版本、操作系统和架构的支持。

贡献

Kurd 目前处于早期开发阶段。

随着公共 API 和架构趋于稳定，将添加贡献指南。

如有 bug、想法或技术讨论，请使用 GitHub issue 跟踪器：

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

安全

Kurd 尚未被视为生产就绪。

如果您发现安全漏洞，请避免在公开 issue 中发布敏感的漏洞利用细节。

随着项目接近生产就绪，将添加专门的安全策略和私密漏洞报告流程。

许可证

Kurd 以 MIT 许可证发布。

名称

Kurd 这个名字致敬库尔德人的身份认同与文化遗产。 Bezhi Kurd u Kurdistan