Scaled MCP

🚀 Scaled-MCP Project Documentation

The Scaled-MCP project offers a powerful framework for managing and invoking tools. This documentation provides quick start examples, tool registry examples, important notes, and more to help you get started with the project.

🚀 Quick Start

MCP Example

The following is a basic example demonstrating how to use the Scaled-MCP to perform a simple calculation operation:

package main

import (
    "context"
    "log"

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

func main() {
    // Create a tool registry
    registry := resources.NewStaticToolRegistry()

    // Register a calculator tool
    calculatorTool := resources.NewTool("calculator").
        WithDescription("Perform basic arithmetic operations").
        WithString("operation").
        Required().
        Description("The operation to perform (add, subtract, multiply, divide)").
        Add().
        WithNumber("a").
        Required().
        Description("The first operand").
        Add().
        WithNumber("b").
        Required().
        Description("The second operand").
        Add().
        Build()

    registry.Register(calculatorTool)

    // Create a context and a tool provider
    ctx := context.Background()
    toolProvider := resources.NewToolProvider(registry)

    // Create an MCP service
    cfg := resources.DefaultConfig()
    mcpServer, err := resources.NewMcpServer(cfg,
        resources.WithToolRegistry(registry),
    )

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

    defer mcpServer.Stop()

    // Start the MCP server
    go func() {
        <-mcpServer.Start()
    }()

    // Example: Create a context and perform a calculation operation
    ctx, cancel := context.WithCancel(ctx)
    defer cancel()

    // Perform an addition operation
    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("Calculation result: %v", result.Value)
}

Execution Result

$ go run main.go 
Calculation result: 30

💻 Tool Registry Examples

Here are examples of using a static tool registry and a dynamic tool registry:

Static Tool Registry Example

package main

import (
    "context"
    "log"

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

func main() {
    // Create a static tool registry
    registry := resources.NewStaticToolRegistry()

    // Register a calculator tool
    calculatorTool := resources.NewTool("calculator").
        WithDescription("Perform basic arithmetic operations").
        WithString("operation").
        Required().
        Description("The operation to perform (add, subtract, multiply, divide)").
        Add().
        WithNumber("a").
        Required().
        Description("The first operand").
        Add().
        WithNumber("b").
        Required().
        Description("The second operand").
        Add().
        Build()

    registry.Register(calculatorTool)

    // Create a context and a tool provider
    ctx := context.Background()
    toolProvider := resources.NewToolProvider(registry)

    // Create an MCP service
    cfg := resources.DefaultConfig()
    mcpServer, err := resources.NewMcpServer(cfg,
        resources.WithToolRegistry(registry),
    )

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

    defer mcpServer.Stop()

    // Start the MCP server
    go func() {
        <-mcpServer.Start()
    }()

    // Example: Create a context and perform a calculation operation
    ctx, cancel := context.WithCancel(ctx)
    defer cancel()

    // Perform an addition operation
    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("Calculation result: %v", result.Value)
}

Dynamic Tool Registry Example

package main

import (
    "context"
    "log"

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

func main() {
    // Create a dynamic tool registry
    registry := resources.NewDynamicToolRegistry()

    // Register a calculator tool
    calculatorTool := resources.NewTool("calculator").
        WithDescription("Perform basic arithmetic operations").
        WithString("operation").
        Required().
        Description("The operation to perform (add, subtract, multiply, divide)").
        Add().
        WithNumber("a").
        Required().
        Description("The first operand").
        Add().
        WithNumber("b").
        Required().
        Description("The second operand").
        Add().
        Build()

    registry.Register(calculatorTool)

    // Create a context and a tool provider
    ctx := context.Background()
    toolProvider := resources.NewToolProvider(registry)

    // Create an MCP service
    cfg := resources.DefaultConfig()
    mcpServer, err := resources.NewMcpServer(cfg,
        resources.WithToolRegistry(registry),
    )

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

    defer mcpServer.Stop()

    // Start the MCP server
    go func() {
        <-mcpServer.Start()
    }()

    // Example: Create a context and perform a calculation operation
    ctx, cancel := context.WithCancel(ctx)
    defer cancel()

    // Perform an addition operation
    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("Calculation result: %v", result.Value)
}

⚠️ Important Notes

1. Use Goroutines to Handle Requests

To ensure performance in high-concurrency scenarios, it is recommended to use goroutines when handling each request.

Example:

// After the MCP server starts, handle each new connection
go func() {
    for {
        // Wait for a new client connection
        conn, err := listener.Accept()
        if err != nil {
            log.Printf("Accept error: %v", err)
            continue
        }

        // Use a goroutine to handle the request
        go handleConnection(conn)
    }
}()

2. Close the MCP Server

Before the application exits, make sure to properly close the MCP server to release resources.

Example:

defer mcpServer.Stop()

📋 To-Do List

• Implement Logging: Add detailed logging for debugging and monitoring.
• Error Handling: Improve the error handling mechanism to ensure graceful handling of errors.
• Performance Optimization: Optimize performance according to actual needs, such as adjusting the number of goroutines or using more efficient communication methods.

🤝 Contribution Guidelines

Code Style

Please follow the Go language code specifications and maintain consistency with the existing code in the project.

Submission Guidelines

1. Before submitting, make sure all unit tests pass.
2. The commit message should be concise and clear, including the relevant features or fixes.

🔑 Key Parts in the Examples

• Tool Registration: Add tools to the registry using registry.Register(tool).
• Tool Invocation: Create a tool invocation using resources.NewToolInvocation and set parameters using chained methods.
• Context Management: Use context.Background() and context.WithCancel to manage the lifecycle of requests.

🐞 Issue Reporting

If you encounter any issues, please submit them in the project's Issues or contact the maintainers directly.