嵌入式MCP服务器

Name: 嵌入式MCP服务器
Author: AaronWander

作者：AaronWander10 星标更新：2025-09-10

安装使用来源：spider==github.com

项目介绍

EmbedMCP - 嵌入式MCP服务器库

一个轻量级的C库，用于创建MCP（模型上下文协议）服务器，可以将现有的C函数转换为AI可访问的工具，并且只需进行少量代码更改。

English • 简体中文

为什么选择EmbedMCP？

EmbedMCP弥合了现有C代码库与现代AI系统之间的差距。无需重写经过验证的C函数，EmbedMCP允许您通过标准化的模型上下文协议（MCP）以最小的代码更改将其暴露给AI模型。

主要特性

🚀 简单集成：复制一个文件夹，包含一个头文件
⚡ 高性能：直接调用C函数，开销极小
🔧 跨平台：通过通用HAL在15个以上平台上运行
📦 零依赖：自包含库，无外部需求
🎯 两种注册方法：简单函数的魔法宏，复杂函数的完全控制
🌐 多种传输方式：支持流式HTTP和STDIO，适用于不同场景
🧠 智能内存管理：自动清理，明确所有权规则
📊 数组支持：处理简单参数和复杂数据结构

快速开始

安装

下载EmbedMCP

git clone https://github.com/AaronWander/EmbedMCP.git
cd EmbedMCP

复制到您的项目
```
cp -r embed_mcp/ your_project/
```

基本用法

#include "embed_mcp/embed_mcp.h"

// 您的业务函数
double add_numbers(double a, double b) {
    return a + b;
}

// 使用宏生成包装器
EMBED_MCP_WRAPPER(add_wrapper, add_numbers, DOUBLE, DOUBLE, a, DOUBLE, b)

int main() {
    embed_mcp_config_t config = {
        .name = "MathServer",
        .version = "1.0.0",
        .instructions = "简单的数学运算服务器",
        .port = 8080
    };

    embed_mcp_server_t *server = embed_mcp_create(&config);

    // 注册函数
    const char* names[] = {"a", "b"};
    const char* descs[] = {"第一个数字", "第二个数字"};
    mcp_param_type_t types[] = {MCP_PARAM_DOUBLE, MCP_PARAM_DOUBLE};

    embed_mcp_add_tool(server, "add", "加两个数",
                       names, descs, types, 2, MCP_RETURN_DOUBLE, add_wrapper, NULL);

    embed_mcp_run(server, EMBED_MCP_TRANSPORT_STREAMABLE_HTTP);
    embed_mcp_destroy(server);
    return 0;
}

构建和运行

# 构建
make

# 运行流式HTTP服务器
./bin/mcp_server --transport streamable-http --port 8080

# 或运行STDIO服务器
./bin/mcp_server --transport stdio

函数注册

EmbedMCP支持两种注册方法：

简单函数（推荐）

// 业务函数
double add_numbers(double a, double b) {
    return a + b;
}

// 一行生成包装器
EMBED_MCP_WRAPPER(add_wrapper, add_numbers, DOUBLE, DOUBLE, a, DOUBLE, b)

// 注册
const char* names[] = {"a", "b"};
const char* descs[] = {"第一个数字", "第二个数字"};
mcp_param_type_t types[] = {MCP_PARAM_DOUBLE, MCP_PARAM_DOUBLE};

embed_mcp_add_tool(server, "add", "加两个数",
                   names, descs, types, 2, MCP_RETURN_DOUBLE, add_wrapper, NULL);

数组函数（高级）

// 业务函数
double sum_numbers(double* numbers, size_t count) {
    double sum = 0.0;
    for (size_t i = 0; i < count; i++) {
        sum += numbers[i];
    }
    return sum;
}

// 手动包装器（处理内存管理）
void* sum_wrapper(mcp_param_accessor_t* params, void* user_data) {
    size_t count;
    double* numbers = params->get_double_array(params, "numbers", &count);

    double result_val = sum_numbers(numbers, count);
    free(numbers); // 清理

    double* result = malloc(sizeof(double));
    *result = result_val;
    return result;
}

// 注册带有数组参数
mcp_param_desc_t params[] = {
    MCP_PARAM_ARRAY_DOUBLE_DEF("numbers", "数字数组", "一个数值", 1)
};

embed_mcp_add_tool(server, "sum", "求和", params, NULL, NULL, 1,
                   MCP_RETURN_DOUBLE, sum_wrapper, NULL);

内存管理

