plugin

README

Cortex Plugin System

The Cortex Plugin System provides a flexible architecture for extending the Cortex MCP (Model Context Protocol) server with external tools and services. This system allows third-party providers to register tools that can be called through the MCP protocol.

Overview

The plugin system includes the following key components:

• Provider Interface: Defines the contract that tool providers must implement
• Registry: Manages the registration and discovery of providers and tools
• Base Provider: Provides a foundation for building tool providers

Provider Interface

Tool providers must implement the Provider interface:

type Provider interface {
    // GetProviderInfo returns information about the tool provider
    GetProviderInfo(ctx context.Context) (*ProviderInfo, error)

    // GetTools returns a list of tools provided by this provider
    GetTools(ctx context.Context) ([]*types.Tool, error)

    // ExecuteTool executes a specific tool with the given parameters
    ExecuteTool(ctx context.Context, request *ExecuteRequest) (*ExecuteResponse, error)
}

Creating a Tool Provider

The easiest way to create a tool provider is to use the BaseProvider implementation:

// Create provider info
info := plugin.ProviderInfo{
    ID:          "my-provider",
    Name:        "My Provider",
    Version:     "1.0.0",
    Description: "A custom tool provider",
    Author:      "Your Name",
    URL:         "https://github.com/yourusername/your-repo",
}

// Create base provider
baseProvider := plugin.NewBaseProvider(info, logger)

// Create your custom provider
myProvider := &MyProvider{
    BaseProvider: baseProvider,
    // Add your custom fields here
}

// Register tools with your provider
myTool := tools.NewTool("my-tool",
    tools.WithDescription("A custom tool"),
    tools.WithString("param1", tools.Description("Parameter 1"), tools.Required()),
)

// Register the tool with your provider
myProvider.RegisterTool(myTool, handleMyTool)

Tool Handler Function

Each tool needs a handler function that follows this signature:

func handleMyTool(ctx context.Context, params map[string]interface{}, session *types.ClientSession) (interface{}, error) {
    // Extract parameters
    param1, ok := params["param1"].(string)
    if !ok {
        return nil, fmt.Errorf("missing or invalid 'param1' parameter")
    }

    // Process the request
    result := fmt.Sprintf("Processed param1: %s", param1)

    // Return the result in the format expected by the MCP protocol
    return map[string]interface{}{
        "content": []map[string]interface{}{
            {
                "type": "text",
                "text": result,
            },
        },
    }, nil
}

Using the Registry

The registry manages the providers and tools:

// Create a registry
registry := plugin.NewRegistry(logger)

// Register a provider
registry.RegisterProvider(ctx, myProvider)

// Get a tool
tool, provider, err := registry.GetTool(ctx, "my-tool")
if err != nil {
    // Handle error
}

// List all tools
tools, err := registry.ListTools(ctx)
if err != nil {
    // Handle error
}

Using the Flexible MCP Server

The FlexibleMCPServer supports dynamic tool providers:

// Create a registry
registry := plugin.NewRegistry(logger)

// Create the flexible MCP server
mcpServer := server.NewFlexibleMCPServer("My MCP Server", "1.0.0", registry, logger)

// Register providers with the server
mcpServer.RegisterProvider(ctx, myProvider)

// Start the server (stdio or HTTP)
mcpServer.ServeStdio()
// or
mcpServer.ServeHTTP()

Example Providers

The Cortex project includes example providers in the examples/providers/ directory:

• Weather Provider: Provides tools for getting weather forecasts
• Database Provider: Provides tools for simple database operations

These examples demonstrate how to create providers that integrate with the Cortex platform.

Security Considerations

When implementing tool providers, consider the following security best practices:

1. Validate all input parameters thoroughly
2. Limit access to sensitive operations
3. Use context for cancellation and timeouts
4. Log security-relevant events
5. Avoid exposing internal details in error messages

Documentation

Overview

Package plugin defines interfaces and utilities for the Cortex plugin system.

Index

• type BaseProvider
  • func NewBaseProvider(info ProviderInfo, logger *log.Logger) *BaseProvider
  • func (p *BaseProvider) ExecuteTool(ctx context.Context, request *ExecuteRequest) (*ExecuteResponse, error)
  • func (p *BaseProvider) GetProviderInfo(ctx context.Context) (*ProviderInfo, error)
  • func (p *BaseProvider) GetTools(ctx context.Context) ([]*types.Tool, error)
  • func (p *BaseProvider) RegisterTool(tool *types.Tool, executor ToolExecutor) error
  • func (p *BaseProvider) UnregisterTool(toolName string) error
• type DefaultRegistry
  • func NewRegistry(logger *log.Logger) *DefaultRegistry
  • func (r *DefaultRegistry) GetProvider(ctx context.Context, providerID string) (Provider, error)
  • func (r *DefaultRegistry) GetTool(ctx context.Context, toolName string) (*types.Tool, Provider, error)
  • func (r *DefaultRegistry) ListProviders(ctx context.Context) ([]Provider, error)
  • func (r *DefaultRegistry) ListTools(ctx context.Context) ([]*types.Tool, error)
  • func (r *DefaultRegistry) RegisterProvider(ctx context.Context, provider Provider) error
  • func (r *DefaultRegistry) UnregisterProvider(ctx context.Context, providerID string) error
