AI降临派 MCP 协议补充文档

Version 1.0
Last Updated: 2025-01-22

1. 概述

1.1 MCP简介

MCP (Model Control Protocol) 是AI降临派TCP协议的扩展功能，允许客户端向服务器注册自定义服务，实现服务器主动调用客户端功能的能力。

1.2 主要特性

服务注册: 客户端可以注册多个自定义服务

双向调用: 服务器可以主动调用客户端服务

异步处理: 支持异步服务调用和响应

标准化接口: 使用JSON Schema定义服务接口

1.3 应用场景

本地文件操作

系统信息查询

设备控制接口

自定义业务逻辑

2. MCP消息类型

2.1 消息类型定义

MCP使用消息类型 \x06 进行通信：

MCP : b'\x06'  # MCP协议消息

2.2 消息结构

MCP消息遵循标准TCP协议格式：

##START\x06[任务ID][序列号][JSON数据]##END

2.3 任务ID规范

MCP消息建议使用固定任务ID: mcp00001

长度固定8字节，不足部分用空格填充

可根据需要使用其他8字节标识符

3. 服务注册机制

3.1 注册时机

客户端可在认证成功后注册MCP服务，也可随时根据端侧的情况发生变化而重新注册。

3.2 注册消息格式

{
    "type": "register",
    "data": {
        "services": {
            "服务名称": {
                "description": "服务描述",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "参数名": {
                            "type": "数据类型",
                            "description": "参数描述",
                            "enum": ["可选值列表"] // 可选
                        }
                    },
                    "required": ["必需参数列表"]
                }
            }
        }
    }
}

3.3 服务定义示例

{
    "type": "register",
    "data": {
        "services": {
            "get_current_time": {
                "description": "获取当前时间信息，包括日期和时间",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "format": {
                            "type": "string",
                            "enum": ["simple", "detailed"],
                            "description": "时间格式，simple为简单格式，detailed为详细格式"
                        }
                    }
                }
            },
            "create_file": {
                "description": "在本地创建文件并写入内容",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "filename": {
                            "type": "string", 
                            "description": "文件名"
                        },
                        "content": {
                            "type": "string", 
                            "description": "文件内容"
                        }
                    },
                    "required": ["filename", "content"]
                }
            }
        }
    }
}

4. 服务调用流程

4.1 调用发起

服务器根据用户请求判断需要调用客户端服务时，会发送调用消息。

4.2 调用消息格式

{
    "type": "call",
    "data": {
        "call_id": "唯一调用标识符",
        "method": "服务名称",
        "params": {
            "参数名": "参数值"
        }
    }
}

4.3 响应消息格式

客户端执行服务后，需要返回执行结果：

{
    "type": "result",
    "data": {
        "call_id": "对应的调用标识符",
        "result": {
            "success": true/false,
            "data": "返回数据",
            "error": "错误信息（仅失败时）"
        }
    }
}

4.4 调用流程图

1. 用户发送请求到服务器
2. 服务器解析请求，判断需要调用客户端服务
3. 服务器发送MCP调用消息到客户端
4. 客户端接收调用消息，执行对应服务
5. 客户端返回执行结果
6. 服务器根据结果生成响应给用户

5. 数据格式规范

5.1 JSON Schema规范

服务定义必须遵循JSON Schema规范：

5.1.1 基础数据类型

string: 字符串类型

number: 数字类型

integer: 整数类型

boolean: 布尔类型

array: 数组类型

object: 对象类型

5.1.2 参数约束

required: 必需参数列表

enum: 枚举值限制

minimum/maximum: 数值范围限制

minLength/maxLength: 字符串长度限制

5.2 返回值格式

所有服务必须返回统一格式的结果：

{
    "success": true,        // 执行是否成功
    "data": "具体返回数据",   // 成功时的数据
    "error": "错误描述"      // 失败时的错误信息
}

5.3 编码规范

所有JSON数据使用UTF-8编码

中文字符正常传输，无需特殊处理

确保JSON格式正确，避免语法错误

