MCP Zig

MCP.zip

A Model Context Protocol (MCP) library for the Zig ecosystem.

文档 | API 参考 | 快速开始 | 贡献

______________________________________________________________________

什么是MCP？

模型上下文协议（MCP） 是将AI应用程序连接到外部系统的开源标准。 将MCP想象成AI应用程序的USB-C端口。 正如USB-C提供了一种连接电子设备的标准化方式一样，MCP也提供了将AI应用程序连接到外部系统的标准化方法。

为什么选择mcp.zig？

这 模型上下文协议（MCP） 是Anthropic为将AI应用程序连接到外部系统而制定的开放标准。虽然MCP有TypeScript、Python和其他语言的官方SDK， Zig目前缺乏适当的MCP支持.

mcp.zig 旨在通过为Zig编程语言提供本机高性能MCP实现来填补这一空白，使Zig开发人员能够：

• 构建MCP服务器，向AI应用程序公开工具、资源和提示
• 创建连接到任何MCP兼容服务器的MCP客户端
• 利用Zig的性能和安全功能进行AI集成

特性

• 服务器框架 -构建公开工具、资源和提示的MCP服务器
• 客户端框架 -创建完全支持根、采样和启发的MCP客户端
• 任务系统 -对长时间运行的交互式任务的高级支持
• 丰富内容 -完全支持文本、图像、音频和嵌入式资源
• 传输层 -STDIO和HTTP传输支持
• 完全协议支持 -JSON-RPC 2.0、能力协商、生命周期管理
• 本地性能 -纯Zig编写，性能最佳
• 综合测试 -所有组件的单元测试

文档

完整文档可在 ****

有关MCP的官方规范和资源，请访问：

• MCP文件
• MCP规范

Zig相关项目

• 有关API框架支持，请查看 api.zip.

• 有关web框架支持，请查看 紫曦.

• 有关日志支持，请查看 logly.zip.

• 有关数据验证和序列化支持，请查看 齐甘蒂克.

• 有关Http客户端和服务器支持，请查看 httpx.zig.

快速开始

安装

运行以下命令将mcp.zig添加到您的项目中：

# Latest development branch
zig fetch --save git+https://github.com/muhammad-fiaz/mcp.zig.git

# Zig 0.16.x (recommended)
zig fetch --save https://github.com/muhammad-fiaz/mcp.zig/archive/refs/tags/0.0.4.tar.gz

# Zig 0.15.x
zig fetch --save https://github.com/muhammad-fiaz/mcp.zig/archive/refs/tags/0.0.3.tar.gz

然后在你的 build.zig:

const mcp_dep = b.dependency("mcp", .{
    .target = target,
    .optimize = optimize,
});
exe.root_module.addImport("mcp", mcp_dep.module("mcp"));

创建服务器

const std = @import("std");
const mcp = @import("mcp");

pub fn main(init: std.process.Init) void {
    run(init.io, init.gpa) catch |err| {
        mcp.reportError(err);
    };
}

fn run(io: std.Io, allocator: std.mem.Allocator) !void {
    // Create server
    var server: mcp.Server = .init(allocator, .{
        .name = "my-server",
        .version = "1.0.0",
    });
    defer server.deinit();

    // Add a tool
    try server.addTool(.{
        .name = "greet",
        .description = "Greet a user",
        .handler = greetHandler,
    });

    // Run with STDIO transport
    try server.run(io, allocator, .stdio);
}

fn greetHandler(
    _: ?*anyopaque,
    _: std.Io,
    allocator: std.mem.Allocator,
    args: ?std.json.Value,
) mcp.tools.ToolError!mcp.tools.ToolResult {
    const name = mcp.tools.getString(args, "name") orelse "World";
    const message = try std.fmt.allocPrint(allocator, "Hello, {s}!", .{name});
    return mcp.tools.textResult(allocator, message);
}

创建客户端

const std = @import("std");
const mcp = @import("mcp");

pub fn main(init: std.process.Init) void {
    run(init.io, init.gpa) catch |err| {
        mcp.reportError(err);
    };
}

fn run(io: std.Io, allocator: std.mem.Allocator) !void {
    var client: mcp.Client = .init(io, allocator, .{
        .name = "my-client",
        .version = "1.0.0",
    });
    defer client.deinit(allocator);

    // Enable capabilities
    client.enableSampling();
    client.enableRoots(true); // Supports list changed notifications

    // Add roots
    try client.addRoot(allocator, "file:///projects", "Projects");
}

例子

这 examples/ 目录包含几个示例实现：

运行示例：

# Build all examples
zig build

# Run examples
zig build run-server
zig build run-weather
zig build run-calc

建筑

src/
├── mcp.zig              # Main entry point
├── protocol/
│   ├── protocol.zig     # MCP protocol definitions
│   ├── types.zig        # Type definitions
│   ├── jsonrpc.zig      # JSON-RPC 2.0 implementation
│   └── schema.zig       # JSON Schema utilities
├── transport/
│   └── transport.zig    # STDIO and HTTP transports
├── server/
│   ├── server.zig       # Server implementation
│   ├── tools.zig        # Tool primitive
│   ├── resources.zig    # Resource primitive
│   └── prompts.zig      # Prompt primitive
└── client/
    └── client.zig       # Client implementation

服务器功能

工具

工具是AI应用程序可以调用的可执行函数：

try server.addTool(.{
    .name = "search_files",
    .description = "Search for files matching a pattern",
    .handler = searchHandler,
});

资源

资源为AI应用程序提供只读数据：

try server.addResource(.{
    .uri = "file:///docs/readme.md",
    .name = "README",
    .mimeType = "text/markdown",
    .handler = readFileHandler,
});

提示

提示是LLM交互的可重用模板：

try server.addPrompt(.{
    .name = "summarize",
    .description = "Summarize a document",
    .arguments = &.{
        .{ .name = "document", .required = true },
    },
    .handler = summarizeHandler,
});

客户端功能

根

定义文件系统边界：

client.enableRoots(true);
try client.addRoot(allocator, "file:///projects", "Projects");

采样

允许服务器请求LLM完成：

client.enableSampling();

测试

运行测试套件：

zig build test

编译目标的测试而不执行它们（对于跨目标验证很有用）：

zig build test-compile -Dtarget=x86_64-linux
zig build test-compile -Dtarget=x86_64-windows
zig build test-compile -Dtarget=x86_64-macos

协议版本

此库实现MCP协议版本 2025-11-25.

贡献

欢迎投稿！请随时提交问题和拉取请求。

看 贡献指南 作为指导方针。

支持

如果你觉得这个项目有帮助，可以考虑支持它的开发：

许可证

该项目根据MIT许可证获得许可。看 许可证 了解详情。

资源

• mcp.zig文档
• MCP官方文件
• MCP规范

-