Documentation

• 1: Tutorials
• 1.1: Getting Started with gomcptest
• 1.2: Building Your First OpenAI-Compatible Server
• 1.3: Using the cliGCP Command Line Interface
• 2: How-To Guides
• 2.1: How to Create a Custom MCP Tool
• 2.2: How to Configure the OpenAI-Compatible Server
• 2.3: How to Configure the cliGCP Command Line Interface
• 2.4: How to Use the OpenAI Server with big-AGI
• 3: Reference
• 3.1: Tools Reference
• 3.2: OpenAI-Compatible Server Reference
• 3.3: cliGCP Reference
• 4: Explanation
• 4.1: gomcptest Architecture
• 4.2: Understanding the Model Context Protocol (MCP)
• 4.3: Understanding the MCP Tools

1 - Tutorials

These tutorials will help you get familiar with gomcptest and its components.

1.1 - Getting Started with gomcptest

This tutorial will guide you through setting up the gomcptest system and configuring Google Cloud authentication for the project.

What is gomcptest?

gomcptest is a proof of concept (POC) implementation of the Model Context Protocol (MCP) with a custom-built host. It enables AI models like Google’s Gemini to interact with their environment through a set of tools, creating powerful agentic systems.

Key Components

The project consists of three main parts:

1. Host Components:

   • cliGCP: A command-line interface similar to Claude Code or ChatGPT, allowing direct interaction with AI models and tools
   • openaiserver: A server that implements the OpenAI API interface, enabling compatibility with existing OpenAI clients while using Google’s Vertex AI behind the scenes

2. MCP Tools:

   • Bash: Execute shell commands
   • Edit/Replace: Modify file contents
   • GlobTool/GrepTool: Find files and search content
   • LS/View: Navigate and read the filesystem
   • dispatch_agent: Create sub-agents with specific tasks
   • imagen: Generate and manipulate images using Google Imagen
   • duckdbserver: Process data using DuckDB

3. MCP Protocol: The standardized communication layer that allows models to discover, invoke, and receive results from tools

Use Cases

gomcptest enables a variety of agent-based applications:

• Code assistance and pair programming
• File system navigation and management
• Data analysis and processing
• Automated documentation
• Custom domain-specific agents

Prerequisites

• Go >= 1.21 installed on your system
• Google Cloud account with access to Vertex AI API
• Google Cloud CLI installed
• Basic familiarity with terminal/command line

Setting up Google Cloud Authentication

Before using gomcptest with Google Cloud Platform services like Vertex AI, you need to set up your authentication.

1. Initialize the Google Cloud CLI

If you haven’t already configured the Google Cloud CLI, run:

gcloud init

This interactive command will guide you through:

• Logging into your Google account
• Selecting a Google Cloud project
• Setting default configurations

2. Log in to Google Cloud

Authenticate your gcloud CLI with your Google account:

gcloud auth login

This will open a browser window where you can sign in to your Google account.

3. Set up Application Default Credentials (ADC)

Application Default Credentials are used by client libraries to automatically find credentials when connecting to Google Cloud services:

gcloud auth application-default login

This command will:

1. Open a browser window for authentication
2. Store your credentials locally (typically in ~/.config/gcloud/application_default_credentials.json)
3. Configure your environment to use these credentials when accessing Google Cloud APIs

These credentials will be used by gomcptest when interacting with Google Cloud services.

Project Setup

1. Clone the repository:

   git clone https://github.com/owulveryck/gomcptest.git
   cd gomcptest
   

2. Build All Components: Compile tools and servers using the root Makefile

   # Build all tools and servers
   make all
   
   # Or build only tools
   make tools
   
   # Or build only servers
   make servers
   

3. Choose Interface:

   • Run the OpenAI-compatible server: See the OpenAI Server Tutorial
   • Use the CLI directly: See the cliGCP Tutorial

What’s Next

After completing the basic setup:

• Explore the different tools in the tools directory
• Try creating agent tasks with gomcptest
• Check out the how-to guides for specific use cases

1.2 - Building Your First OpenAI-Compatible Server

This tutorial will guide you step-by-step through running and configuring the OpenAI-compatible server in gomcptest. By the end, you’ll have a working server that can communicate with LLM models and execute MCP tools.

Prerequisites

• Go >= 1.21 installed
• Access to Google Cloud Platform with Vertex AI API enabled
• GCP authentication set up via gcloud auth login
• Basic familiarity with terminal commands
• The gomcptest repository cloned and tools built (see the Getting Started guide)

Step 1: Set Up Environment Variables

The OpenAI server requires several environment variables. Create a .envrc file in the host/openaiserver directory:

cd host/openaiserver
touch .envrc

Add the following content to the .envrc file, adjusting the values according to your setup:

# Server configuration
PORT=8080
LOG_LEVEL=INFO

# GCP configuration
GCP_PROJECT=your-gcp-project-id
GCP_REGION=us-central1
GEMINI_MODELS=gemini-2.0-flash

Note: IMAGE_DIR and IMAGEN_MODELS environment variables are no longer needed for the openaiserver host. Image generation is now handled by the independent tools/imagen MCP server.

Load the environment variables:

source .envrc

Step 2: Start the OpenAI Server

Now you can start the OpenAI-compatible server:

cd host/openaiserver
go run . -mcpservers "../bin/GlobTool;../bin/GrepTool;../bin/LS;../bin/View;../bin/Bash;../bin/Replace"

