Scaled-MCP 项目文档

快速开始示例

MCP 示例

package main

import (
    "context"
    "log"

    "github.com/traego/scaled-mcp/v2/resources"
)

func main() {
    // 创建工具注册表
    registry := resources.NewStaticToolRegistry()

    // 注册一个计算器工具
    calculatorTool := resources.NewTool("calculator").
        WithDescription("执行基本算术运算").
       WithString("operation").
        必要().
        描述("要执行的操作（加法，减法，乘法，除法）").
        添加().
        WithNumber("a").
        必要().
        描述("第一个操作数").
        添加().
        WithNumber("b").
        必要().
        描述("第二个操作数").
        添加().
        Build()

    registry.Register(calculatorTool)

    // 创建上下文和工具提供程序
    ctx := context.Background()
    toolProvider := resources.NewToolProvider(registry)

    // 创建 MCP 服务
    cfg := resources.DefaultConfig()
    mcpServer, err := resources.NewMcpServer(cfg,
        resources.WithToolRegistry(registry),
    )

    if err != nil {
        log.Fatal(err)
    }

    defer mcpServer.Stop()

    // 启动 MCP 服务器
    go func() {
        <-mcpServer.Start()
    }()

    // 示例：创建上下文并执行计算操作
    ctx, cancel := context.WithCancel(ctx)
    defer cancel()

    // 执行加法运算
    result, err := resources.NewToolInvocation("calculator").
        WithStringMapParameter("operation", "add").
        WithNumber(10).
        Add().
        WithNumber(20).
        Add().
        Invoke(ctx, toolProvider)

    if err != nil {
        log.Fatal(err)
    }

    log.Printf("计算结果： %v", result.Value)
}

执行结果

$ go run main.go 
计算结果： 30

工具注册表示例

以下是使用静态工具注册表和动态工具注册表的示例：

静态工具注册表示例

package main

import (
    "context"
    "log"

    "github.com/traego/scaled-mcp/v2/resources"
)

func main() {
    // 创建静态工具注册表
    registry := resources.NewStaticToolRegistry()

    // 注册一个计算器工具
    calculatorTool := resources.NewTool("calculator").
        WithDescription("执行基本算术运算").
       WithString("operation").
        必要().
        描述("要执行的操作（加法，减法，乘法，除法）").
        添加().
        WithNumber("a").
        必要().
        描述("第一个操作数").
        添加().
        WithNumber("b").
        必要().
        描述("第二个操作数").
        添加().
        Build()

    registry.Register(calculatorTool)

    // 创建上下文和工具提供程序
    ctx := context.Background()
    toolProvider := resources.NewToolProvider(registry)

    // 创建 MCP 服务
    cfg := resources.DefaultConfig()
    mcpServer, err := resources.NewMcpServer(cfg,
        resources.WithToolRegistry(registry),
    )

    if err != nil {
        log.Fatal(err)
    }

    defer mcpServer.Stop()

    // 启动 MCP 服务器
    go func() {
        <-mcpServer.Start()
    }()

    // 示例：创建上下文并执行计算操作
    ctx, cancel := context.WithCancel(ctx)
    defer cancel()

    // 执行加法运算
    result, err := resources.NewToolInvocation("calculator").
        WithStringMapParameter("operation", "add").
        WithNumber(10).
        Add().
        WithNumber(20).
        Add().
        Invoke(ctx, toolProvider)

    if err != nil {
        log.Fatal(err)
    }

    log.Printf("计算结果： %v", result.Value)
}

动态工具注册表示例

package main

import (
    "context"
    "log"

    "github.com/traego/scaled-mcp/v2/resources"
)

func main() {
    // 创建动态工具注册表
    registry := resources.NewDynamicToolRegistry()

    // 注册一个计算器工具
    calculatorTool := resources.NewTool("calculator").
        WithDescription("执行基本算术运算").
       WithString("operation").
        必要().
        描述("要执行的操作（加法，减法，乘法，除法）").
        添加().
        WithNumber("a").
        必要().
        描述("第一个操作数").
        添加().
        WithNumber("b").
        必要().
        描述("第二个操作数").
        添加().
        Build()

    registry.Register(calculatorTool)

    // 创建上下文和工具提供程序
    ctx := context.Background()
    toolProvider := resources.NewToolProvider(registry)

    // 创建 MCP 服务
    cfg := resources.DefaultConfig()
    mcpServer, err := resources.NewMcpServer(cfg,
        resources.WithToolRegistry(registry),
    )

    if err != nil {
        log.Fatal(err)
    }

    defer mcpServer.Stop()

    // 启动 MCP 服务器
    go func() {
        <-mcpServer.Start()
    }()

    // 示例：创建上下文并执行计算操作
    ctx, cancel := context.WithCancel(ctx)
    defer cancel()

    // 执行加法运算
    result, err := resources.NewToolInvocation("calculator").
        WithStringMapParameter("operation", "add").
        WithNumber(10).
        Add().
        WithNumber(20).
        Add().
        Invoke(ctx, toolProvider)

    if err != nil {
        log.Fatal(err)
    }

    log.Printf("计算结果： %v", result.Value)
}

重要注意事项

1. 使用 goroutine 处理请求

为了确保高并发场景下的性能，建议在处理每个请求时使用 goroutine。

示例：

// 在 MCP 服务器启动后，处理每个新连接
go func() {
    for {
        // 等待新的客户端连接
        conn, err := listener.Accept()
        if err != nil {
            log.Printf("接受错误： %v", err)
            continue
        }

        // 使用 goroutine 处理请求
        go handleConnection(conn)
    }
}()

2. 关闭 MCP 服务器

在应用程序退出前，确保正确关闭 MCP 服务器以释放资源。

示例：

defer mcpServer.Stop()

待办事项

• 实现日志记录：添加详细的日志记录以便于调试和监控。
• 错误处理：完善错误处理机制，确保在出现错误时能够优雅地处理。
• 性能优化：根据实际需求进行性能调优，例如调整goroutine数量或使用更高效的通信方式。

贡献指南

代码风格

请遵循 Go 语言的代码规范，并且保持与项目现有代码的一致性。

提交指南

1. 在提交前，请确保通过了所有单元测试。
2. 提交信息应简洁明了，包含相关功能或修复的内容。

示例中的关键部分

• 工具注册：通过 registry.Register(tool) 将工具添加到注册表中。
• 工具调用：使用 resources.NewToolInvocation 创建工具调用，并通过链式方法设置参数。
• 上下文管理：合理使用 context.Background() 和 context.WithCancel 管理请求的生命周期。

问题反馈

如遇到任何问题，请在项目Issues中提交，或者直接联系维护人员。