Reference

• 1: Tools Reference
• 2: OpenAI-Compatible Server Reference
• 3: cliGCP Reference

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.

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

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