You should see output indicating that the server has started and registered the MCP tools.

Step 3: Test the Server with a Simple Request

Open a new terminal window and use curl to test the server:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.0-flash",
    "messages": [
      {
        "role": "user",
        "content": "Hello, what can you do?"
      }
    ]
  }'

You should receive a response from the model explaining its capabilities.

Step 4: Test Function Calling

Now let’s test function calling by asking the model to list files in a directory:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.0-flash",
    "messages": [
      {
        "role": "user",
        "content": "List the files in the current directory"
      }
    ]
  }'

The model should respond by calling the LS tool and returning the results.

What You’ve Learned

In this tutorial, you’ve:

1. Set up the environment for the OpenAI-compatible server
2. Built and registered MCP tools
3. Started the server
4. Tested basic chat completion
5. Demonstrated function calling capabilities

Next Steps

Now that you have a working OpenAI-compatible server, you can:

• Explore the API by sending different types of requests
• Add custom tools to expand the server’s capabilities
• Connect a client like the cliGCP to interact with the server
• Experiment with different Gemini models

Check out the How to Configure the OpenAI Server guide for more advanced configuration options.

1.3 - Using the cliGCP Command Line Interface

This tutorial guides you through setting up and using the cliGCP command line interface to interact with LLMs and MCP tools. By the end, you’ll be able to run the CLI and perform basic tasks with it.

Prerequisites

• Go >= 1.21 installed on your system
• Access to Google Cloud Platform with Vertex AI API enabled
• GCP authentication set up via gcloud auth login
• The gomcptest repository cloned and tools built (see the Getting Started guide)

Step 1: Understand the cliGCP Tool

The cliGCP tool is a command-line interface similar to tools like Claude Code. It connects directly to the Google Cloud Platform’s Vertex AI API to access Gemini models and can use local MCP tools to perform actions on your system.

Step 2: Build the cliGCP Tool

First, build the cliGCP tool if you haven’t already:

cd gomcptest
make all  # This builds all tools including cliGCP

If you only want to build cliGCP, you can run:

cd host/cliGCP/cmd
go build -o ../../../bin/cliGCP

Step 3: Set Up Environment Variables

The cliGCP tool requires environment variables for GCP configuration. You can set these directly or create an .envrc file:

cd bin
touch .envrc

Add the following content to the .envrc file:

export GCP_PROJECT=your-gcp-project-id
export GCP_REGION=us-central1
export GEMINI_MODELS=gemini-2.0-flash

Note: IMAGEN_MODELS and IMAGE_DIR are no longer needed for the cliGCP host. Image generation is available through the independent tools/imagen MCP server.

Load the environment variables:

source .envrc

Step 4: Run the cliGCP Tool

Now you can run the cliGCP tool with MCP tools:

cd bin
./cliGCP -mcpservers "./GlobTool;./GrepTool;./LS;./View;./dispatch_agent -glob-path ./GlobTool -grep-path ./GrepTool -ls-path ./LS -view-path ./View;./Bash;./Replace"

You should see a welcome message and a prompt where you can start interacting with the CLI.

Step 5: Simple Queries

Let’s try a few simple interactions:

> Hello, who are you?

You should get a response introducing the agent.

Step 6: Using Tools

Now let’s try using some of the MCP tools:

> List the files in the current directory

The CLI should call the LS tool and show you the files in the current directory.

> Search for files with "go" in the name

The CLI will use the GlobTool to find files matching that pattern.

> Read the README.md file

The CLI will use the View tool to show you the contents of the README.md file.

Step 7: Creating a Simple Task

Let’s create a simple task that combines multiple tools:

> Create a new file called test.txt with the text "Hello, world!" and then verify it exists

The CLI should:

1. Use the Replace tool to create the file
2. Use the LS tool to verify the file exists
3. Use the View tool to show you the contents of the file

What You’ve Learned

In this tutorial, you’ve:

1. Set up the cliGCP environment
2. Run the CLI with MCP tools
3. Performed basic interactions with the CLI
4. Used various tools through the CLI to manipulate files
5. Created a simple workflow combining multiple tools

Next Steps

Now that you’re familiar with the cliGCP tool, you can:

• Explore more complex tasks that use multiple tools
• Try using the dispatch_agent for more complex operations
• Create custom tools and use them with the CLI
• Experiment with different Gemini models

Check out the How to Configure the cliGCP Tool guide for advanced configuration options.

2 - How-To Guides

These guides will help you solve specific tasks and customize gomcptest for your needs.

2.1 - How to Create a Custom MCP Tool

This guide shows you how to create a new custom tool that’s compatible with the Model Context Protocol (MCP) in gomcptest.

Prerequisites

• A working installation of gomcptest
• Go programming knowledge
• Understanding of the MCP protocol basics

Steps to create a custom tool

1. Create the tool directory structure

mkdir -p tools/YourToolName/cmd

2. Create the README.md file

Create a README.md in the tool directory with documentation:

touch tools/YourToolName/README.md

Include the following sections:

• Tool description
• Parameters
• Usage notes
• Example

3. Create the main.go file

Create a main.go file in the cmd directory:

touch tools/YourToolName/cmd/main.go

4. Implement the tool functionality

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",
	}
}

5. Add the tool to the Makefile

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.

6. Build your tool

make YourToolName

7. Test your tool

Test the tool directly:

