Speelka Agent

Universal LLM agent based on Model Context Protocol (MCP) with support for external tools, flexible configuration, and extensible logging.

Key Features

• Multi-agent orchestration: Supports tools from other MCP servers.
• Flexible configuration: YAML, JSON, environment variables, overlay, and property-based overlay.
• Extensible logging: Centralized LogConfig, output to stdout, stderr, file, MCP protocol, custom/json/text formats.
• Security: Key isolation, log protection, tool access control.
• Testing: Golden serialization tests, property-based overlay, unit/integration/E2E.
• Scalability: HTTP and stdio support, dynamic tool/session management.

Architecture

• All components are interface-driven, tested, and follow single-responsibility.
• See documents/architecture.md for details.

Example Configuration (YAML)

runtime:
  log:
    defaultLevel: info
    output: ':mcp:'
    format: json
  transports:
    stdio:
      enabled: true
      buffer_size: 1024
    http:
      enabled: false
      host: localhost
      port: 3000
agent:
  name: "speelka-agent"
  version: "v1.0.0"
  tool:
    name: "process"
    description: "Process tool for user queries"
    argument_name: "input"
    argument_description: "User query"
  chat:
    max_tokens: 0
    max_llm_iterations: 25
    request_budget: 0.0
  llm:
    provider: "openai"
    apiKey: "dummy-api-key"
    model: "gpt-4o"
    temperature: 0.7
    promptTemplate: "You are a helpful assistant. {{input}}. Available tools: {{tools}}"
    retry:
      max_retries: 3
      initial_backoff: 1.0
      max_backoff: 30.0
      backoff_multiplier: 2.0
  connections:
    mcpServers:
      time:
        command: "docker"
        args: ["run", "-i", "--rm", "mcp/time"]
        timeout: 10
      filesystem:
        command: "mcp-filesystem-server"
        args: ["/path/to/directory"]
    retry:
      max_retries: 2
      initial_backoff: 1.5
      max_backoff: 10.0
      backoff_multiplier: 2.5

Logging

• Managed via LogConfig: level, format, output (stdout, stderr, file, MCP).
• MCP logs available via protocol or fallback to stderr (for stdio servers).
• Formats: custom, json, text, unknown.
• See documents/architecture.md and documents/implementation.md for details.

Testing

• Unit, integration, E2E.
• Property-based overlay tests (edge-cases, map merge, zero-value preservation).
• Test examples: documents/implementation.md.

Project Structure

• See documents/file_structure.md for details.
• Key directories: internal/agent, internal/logger, internal/mcp_connector, internal/types.

Quick Start

1. Clone the repository and build the agent:

   git clone https://github.com/korchasa/speelka-agent-go.git
   cd speelka-agent-go
   go build ./cmd/server
   

2. Prepare a config (see example above) or use environment variables (SPL_...).
3. Run the agent:
   • HTTP mode: ./speelka-agent --daemon [--config config.yaml]
   • CLI/stdio: ./speelka-agent [--config config.yaml]

Documentation

• Architecture: documents/architecture.md
• Implementation & tests: documents/implementation.md
• File structure: documents/file_structure.md
• External resources: documents/remote_resources.md

---

For overlay, MCP logs, tests, and structure details, see the documentation in the documents/ folder.

flowchart TB
    User["Any MCP Client"] --> |"1.Request"| Agent["Speelka Agent"]
    Agent --> |"2.Format prompt"| LLM["LLM Service"]
    LLM --> |"3.Tool calls"| Agent
    Agent --> |"4.Execute tools"| Tools["External MCP Tools"]
    Tools --> |"5.Return results"| Agent
    Agent --> |"6.Process repeat"| LLM
    Agent --> |"7.Final answer"| User

Use Cases

• Improve accuracy by splitting large, complex instructions into specialized, focused tasks.
• Reduce cost by using different models for different task parts.
• Extend, narrow, or modify third-party MCP server responses.
• Switch between "real" and LLM-based tool implementations easily.
• Restrict capabilities by limiting available tools in an MCP server.
• Orchestrate multi-step workflows across multiple MCP tools in a single session.
• Enforce per-request token and cost budgets for predictable usage.
• Automatic retry and exponential backoff for transient LLM or MCP server errors.
• Seamless provider switching between LLM services (OpenAI, Anthropic) via unified config.

Key Features

• Precise Agent Definition: Define agent behavior via prompt engineering
• Client-Side Context Optimization: Reduce context size for efficient token usage
• LLM Flexibility: Use different LLM providers on client and agent sides
• Centralized Tool Management: Single control point for all tools
• Multiple Integration Options: MCP stdio, MCP HTTP, Simple HTTP API
• Built-in Reliability: Retry mechanisms for transient failures
• Extensibility: Extend system behavior without client changes
• MCP-Aware Logging: Structured logging with MCP notifications
• Token Management: Automatic token counting
• Flexible Configuration: Environment variables, YAML, JSON
• LLMService.SendRequest returns an LLMResponse struct with:
  • Response text
  • List of tool calls
  • CompletionTokens, PromptTokens, ReasoningTokens, TotalTokens (token usage)
