Sira AI

主题

自定义MCP工具开发 ​

为企业特殊需求开发专属的MCP工具，让AI助手拥有企业独有的能力。

开发概述 ​

为什么需要自定义工具 ​

当内置工具无法满足企业特殊需求时，可以开发专属的MCP工具：

🏢 企业系统集成

连接企业内部的ERP、CRM、OA等系统

如：用友、金蝶、钉钉等

📊 专业数据处理

处理行业特定的数据格式和业务逻辑

如：金融风控、医疗诊断等

🔧 定制化功能

实现企业独有的业务流程自动化

如：审批流程、报表生成等

🔒 安全合规要求

满足特殊的安全和合规要求

如：内网部署、数据不出网等

开发方式选择 ​

开发方式难度适用场景开发周期
配置式⭐ 简单API接口对接1-3天
模板式⭐⭐ 中等常见业务场景1-2周
自研式⭐⭐⭐ 复杂完全定制需求2-4周

配置式开发（推荐） ​

适用场景 ​

已有HTTP API接口，只需要配置对接参数即可：

示例场景：

  • 查询客户信息（CRM系统）
  • 获取库存数据（ERP系统）
  • 发送通知消息（内部系统）

开发步骤 ​

第一步：创建工具 ​

  1. 进入开发界面

    • 点击左侧菜单「MCP工具」
    • 点击「创建自定义工具」
    • 选择「配置式开发」

  2. 基本信息配置

    • 工具名称：如"客户信息查询"
    • 工具描述：清楚说明工具功能
    • 工具图标：选择合适的图标
    • 权限级别：设置使用权限

第二步：API配置 ​

  1. 接口信息

  2. 参数配置

    • 输入参数：客户名称、客户ID等
    • 输出格式：JSON结构映射
    • 错误处理：异常情况处理

第三步：测试验证 ​

  1. 功能测试

    • 输入测试参数
    • 检查API调用结果
    • 验证数据格式正确

  2. 集成测试

    • 绑定到测试助手
    • 进行对话测试
    • 确认AI能正确使用工具

配置示例 ​

客户信息查询工具 ​

基本配置：

工具名称: 客户信息查询
描述: 根据客户名称或ID查询客户详细信息
输入参数: 客户标识（名称或ID）
权限要求: 销售部门及以上

API配置：

请求地址: https://crm.company.com/api/customer/query
请求方法: POST
认证方式: API密钥
请求格式: {
  "query": "{客户标识}",
  "fields": ["name", "phone", "email", "status"]
}
响应处理: 提取客户基本信息并格式化显示

使用效果：

用户：查询客户"ABC公司"的信息
助手：正在查询ABC公司的客户信息...

客户信息查询结果：
📋 客户名称：ABC科技有限公司
📞 联系电话：010-12345678  
📧 邮箱地址：contact@abc.com
👤 负责销售：张经理
💰 客户状态：重要客户
📅 创建时间：2023-08-15

模板式开发 ​

内置模板库 ​

系统提供常见业务场景的开发模板：

数据库查询模板 ​

适用场景：查询企业内部数据库信息

配置项：

  • 数据库连接信息
  • SQL查询语句模板
  • 结果格式化规则
  • 权限控制设置

使用示例：员工信息查询、产品库存查询、订单状态查询

文件处理模板 ​

适用场景：处理企业内部文档

功能包含：

  • 文件上传下载
  • 格式转换
  • 内容提取
  • 批量处理

使用示例：合同解析、报表生成、文档归档

流程审批模板 ​

适用场景：企业审批流程自动化

功能包含：

  • 发起审批申请
  • 查询审批状态
  • 自动催办
  • 结果通知

使用示例：请假申请、采购审批、费用报销

模板开发步骤 ​

  1. 选择模板

    • 浏览模板库
    • 选择最匹配的业务模板
    • 了解模板功能和配置项

  2. 参数配置

    • 填写业务相关参数
    • 配置接口连接信息
    • 设置数据映射关系

  3. 功能定制

    • 调整业务逻辑
    • 修改输出格式
    • 增加特殊处理规则

  4. 测试部署

    • 完整功能测试
    • 性能压力测试
    • 部署到生产环境

自研式开发（高级） ​

开发环境要求 ​

技术栈：

  • Python 3.8+ 或 Node.js 16+
  • MCP SDK开发包
  • 企业内网开发环境

开发工具：

  • Visual Studio Code
  • MCP开发插件
  • API测试工具（Postman）

开发框架 ​

Python示例 ​

python
# 企业内部工具示例（伪代码展示概念）
from mcp_sdk import MCPTool, Parameter, Response

