Speelka Agent MCP

游戏代理

基于模型上下文协议（MCP）的通用LLM代理，支持外部工具、灵活配置和可扩展日志记录。

主要特点

• 多代理编排：支持来自其他MCP服务器的工具。
• 灵活配置：YAML、JSON、环境变量、覆盖和基于属性的覆盖。
• 可扩展日志记录：集中式LogConfig，输出到stdout、stderr、文件、MCP协议、自定义/json/text格式。
• 安全：密钥隔离、日志保护、工具访问控制。
• 测试：黄金系列化测试、基于属性的覆盖、单元/集成/E2E。
• 可扩展性：HTTP和stdio支持，动态工具/会话管理。

建筑

• 所有组件均由接口驱动、经过测试，并遵循单一职责。
• 看 文档/架构.md 了解详情。

示例配置（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

日志记录

• 通过LogConfig管理：级别、格式、输出（stdout、stderr、文件、MCP）。
• MCP日志可通过协议或回退到stderr（用于stdio服务器）。
• 格式：自定义、json、文本、未知。
• 看 文档/架构.md 和 文件/实施.md 了解详情。

测试

• 单元，集成，E2E。
• 基于属性的覆盖测试（边缘情况、地图合并、零值保存）。
• 测试示例： 文件/实施.md.

项目结构

• 看 documents/file_structure.md 了解详情。
• 关键目录：内部/代理、内部/记录器、内部/mcp_connector、内部/类型。

快速开始

1. 克隆存储库并构建代理：

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

1. 准备一个配置（见上面的示例）或使用环境变量（SPL\_…）。
2. 运行代理：

- HTTP模式： ./speelka-agent --daemon [--config config.yaml] - CLI/stdio： ./speelka-agent [--config config.yaml]

文档

• 架构： 文档/架构.md
• 实施和测试： 文件/实施.md
• 文件结构： documents/file_structure.md
• 外部资源： documents/remote_resources.md

______________________________________________________________________

有关叠加、MCP日志、测试和结构详细信息，请参阅documents/文件夹中的文档。

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

用例

• 通过将大型复杂指令拆分为专门、专注的任务来提高准确性。
• 通过为不同的任务部件使用不同的型号来降低成本。
• 扩展、缩小或修改第三方MCP服务器响应。
• 在“真实”和基于LLM的工具实现之间轻松切换。
• 通过限制MCP服务器中的可用工具来限制功能。
• 在单个会话中跨多个MCP工具编排多步骤工作流。
• 强制执行每个请求的令牌和成本预算，以实现可预测的使用。
• 临时LLM或MCP服务器错误的自动重试和指数回退。
• 通过统一配置在LLM服务（OpenAI、Anthropic）之间无缝切换提供者。

主要特点

• 精确的代理定义：通过即时工程定义代理行为
• 客户端上下文优化：减小上下文大小以实现有效的令牌使用
• LLM灵活性：在客户端和代理端使用不同的LLM提供商
• 集中工具管理：所有工具的单一控制点
• 多种集成选项：MCP stdio、MCP HTTP、简单HTTP API
• 结构可靠性：瞬态故障的重试机制
• 可扩展性：在不更改客户端的情况下扩展系统行为
• MCP感知日志记录：带MCP通知的结构化日志记录
• 许可证管理：自动令牌计数
• 灵活的配置：环境变量、YAML、JSON
• LLMS服务。发送请求 返回a LLMResponse 结构体：

- 响应文本 - 工具调用列表 - 完成令牌、提示令牌、推理令牌、总令牌（令牌使用）

• 接口: SendRequest(ctx, messages, tools) (LLMResponse, error)

入门指南

先决条件

• 上涨1.19或更高
• API LLM证书（OpenAI或Anthropic）
• 外部MCP工具（可选）

安装

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

配置

可以使用YAML、JSON或环境变量提供配置。

注： 这 ./examples 目录已弃用。使用示例 ./site/examples 相反。

示例配置文件位于 site/examples:

• site/examples/minimal.yaml：基本代理配置（YAML）
• site/examples/ai-news.yaml：AI新闻代理配置（YAML）
• site/examples/architect.yaml：架构师代理配置（YAML）

简单的YAML配置示例：

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

使用环境变量

所有环境变量都以前缀 SPL_:

有关更多详细信息，请参阅 环境变量引用.

运行代理

守护程序模式（HTTP服务器）

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

CLI模式（标准输入/输出）

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

使用示例

HTTP API

在守护进程模式下运行时，代理会公开HTTP端点：

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

外部工具集成

使用YAML配置中的MCP协议连接到外部工具：

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: ["."]

或者使用环境变量：

# 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="."

支持的LLM提供商

• 开放人工智能：GPT-3.5、GPT-4、GPT-4o
• Anthropic：克劳德模型

文档

有关更多详细信息，请参阅：

• 系统架构
• 实现细节
• 项目文件结构
• 参考资料
• 外部资源

发展

运行测试

go test ./...

助手命令

这 run 脚本提供了常见操作的命令：

# 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

看 命令参考 更多选择。

许可证

MIT许可证

MCP服务器工具筛选

您可以使用以下选项控制从每个MCP服务器导出哪些工具 mcpServers 章节：

• includeTools：（可选）要包含的工具名称列表。服务器上只有这些工具可用。
• excludeTools：（可选）要排除的工具名称列表。这些工具将无法从服务器获得。
• 如果两者都被设置， includeTools 先应用，然后 excludeTools.
• 工具名称区分大小写。

例子：

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

直接通话模式

您可以在直接调用模式下运行代理来处理单个查询并输出JSON结果。这对于脚本编写、自动化或与其他工具的集成非常有用。

例子：

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

• 代理将处理查询并将单个JSON结果打印到stdout。
• 所有日志和调试输出都会发送到stderr。
• 输出JSON将始终包含以下字段： success, result, meta，以及 error.

提示：

• 您可以在脚本中使用此模式，并将输出传输到 jq 或用于进一步加工的其他工具。