6. 错误处理

6.1 服务注册错误

重复注册相同服务名称

JSON格式错误

服务定义不符合规范

6.2 服务调用错误

调用不存在的服务

参数类型不匹配

必需参数缺失

服务执行异常

6.3 错误响应格式

{
    "type": "result",
    "data": {
        "call_id": "调用标识符",
        "result": {
            "success": false,
            "error": "详细错误信息"
        }
    }
}

7. 示例实现

7.1 完整MCP通信示例

# 1. 客户端注册服务
C -> S: ##START\x06mcp00001[0000]{
    "type": "register",
    "data": {
        "services": {
            "get_current_time": {
                "description": "获取当前时间",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "format": {
                            "type": "string",
                            "enum": ["simple", "detailed"]
                        }
                    }
                }
            }
        }
    }
}##END

# 2. 用户请求时间
C -> S: ##START\x04task12340000现在几点了？##END
C -> S: ##START\x03task12340001##END

# 3. 服务器调用客户端服务
S -> C: ##START\x06mcp00001[0000]{
    "type": "call",
    "data": {
        "call_id": "call_001",
        "method": "get_current_time",
        "params": {
            "format": "simple"
        }
    }
}##END

# 4. 客户端返回结果
C -> S: ##START\x06mcp00001[0000]{
    "type": "result",
    "data": {
        "call_id": "call_001",
        "result": {
            "success": true,
            "data": "2025-01-22 14:30:25"
        }
    }
}##END

# 5. 服务器响应用户
S -> C: ##START\x04task12340000现在是2025年1月22日14点30分25秒##END
S -> C: ##START\x03task12340001##END

7.2 Python实现示例

7.2.1 服务注册

7.2.2 服务调用处理

7.2.3 结果返回

8. 最佳实践

8.1 服务设计原则

单一职责: 每个服务只负责一个具体功能

参数验证: 严格验证输入参数的类型和范围

错误处理: 提供详细的错误信息和异常处理

性能考虑: 避免长时间阻塞的操作

8.2 实现建议

及时注册: 在认证成功后立即注册服务

唯一标识: 确保call_id的唯一性和正确对应

异常安全: 所有服务调用都应该有异常处理

日志记录: 记录服务调用的关键信息便于调试

8.3 测试验证

功能测试: 验证每个服务的基本功能

参数测试: 测试各种参数组合和边界情况

错误测试: 验证错误处理的正确性

性能测试: 确保服务响应时间在可接受范围内

8.4 安全考虑

参数过滤: 对输入参数进行安全性检查

权限控制: 限制敏感操作的执行权限

数据验证: 验证数据的合法性和完整性

资源限制: 防止资源滥用和内存泄漏

注意事项:

MCP功能需要服务器端支持，请确认服务器版本

建议在开发环境中充分测试MCP服务的稳定性

生产环境使用时注意服务的安全性和性能影响

MCP协议接入

AI降临派 MCP 协议补充文档#

目录#

1. 概述#

1.1 MCP简介#

1.2 主要特性#

1.3 应用场景#

2. MCP消息类型#

2.1 消息类型定义#

2.2 消息结构#

2.3 任务ID规范#

3. 服务注册机制#

3.1 注册时机#

3.2 注册消息格式#

3.3 服务定义示例#

4. 服务调用流程#

4.1 调用发起#

4.2 调用消息格式#

4.3 响应消息格式#

4.4 调用流程图#

5. 数据格式规范#

5.1 JSON Schema规范#

5.1.1 基础数据类型#

5.1.2 参数约束#

5.2 返回值格式#

5.3 编码规范#

6. 错误处理#

6.1 服务注册错误#

6.2 服务调用错误#

6.3 错误响应格式#

7. 示例实现#

7.1 完整MCP通信示例#

7.2 Python实现示例#

7.2.1 服务注册#

7.2.2 服务调用处理#

7.2.3 结果返回#

8. 最佳实践#

8.1 服务设计原则#

8.2 实现建议#

8.3 测试验证#

8.4 安全考虑#