This is the multi-page printable view of this section. Click here to print.
How-to guides are problem-oriented recipes that guide you through the steps involved in addressing key problems and use cases. They are practical and goal-oriented.
These guides will help you solve specific tasks and customize gomcptest for your needs.
This guide shows you how to create a new custom tool that’s compatible with the Model Context Protocol (MCP) in gomcptest.
mkdir -p tools/YourToolName/cmd
Create a README.md in the tool directory with documentation:
touch tools/YourToolName/README.md
Include the following sections:
Create a main.go file in the cmd directory:
touch tools/YourToolName/cmd/main.go
Here’s a template to start with:
package main
import (
"encoding/json"
"fmt"
"log"
"os"
"github.com/mark3labs/mcp-go"
)
// Define your tool's parameters structure
type Params struct {
// Add your parameters here
// Example:
InputParam string `json:"input_param"`
}
func main() {
server := mcp.NewServer()
// Register your tool function
server.RegisterFunction("YourToolName", func(params json.RawMessage) (any, error) {
var p Params
if err := json.Unmarshal(params, &p); err != nil {
return nil, fmt.Errorf("failed to parse parameters: %w", err)
}
// Implement your tool's logic here
result := doSomethingWithParams(p)
return result, nil
})
if err := server.Run(os.Stdin, os.Stdout); err != nil {
log.Fatalf("Server error: %v", err)
}
}
func doSomethingWithParams(p Params) interface{} {
// Your tool's core functionality
// ...
// Return the result
return map[string]interface{}{
"result": "Your processed result",
}
}
Open the Makefile in the root directory and add your tool:
YourToolName:
go build -o bin/YourToolName tools/YourToolName/cmd/main.go
Also add it to the all target.
make YourToolName
Test the tool directly:
echo '{"name":"YourToolName","params":{"input_param":"test"}}' | ./bin/YourToolName
Add your tool to the CLI command:
./bin/cliGCP -mcpservers "./GlobTool;./GrepTool;./LS;./View;./YourToolName;./dispatch_agent;./Bash;./Replace"
This guide shows you how to configure and customize the OpenAI-compatible server in gomcptest for different use cases.
The OpenAI server can be configured using the following environment variables:
# Server port (default: 8080)
export PORT=8080
# Log level: DEBUG, INFO, WARN, ERROR (default: INFO)
export LOG_LEVEL=INFO
# Directory to store images (required)
export IMAGE_DIR=/path/to/image/directory
Configure the Google Cloud Platform integration:
# GCP Project ID (required)
export GCP_PROJECT=your-gcp-project-id
# GCP Region (default: us-central1)
export GCP_REGION=us-central1
# Comma-separated list of Gemini models (default: gemini-1.5-pro,gemini-2.0-flash)
export GEMINI_MODELS=gemini-1.5-pro,gemini-2.0-flash
# Comma-separated list of Imagen models (optional)
export IMAGEN_MODELS=imagen-3.0-generate-002
For a production environment, create a proper systemd service file:
sudo nano /etc/systemd/system/gomcptest-openai.service
Add the following content:
[Unit]
Description=gomcptest OpenAI Server
After=network.target
[Service]
User=yourusername
WorkingDirectory=/path/to/gomcptest/host/openaiserver
ExecStart=/path/to/gomcptest/host/openaiserver/openaiserver -mcpservers "/path/to/gomcptest/bin/GlobTool;/path/to/gomcptest/bin/GrepTool;/path/to/gomcptest/bin/LS;/path/to/gomcptest/bin/View;/path/to/gomcptest/bin/Bash;/path/to/gomcptest/bin/Replace"
Environment=PORT=8080
Environment=LOG_LEVEL=INFO
Environment=IMAGE_DIR=/path/to/image/directory
Environment=GCP_PROJECT=your-gcp-project-id
Environment=GCP_REGION=us-central1
Environment=GEMINI_MODELS=gemini-1.5-pro,gemini-2.0-flash
Restart=on-failure
[Install]
WantedBy=multi-user.target
Then enable and start the service:
sudo systemctl enable gomcptest-openai
sudo systemctl start gomcptest-openai
To add custom MCP tools to the server, include them in the -mcpservers parameter when starting the server:
go run . -mcpservers "../bin/GlobTool;../bin/GrepTool;../bin/LS;../bin/View;../bin/YourCustomTool;../bin/Bash;../bin/Replace"
Some tools require additional parameters. You can specify these after the tool path:
go run . -mcpservers "../bin/GlobTool;../bin/dispatch_agent -glob-path ../bin/GlobTool -grep-path ../bin/GrepTool -ls-path ../bin/LS -view-path ../bin/View"
For web applications, you may need to enable CORS. Add a middleware to the main.go file:
package main
import (
"net/http"
// other imports
)
// CORS middleware
func corsMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Access-Control-Allow-Origin", "*")
w.Header().Set("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
w.Header().Set("Access-Control-Allow-Headers", "Content-Type, Authorization")
if r.Method == "OPTIONS" {
w.WriteHeader(http.StatusOK)
return
}
next.ServeHTTP(w, r)
})
}
func main() {
// existing code...
http.Handle("/", corsMiddleware(openAIHandler))
// existing code...
}
Add a simple rate limiting middleware:
package main
import (
"net/http"
"sync"
"time"
// other imports
)
type RateLimiter struct {
requests map[string][]time.Time
maxRequests int
timeWindow time.Duration
mu sync.Mutex
}
func NewRateLimiter(maxRequests int, timeWindow time.Duration) *RateLimiter {
return &RateLimiter{
requests: make(map[string][]time.Time),
maxRequests: maxRequests,
timeWindow: timeWindow,
}
}
func (rl *RateLimiter) Middleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
ip := r.RemoteAddr
rl.mu.Lock()
// Clean up old requests
now := time.Now()
if reqs, exists := rl.requests[ip]; exists {
var validReqs []time.Time
for _, req := range reqs {
if now.Sub(req) <= rl.timeWindow {
validReqs = append(validReqs, req)
}
}
rl.requests[ip] = validReqs
}
// Check if rate limit is exceeded
if len(rl.requests[ip]) >= rl.maxRequests {
rl.mu.Unlock()
http.Error(w, "Rate limit exceeded", http.StatusTooManyRequests)
return
}
// Add current request
rl.requests[ip] = append(rl.requests[ip], now)
rl.mu.Unlock()
next.ServeHTTP(w, r)
})
}
func main() {
// existing code...
rateLimiter := NewRateLimiter(10, time.Minute) // 10 requests per minute
http.Handle("/", rateLimiter.Middleware(corsMiddleware(openAIHandler)))
// existing code...
}
For high-load scenarios, adjust Go’s garbage collector:
export GOGC=100 # Default is 100, lower values lead to more frequent GC
If handling many concurrent requests, adjust the server’s concurrency limits:
package main
import (
"net/http"
// other imports
)
func main() {
// existing code...
server := &http.Server{
Addr: ":" + strconv.Itoa(cfg.Port),
Handler: openAIHandler,
ReadTimeout: 30 * time.Second,
WriteTimeout: 120 * time.Second,
IdleTimeout: 120 * time.Second,
MaxHeaderBytes: 1 << 20,
}
err = server.ListenAndServe()
// existing code...
}
If you’re experiencing connection issues, set the log level to DEBUG:
export LOG_LEVEL=DEBUG
To verify tools are registered correctly, look for log messages like:
INFO server0 Registering command=../bin/GlobTool
INFO server1 Registering command=../bin/GrepTool
This guide shows you how to configure and customize the cliGCP command line interface for various use cases.
The cliGCP tool accepts the following command line arguments:
# Specify the MCP servers to use (required)
-mcpservers "tool1;tool2;tool3"
# Example with tool arguments
./cliGCP -mcpservers "./GlobTool;./GrepTool;./dispatch_agent -glob-path ./GlobTool -grep-path ./GrepTool -ls-path ./LS -view-path ./View;./Bash"
Configure the Google Cloud Platform integration with these environment variables:
# GCP Project ID (required)
export GCP_PROJECT=your-gcp-project-id
# GCP Region (default: us-central1)
export GCP_REGION=us-central1
# Comma-separated list of Gemini models (required)
export GEMINI_MODELS=gemini-1.5-pro,gemini-2.0-flash
# Directory to store images (required for image generation)
export IMAGE_DIR=/path/to/image/directory
You can customize the behavior of the cliGCP tool with these additional environment variables:
# Set a custom system instruction for the model
export SYSTEM_INSTRUCTION="You are a helpful assistant specialized in Go programming."
# Adjust the model's temperature (0.0-1.0, default is 0.2)
# Lower values make output more deterministic, higher values more creative
export MODEL_TEMPERATURE=0.3
# Set a maximum token limit for responses
export MAX_OUTPUT_TOKENS=2048
To simplify usage, create shell aliases in your .bashrc or .zshrc:
# Add to ~/.bashrc or ~/.zshrc
alias gpt='cd /path/to/gomcptest/bin && ./cliGCP -mcpservers "./GlobTool;./GrepTool;./LS;./View;./Bash;./Replace"'
# Create specialized aliases for different tasks
alias code-assistant='cd /path/to/gomcptest/bin && GCP_PROJECT=your-project GEMINI_MODELS=gemini-2.0-flash ./cliGCP -mcpservers "./GlobTool;./GrepTool;./LS;./View;./Bash;./Replace"'
alias security-scanner='cd /path/to/gomcptest/bin && SYSTEM_INSTRUCTION="You are a security expert focused on finding vulnerabilities in code" ./cliGCP -mcpservers "./GlobTool;./GrepTool;./LS;./View;./Bash"'
To modify the default system instruction, edit the agent.go file:
// In host/cliGCP/cmd/agent.go
genaimodels[model].SystemInstruction = &genai.Content{
Role: "user",
Parts: []genai.Part{
genai.Text("You are a helpful agent with access to tools. " +
"Your job is to help the user by performing tasks using these tools. " +
"You should not make up information. " +
"If you don't know something, say so and explain what you would need to know to help. " +
"If not indication, use the current working directory which is " + cwd),
},
}
For different use cases, you can create specialized configuration scripts:
Create a file called code-reviewer.sh:
#!/bin/bash
export GCP_PROJECT=your-gcp-project-id
export GCP_REGION=us-central1
export GEMINI_MODELS=gemini-2.0-flash
export IMAGE_DIR=/tmp/images
export SYSTEM_INSTRUCTION="You are a code review expert. Analyze code for bugs, security issues, and areas for improvement. Focus on providing constructive feedback and detailed explanations."
cd /path/to/gomcptest/bin
./cliGCP -mcpservers "./GlobTool;./GrepTool;./LS;./View;./Bash"
Make it executable:
chmod +x code-reviewer.sh
Create a file called doc-generator.sh:
#!/bin/bash
export GCP_PROJECT=your-gcp-project-id
export GCP_REGION=us-central1
export GEMINI_MODELS=gemini-2.0-flash
export IMAGE_DIR=/tmp/images
export SYSTEM_INSTRUCTION="You are a documentation specialist. Your task is to help create clear, comprehensive documentation for code. Analyze code structure and create appropriate documentation following best practices."
cd /path/to/gomcptest/bin
./cliGCP -mcpservers "./GlobTool;./GrepTool;./LS;./View;./Bash;./Replace"
When using the dispatch_agent tool, you can configure its behavior with additional arguments:
./cliGCP -mcpservers "./GlobTool;./GrepTool;./LS;./View;./dispatch_agent -glob-path ./GlobTool -grep-path ./GrepTool -ls-path ./LS -view-path ./View -timeout 30s;./Bash;./Replace"
You can create specialized tool combinations for different tasks:
# Web development toolset
./cliGCP -mcpservers "./GlobTool -include '*.{html,css,js}';./GrepTool;./LS;./View;./Bash;./Replace"
# Go development toolset
./cliGCP -mcpservers "./GlobTool -include '*.go';./GrepTool;./LS;./View;./Bash;./Replace"
If you’re having trouble connecting to the Gemini model:
gcloud auth application-default print-access-token
gcloud services list --enabled | grep aiplatform
If tools are failing to execute:
For better performance:
This guide shows you how to set up and configure the gomcptest OpenAI-compatible server to work with big-AGI, a popular open-source web client for AI assistants.
big-AGI provides a polished, feature-rich web interface for interacting with AI models. By connecting it to the gomcptest OpenAI-compatible server, you get:
Clone the big-AGI repository:
git clone https://github.com/enricoros/big-agi.git
cd big-agi
Install dependencies:
npm install
Create a .env.local file for configuration:
cp .env.example .env.local
Edit the .env.local file to configure your gomcptest server connection:
# big-AGI configuration
# Your gomcptest OpenAI-compatible server URL
OPENAI_API_HOST=http://localhost:8080
# This can be any string since the gomcptest server doesn't use API keys
OPENAI_API_KEY=gomcptest-local-server
# Set this to true to enable the custom server
OPENAI_API_ENABLE_CUSTOM_PROVIDER=true
Start big-AGI:
npm run dev
Open your browser and navigate to http://localhost:3000 to access the big-AGI interface.
The gomcptest OpenAI-compatible server exposes Google Cloud models through an OpenAI-compatible API. In big-AGI, you’ll need to configure the models:
gemini-1.5-pro, gemini-2.0-flash)true for models that support itTo use the MCP tools through big-AGI’s function calling interface:
If you’re running big-AGI on a different domain or port than your gomcptest server, you’ll need to enable CORS on the server side. Edit the OpenAI server configuration:
Create or edit a CORS middleware for the OpenAI server:
// CORS middleware with specific origin allowance
func corsMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// Allow requests from big-AGI origin
w.Header().Set("Access-Control-Allow-Origin", "http://localhost:3000")
w.Header().Set("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
w.Header().Set("Access-Control-Allow-Headers", "Content-Type, Authorization")
if r.Method == "OPTIONS" {
w.WriteHeader(http.StatusOK)
return
}
next.ServeHTTP(w, r)
})
}
Apply this middleware to your server routes
If big-AGI reports that models cannot be found:
If tools aren’t working properly:
If big-AGI can’t connect to your server:
OPENAI_API_HOST value in your .env.local fileFor production use, consider:
Securing your API:
OPENAI_API_KEY in big-AGI accordinglyDeploying big-AGI:
Setting up HTTPS:
Once everything is set up, you can use big-AGI’s interface to interact with your AI models:
gemini-1.5-pro)The big-AGI interface provides a much richer experience than a command-line interface, with features like conversation history, markdown rendering, code highlighting, and more.