• type ExecuteRequest
• type ExecuteResponse
• type Provider
• type ProviderInfo
• type Registry
• type ToolExecutor

Types

type BaseProvider

type BaseProvider struct {
	// contains filtered or unexported fields
}

BaseProvider implements the Provider interface and provides a foundation for building tool providers.

func NewBaseProvider

func NewBaseProvider(info ProviderInfo, logger *log.Logger) *BaseProvider

NewBaseProvider creates a new BaseProvider with the given info.

func (*BaseProvider) ExecuteTool

func (p *BaseProvider) ExecuteTool(ctx context.Context, request *ExecuteRequest) (*ExecuteResponse, error)

ExecuteTool executes a specific tool with the given parameters.

func (*BaseProvider) GetProviderInfo

func (p *BaseProvider) GetProviderInfo(ctx context.Context) (*ProviderInfo, error)

GetProviderInfo returns information about the tool provider.

func (*BaseProvider) GetTools

func (p *BaseProvider) GetTools(ctx context.Context) ([]*types.Tool, error)

GetTools returns a list of tools provided by this provider.

func (*BaseProvider) RegisterTool

func (p *BaseProvider) RegisterTool(tool *types.Tool, executor ToolExecutor) error

RegisterTool registers a new tool with the provider.

func (*BaseProvider) UnregisterTool

func (p *BaseProvider) UnregisterTool(toolName string) error

UnregisterTool removes a tool from the provider.

type DefaultRegistry

type DefaultRegistry struct {
	// contains filtered or unexported fields
}

DefaultRegistry is the default implementation of the Registry interface.

func NewRegistry

func NewRegistry(logger *log.Logger) *DefaultRegistry

NewRegistry creates a new registry for managing tool providers.

func (*DefaultRegistry) GetProvider

func (r *DefaultRegistry) GetProvider(ctx context.Context, providerID string) (Provider, error)

GetProvider retrieves a specific provider by ID.

func (*DefaultRegistry) GetTool

func (r *DefaultRegistry) GetTool(ctx context.Context, toolName string) (*types.Tool, Provider, error)

GetTool retrieves a specific tool by name.

func (*DefaultRegistry) ListProviders

func (r *DefaultRegistry) ListProviders(ctx context.Context) ([]Provider, error)

ListProviders returns all registered providers.

func (*DefaultRegistry) ListTools

func (r *DefaultRegistry) ListTools(ctx context.Context) ([]*types.Tool, error)

ListTools returns all tools from all registered providers.

func (*DefaultRegistry) RegisterProvider

func (r *DefaultRegistry) RegisterProvider(ctx context.Context, provider Provider) error

RegisterProvider registers a new tool provider with the registry.

func (*DefaultRegistry) UnregisterProvider

func (r *DefaultRegistry) UnregisterProvider(ctx context.Context, providerID string) error

UnregisterProvider removes a tool provider from the registry.

type ExecuteRequest

type ExecuteRequest struct {
	ToolName   string
	Parameters map[string]interface{}
	Session    *types.ClientSession
}

ExecuteRequest contains information for executing a tool.

type ExecuteResponse

type ExecuteResponse struct {
	Content interface{}
	Error   error
}

ExecuteResponse contains the result of executing a tool.

type Provider

type Provider interface {
	// GetProviderInfo returns information about the tool provider.
	GetProviderInfo(ctx context.Context) (*ProviderInfo, error)

	// GetTools returns a list of tools provided by this provider.
	GetTools(ctx context.Context) ([]*types.Tool, error)

	// ExecuteTool executes a specific tool with the given parameters.
	ExecuteTool(ctx context.Context, request *ExecuteRequest) (*ExecuteResponse, error)
}

Provider represents a tool provider that can register tools with the Cortex platform.

type ProviderInfo

type ProviderInfo struct {
	ID          string
	Name        string
	Version     string
	Description string
	Author      string
	URL         string
}

ProviderInfo contains metadata about a tool provider.

type Registry

type Registry interface {
	// RegisterProvider registers a new tool provider with the registry.
	RegisterProvider(ctx context.Context, provider Provider) error

	// UnregisterProvider removes a tool provider from the registry.
	UnregisterProvider(ctx context.Context, providerID string) error

	// GetProvider retrieves a specific provider by ID.
	GetProvider(ctx context.Context, providerID string) (Provider, error)

	// ListProviders returns all registered providers.
	ListProviders(ctx context.Context) ([]Provider, error)

	// GetTool retrieves a specific tool by name.
	GetTool(ctx context.Context, toolName string) (*types.Tool, Provider, error)

	// ListTools returns all tools from all registered providers.
	ListTools(ctx context.Context) ([]*types.Tool, error)
}

Registry manages the registration and discovery of tool providers.

type ToolExecutor

type ToolExecutor func(ctx context.Context, params map[string]interface{}, session *types.ClientSession) (interface{}, error)

ToolExecutor is a function that executes a tool and returns a result.