Used as the runtime environment for the MCP server, enabling fast JavaScript execution for the tools
Supported as a command-line tool for testing MCP tool endpoints and functionality
Serves as the web framework for the MCP server to handle HTTP requests and responses
Used for version control and distribution of the MCP server codebase
Recommended as a testing tool for making API requests to the MCP server endpoints
Provides type safety for developing MCP tools with interface definitions and type checking
Provides notification capabilities to send alerts with titles and descriptions to WeChat users
Implements schema validation for tool parameters, ensuring proper data types and formats
MCP 工具开发脚手架
这是一个用于开发 Model Context Protocol (MCP) 工具的脚手架项目,基于 Bun 运行时和 Express 框架构建。本项目提供了基础架构和示例工具,帮助开发者快速开始构建自己的 MCP 工具。
什么是 MCP?
Model Context Protocol (MCP) 是一种允许 AI 模型调用外部工具和服务的协议。通过 MCP,AI 可以执行各种操作,如发送邮件、推送通知、查询数据库等,从而扩展其能力范围。
脚手架特点
- 完整的 MCP 服务器实现,支持流式响应
- 基于 API 密钥的身份验证机制
- 工具注册和管理系统
- 包含 3 个示例工具(回显、邮件发送、微信通知)供参考
快速开始
环境要求
- Bun 1.0.0 或更高版本
安装
运行
服务器将在指定端口上启动(默认为 3000)。
MCP 工具开发指南
本脚手架的主要目的是帮助开发者快速开始构建自己的 MCP 工具。以下是开发自定义 MCP 工具的完整指南。
MCP 工具的基本结构
一个 MCP 工具通常包含以下组件:
- 参数模式(Schema):定义工具接受的参数及其验证规则
- 实现逻辑:执行工具功能的代码
- 响应格式化:将工具执行结果格式化为 MCP 兼容的响应
开发自定义 MCP 工具的步骤
1. 创建工具定义文件
在 src/tools/
目录下创建一个新文件,例如 src/tools/my-tool.ts
:
2. 在工具注册器中注册您的工具
修改 src/services/tools-registry.ts
文件,导入并注册您的新工具:
MCP 工具开发最佳实践
工具设计原则
- 单一职责:每个工具应专注于完成一个特定任务
- 简单明了:工具名称和描述应清晰表达其功能
- 可组合性:工具应易于与其他工具组合使用
- 错误处理:妥善处理所有可能的错误情况
- 安全性:不暴露敏感信息,谨慎处理认证凭据
参数验证
- 使用 Zod 库定义严格的参数 schema
- 对所有必填参数进行类型和值的验证
- 为验证错误提供明确的错误消息
- 考虑参数的边界条件和特殊情况
错误处理
- 使用 try/catch 块捕获所有可能的错误
- 区分不同类型的错误(验证错误、API 错误、网络错误等)
- 记录详细的错误信息以便调试
- 向用户返回有帮助的错误消息
日志记录
- 记录工具的调用信息和参数(注意不要记录敏感数据)
- 使用不同的日志级别(info、warning、error)
- 在生产环境中控制日志的详细程度
- 记录响应时间和性能指标
响应格式化
- 使用一致的响应格式
- 提供结构化和易于理解的结果
- 对于复杂数据,考虑如何最好地呈现给AI和用户
- 明确区分成功和错误响应
高级开发技巧
1. 工具链式调用
设计工具时考虑它们如何协同工作,一个工具的输出可以作为另一个工具的输入。
2. 上下文共享
通过请求对象传递上下文信息(如API密钥、用户信息等)。
3. 流式响应
对于长时间运行的操作,考虑使用流式响应提供进度更新。
4. 缓存策略
对频繁请求的数据实现缓存,提高性能并减少外部API调用。
5. 超时和重试逻辑
对外部API调用实现超时和重试逻辑,提高可靠性。
示例工具参考
本脚手架包含三个示例工具,您可以参考它们的实现来开发自己的工具:
1. Echo 工具 (简单示例)
一个简单的回显工具,接收消息并返回相同的消息。
2. 发送电子邮件工具 (API调用示例)
展示如何调用外部API发送电子邮件的示例。
3. 微信通知工具 (错误处理示例)
展示如何处理外部API响应和错误情况的示例。
测试您的工具
使用 cURL 或 Postman 向 /mcp
端点发送请求来测试您的工具:
贡献指南
我们欢迎您为这个MCP工具开发脚手架做出贡献!请参考以下步骤:
- Fork 本仓库
- 创建您的特性分支 (
git checkout -b feature/amazing-feature
) - 提交您的更改 (
git commit -m 'Add some amazing feature'
) - 推送到分支 (
git push origin feature/amazing-feature
) - 打开一个 Pull Request
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A TypeScript scaffold for building Model Context Protocol (MCP) tools that let AI models call external services like sending emails or notifications.
Related MCP Servers
- AsecurityFlicenseAqualityA template for creating Model Context Protocol (MCP) servers in TypeScript, offering features like container-based dependency injection, a service-based architecture, and integration with the LLM CLI for architectural design feedback through natural language.Last updated -196TypeScript
- -securityFlicense-qualityImplements the Model Context Protocol (MCP) to provide AI models with a standardized interface for connecting to external data sources and tools like file systems, databases, or APIs.Last updated -123Python
- -securityAlicense-qualityA TypeScript implementation of a Model Context Protocol server that provides a frictionless framework for developers to build and deploy AI tools and prompts, focusing on developer experience with zero boilerplate and automatic tool registration.Last updated -54412TypeScriptMIT License
- -securityFlicense-qualityA TypeScript framework for building Model Context Protocol (MCP) servers with automatic discovery and loading of tools, resources, and prompts.Last updated -0TypeScript