class CustomerQueryTool(MCPTool):
    """客户信息查询工具"""
    
    name = "customer_query"
    description = "查询客户详细信息"
    
    parameters = [
        Parameter("customer_id", "string", "客户ID或名称"),
        Parameter("fields", "array", "需要查询的字段", optional=True)
    ]
    
    async def execute(self, customer_id: str, fields: list = None):
        # 调用企业CRM API
        customer_data = await self.call_crm_api(customer_id)
        
        if not customer_data:
            return Response.error("未找到客户信息")
        
        # 格式化结果
        result = self.format_customer_info(customer_data, fields)
        return Response.success(result)
    
    async def call_crm_api(self, customer_id: str):
        """调用企业CRM系统API"""
        # 实际的API调用逻辑
        pass
    
    def format_customer_info(self, data: dict, fields: list):
        """格式化客户信息"""
        # 数据格式化逻辑
        pass

关键开发要点 ​

  1. 工具定义

    • 清晰的工具名称和描述
    • 明确的参数定义
    • 完善的错误处理

  2. API集成

    • 安全的认证机制
    • 稳定的网络连接
    • 合理的超时设置

  3. 数据处理

    • 结构化的数据输出
    • 用户友好的格式化
    • 错误情况的优雅处理

部署配置 ​

  1. 服务部署

    • 容器化部署（Docker）
    • 内网服务注册
    • 健康检查配置

  2. 注册工具

    • 在系统中注册新工具
    • 配置访问权限
    • 设置使用限制

  3. 监控维护

    • 性能指标监控
    • 错误日志收集
    • 定期维护更新

工具管理 ​

版本控制 ​

版本管理：

  • 开发版本：内部测试使用
  • 测试版本：小范围验证
  • 生产版本：正式发布使用

升级策略：

  • 向后兼容原则
  • 灰度发布流程
  • 回滚应急预案

权限管理 ​

使用权限：

  • 按部门分配工具使用权限
  • 按角色设置功能访问级别
  • 按用户控制调用频率

管理权限：

  • 工具配置权限
  • 数据访问权限
  • 系统集成权限

监控统计 ​

使用统计：

  • 工具调用次数
  • 成功失败比例
  • 响应时间分析
  • 用户使用分布

性能监控：

  • 服务运行状态
  • 资源使用情况
  • 异常告警处理

最佳实践 ​

设计原则 ​

  1. 单一职责

    • 每个工具专注解决一类问题
    • 功能边界清晰明确
    • 避免功能重复

  2. 用户友好

    • 直观的工具名称
    • 清楚的功能描述
    • 友好的错误提示

  3. 安全可靠

    • 严格的权限控制
    • 完善的错误处理
    • 详细的操作日志

开发建议 ​

接口设计：

  • 遵循RESTful规范
  • 使用标准HTTP状态码
  • 提供详细的错误信息

数据处理：

  • 输入参数验证
  • 输出格式统一
  • 异常情况处理

性能优化：

  • 合理的超时设置
  • 结果缓存机制
  • 批量处理支持

测试策略 ​

单元测试：

  • 工具功能测试
  • 边界条件测试
  • 异常情况测试

集成测试：

  • 与AI助手集成测试
  • 多工具协作测试
  • 端到端流程测试

性能测试：

  • 并发访问测试
  • 大数据量处理测试
  • 长时间运行稳定性测试

常见问题 ​

Q: 开发工具需要什么技术基础？ A: 配置式开发无需编程基础，模板式需要基本配置能力，自研式需要Python或Node.js开发经验。

Q: 工具开发周期一般多长？ A: 配置式1-3天，模板式1-2周，自研式2-4周，具体取决于复杂度和需求变更。

Q: 工具安全如何保障？ A: 托管 MCP 支持 API 密钥（api_key）、Bearer 令牌、基础认证（basic）三种认证方式，数据传输加密，权限细分控制，操作日志审计。OAuth 2.0 / 个人身份绑定的 MCP（如 Notion、GitHub）走员工本地 sandrpod 授权，平台不托管用户 token。此外可逐工具开启「用户上下文透传（passUserContext）」，向 MCP Server 透传 X-Sira-* 头用于 ACL / 审计（默认关）。

Q: 工具出现问题如何调试？ A: 提供详细的调试日志，支持单步调试，有完整的错误信息和解决建议。

Q: 工具维护更新如何进行？ A: 支持热更新，版本管理，回滚机制，以及详细的变更记录。

技术支持 ​

开发资源 ​

文档资料：

  • MCP协议规范
  • SDK使用指南
  • 最佳实践案例
  • 常见问题解答

示例代码：

  • 各种场景的示例工具
  • 完整的项目模板
  • 调试和测试代码

开发工具：

  • MCP开发SDK
  • 调试测试工具
  • 部署运维脚本

技术咨询 ​

获取帮助：

  • 在线技术文档
  • 开发者社区论坛
  • 专业技术支持团队

培训服务：

  • 工具开发培训
  • 最佳实践分享
  • 技术交流会议

下一步 ​

了解自定义工具开发后，您可以：

Apache-2.0 Licensed

Copyright © 2024 Sira AI Inc.