Scaled MCP

🚀 Scaled - MCP 項目文檔

Scaled - 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 中提交，或者直接聯繫維護人員。