echo '{"name":"YourToolName","params":{"input_param":"test"}}' | ./bin/YourToolName

8. Use with the CLI

Add your tool to the CLI command:

./bin/cliGCP -mcpservers "./GlobTool;./GrepTool;./LS;./View;./YourToolName;./dispatch_agent;./Bash;./Replace"

Tips for effective tool development

• Focus on a single, well-defined purpose
• Provide clear error messages
• Include meaningful response formatting
• Implement proper parameter validation
• Handle edge cases gracefully
• Consider adding unit tests in a _test.go file

2.2 - How to Configure the OpenAI-Compatible Server

This guide shows you how to configure and customize the OpenAI-compatible server in gomcptest for different use cases.

Prerequisites

• A working installation of gomcptest
• Basic familiarity with the OpenAI server from the tutorial
• Understanding of environment variables and configuration

Environment Variables Configuration

Basic Server Configuration

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

GCP Configuration

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

Note: IMAGEN_MODELS and IMAGE_DIR environment variables are no longer needed for the openaiserver. Image generation is now handled by the independent tools/imagen MCP server.

Setting Up a Production Environment

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=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

Configuring MCP Tools

Adding Custom Tools

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"

Tool Parameters and Arguments

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"

API Usage Configuration

Enabling CORS

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...
}

Setting Rate Limits

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...
}

Performance Tuning

Adjusting Memory Usage

For high-load scenarios, adjust Go’s garbage collector:

export GOGC=100  # Default is 100, lower values lead to more frequent GC

Increasing Concurrency

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...
}

Troubleshooting Common Issues

Debugging Connection Problems

If you’re experiencing connection issues, set the log level to DEBUG:

export LOG_LEVEL=DEBUG

Common Error Messages

• Failed to create MCP client: Ensure the tool path is correct and the tool is executable
• Failed to load GCP config: Check your GCP environment variables
• Error in LLM request: Verify your GCP credentials and project access

Checking Tool Registration

To verify tools are registered correctly, look for log messages like:

INFO server0 Registering command=../bin/GlobTool
INFO server1 Registering command=../bin/GrepTool

2.3 - How to Configure the cliGCP Command Line Interface

This guide shows you how to configure and customize the cliGCP command line interface for various use cases.

Prerequisites

• A working installation of gomcptest
• Basic familiarity with the cliGCP tool from the tutorial
• Understanding of environment variables and configuration

Command Line Arguments

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"

Environment Variables Configuration

GCP Configuration

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

Advanced Configuration

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

Creating Shell Aliases

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"'

Customizing the System Instruction

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),
    },
}

Creating Task-Specific Configurations

For different use cases, you can create specialized configuration scripts:

Code Review Helper

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

Documentation Generator

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"

Advanced Tool Configurations

Configuring dispatch_agent

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"

Creating Tool Combinations

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"

Troubleshooting Common Issues

Model Connection Issues

If you’re having trouble connecting to the Gemini model:

1. Verify your GCP credentials:

gcloud auth application-default print-access-token

2. Check that the Vertex AI API is enabled:

gcloud services list --enabled | grep aiplatform

3. Verify your project has access to the models you’re requesting

Tool Execution Failures

If tools are failing to execute:

1. Ensure the tool paths are correct
2. Verify the tools are executable
3. Check for permission issues in the directories you’re accessing

Performance Optimization

For better performance:

1. Use more specific tool patterns to reduce search scope
2. Consider creating specialized agents for different tasks
3. Set a lower temperature for more deterministic responses

2.4 - How to Use the OpenAI Server with big-AGI

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.

Prerequisites

• A working installation of gomcptest
• The OpenAI-compatible server running (see the OpenAI Server tutorial)
• Node.js (version 18.17.0 or newer)
• Git

Why Use big-AGI with gomcptest?

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:

• A professional web interface for your AI interactions
• Support for tools/function calling
• Conversation history management
• Persona management
• Image generation capabilities
• Multiple user support

Setting Up big-AGI

1. Clone the big-AGI repository:

   git clone https://github.com/enricoros/big-agi.git
   cd big-agi
   

2. Install dependencies:

   npm install
   

3. Create a .env.local file for configuration:

   cp .env.example .env.local
   

4. 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
   

5. Start big-AGI:

   npm run dev
   

6. Open your browser and navigate to http://localhost:3000 to access the big-AGI interface.

Configuring big-AGI to Use Your Models

The gomcptest OpenAI-compatible server exposes Google Cloud models through an OpenAI-compatible API. In big-AGI, you’ll need to configure the models:

1. Open big-AGI in your browser
2. Click on the Settings icon (gear) in the top right
3. Go to the Models tab
4. Under “OpenAI Models”:
   • Click “Add Models”
   • Add your models by ID (e.g., gemini-1.5-pro, gemini-2.0-flash)
   • Set context length appropriately (8K-32K depending on the model)
   • Set function calling capability to true for models that support it

Enabling Function Calling with Tools

To use the MCP tools through big-AGI’s function calling interface:

1. In big-AGI, click on the Settings icon
2. Go to the Advanced tab
3. Enable “Function Calling” under the “Experimental Features” section
4. In a new chat, click on the “Functions” tab (plugin icon) in the chat interface
5. The available tools from your gomcptest server should be listed

Configuring CORS for big-AGI

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:

1. 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)
       })
   }
   

2. Apply this middleware to your server routes

Troubleshooting Common Issues