EmbedMCP自动处理大部分内存管理：

参数：所有输入参数在您的函数返回后自动释放
JSON处理：请求/响应解析和清理由内部处理
数组：动态数组自动分配和释放
错误处理：即使发生错误，内存也会被正确清理

您的责任：字符串返回值必须使用malloc()：

char* get_weather(const char* city) {
    char* result = malloc(200);  // ✅ EmbedMCP会调用free()
    sprintf(result, "天气：%s：晴朗", city);
    return result;
}

服务器模式

流式HTTP传输（示例）

./my_server --transport streamable-http --port 8080

支持多个并发客户端
会话管理通过Mcp-Session-Id头部
协议版本协商通过Mcp-Protocol-Version头部
Web应用程序后端
开发和测试

STDIO传输

适用于如Claude Desktop的MCP客户端：

./my_server --transport stdio

Claude Desktop集成
AI助手工具
命令行工作流程
单客户端通信

🔧 参数定义宏

强大的宏用于复杂的参数定义

📊 数组参数

// 双精度数组
MCP_PARAM_ARRAY_DOUBLE_DEF(
    "numbers",
    "数字数组",
    "一个数值",
    1  // 必需
)

// 字符串数组
MCP_PARAM_ARRAY_STRING_DEF(
    "items",
    "项目列表",
    "一个项目名称",
    1  // 必需
)

</td> <td width="50%">

🎯 简单参数

// 双精度参数
MCP_PARAM_DOUBLE_DEF(
    "temperature",
    "摄氏温度",
    1  // 必需
)

// 字符串参数
MCP_PARAM_STRING_DEF(
    "city",
    "城市名称",
    0  // 可选
)

</td> </tr> </table>

示例服务器

包含的示例演示了所有EmbedMCP功能：

# 构建并运行示例
make && ./bin/mcp_server --transport stdio

可用的Demo工具

工具	参数	描述	示例
`add`	`a: number, b: number`	加两个数	`add(10, 20)` → `30`
`sum_numbers`	`numbers: number[]`	求数组的和	`sum_numbers([1,2,3])` → `6`
`join_strings`	`strings: string[], separator: string`	连接字符串数组	`join_strings(["a","b"], ",")` → `"a,b"`
`weather`	`city: string`	获取天气信息	`weather("济南")` → 天气报告
`calculate_score`	`base_points: int, grade: string, multiplier: number`	计算带奖励的分数	`calculate_score(80, "A", 1.2)` → `120`

使用MCP Inspector测试

启动服务器：./bin/mcp_server --transport streamable-http --port 8080
打开MCP Inspector
连接到：http://localhost:8080/mcp
测试可用工具

平台支持

EmbedMCP设计用于嵌入式系统的最大可移植性：

嵌入式系统

RTOS：FreeRTOS, Zephyr, ThreadX, embOS
MCUs：STM32, ESP32, Nordic nRF系列
SBCs：Raspberry Pi, BeagleBone, Orange Pi

要求

最低：C99编译器，64KB RAM，100KB闪存
推荐：对于复杂应用，512KB RAM
依赖：无（自包含）

使用案例

工业物联网

传感器数据处理：将C传感器驱动程序暴露给AI模型
设备监控：实时分析机器数据
预测维护：AI驱动的故障预测

嵌入式AI

边缘计算：在嵌入式设备上运行AI推理
智能设备：语音助手，智能摄像头，IoT中心
机器人：AI控制的机器人系统

故障排除

常见问题

构建错误：

# 缺少依赖项
make deps

# 清洁构建
make clean && make

运行时错误：

# 启用调试日志
./bin/mcp_server --transport stdio --debug

# 检查内存使用情况
valgrind ./bin/mcp_server --transport stdio

连接问题：

确保正确的传输模式（流式HTTP vs STDIO）
检查流式HTTP模式下的防火墙设置
验证MCP客户端配置和协议版本头部

贡献

我们欢迎贡献！请参阅我们的贡献指南：

分叉仓库
创建功能分支 (git checkout -b feature/amazing-feature)
提交您的更改 (git commit -m '添加惊人的功能')
测试多个平台
推送到分支 (git push origin feature/amazing-feature)
打开拉取请求

开发环境设置

# 克隆仓库
git clone https://github.com/AaronWander/EmbedMCP.git
cd EmbedMCP

# 构建调试版本
make debug

# 运行测试
make test

许可证

此项目采用MIT许可证 - 详情请参阅LICENSE文件。

支持

问题：GitHub Issues
讨论：GitHub Discussions