Crate mcp_plugin_api 

MCP Plugin API - Interface definitions for plugin development

This crate defines the C ABI interface between the MCP framework and plugins. Both the framework and plugins depend on this crate.

Overview

This crate provides two ways to create plugins:

1. High-Level API (Recommended)

Use the Tool builder and declare_tools! macro for a clean, type-safe API:

use mcp_plugin_api::*;
use serde_json::{json, Value};

fn handle_hello(args: &Value) -> Result<Value, String> {
    let name = args["name"].as_str().unwrap_or("World");
    Ok(json!({ "message": format!("Hello, {}!", name) }))
}

declare_tools! {
    tools: [
        Tool::new("hello", "Say hello")
            .param_string("name", "Name to greet", false)
            .handler(handle_hello),
    ]
}

declare_plugin! {
    list_tools: generated_list_tools,
    execute_tool: generated_execute_tool,
    free_string: mcp_plugin_api::utils::standard_free_string
}

2. Low-Level API

Manually implement the three C functions for maximum control:

• list_tools: Returns JSON array of available tools
• execute_tool: Executes a tool by name
• free_string: Deallocates plugin-allocated memory

Memory Management

The utils module provides safe wrappers for memory management:

• return_success: Return a success result
• return_error: Return an error result
• standard_free_string: Standard deallocation function

Thread Safety

The execute_tool function will be called concurrently from multiple threads. Implementations must be thread-safe.

Re-exports

pub use tool::ParamType;

pub use tool::Tool;

pub use tool::ToolBuilder;

pub use tool::ToolHandler;

pub use tool::ToolParam;

pub use serde_json;

pub use once_cell;

Modules

tool

Type-safe tool definitions

utils

Memory management utilities for plugins

Macros

declare_config_schema

Declare configuration schema export with automatic generation

declare_plugin

Helper macro to declare a plugin with automatic version management

declare_plugin_config

Declare plugin configuration with automatic boilerplate generation

declare_plugin_init

Declare a plugin initialization function with automatic wrapper generation

declare_tools

Declare tools and auto-generate list_tools and execute_tool functions

Structs

PluginDeclaration

Plugin declaration exported by each plugin

Constants

API_VERSION

Current MCP Plugin API version (from Cargo.toml at compile time)

API_VERSION_CSTR

API version as a null-terminated C string (for PluginDeclaration)

Type Aliases

ConfigureFn

Function signature for plugin configuration

ExecuteToolFn

Function signature for executing a tool by name

FreeStringFn

Function signature for freeing memory allocated by the plugin

GetConfigSchemaFn

Function signature for getting plugin configuration schema

InitFn

Function signature for plugin initialization

ListToolsFn

Function signature for listing available tools