Skip to main content

CWCloud MCP Public API

This document describes the public API provided by the pkg/mcp package, which allows other Go projects to integrate with CWCloud AI services and create their own MCP servers.

Installation​

go get github.com/cwloudtech/cwcloud-mcp/pkg/mcp

Quick Start​

package main

import (
    "log"
    "cwcloud-mcp/pkg/mcp"
)

func main() {
    // Create a CWCloud client
    client := mcp.NewClient(
        mcp.DefaultAPIURL,
        "your-access-key",
        "your-secret-key", 
        mcp.LogLevelInfo,
    )
    
    // Generate AI content
    response, err := client.GeneratePrompt(&mcp.PromptRequest{
        Adapter: mcp.AdapterGPT4o,
        Message: "Hello, World!",
        EnableHistory: true,
    })
    if err != nil {
        log.Fatal(err)
    }
    
    log.Printf("AI Response: %s", response.Response)
}

Core Components​

Client Interface​

The Client interface provides access to all CWCloud AI services:

type Client interface {
    GeneratePrompt(req *PromptRequest) (*PromptResponse, error)
    ListConversations() (*ConversationList, error)
    GetConversation(id string) (*ConversationDetail, error)
    DeleteConversation(id string) error
    ListAdapters() (*AdapterList, error)
    GetUsageStats(params map[string]string) (*UsageStats, error)
    ValidateAuth() error
}

Factory Function​

func NewClient(baseURL, accessKey, secretKey, logLevel string) Client

Creates a new CWCloud API client. Use mcp.DefaultAPIURL for production.

Available AI Adapters​

Use these constants when specifying which AI model to use:

const (
    AdapterGPT4o         = "gpt4o"
    AdapterGPT4oMini     = "gpt4o-mini"
    AdapterClaude3Sonnet = "claude3sonnet"
    AdapterClaude3Haiku  = "claude3haiku"
    AdapterGemini        = "gemini"
    AdapterGeminiPro     = "gemini-pro"
)

MCP Tool Creation​

The library provides helpers for creating MCP tools:

Simple AI Tool​

tool := mcp.NewSimpleAITool(
    "summarize",
    "Summarize text using AI",
    client,
    mcp.AdapterGPT4o,
)

Conversation Management Tool​

tool := mcp.NewConversationTool(
    "list_conversations",
    "List all AI conversations",
    client,
)

Custom Tools​

Implement the MCPTool interface:

type MCPTool interface {
    GetName() string
    GetDescription() string
    GetInputSchema() map[string]interface{}
    Execute(ctx context.Context, params map[string]interface{}) (*MCPToolResult, error)
}

Data Types​

PromptRequest​

type PromptRequest struct {
    Adapter       string            // AI model to use
    Message       string            // Prompt text
    Settings      *PromptSettings   // Optional parameters
    ListID        string            // Conversation ID (optional)
    EnableHistory bool              // Save to conversation history
}

PromptSettings​

type PromptSettings struct {
    MaxTokens   *int     // Maximum tokens to generate
    Temperature *float64 // Creativity (0.0 to 1.0)
    TopP        *int     // Nucleus sampling
    Model       *string  // Specific model variant
}

PromptResponse​

type PromptResponse struct {
    Status   string     // Response status
    Response string     // AI-generated text
    ListID   string     // Conversation ID
    Usage    TokenUsage // Token usage statistics
}

Authentication​

Before making API calls, validate your credentials:

if err := client.ValidateAuth(); err != nil {
    log.Fatal("Authentication failed:", err)
}

Error Handling​

All methods return standard Go errors. Check for authentication failures, network issues, and API errors:

response, err := client.GeneratePrompt(req)
if err != nil {
    // Handle error appropriately
    log.Printf("API call failed: %v", err)
    return
}

Conversation Management​

Start a Conversation​

response, err := client.GeneratePrompt(&mcp.PromptRequest{
    Adapter:       mcp.AdapterGPT4o,
    Message:       "Hello, let's chat!",
    EnableHistory: true, // This creates a conversation
})
conversationID := response.ListID

Continue a Conversation​

response, err := client.GeneratePrompt(&mcp.PromptRequest{
    Adapter: mcp.AdapterGPT4o,
    Message: "Tell me more about that.",
    ListID:  conversationID, // Continue existing conversation
})

List All Conversations​

conversations, err := client.ListConversations()
if err != nil {
    return err
}

for _, conv := range conversations.Conversations {
    fmt.Printf("ID: %s, Title: %s\n", conv.ID, conv.Title)
}

Usage Statistics​

Track your AI usage and costs:

stats, err := client.GetUsageStats(nil)
if err != nil {
    return err
}

fmt.Printf("Total tokens: %d\n", stats.Usage.TotalTokens)
fmt.Printf("Total cost: $%.4f\n", stats.Usage.TotalCost)

// Usage by adapter
for adapter, usage := range stats.Usage.ByAdapter {
    fmt.Printf("%s: %d tokens, $%.4f\n", 
        adapter, usage.Tokens, usage.Cost)
}

Examples​

See the examples/ directory for complete working examples:

  • examples/usage.go - Comprehensive usage examples
  • Basic client operations
  • Custom MCP tool creation
  • Conversation management
  • Usage statistics

Thread Safety​

The client is safe for concurrent use across multiple goroutines.

Best Practices​

  1. Reuse Clients: Create one client instance and reuse it across your application
  2. Handle Errors: Always check for errors, especially authentication failures
  3. Set Limits: Use MaxTokens to control costs and response length
  4. Save Conversations: Use EnableHistory: true for multi-turn conversations
  5. Monitor Usage: Regularly check usage statistics to track costs

Integration with MCP Servers​

This library is designed to be used within MCP servers. The tools created with this library can be easily integrated into MCP protocol implementations.

For a complete example of an MCP server using this library, see the main cwcloud-mcp server implementation in the project root.