• Interface: SendRequest(ctx, messages, tools) (LLMResponse, error)

Getting Started

Prerequisites

• Go 1.19 or higher
• LLM API credentials (OpenAI or Anthropic)
• External MCP tools (optional)

Installation

git clone https://github.com/korchasa/speelka-agent-go.git
cd speelka-agent-go
go build ./cmd/server

Configuration

Configuration can be provided using YAML, JSON, or environment variables.

Note: The ./examples directory is deprecated. Use examples in ./site/examples instead.

Example configuration files are in site/examples:

• site/examples/minimal.yaml: Basic agent config (YAML)
• site/examples/ai-news.yaml: AI news agent config (YAML)
• site/examples/architect.yaml: Architect agent config (YAML)

Simple YAML config example:

agent:
  name: "simple-speelka-agent"
  version: "1.0.0"
  tool:
    name: "process"
    description: "Process tool for handling user queries with LLM"
    argument_name: "input"
    argument_description: "The user query to process"
  llm:
    provider: "openai"
    apiKey: ""  # Set via environment variable for security
    model: "gpt-4o"
    temperature: 0.7
    promptTemplate: "You are a helpful AI assistant. Respond to the following request: {{input}}. Provide a detailed and helpful response. Available tools: {{tools}}"
  chat:
    max_tokens: 0
    max_llm_iterations: 25
    request_budget: 0.0
  connections:
    mcpServers:
      time:
        command: "docker"
        args: ["run", "-i", "--rm", "mcp/time"]
        includeTools:
          - now
          - utc
      filesystem:
        command: "mcp-filesystem-server"
        args: ["/path/to/directory"]
        excludeTools:
          - delete
runtime:
  log:
    level: "info"
  transports:
    stdio:
      enabled: true

Using Environment Variables

All environment variables are prefixed with SPL_:

Environment Variable	Default Value	Description
Agent Configuration
SPL_AGENT_NAME	Required	Name of the agent
SPL_AGENT_VERSION	"1.0.0"	Version of the agent
Tool Configuration
SPL_AGENT_TOOL_NAME	Required	Name of the tool provided by the agent
SPL_AGENT_TOOL_DESCRIPTION	Required	Description of the tool functionality
SPL_AGENT_TOOL_ARGUMENT_NAME	Required	Name of the argument for the tool
SPL_AGENT_TOOL_ARGUMENT_DESCRIPTION	Required	Description of the argument for the tool
LLM Configuration
SPL_AGENT_LLM_PROVIDER	Required	Provider of LLM service (e.g., "openai", "anthropic")
SPL_AGENT_LLM_APIKEY	Required	API key for the LLM provider
SPL_AGENT_LLM_MODEL	Required	Model name (e.g., "gpt-4o", "claude-3-opus-20240229")
SPL_AGENT_LLM_MAX_TOKENS	0	Maximum tokens to generate (0 means no limit)
SPL_AGENT_LLM_TEMPERATURE	0.7	Temperature parameter for randomness in generation
SPL_AGENT_LLM_PROMPTTEMPLATE	Required	Template for system prompts (must include placeholder matching the SPL_AGENT_TOOL_ARGUMENTNAME value and {{tools}})
Chat Configuration
SPL_AGENT_CHAT_MAX_LLM_ITERATIONS	100	Maximum number of LLM iterations
SPL_AGENT_CHAT_MAX_TOKENS	0	Maximum tokens in chat history (0 means based on model)
SPL_AGENT_CHAT_REQUEST_BUDGET	1.0	Maximum cost (USD or token-equivalent) per request (0 = unlimited)
LLM Retry Configuration
SPL_AGENT_LLM_RETRY_MAX_RETRIES	3	Maximum number of retry attempts for LLM API calls
SPL_AGENT_LLM_RETRY_INITIAL_BACKOFF	1.0	Initial backoff time in seconds
SPL_AGENT_LLM_RETRY_MAX_BACKOFF	30.0	Maximum backoff time in seconds
SPL_AGENT_LLM_RETRY_BACKOFF_MULTIPLIER	2.0	Multiplier for increasing backoff time
MCP Servers Configuration
SPL_AGENT_CONNECTIONS_MCPSERVERS_0_ID	""	Identifier for the first MCP server
SPL_AGENT_CONNECTIONS_MCPSERVERS_0_COMMAND	""	Command to execute for the first server
SPL_AGENT_CONNECTIONS_MCPSERVERS_0_ARGS	""	Command arguments as space-separated string
SPL_AGENT_CONNECTIONS_MCPSERVERS_0_ENV_*	""	Environment variables for the server (prefix with SPL_AGENT_CONNECTIONS_MCPSERVERS_0_ENV_)
SPL_AGENT_CONNECTIONS_MCPSERVERS_1_ID, etc.	""	Configuration for additional servers (increment index)
MCP Retry Configuration
SPL_AGENT_CONNECTIONS_RETRY_MAX_RETRIES	3	Maximum number of retry attempts for MCP server connections
SPL_AGENT_CONNECTIONS_RETRY_INITIAL_BACKOFF	1.0	Initial backoff time in seconds
SPL_AGENT_CONNECTIONS_RETRY_MAX_BACKOFF	30.0	Maximum backoff time in seconds
SPL_AGENT_CONNECTIONS_RETRY_BACKOFF_MULTIPLIER	2.0	Multiplier for increasing backoff time
Runtime Configuration
SPL_RUNTIME_LOG_DEFAULTLEVEL	"info"	Log defaultLevel (debug, info, warn, error)
SPL_RUNTIME_LOG_OUTPUT	":stderr:"	Log output destination (:stdout:, :stderr:, :mcp:, file path)
SPL_RUNTIME_STDIO_ENABLED	true	Enable stdin/stdout transport
SPL_RUNTIME_STDIO_BUFFER_SIZE	8192	Buffer size for stdio transport
SPL_RUNTIME_HTTP_ENABLED	false	Enable HTTP transport
SPL_RUNTIME_HTTP_HOST	"localhost"	Host for HTTP server
SPL_RUNTIME_HTTP_PORT	3000	Port for HTTP server

