MCP Plugin API

MCP插件API

用于构建MCP（模型上下文协议）服务器插件的接口机箱。

概述

此机箱定义了MCP框架和插件之间的C ABI接口。它只包含类型定义，没有实现代码，使其轻量级和稳定。

为什么要单独装箱？

将插件API放在一个单独的机箱中提供了几个好处：

1. 无代码重复：接口定义一次并共享
2. 轻量级：插件仅依赖于这个小机箱（~5KB）
3. 清洁依赖关系：没有循环依赖或框架膨胀
4. 版本控制：API可以独立进行版本控制
5. 外部发展：第三方可以在不访问框架代码的情况下开发插件

依赖图

┌─────────────────┐
│ mcp-plugin-api  │  ← Interface definitions only
└────────┬────────┘
         │
    ┌────┴────┬──────────┐
    │         │          │
    ▼         ▼          ▼
framework  plugin-A  plugin-B

插件中的用法

添加到您的插件 Cargo.toml:

[dependencies]
mcp-plugin-api = { path = "../../mcp-plugin-api" }
# Or from crates.io:
# mcp-plugin-api = "0.1"

然后在你的插件中：

use mcp_plugin_api::*;

// Declare plugin with automatic version management
declare_plugin! {
    register: register_plugin,
    free_string: plugin_free_string
}

extern "C" fn register_plugin(registrar: *mut PluginRegistrar) -> i32 {
    // Register your tools...
    0
}

unsafe extern "C" fn plugin_free_string(ptr: *mut u8, len: usize) {
    if !ptr.is_null() && len > 0 {
        let _ = Vec::from_raw_parts(ptr, len, len);
    }
}

这 declare_plugin! 宏自动从您构建的机箱中嵌入API版本，确保无需手动管理即可进行版本跟踪。

密钥类型

• PluginDeclaration：主要插件入口点
• PluginRegistrar：用于在初始化过程中注册工具
• ToolDeclaration：定义工具的元数据和执行函数

内存安全

API通过插件边界强制执行正确的内存管理：

1. 插件使用其分配器分配内存
2. 插件向框架返回指针和容量
3. 框架使用数据
4. 框架调用插件 free_string 取消分配
5. 插件使用其分配器正确解除分配

这可以防止交叉分配器损坏。

线程安全

所有工具执行函数将从多个线程并发调用。实现 必须是线程安全的.

版本兼容性

API使用语义版本控制。重大更改会增加主版本。针对API v0.1.x构建的插件与使用API v0.1.y的框架兼容（其中y>=x）。

自动版本跟踪

插件API版本在编译时自动嵌入到您的插件中。当你构建一个插件时：

1. 这 declare_plugin! 宏从中读取API版本 mcp-plugin-api的Cargo.toml
2. 此版本作为常量嵌入到您的编译中 .so 文件
3. 框架在加载插件时读取此版本
4. 主要版本不匹配会产生警告

这意味着：

• ✅ 无需手动版本管理
• ✅ 插件版本总是与它所针对的API相匹配
• ✅ 框架可以自动验证兼容性
• ✅ 版本可以从插件二进制文件中审计

注： Rust编译器版本无关紧要。C ABI在rustc版本中是稳定的，因此只有API版本才有利于兼容性。

许可证

麻省理工学院或阿帕奇-2.0