hypermcp - 可重用的MCP服务器基础设施
hypermcp 这是一个可重用的包，为构建模型上下文协议（MCP）服务器提供了通用基础设施。它处理了所有模板代码，使您能够专注于实现自定义工具和资源。
特点/特性
- ✅ MCP服务器设置及生命周期管理
- ✅ 带日志记录功能的HTTP客户端
- ✅ 缓存层（可选择禁用）
- ✅ 传输抽象（stdio，未来：可流式HTTP）
- ✅ 使用 zap 进行结构化日志记录
- ✅ 用于注册工具和资源的辅助方法
- ✅ 自动统计追踪
快速入门
1. 创建一个新的MCP服务器
package main
import (
"context"
"github.com/rayprogramming/hypermcp"
"github.com/rayprogramming/hypermcp/cache"
"go.uber.org/zap"
)
func main() {
// Setup logger
logger, _ := zap.NewProduction()
defer logger.Sync()
// Configure server
cfg := hypermcp.Config{
Name: "my-mcp-server",
Version: "1.0.0",
CacheEnabled: true,
CacheConfig: cache.Config{
MaxCost: 100 * 1024 * 1024, // 100MB
NumCounters: 10_000,
BufferItems: 64,
},
}
// Create base server
srv, err := hypermcp.New(cfg, logger)
if err != nil {
logger.Fatal("failed to create server", zap.Error(err))
}
// Register your tools and resources
registerFeatures(srv)
// Log registration stats
srv.LogRegistrationStats()
// Run with stdio transport
ctx := context.Background()
if err := hypermcp.RunWithTransport(ctx, srv, hypermcp.TransportStdio, logger); err != nil {
logger.Fatal("server failed", zap.Error(err))
}
}2. 实现您的服务提供者
创建使用共享基础设施的提供者：
package providers
import (
"context"
"github.com/modelcontextprotocol/go-sdk/mcp"
"github.com/rayprogramming/hypermcp"
"github.com/rayprogramming/hypermcp/cache"
"github.com/rayprogramming/hypermcp/httpx"
"go.uber.org/zap"
)
type MyProvider struct {
httpClient *httpx.Client
cache *cache.Cache
logger *zap.Logger
}
func NewMyProvider(srv *hypermcp.Server) *MyProvider {
return &MyProvider{
httpClient: srv.HTTPClient(),
cache: srv.Cache(),
logger: srv.Logger(),
}
}
func (p *MyProvider) MyTool(
ctx context.Context,
req *mcp.CallToolRequest,
input MyToolInput,
) (*mcp.CallToolResult, MyToolOutput, error) {
// Your implementation here
// Use p.httpClient, p.cache, p.logger as needed
}3. 注册您的功能
func registerFeatures(srv *hypermcp.Server) {
// Create providers
myProvider := providers.NewMyProvider(srv)
// Register tools using the helper function
hypermcp.AddTool(
srv,
&mcp.Tool{
Name: "my_tool",
Description: "Does something cool",
},
myProvider.MyTool,
)
// Register resources using the helper method
srv.AddResource(
&mcp.Resource{
URI: "myresource://data",
Name: "My Resource",
Description: "Provides some data",
MIMEType: "application/json",
},
func(ctx context.Context, req *mcp.ReadResourceRequest) (*mcp.ReadResourceResult, error) {
// Your resource implementation
},
)
}API 参考
服务器创建
func New(cfg Config, logger *zap.Logger) (*Server, error)创建一个带有通用基础设施的新MCP服务器。
配置
type Config struct {
Name string // Server name
Version string // Server version
CacheEnabled bool // Enable caching
CacheConfig cache.Config // Cache configuration
}服务器方法
HTTPClient() *httpx.Client- 获取共享的HTTP客户端Cache() *cache.Cache- 获取缓存实例Logger() *zap.Logger- 获取日志记录器Metrics() *Metrics- 获取用于跟踪的指标实例GetMetrics() MetricsSnapshot- 获取当前指标的快照MCP() *mcp.Server- 获取底层的MCP服务器AddResource(resource, handler)- 注册一个资源（自动递增计数器）AddResourceTemplate(template, handler)- 注册资源模板（自动递增计数器）LogRegistrationStats()- 日志工具/资源计数Run(ctx, transport)- 启动服务器Shutdown(ctx)- 平滑关闭（关闭缓存，记录最终统计信息）
包级别函数
AddTool[In, Out](srv, tool, handler)- 注册一个工具（自动递增计数器）New(cfg, logger)- 创建一个新的服务器实例RunWithTransport(ctx, srv, transportType, logger)- 使用指定的传输方式启动服务器
交通
func RunWithTransport(ctx context.Context, srv *Server, transportType TransportType, logger *zap.Logger) error使用指定的传输方式启动服务器。
可用的交通工具：
TransportStdio- 标准输入/输出（推荐用于大多数使用场景）TransportStreamableHTTP- 可流式传输的HTTP（用于处理多个客户端连接的服务器，尚未实现）
运输类型
hypermcp 支持MCP规范推荐的传输方式：
标准I/O传输（推荐）
- 默认选择 对于大多数MCP服务器
- 客户端将服务器作为子进程启动
- 通过标准输入/输出进行通信
- 更简单的设置和部署
- 客户端应尽可能支持标准输入输出（根据MCP规范）
可流式传输的HTTP传输
- 对于处理多个并发客户端的服务器
- 基于HTTP，可选支持服务器发送事件（Server-Sent Events）
- 替换已弃用的HTTP+SSE传输方式
- 更复杂，但支持高级场景
- 注在此包中尚未实现
益处
为你
- 🚀 表情符号“🚀”在中文中通常被翻译为“火箭”或直接用该表情符号表示，因为它形象地代表了火箭升空的场景。在没有具体上下文的情况下，我们通常直接使用该表情符号或者简单地称之为“火箭”表情。所以，🚀 可以翻译为“火箭”或直接保留为“🚀”。 快速设置几分钟内启动服务器，而非数小时
- 🔧（扳手或修理工具的符号，常用于表示修理、维护或技术相关的意思） 关注特性把时间花在工具上，而不是模板代码上
- 📦 箱子/包裹 电池已包含HTTP客户端、缓存、日志均已配置完毕
- 🎯（目标/靶心） 最佳实践遵循MCP模式和Go惯用法
为了您的用户
- ⚡（闪电符号，常用于表示速度、活力、电或快速充电等含义） 演出内置缓存和连接池
- 📊 表格/数据图表 可观测性使用zap进行结构化日志记录
- 🛡️ 翻译为中文是“盾牌”。这个符号通常用来表示防御、保护或安全的概念。 可靠性适当的错误处理和优雅的关闭
示例
这个（或“它”） examples/ 目录中包含完整且可运行的示例：
你好 - 基本服务器
最小示例展示：
- 服务器配置与设置
- 简单的工具注册
- 优雅的关闭处理
天气 - 缓存演示
展示：
- 启用并使用缓存
- 缓存命中/未命中模式
- 一个服务器上集成多种工具
- 关闭时记录指标
指标（或度量标准） - 指标与监控
展示如何：
- 追踪工具调用
- 监控缓存性能
- 通过工具暴露指标
- 对数周期性统计
- 访问特定缓存的指标
文件服务器 - 资源提供者
示例：
- 资源注册
- 带参数的资源模板
- 处理文件和数据
运行任意示例：
cd examples/hello && go run main.go
cd examples/weather && go run main.go
cd examples/metrics && go run main.go性能指标
hypermcp 包含内置的性能追踪功能：
// Track operations
srv.Metrics().IncrementToolInvocations()
srv.Metrics().IncrementCacheHits()
srv.Metrics().IncrementCacheMisses()
srv.Metrics().IncrementErrors()
// Get snapshot
metrics := srv.GetMetrics()
fmt.Printf("Uptime: %v\n", metrics.Uptime)
fmt.Printf("Cache hit rate: %.2f%%\n", metrics.CacheHitRate*100)跟踪的指标：
- 服务器运行时间
- 工具调用
- 资源读取
- 缓存命中/未命中和命中率
- 错误计数
最佳实践
优雅地关闭
始终执行优雅关闭以确保资源得到妥善清理：
// Setup signal handling
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
sigChan := make(chan os.Signal, 1)
signal.Notify(sigChan, os.Interrupt, syscall.SIGTERM)
go func() {
<-sigChan
logger.Info("shutting down...")
cancel()
}()
// Run server
if err := hypermcp.RunWithTransport(ctx, srv, hypermcp.TransportStdio, logger); err != nil {
logger.Error("server error", zap.Error(err))
os.Exit(1)
}
// Graceful shutdown with timeout
shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 5*time.Second)
defer shutdownCancel()
if err := srv.Shutdown(shutdownCtx); err != nil {
logger.Error("shutdown error", zap.Error(err))
}缓存使用情况
对昂贵的操作使用缓存：
cacheKey := fmt.Sprintf("data:%s", id)
// Check cache first
if cached, ok := srv.Cache().Get(cacheKey); ok {
srv.Metrics().IncrementCacheHits()
return cached
}
srv.Metrics().IncrementCacheMisses()
// Fetch data...
result := fetchExpensiveData(id)
// Cache for 5 minutes
srv.Cache().Set(cacheKey, result, 5*time.Minute)HTTP客户端使用
提供的HTTP客户端包含重试机制和适当的超时设置：
type Response struct {
Status string `json:"status"`
}
var resp Response
if err := srv.HTTPClient().Get(ctx, apiURL, &resp); err != nil {
srv.Metrics().IncrementErrors()
return err
}示例
依赖项
github.com/modelcontextprotocol/go-sdk- MCP SDK（MCP软件开发工具包）go.uber.org/zap- 结构化日志记录github.com/dgraph-io/ristretto- 缓存（通过 pkg/cache）