speelka-agent

Speelka Agent is a universal MCP-based LLM agent designed to orchestrate multiple tools and external MCP servers. It supports multi-agent workflows, tool integration from other MCP servers, and flexible configuration through YAML, JSON, environment variables, and overlays. The agent manages logging via a centralized LogConfig and can route MCP protocol logs to different outputs. You can connect to external MCP tools such as time and filesystem services, and you can adjust how tools are invoked and how the agent interacts with LLMs to balance performance and cost. Typical usage involves running the agent in HTTP or stdio mode and wiring your desired MCP tools and sessions into the agent’s connections section. The configuration allows you to tune token budgets, retries, and prompt templates to tailor behavior for your use case.

Prerequisites:\n- Go 1.19 or higher\n- A compatible MCP toolset or external MCP tools you want to connect to (optional)\n- If using HTTP mode, ensure a suitable environment for running a server (port exposure, network access)\n\nInstallation steps:\n1) Clone the repository:\n git clone https://github.com/korchasa/speelka-agent-go.git\n2) Build the server binary:\n cd speelka-agent-go\n go build ./cmd/server\n3) Prepare a configuration file (YAML or JSON) describing your agent, tools, and connections. See the example in the repository README for guidance.\n4) Run the server:\n - In HTTP mode: ./speelka-agent --daemon --config config.yaml\n - In CLI/stdio mode: ./speelka-agent --config config.yaml\n5) (Optional) Set environment variables for sensitive config, such as API keys or secrets, prefixed with SPL_.

Tips and common considerations:\n- Environment variables can override values in YAML/JSON configurations; use SPL_ prefix for sensitive data like API keys.\n- For external MCP tools, ensure the tool endpoints (time, filesystem, etc.) are reachable by the agent.\n- The logging system (LogConfig) supports multiple formats and outputs; configure defaultLevel and output to suit your environment.\n- When using stdio mode, MCP logs may fallback to stderr; configure output appropriately.\n- If you run into tool or session management issues, verify the mcpServers mappings and network access between the agent and external MCP services.\n- The provided example uses Docker for the time tool and a local filesystem tool; you can swap in other MCP-enabled tools as needed.