For more details, see Environment Variables Reference.

Running the Agent

Daemon Mode (HTTP Server)

./speelka-agent --daemon [--config config.yaml]

CLI Mode (Standard Input/Output)

./speelka-agent [--config config.yaml]

Usage Examples

HTTP API

When running in daemon mode, the agent exposes HTTP endpoints:

# Send a request to the agent
curl -X POST http://localhost:3000/message -H "Content-Type: application/json" -d '{
  "method": "tools/call",
  "params": {
    "name": "process",
    "arguments": {
      "input": "Your query here"
    }
  }
}'

External Tool Integration

Connect to external tools using the MCP protocol in your YAML configuration:

agent:
  # ... other agent configuration ...
  connections:
    mcpServers:
      # MCP server for Playwright browser automation
      playwright:
        command: "mcp-playwright"
        args: []

      # MCP server for filesystem operations
      filesystem:
        command: "mcp-filesystem-server"
        args: ["."]

Or using environment variables:

# MCP server for Playwright browser automation
export SPL_AGENT_CONNECTIONS_MCPSERVERS_0_ID="playwright"
export SPL_AGENT_CONNECTIONS_MCPSERVERS_0_COMMAND="mcp-playwright"
export SPL_AGENT_CONNECTIONS_MCPSERVERS_0_ARGS=""

# MCP server for filesystem operations
export SPL_AGENT_CONNECTIONS_MCPSERVERS_1_ID="filesystem"
export SPL_AGENT_CONNECTIONS_MCPSERVERS_1_COMMAND="mcp-filesystem-server"
export SPL_AGENT_CONNECTIONS_MCPSERVERS_1_ARGS="."

Supported LLM Providers

• OpenAI: GPT-3.5, GPT-4, GPT-4o
• Anthropic: Claude models

Documentation

For more details, see:

• System Architecture
• Implementation Details
• Project File Structure
• Reference Materials
• External Resources

Development

Running Tests

go test ./...

Helper Commands

The run script provides commands for common operations:

# Development
./run build        # Build the project
./run test         # Run tests with coverage
./run check        # Run all checks
./run lint         # Run linter

# Interaction
./run call         # Test with simple query
./run call-multistep # Test with multi-step query
./run call-news    # Test news agent
./run fetch_url    # Fetch a URL using MCP

# Inspection
./run inspect      # Run with MCP inspector

See Command Reference for more options.

License

MIT License

MCP Server Tool Filtering

You can control which tools are exported from each MCP server using the following options in the mcpServers section:

• includeTools: (optional) List of tool names to include. Only these tools will be available from the server.
• excludeTools: (optional) List of tool names to exclude. These tools will not be available from the server.
• If both are set, includeTools is applied first, then excludeTools.
• Tool names are case-sensitive.

Example:

connections:
  mcpServers:
    time:
      command: "docker"
      args: ["run", "-i", "--rm", "mcp/time"]
      includeTools:
        - now
        - utc
    filesystem:
      command: "mcp-filesystem-server"
      args: ["/path/to/directory"]
      excludeTools:
        - delete

Direct Call Mode

You can run the agent in direct call mode to process a single query and output a JSON result. This is useful for scripting, automation, or integration with other tools.

Example:

./bin/speelka-agent --config site/examples/minimal.yaml --call 'What is 2+2?'

• The agent will process the query and print a single JSON result to stdout.
• All logs and debug output are sent to stderr.
• The output JSON will always include the fields: success, result, meta, and error.

Tip:

• You can use this mode in scripts and pipe the output to jq or other tools for further processing.