Template Smart MCP Agent

智能MCP代理模板

Mastra模板用于创建智能AI代理，这些代理可以在运行时动态发现、安装和使用MCP（模型上下文协议）服务器。此模板为构建代理提供了基础，这些代理可以通过MCP生态系统自动查找和集成外部服务。

🚀 特性

• 动态MCP服务器发现：在Smithery注册表中搜索可用的MCP服务器
• 自动服务器安装：将服务器动态添加到代理的配置中
• 持久配置：服务器被永久添加到代码库中
• 文件系统访问：用于项目文件操作的内置文件系统MCP服务器
• 内存管理：基于LibSQL的代理状态内存存储
• 类型安全：通过Zod模式验证完全支持TypeScript

🏗️ 项目结构

src/
├── mastra/
│   ├── agents/
│   │   └── smart-mcp-agent.ts      # Main AI agent with MCP capabilities
│   ├── tools/
│   │   ├── add-mcp-server.ts       # Dynamically add MCP servers to config
│   │   ├── discover-servers.ts     # Search Smithery registry for servers
│   │   └── list-servers.ts         # List currently configured servers
│   ├── index.ts                    # Mastra configuration
│   ├── mcp.ts                      # MCP client configuration
│   └── types.ts                    # TypeScript type definitions

🛠️ 安装

1. 克隆模板:

   npx create-mastra@latest template-smart-mcp-agent
   cd template-smart-mcp-agent

1. 安装依赖项:

   npm install

1. 设置环境变量:

   cp .env.example .env
   # Edit .env with your API keys

1. 启动开发服务器:

   npm run dev

🔧 配置

环境变量

代理配置

import { smartMcpAgent } from './src/mastra/agents/smart-mcp-agent';

// Agent is configured with:
// - OpenAI GPT-4o-mini model
// - LibSQL memory storage
// - Dynamic MCP server management

🔄 工作流程

智能MCP代理遵循以下工作流程：

1. 发现：使用 discover-servers 在Smithery上搜索MCP服务器
2. 安装：使用 add-mcp-server 将服务器动态添加到配置中
3. 验证：使用 list-servers 确认安装
4. 用法：通过代理访问服务器工具

示例用法

// Search for web search servers
await discoverServersTool.execute({
  context: { query: "web search", limit: 5 }
});

// Add a web search server
await addMcpServerTool.execute({
  context: {
    name: "websearch",
    serverId: "@Aas-ee/open-websearch",
    description: "Web search capabilities"
  }
});

// List configured servers
await listServersTool.execute({ context: {} });

🛠️ 工具

添加MCP服务器工具

将MCP服务器动态添加到 mcp.ts 配置文件。

输入架构:

{
  name: z.string().min(1),           // Server name (e.g., "websearch")
  serverId: z.string().min(1),       // Full server ID (e.g., "@Aas-ee/open-websearch")
  description: z.string().optional() // Optional description
}

特性:

• 自动将服务器名称转换为有效的JavaScript标识符
• 更新 mcp.ts 配置正确的文件
• 触发服务器自动重启以加载新服务器
• 提供明确的反馈和下一步行动

发现服务器工具

在Smithery注册表中搜索可用的MCP服务器。

输入架构:

{
  query: z.string(),                 // Search query
  limit: z.number().int().min(1).max(20).optional() // Result limit
}

特性:

• 使用可选的API密钥搜索Smithery注册表
• 返回服务器详细信息，包括名称、描述和使用统计信息
• API不可用时的优雅回退

列表服务器工具

列出当前配置的所有MCP服务器。

特性:

• 读取当前 mcp.ts 配置
• 标识服务器类型（Smithery、文件系统等）
• 显示服务器ID和配置详细信息
• 提供清晰的状态信息

🔄 服务器管理

添加服务器

当您使用添加服务器时 add-mcp-server:

1. 配置更新：服务器已添加到 src/mastra/mcp.ts
2. 自动重新启动：Mastra服务器重新启动以加载新服务器
3. 持久性：服务器配置在重新启动后仍然存在
4. 验证：使用 list-servers 确认添加成功

服务器类型

• Smithery服务器：Smithery上托管的远程MCP服务器
• 文件系统服务器：项目文件的本地文件系统访问
• 自定义服务器：任何与MCP兼容的服务器

当前配置

该模板附带了这些预配置的服务器：

• 文本编辑器：项目文件的文件系统访问权限
• 极客新闻：技术新闻和更新
• 标识：人工智能每日新闻和见解

🛡️ 错误处理

该模板包括全面的错误处理：

• MCP连接故障：妥善处理服务器连接问题
• 文件系统错误：带有正确错误消息的安全文件操作
• API速率限制：外部API调用的内置重试逻辑
• 验证错误：Zod模式验证，并显示明确的错误消息

🚀 发展

可用脚本

• npm run dev -使用热重新加载启动开发服务器
• npm run build -为生产而建
• npm run start -启动生产服务器

开发工作流程

1. 启动开发服务器: npm run dev
2. 进入游乐场: http://localhost:4111
3. 测试代理交互：使用操场与代理人互动
4. 添加新服务器：使用代理发现和添加MCP服务器
5. 监控日志：检查终端输出的服务器状态和错误

📝 api参考

代理

这 smartMcpAgent 提供：

• 模型：OpenAI GPT-4o-mini
• 记忆：基于LibSQL的持久存储
• 工具：动态MCP服务器管理工具
• 说明：全面的工作流程指导

MCP客户端

MCP客户端(buildMcp)管理：

• 服务器连接：自动连接到已配置的服务器
• 工具发现：从MCP服务器动态加载工具
• 错误恢复：妥善处理连接问题
• 心跳管理：自动连接维护

🤝 贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

📄 许可证

ISC许可证-有关详细信息，请参阅许可证文件。

🔗 资源

• Mastra文档
• MCP协议
• Smithery登记处
• OpenAI API