Model Not Found

If big-AGI reports that models cannot be found:

1. Verify your gomcptest server is running and accessible
2. Check the server logs to ensure models are properly registered
3. Make sure the model IDs in big-AGI match exactly the ones provided by your gomcptest server

Function Calling Not Working

If tools aren’t working properly:

1. Ensure the tools are properly registered in your gomcptest server
2. Check that function calling is enabled in big-AGI settings
3. Verify the model you’re using supports function calling

Connection Issues

If big-AGI can’t connect to your server:

1. Verify the OPENAI_API_HOST value in your .env.local file
2. Check for CORS issues in your browser’s developer console
3. Ensure your server is running and accessible from the browser

Production Deployment

For production use, consider:

1. Securing your API:

   • Add proper authentication to your gomcptest OpenAI server
   • Update the OPENAI_API_KEY in big-AGI accordingly

2. Deploying big-AGI:

   • Follow the big-AGI deployment guide
   • Configure the environment variables to point to your production gomcptest server

3. Setting up HTTPS:

   • For production, both big-AGI and your gomcptest server should use HTTPS
   • Consider using a reverse proxy like Nginx with Let’s Encrypt certificates

Example: Basic Chat Interface

Once everything is set up, you can use big-AGI’s interface to interact with your AI models:

1. Start a new chat
2. Select your model from the model dropdown (e.g., gemini-1.5-pro)
3. Enable function calling if you want to use tools
4. Begin chatting with your AI assistant, powered by gomcptest

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.

3 - Reference

This section provides detailed technical documentation on gomcptest’s components, APIs, parameters, and tools.

3.1 - Tools Reference

Bash

Executes bash commands in a persistent shell session.

Parameters

Response

The tool returns the command output as a string.

Banned Commands

For security reasons, the following commands are banned: alias, curl, curlie, wget, axel, aria2c, nc, telnet, lynx, w3m, links, httpie, xh, http-prompt, chrome, firefox, safari

Edit

Modifies file content by replacing specified text.

Parameters

Response

Confirmation message with the updated content.

GlobTool

Finds files matching glob patterns with metadata.

Parameters

Response

A list of matching files with metadata including path, size, modification time, and permissions.

GrepTool

Searches file contents using regular expressions.

Parameters

Response

A list of matches with file paths, line numbers, and matched content.

LS

Lists files and directories in a given path.

Parameters

Response

A list of files and directories with metadata.

Replace

Completely replaces a file’s contents.

Parameters

Response

Confirmation message with the content written.

View

Reads file contents with optional line range.

Parameters

Response

The file content with line numbers in cat -n format.

dispatch_agent

Launches a new agent with access to specific tools.

Parameters

Response

The result of the agent’s task execution.

imagen

Generates and manipulates images using Google’s Imagen API.

Parameters

Response

Returns a JSON object with the generated image path and metadata.

duckdbserver

Provides data processing capabilities using DuckDB.

Parameters

Response

Query results in JSON format.

Tool Response Format

Most tools return JSON responses with the following structure:

{
  "result": "...", // String result or
  "results": [...], // Array of results
  "error": "..." // Error message if applicable
}

Error Handling

All tools follow a consistent error reporting format:

{
  "error": "Error message",
  "code": "ERROR_CODE"
}

Common error codes include:

• INVALID_PARAMS: Parameters are missing or invalid
• EXECUTION_ERROR: Error executing the requested operation
• PERMISSION_DENIED: Permission issues
• TIMEOUT: Operation timed out

3.2 - OpenAI-Compatible Server Reference

Overview

The OpenAI-compatible server is a core component of the gomcptest system. It implements an API surface compatible with the OpenAI Chat Completions API while connecting to Google’s Vertex AI for model inference. The server acts as a bridge between clients (like the cliGCP tool) and the underlying LLM models, handling session management, function calling, and tool execution.

API Endpoints

POST /v1/chat/completions

The primary endpoint that mimics the OpenAI Chat Completions API.

Request

{
  "model": "gemini-pro",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello, world!"}
  ],
  "stream": true,
  "max_tokens": 1024,
  "temperature": 0.7,
  "functions": [
    {
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA"
          }
        },
        "required": ["location"]
      }
    }
  ]
}

Response (non-streamed)

{
  "id": "chatcmpl-123456789",
  "object": "chat.completion",
  "created": 1677858242,
  "model": "gemini-pro",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop",
      "index": 0
    }
  ],
  "usage": {
    "prompt_tokens": 13,
    "completion_tokens": 7,
    "total_tokens": 20
  }
}

Response (streamed)

When stream is set to true, the server returns a stream of SSE (Server-Sent Events) with partial responses:

data: {"id":"chatcmpl-123456789","object":"chat.completion.chunk","created":1677858242,"model":"gemini-pro","choices":[{"delta":{"role":"assistant"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-123456789","object":"chat.completion.chunk","created":1677858242,"model":"gemini-pro","choices":[{"delta":{"content":"Hello"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-123456789","object":"chat.completion.chunk","created":1677858242,"model":"gemini-pro","choices":[{"delta":{"content":"!"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-123456789","object":"chat.completion.chunk","created":1677858242,"model":"gemini-pro","choices":[{"delta":{"content":" How"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-123456789","object":"chat.completion.chunk","created":1677858242,"model":"gemini-pro","choices":[{"delta":{},"index":0,"finish_reason":"stop"}]}

data: [DONE]

Supported Features

Models

The server supports the following Vertex AI models:

• gemini-pro
• gemini-pro-vision

Parameters

Function Calling

The server supports function calling similar to the OpenAI API. When the model identifies that a function should be called, the server:

1. Parses the function call parameters
2. Locates the appropriate MCP tool
3. Executes the tool with the provided parameters
4. Returns the result to the model for further processing

Architecture

The server consists of these key components:

HTTP Server

A standard Go HTTP server that handles incoming requests and routes them to the appropriate handlers.

Session Manager

Maintains chat history and context for ongoing conversations. Ensures that the model has necessary context when generating responses.

Vertex AI Client

Communicates with Google’s Vertex AI API to:

• Send prompt templates to the model
• Receive completions from the model
• Stream partial responses back to the client

MCP Tool Manager

Manages the available MCP tools and handles:

• Tool registration and discovery
• Parameter validation
• Tool execution
• Response processing

Response Streamer

Handles streaming responses to clients in SSE format, ensuring low latency and progressive rendering.

Configuration

The server can be configured using environment variables:

Error Handling

The server implements consistent error handling with HTTP status codes:

Error responses follow this format:

{
  "error": {
    "message": "Detailed error message",
    "type": "error_type",
    "param": "parameter_name",
    "code": "error_code"
  }
}

Security Considerations

The server does not implement authentication or authorization by default. In production deployments, consider:

• Running behind a reverse proxy with authentication
• Using API keys or OAuth2
• Implementing rate limiting
• Setting up proper firewall rules

Examples

Basic Usage

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credentials.json"
export GOOGLE_CLOUD_PROJECT="your-project-id"
./bin/openaiserver

With Custom Tools

export MCP_TOOLS_PATH="/path/to/tools"
./bin/openaiserver

Client Connection

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-pro",
    "messages": [{"role": "user", "content": "Hello, world!"}]
  }'

Limitations

• Single chat session support only
• No persistent storage of conversations
• Limited authentication options
• Basic rate limiting
• Limited model parameter controls

Advanced Usage

Tool Registration

Tools are automatically registered when the server starts. To register custom tools:

1. Place executable files in the MCP_TOOLS_PATH directory
2. Ensure they follow the MCP protocol
3. Restart the server

Streaming with Function Calls

When using function calling with streaming, the stream will pause during tool execution and resume with the tool results included in the context.

3.3 - cliGCP Reference

Overview

The cliGCP (Command Line Interface for Google Cloud Platform) is a command-line tool that provides a chat interface similar to tools like “Claude Code” or “ChatGPT”. It connects to an OpenAI-compatible server and allows users to interact with LLMs and MCP tools through a conversational interface.

Command Structure

Basic Usage

./bin/cliGCP [flags]

Flags

Example

./bin/cliGCP -mcpservers "./bin/Bash;./bin/View;./bin/GlobTool;./bin/GrepTool;./bin/LS;./bin/Edit;./bin/Replace;./bin/dispatch_agent" -server "http://localhost:8080" -model "gemini-pro" -prompt "You are a helpful command-line assistant."

Components

Chat Interface

The chat interface provides:

• Text-based input for user messages
• Markdown rendering of AI responses
• Real-time streaming of responses
• Input history and navigation
• Multi-line input support

MCP Tool Manager

The tool manager:

• Loads and initializes MCP tools
• Registers tools with the OpenAI-compatible server
• Routes function calls to appropriate tools
• Processes tool results

Session Manager

The session manager:

• Maintains chat history within the session
• Handles context windowing for long conversations
• Optionally persists conversations to disk
• Provides conversation resume functionality

Interaction Patterns

Basic Chat

The most common interaction pattern is a simple turn-based chat:

1. User enters a message
2. Model generates and streams a response
3. Chat history is updated
4. User enters the next message

Function Calling

When the model determines a function should be called:

1. User enters a message requesting an action (e.g., “List files in /tmp”)
2. Model analyzes the request and generates a function call
3. cliGCP intercepts the function call and routes it to the appropriate tool
4. Tool executes and returns results
5. Results are injected back into the model’s context
6. Model continues generating a response that incorporates the tool results
7. The complete response is shown to the user

Multi-turn Function Calling

For complex tasks, the model may make multiple function calls:

1. User requests a complex task (e.g., “Find all Python files containing ’error’”)
2. Model makes a function call to list directories
3. Tool returns directory listing
4. Model makes additional function calls to search file contents
5. Each tool result is returned to the model
6. Model synthesizes the information and responds to the user

Technical Details

Message Format

Messages between cliGCP and the server follow the OpenAI Chat API format:

{
  "role": "user"|"assistant"|"system",
  "content": "Message text"
}

Function calls use this format:

{
  "role": "assistant",
  "content": null,
  "function_call": {
    "name": "function_name",
    "arguments": "{\"arg1\":\"value1\",\"arg2\":\"value2\"}"
  }
}

Tool Registration

Tools are registered with the server using JSONSchema:

{
  "name": "tool_name",
  "description": "Tool description",
  "parameters": {
    "type": "object",
    "properties": {
      "param1": {
        "type": "string",
        "description": "Parameter description"
      }
    },
    "required": ["param1"]
  }
}

Error Handling

The CLI implements robust error handling for:

• Connection issues with the server
• Tool execution failures
• Model errors
• Input validation

Error messages are displayed to the user with context and possible solutions.

Configuration

Environment Variables

Configuration File

You can create a ~/.cligcp.json configuration file with these settings:

{
  "server": "http://localhost:8080",
  "model": "gemini-pro",
  "prompt": "You are a helpful assistant.",
  "temperature": 0.7,
  "max_tokens": 1024,
  "tools": [
    "./bin/Bash",
    "./bin/View",
    "./bin/GlobTool"
  ]
}

Advanced Usage

Persistent History

To save and load chat history:

./bin/cliGCP -history ./chat_history.json

Custom System Prompt

To set a specific system prompt:

./bin/cliGCP -prompt "You are a Linux command-line expert that helps users with shell commands and filesystem operations."

Combining with Shell Scripts

You can use cliGCP in shell scripts by piping input and capturing output:

echo "Explain how to find large files in Linux" | ./bin/cliGCP -noninteractive

Limitations

• Single conversation per instance
• Limited rendering capabilities for complex markdown
• No built-in authentication management
• Limited offline functionality
• No multi-modal input support (e.g., images)

Troubleshooting

Common Issues

Diagnostic Mode

Run with the -verbose flag to enable detailed logging:

./bin/cliGCP -verbose

This will show all API requests, responses, and tool interactions, which can be helpful for debugging.

4 - Explanation

This section provides deeper background on how gomcptest works, its architecture, and the concepts behind it.

4.1 - gomcptest Architecture

The Big Picture

The gomcptest project implements a custom host that provides a Model Context Protocol (MCP) implementation. It’s designed to enable testing and experimentation with agentic systems without requiring direct integration with commercial LLM platforms.

The system is built with these key principles in mind:

• Modularity: Components are designed to be interchangeable
• Compatibility: The API mimics the OpenAI API for easy integration
• Extensibility: New tools can be easily added to the system
• Testing: The architecture facilitates testing of agentic applications

Core Components

Host (OpenAI Server)

The host is the central component, located in /host/openaiserver. It presents an OpenAI-compatible API interface and connects to Google’s Vertex AI for model inference. This compatibility layer makes it easy to integrate with existing tools and libraries designed for OpenAI.

The host has several key responsibilities:

1. API Compatibility: Implementing the OpenAI chat completions API
2. Session Management: Maintaining chat history and context
3. Model Integration: Connecting to Vertex AI’s Gemini models
4. Function Calling: Orchestrating function/tool calls based on model outputs
5. Response Streaming: Supporting streaming responses to the client

Unlike commercial implementations, this host is designed for local development and testing, emphasizing flexibility and observability over production-ready features like authentication or rate limiting.

MCP Tools

The tools are standalone executables that implement the Model Context Protocol. Each tool is designed to perform a specific function, such as executing shell commands or manipulating files.

Tools follow a consistent pattern:

• They communicate via standard I/O using the MCP JSON-RPC protocol
• They expose a specific set of parameters
• They handle their own error conditions
• They return results in a standardized format

This approach allows tools to be:

• Developed independently
• Tested in isolation
• Used in different host environments
• Chained together in complex workflows

CLI

The CLI provides a user interface similar to tools like “Claude Code” or “OpenAI ChatGPT”. It connects to the OpenAI-compatible server and provides a way to interact with the LLM and tools through a conversational interface.

Data Flow

1. The user sends a request to the CLI
2. The CLI forwards this request to the OpenAI-compatible server
3. The server sends the request to Vertex AI’s Gemini model
4. The model may identify function calls in its response
5. The server executes these function calls by invoking the appropriate MCP tools
6. The results are provided back to the model to continue its response
7. The final response is streamed back to the CLI and presented to the user

Design Decisions Explained

Why OpenAI API Compatibility?

The OpenAI API has become a de facto standard in the LLM space. By implementing this interface, gomcptest can work with a wide variety of existing tools, libraries, and frontends with minimal adaptation.

Why Google Vertex AI?

Vertex AI provides access to Google’s Gemini models, which have strong function calling capabilities. The implementation could be extended to support other model providers as needed.

Why Standalone Tools?

By implementing tools as standalone executables rather than library functions, we gain several advantages:

• Security through isolation
• Language agnosticism (tools can be written in any language)
• Ability to distribute tools separately from the host
• Easier testing and development

Why MCP?

The Model Context Protocol provides a standardized way for LLMs to interact with external tools. By adopting this protocol, gomcptest ensures compatibility with tools developed for other MCP-compatible hosts.

Limitations and Future Directions

The current implementation has several limitations:

• Single chat session per instance
• Limited support for authentication and authorization
• No persistence of chat history between restarts
• No built-in support for rate limiting or quotas

Future enhancements could include:

• Support for multiple chat sessions
• Integration with additional model providers
• Enhanced security features
• Improved error handling and logging
• Performance optimizations for large-scale deployments

Conclusion

The gomcptest architecture represents a flexible and extensible approach to building custom MCP hosts. It prioritizes simplicity, modularity, and developer experience, making it an excellent platform for experimentation with agentic systems.

By understanding this architecture, developers can effectively utilize the system, extend it with new tools, and potentially adapt it for their specific needs.

4.2 - Understanding the Model Context Protocol (MCP)

What is the Model Context Protocol?

The Model Context Protocol (MCP) is a standardized communication protocol that enables Large Language Models (LLMs) to interact with external tools and capabilities. It defines a structured way for models to request information or take actions in the real world, and for tools to provide responses back to the model.

MCP is designed to solve the problem of extending LLMs beyond their training data by giving them access to:

• Current information (e.g., via web search)
• Computational capabilities (e.g., calculators, code execution)
• External systems (e.g., databases, APIs)
• User environment (e.g., file system, terminal)

How MCP Works

At its core, MCP is a protocol based on JSON-RPC that enables bidirectional communication between LLMs and tools. The basic workflow is:

1. The LLM generates a call to a tool with specific parameters
2. The host intercepts this call and routes it to the appropriate tool
3. The tool executes the requested action and returns the result
4. The result is injected into the model’s context
5. The model continues generating a response incorporating the new information

The protocol specifies:

• How tools declare their capabilities and parameters
• How the model requests tool actions
• How tools return results or errors
• How multiple tools can be combined

MCP in gomcptest

In gomcptest, MCP is implemented using a set of independent executables that communicate over standard I/O. This approach has several advantages:

• Language-agnostic: Tools can be written in any programming language
• Process isolation: Each tool runs in its own process for security and stability
• Compatibility: The protocol works with various LLM providers
• Extensibility: New tools can be easily added to the system

Each tool in gomcptest follows a consistent pattern:

1. It receives a JSON request on stdin
2. It parses the parameters and performs its action
3. It formats the result as JSON and returns it on stdout

The Protocol Specification

The core MCP protocol in gomcptest follows this format:

Tool Registration

Tools register themselves with a schema that defines their capabilities:

{
  "name": "ToolName",
  "description": "Description of what the tool does",
  "parameters": {
    "type": "object",
    "properties": {
      "param1": {
        "type": "string",
        "description": "Description of parameter 1"
      },
      "param2": {
        "type": "number",
        "description": "Description of parameter 2"
      }
    },
    "required": ["param1"]
  }
}

Function Call Request

When a model wants to use a tool, it generates a function call like:

{
  "name": "ToolName",
  "params": {
    "param1": "value1",
    "param2": 42
  }
}

Function Call Response

The tool executes the requested action and returns:

{
  "result": "Output of the tool's execution"
}

Or, in case of an error:

{
  "error": {
    "message": "Error message",
    "code": "ERROR_CODE"
  }
}

Design Decisions in MCP

Several key design decisions shape the MCP implementation in gomcptest:

Standard I/O Communication

By using stdin/stdout for communication, tools can be written in any language that can read from stdin and write to stdout. This makes it easy to integrate existing utilities and libraries.

JSON Schema for Tool Definition

Using JSON Schema for tool definitions provides a clear contract between the model and the tools. It enables:

• Validation of parameters
• Documentation of capabilities
• Potential for automatic code generation

Stateless Design

Tools are designed to be stateless, with each invocation being independent. This simplifies the protocol and makes tools easier to reason about and test.

Pass-through Authentication

The protocol doesn’t handle authentication directly; instead, it relies on the host to manage permissions and authentication. This separation of concerns keeps the protocol simple.

Comparison with Alternatives

vs. OpenAI Function Calling

MCP is similar to OpenAI’s function calling feature but with these key differences:

• MCP is designed to be provider-agnostic
• MCP tools run as separate processes
• MCP provides more detailed error handling

vs. LangChain Tools

Compared to LangChain:

• MCP is a lower-level protocol rather than a framework
• MCP focuses on interoperability rather than abstraction
• MCP allows for stronger process isolation

vs. Agent Protocols

Other agent protocols often focus on higher-level concepts like goals and planning, while MCP focuses specifically on the mechanics of tool invocation.

Future Directions

The MCP protocol in gomcptest could evolve in several ways:

• Enhanced security: More granular permissions and sand-boxing
• Streaming responses: Support for tools that produce incremental results
• Bidirectional communication: Supporting tools that can request clarification
• Tool composition: First-class support for chaining tools together
• State management: Optional session state for tools that need to maintain context

Conclusion

The Model Context Protocol as implemented in gomcptest represents a pragmatic approach to extending LLM capabilities through external tools. Its simplicity, extensibility, and focus on interoperability make it a solid foundation for building and experimenting with agentic systems.

By understanding the protocol, developers can create new tools that seamlessly integrate with the system, unlocking new capabilities for LLM applications.

4.3 - Understanding the MCP Tools

What are MCP Tools?

MCP (Model Context Protocol) tools are standalone executables that provide specific functions that can be invoked by AI models. They allow the AI to interact with its environment - performing tasks like reading and writing files, executing commands, or searching for information.

In gomcptest, tools are implemented as independent Go executables that follow a standard protocol for receiving requests and returning results through standard input/output streams.

Tool Architecture

Each tool in gomcptest follows a consistent architecture:

1. Standard I/O Interface: Tools communicate via stdin/stdout using JSON-formatted requests and responses
2. Parameter Validation: Tools validate their input parameters according to a JSON schema
3. Stateless Execution: Each tool invocation is independent and does not maintain state
4. Controlled Access: Tools implement appropriate security measures and permission checks
5. Structured Results: Results are returned in a standardized JSON format

Common Components

Most tools share these common components:

• Main Function: Parses JSON input, validates parameters, executes the core function, formats and returns the result
• Parameter Structure: Defines the expected input parameters for the tool
• Result Structure: Defines the format of the tool’s output
• Error Handling: Standardized error reporting and handling
• Security Checks: Validation to prevent dangerous operations

Tool Categories

The tools in gomcptest can be categorized into several functional groups:

Filesystem Navigation

• LS: Lists files and directories, providing metadata and structure
• GlobTool: Finds files matching specific patterns, making it easier to locate relevant files
• GrepTool: Searches file contents using regular expressions, helping find specific information in codebases

Content Management

• View: Reads and displays file contents, allowing the model to analyze existing code or documentation
• Edit: Makes targeted modifications to files, enabling precise changes without overwriting the entire file
• Replace: Completely overwrites file contents, useful for generating new files or making major changes

System Interaction

• Bash: Executes shell commands, allowing the model to run commands, scripts, and programs
• dispatch_agent: A meta-tool that can create specialized sub-agents for specific tasks

AI/ML Services

• imagen: Generates and manipulates images using Google’s Imagen API, enabling visual content creation

Data Processing

• duckdbserver: Provides SQL-based data processing capabilities using DuckDB, enabling complex data analysis and transformations

Design Principles

The tools in gomcptest were designed with several key principles in mind:

1. Modularity

Each tool is a standalone executable that can be developed, tested, and deployed independently. This modular approach allows for:

• Independent development cycles
• Targeted testing
• Simpler debugging
• Ability to add or replace tools without affecting the entire system

2. Security

Security is a major consideration in the tool design:

• Tools validate inputs to prevent injection attacks
• File operations are limited to appropriate directories
• Bash command execution is restricted with banned commands
• Timeouts prevent infinite operations
• Process isolation prevents one tool from affecting others

3. Simplicity

The tools are designed to be simple to understand and use:

• Clear, focused functionality for each tool
• Straightforward parameter structures
• Consistent result formats
• Well-documented behaviors and limitations

4. Extensibility

The system is designed to be easily extended:

• New tools can be added by following the standard protocol
• Existing tools can be enhanced with additional parameters
• Alternative implementations can replace existing tools

Tool Protocol Details

The communication protocol for tools follows this pattern:

Input Format

Tools receive JSON input on stdin in this format:

{
  "param1": "value1",
  "param2": "value2",
  "param3": 123
}

Output Format

Tools return JSON output on stdout in one of these formats:

Success:

{
  "result": "text result"
}

or

{
  "results": [
    {"field1": "value1", "field2": "value2"},
    {"field1": "value3", "field2": "value4"}
  ]
}

Error:

{
  "error": "Error message",
  "code": "ERROR_CODE"
}

Implementation Examples

Basic Tool Structure

Most tools follow this basic structure:

package main

import (
	"encoding/json"
	"fmt"
	"os"
)

// Parameters defines the expected input structure
type Parameters struct {
	Param1 string `json:"param1"`
	Param2 int    `json:"param2,omitempty"`
}

// Result defines the output structure
type Result struct {
	Result  string `json:"result,omitempty"`
	Error   string `json:"error,omitempty"`
	Code    string `json:"code,omitempty"`
}

func main() {
	// Parse input
	var params Parameters
	decoder := json.NewDecoder(os.Stdin)
	if err := decoder.Decode(&params); err != nil {
		outputError("Failed to parse input", "INVALID_INPUT")
		return
	}

	// Validate parameters
	if params.Param1 == "" {
		outputError("param1 is required", "MISSING_PARAMETER")
		return
	}

	// Execute core functionality
	result, err := executeTool(params)
	if err != nil {
		outputError(err.Error(), "EXECUTION_ERROR")
		return
	}

	// Return result
	output := Result{Result: result}
	encoder := json.NewEncoder(os.Stdout)
	encoder.Encode(output)
}

func executeTool(params Parameters) (string, error) {
	// Tool-specific logic here
	return "result", nil
}

func outputError(message, code string) {
	result := Result{
		Error: message,
		Code:  code,
	}
	encoder := json.NewEncoder(os.Stdout)
	encoder.Encode(result)
}

Advanced Concepts

Tool Composition

The dispatch_agent tool demonstrates how tools can be composed to create more powerful capabilities. It:

1. Accepts a high-level task description
2. Plans a sequence of tool operations to accomplish the task
3. Executes these operations using the available tools
4. Synthesizes the results into a coherent response

Error Propagation

The tool error mechanism is designed to provide useful information back to the model:

• Error messages are human-readable and descriptive
• Error codes allow programmatic handling of specific error types
• Stacktraces and debugging information are not exposed to maintain security

Performance Considerations

Tools are designed with performance in mind:

• File operations use efficient libraries and patterns
• Search operations employ indexing and filtering when appropriate
• Large results can be paginated or truncated to prevent context overflows
• Resource-intensive operations have configurable timeouts

Future Directions

The tool architecture in gomcptest could evolve in several ways:

1. Streaming Results: Supporting incremental results for long-running operations
2. Tool Discovery: More sophisticated mechanisms for models to discover available tools
3. Tool Chaining: First-class support for composing multiple tools in sequences or pipelines
4. Interactive Tools: Tools that can engage in multi-step interactions with the model
5. Persistent State: Optional state maintenance for tools that benefit from context

Conclusion

The MCP tools in gomcptest provide a flexible, secure, and extensible foundation for enabling AI agents to interact with their environment. By understanding the architecture and design principles of these tools, developers can effectively utilize the existing tools, extend them with new capabilities, or create entirely new tools that integrate seamlessly with the system.