### Start Development Server (Frontend and Backend)

Source: https://github.com/lubyruffy/mcpagent/blob/main/web/README.md

Commands to launch the frontend development server using npm and the backend server using Go. This setup is for local development and debugging purposes.

```bash
# 启动前端开发服务器
npm run dev

# 在另一个终端启动后端服务器
cd ..
go run cmd/mcpagent-web/main.go -config config_public.yaml -dev
```

--------------------------------

### Web Server Start

Source: https://context7.com/lubyruffy/mcpagent/llms.txt

Instructions on how to build and start the web interface server for visualization and management.

```APIDOC
## Web Server Start

### Description
Start the web interface server to provide a visual management interface.

### Method
Shell commands

### Endpoint
N/A

### Parameters
- **port** (int) - Optional - The port to run the web server on. Defaults to 8080.
- **host** (string) - Optional - The host address to bind to. Defaults to 127.0.0.1.
- **db** (string) - Optional - Path to the database file. Defaults to ./data/mcpagent.db.

### Request Example
```bash
./mcpagent-web -port 8081 -host 0.0.0.0 -db ./data/mcpagent.db
```

### Response
N/A

### Notes
- Build the web application using `./scripts/build-web.sh`.
- Start the production server with `cd build && ./start.sh`.
- Use `./scripts/dev.sh` for development mode with hot-reloading.
- Access the web interface at `http://localhost:8081`.
- SSE endpoint: `http://localhost:8081/events`.
- API base path: `http://localhost:8081/api`.
```

--------------------------------

### Install Frontend Dependencies (npm, yarn, pnpm)

Source: https://github.com/lubyruffy/mcpagent/blob/main/web/README.md

Commands to install frontend dependencies using npm, yarn, or pnpm within the web directory. Ensures all necessary packages for the Vue3 application are downloaded and installed.

```bash
cd web

npm install
# 或使用yarn
yarn install
# 或使用pnpm
pnpm install
```

--------------------------------

### Backend Configuration Example (YAML)

Source: https://github.com/lubyruffy/mcpagent/blob/main/web/README.md

An example YAML configuration file for the MCP Agent backend. It shows settings for LLM providers, MCP server configuration, tool selection, system prompts, and other parameters.

```yaml
llm:
  type: openai
  base_url: https://api.openai.com/v1
  model: gpt-4
  api_key: your-api-key

mcp:
  config_file: mcp_servers.json
  tools:
    - fetch_fetch
    - ddg-search_search

system_prompt: |
  你是一个智能助手...

max_step: 20
```

--------------------------------

### Frontend Environment Variables Example

Source: https://github.com/lubyruffy/mcpagent/blob/main/web/README.md

Examples of frontend configuration using environment variables for development and production. These variables define API endpoints and Server-Sent Events URLs.

```bash
# 开发环境
VITE_API_BASE_URL=http://localhost:8080
VITE_SSE_URL=http://localhost:8080/events

# 生产环境
VITE_API_BASE_URL=/api
VITE_SSE_URL=/events
```

--------------------------------

### Tool and Model Retrieval (Go SDK Example)

Source: https://context7.com/lubyruffy/mcpagent/llms.txt

Example demonstrating how to use the MCP Agent Go SDK to retrieve LLM models and tools.

```APIDOC
## Go SDK Example for Tool and Model Retrieval

### Description
This Go code snippet demonstrates how to load configuration, get an LLM model instance, and retrieve available tools using the MCP Agent SDK.

### Method
N/A (SDK Usage)

### Endpoint
N/A (SDK Usage)

### Code Example
```go
package main

import (
    "context"
    "log"

    "github.com/LubyRuffy/mcpagent/pkg/config"
)

func main() {
    cfg, err := config.LoadConfig("config.yaml")
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()

    // 获取LLM模型实例
    chatModel, err := cfg.GetModel(ctx)
    if err != nil {
        log.Fatalf("获取模型失败: %v", err)
    }
    log.Printf("LLM模型创建成功: %s", cfg.LLM.Model)

    // 获取MCP工具(包含内置工具和外部MCP服务器工具)
    tools, cleanup, err := cfg.GetTools(ctx)
    if err != nil {
        log.Fatalf("获取工具失败: %v", err)
    }
    defer cleanup() // 重要: 必须调用cleanup关闭MCP连接

    log.Printf("成功获取 %d 个工具:", len(tools))
    for _, tool := range tools {
        log.Printf("  - %s", tool.Info().Name)
    }

    // 工具可以传递给Agent使用
    // ... Agent执行逻辑
}
```
```

--------------------------------

### Bash Web Server Startup and Configuration

Source: https://context7.com/lubyruffy/mcpagent/llms.txt

Provides bash commands to build and start the web application for the MCP Agent. It includes instructions for production and development modes, as well as how to customize the port, host, and database path.

```bash
# 构建Web应用
./scripts/build-web.sh

# 启动生产环境Web服务器
cd build
./start.sh

# 或使用开发模式(前端热重载)
./scripts/dev.sh

# 自定义端口和数据库路径
./mcpagent-web -port 8081 -host 0.0.0.0 -db ./data/mcpagent.db

# 访问地址
# Web界面: http://localhost:8081
# SSE端点: http://localhost:8081/events
# API基础路径: http://localhost:8081/api
```

--------------------------------

### Get Configured Tools - GET /api/mcp/tools/configured

Source: https://context7.com/lubyruffy/mcpagent/llms.txt

Retrieves a list of tools that are already configured and cached in the database.

```bash
curl http://localhost:8081/api/mcp/tools/configured
```

--------------------------------

### Load Config and Get LLM Model and Tools - Go

Source: https://context7.com/lubyruffy/mcpagent/llms.txt

Go program to load configuration, retrieve an LLM model instance, and fetch MCP tools. Includes essential error handling and resource cleanup.

```go
package main

import (
    "context"
    "log"

    "github.com/LubyRuffy/mcpagent/pkg/config"
)

func main() {
    cfg, err := config.LoadConfig("config.yaml")
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()

    // 获取LLM模型实例
    chatModel, err := cfg.GetModel(ctx)
    if err != nil {
        log.Fatalf("获取模型失败: %v", err)
    }
    log.Printf("LLM模型创建成功: %s", cfg.LLM.Model)

    // 获取MCP工具(包含内置工具和外部MCP服务器工具)
    tools, cleanup, err := cfg.GetTools(ctx)
    if err != nil {
        log.Fatalf("获取工具失败: %v", err)
    }
    defer cleanup() // 重要: 必须调用cleanup关闭MCP连接

    log.Printf("成功获取 %d 个工具:", len(tools))
    for _, tool := range tools {
        log.Printf("  - %s", tool.Info().Name)
    }

    // 工具可以传递给Agent使用
    // ... Agent执行逻辑
}
```

--------------------------------

### Install MCP Dependencies - UV and NPX

Source: https://github.com/lubyruffy/mcpagent/blob/main/README.md

Install required package managers and tools for MCP server management. UV is used for Python package management and NPX for Node.js package execution.

```shell
# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh
# Or: pip install uv

# Install NPX
brew install node
npm install -g npx
```

--------------------------------

### Build and Run MCPAgent Web Application

Source: https://github.com/lubyruffy/mcpagent/blob/main/README.md

Build the Vue3-based Web UI and start the development or production server. Provides a modern interface for MCPAgent interaction at http://localhost:8080.

```bash
# Build Web application
./scripts/build-web.sh

# Start Web server
cd build
./start.sh

# Or run development mode directly
./scripts/dev.sh
```

--------------------------------

### List System Prompts - GET /api/system-prompts

Source: https://context7.com/lubyruffy/mcpagent/llms.txt

Retrieves a list of all available system prompt templates.

```bash
curl http://localhost:8081/api/system-prompts
```

--------------------------------

### Install Ollama for Local LLM Support

Source: https://github.com/lubyruffy/mcpagent/blob/main/README.md

Install Ollama on macOS to enable local language model execution. Ollama provides local LLM capabilities as an alternative to cloud-based APIs.

```shell
brew install ollama
```

--------------------------------

### Bash CLI for Global Configuration Management

Source: https://context7.com/lubyruffy/mcpagent/llms.txt

Shows how to manage the application's global configuration via the HTTP API. It includes `curl` commands to GET the current configuration and POST an updated configuration to the `/api/config` endpoint. The payload structure for updating the configuration is also provided.

```bash
# 获取当前配置 - GET /api/config
curl http://localhost:8081/api/config

# 响应示例
# {
#   "llm": {
#     "type": "ollama",
#     "base_url": "http://127.0.0.1:11434",
#     "model": "qwen3:14b",
#     "api_key": "ollama"
#   },
#   "mcp": {
#     "mcp_servers": { ... },
#     "tools": [ ... ]
#   },
#   "proxy": "",
#   "max_step": 20,
#   "system_prompt": "...",
#   "placeholders": {
#     "field": "网络安全研究领域"
#   }
# }

# 更新配置 - POST /api/config
curl -X POST http://localhost:8081/api/config \
  -H "Content-Type: application/json" \
  -d '{
    "llm": {
      "type": "openai",
      "base_url": "https://api.openai.com/v1",
      "model": "gpt-4",
      "api_key": "sk-xxx"
    },
    "mcp": {
      "mcp_servers": {},
      "tools": []
    },
    "max_step": 30,
    "system_prompt": "你是专业的AI助手",
    "placeholders": {}
  }'

# 响应示例
# {
#   "success": true,
#   "message": "配置更新成功并已保存到数据库"
# }
```

--------------------------------

### Get Tools from MCP Server - POST /api/mcp/tools

Source: https://context7.com/lubyruffy/mcpagent/llms.txt

Requests a list of tools from specified MCP servers. Requires a JSON payload defining which servers to query and their configurations.

```bash
curl -X POST http://localhost:8081/api/mcp/tools \
  -H "Content-Type: application/json" \
  -d '{
    "mcp_servers": {
      "fetch": {
        "command": "uvx",
        "args": ["mcp-server-fetch"]
      }
    }
  }'
```

--------------------------------

### List MCP Servers - GET /api/mcp/servers

Source: https://context7.com/lubyruffy/mcpagent/llms.txt

Retrieves a list of all configured MCP servers.

```bash
curl http://localhost:8081/api/mcp/servers
```

--------------------------------

### Get System Prompt - GET /api/system-prompts/{id}

Source: https://context7.com/lubyruffy/mcpagent/llms.txt

Retrieves a specific system prompt template by its ID.

```bash
curl http://localhost:8081/api/system-prompts/1
```

--------------------------------

### Bash CLI for Task Execution via HTTP API

Source: https://context7.com/lubyruffy/mcpagent/llms.txt

Demonstrates how to execute tasks using the MCP Agent's HTTP API. It shows a `curl` command to send a POST request to the `/api/task` endpoint with a JSON payload specifying the task and its configuration. It also includes an example for cancelling a task.

```bash
# 执行任务 - POST /api/task
curl -X POST http://localhost:8081/api/task \
  -H "Content-Type: application/json" \
  -d '{
    "task": "分析网络安全领域的最新研究趋势",
    "config": {
      "llm": {
        "type": "ollama",
        "base_url": "http://127.0.0.1:11434",
        "model": "qwen3:14b",
        "api_key": "ollama"
      },
      "mcp": {
        "mcp_servers": {
          "fetch": {
            "command": "uvx",
            "args": ["mcp-server-fetch"]
          }
        },
        "tools": [
          {"server": "inner", "name": "sequentialthinking"},
          {"server": "fetch", "name": "fetch"}
        ]
      },
      "max_step": 20,
      "system_prompt": "你是一位专业的研究员"
    }
  }'

# 响应示例
# {
#   "success": true,
#   "message": "任务已开始执行",
#   "task_id": "task_1234567890"
# }

# 取消任务 - POST /api/task/{taskId}/cancel
curl -X POST http://localhost:8081/api/task/task_1234567890/cancel

# 响应示例
# {
#   "success": true,
#   "message": "任务取消请求已发送"
# }
```

--------------------------------

### JavaScript Client for SSE Real-time Task Updates

Source: https://context7.com/lubyruffy/mcpagent/llms.txt

A JavaScript example demonstrating how to connect to the Server-Sent Events (SSE) endpoint to receive real-time updates on task execution. It uses the `EventSource` API to listen for different message types like 'status', 'thinking', 'tool_call', 'result', and 'error', and closes the connection upon task completion or error.

```javascript
// JavaScript客户端示例
const taskId = 'task_1234567890';
const eventSource = new EventSource(`http://localhost:8081/events?taskId=${taskId}`);

eventSource.onmessage = (event) => {
  const message = JSON.parse(event.data);

  switch (message.type) {
    case 'status':
      console.log('任务状态:', message.data);
      // { id: "task_xxx", status: "running", current_step: "开始执行任务" }
      break;

    case 'notify':
      const notify = message.data;
      switch (notify.type) {
        case 'thinking':
          console.log('Agent思考:', notify.content);
          break;
        case 'tool_call':
          console.log('工具调用:', notify.tool_name, notify.parameters);
          break;
        case 'result':
          console.log('最终结果:', notify.content);
          break;
        case 'error':
          console.error('错误:', notify.error);
          break;
      }
      break;
  }

  // 任务完成或出错时关闭连接
  if (message.type === 'status' &&
      (message.data.status === 'completed' || message.data.status === 'error')) {
    eventSource.close();
  }
};

eventSource.onerror = (error) => {
  console.error('SSE连接错误:', error);
  eventSource.close();
};
```

--------------------------------

### Get LLM Configuration - GET /api/llm/configs/{id}

Source: https://context7.com/lubyruffy/mcpagent/llms.txt

Retrieves a specific LLM configuration by its ID.

```bash
curl http://localhost:8081/api/llm/configs/1
```

--------------------------------

### Build for Production (Frontend and Backend)

Source: https://github.com/lubyruffy/mcpagent/blob/main/web/README.md

Commands to build the frontend application for production using npm and compile the backend Go application. These commands generate optimized assets for deployment.

```bash
# 构建前端
npm run build

# 构建后端
go build -o mcpagent-web cmd/mcpagent-web/main.go
```

--------------------------------

### Clone and Build MCPAgent Project in Go

Source: https://github.com/lubyruffy/mcpagent/blob/main/README.md

Clone the MCPAgent repository and build the executable using Go mod and the build command. This sets up the main project binary for command-line execution.

```bash
# Clone project
git clone https://github.com/LubyRuffy/mcpagent.git
cd mcpagent

# Install dependencies
go mod download

# Build project
go build -o mcpagent ./cmd/mcpagent
```

--------------------------------

### Go - 初始化和管理数据库模型

Source: https://context7.com/lubyruffy/mcpagent/llms.txt

使用GORM初始化数据库连接，并演示了创建和管理LLM配置、MCP服务器配置以及系统提示词的CRUD操作。此代码依赖于mcpagent/pkg/database, mcpagent/pkg/models, 和 mcpagent/pkg/services包。

```go
package main

import (
    "log"

    "github.com/LubyRuffy/mcpagent/pkg/database"
    "github.com/LubyRuffy/mcpagent/pkg/models"
    "github.com/LubyRuffy/mcpagent/pkg/services"
)

func main() {
    // 初始化数据库
    err := database.InitDatabase("./data/mcpagent.db")
    if err != nil {
        log.Fatal(err)
    }
    defer database.CloseDatabase()

    // 创建服务实例
    llmService := services.NewLLMConfigService()
    mcpServerService := services.NewMCPServerConfigService()
    promptService := services.NewSystemPromptService()

    // 创建LLM配置
    llmConfig := &models.LLMConfigModel{
        Name:         "OpenAI GPT-4",
        Description:  "OpenAI GPT-4配置",
        ProviderType: "openai",
        BaseURL:      "https://api.openai.com/v1",
        Model:        "gpt-4",
        APIKey:       "sk-xxx",
        IsDefault:    true,
    }

    err = llmService.CreateConfig(llmConfig)
    if err != nil {
        log.Printf("创建LLM配置失败: %v", err)
    }

    // 查询默认LLM配置
    defaultLLM, err := llmService.GetDefaultConfig()
    if err != nil {
        log.Printf("获取默认LLM配置失败: %v", err)
    } else {
        log.Printf("默认LLM: %s (%s)", defaultLLM.Name, defaultLLM.Model)
    }

    // 创建MCP服务器配置
    mcpConfig := &models.MCPServerConfigModel{
        Name:          "fetch-server",
        Description:   "网页抓取服务器",
        TransportType: "stdio",
        Command:       "uvx",
        Disabled:      false,
        IsActive:      true,
    }
    mcpConfig.SetArgs([]string{"mcp-server-fetch"})

    err = mcpServerService.CreateConfig(mcpConfig)
    if err != nil {
        log.Printf("创建MCP服务器配置失败: %v", err)
    }

    // 查询所有活跃的MCP服务器
    activeServers, err := mcpServerService.GetAllActiveConfigs()
    if err != nil {
        log.Printf("获取活跃服务器失败: %v", err)
    } else {
        log.Printf("活跃的MCP服务器: %d 个", len(activeServers))
    }

    // 创建系统提示词
    prompt := &models.SystemPromptModel{
        Name:        "研究助手",
        Description: "学术研究系统提示词",
        Content:     "你是一位专业的研究员...",
        IsDefault:   true,
    }

    err = promptService.CreatePrompt(prompt)
    if err != nil {
        log.Printf("创建系统提示词失败: %v", err)
    }
}

```

--------------------------------

### JSON: Configure MCP Server Connections

Source: https://context7.com/lubyruffy/mcpagent/llms.txt

mcp_servers.json文件用于配置各种类型的MCP服务器连接。它支持通过命令行启动服务器,例如使用"uvx"或"npx"命令,并可以指定服务器名称和参数。此外,它还支持配置远程API连接,包括URL、请求头和认证信息。

```json
{
  "mcpServers": {
    "ddg-search": {
      "command": "uvx",
      "args": ["duckduckgo-mcp-server"]
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    },
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "remote-api": {
      "url": "http://localhost:8000/sse",
      "headers": [
        "Authorization: Bearer your-token-here",
        "Content-Type: application/json"
      ]
    },
    "cloud-service": {
      "url": "https://api.example.com/mcp/sse"
    }
  }
}

```

--------------------------------

### CLI: Execute MCPAgent Tasks

Source: https://context7.com/lubyruffy/mcpagent/llms.txt

使用mcpagent命令行工具执行基于MCP的智能任务。支持基本使用、自定义配置文件以及完整参数覆盖。默认情况下,它会使用默认配置执行任务,也可以通过-config参数指定配置文件。CLI工具支持任务执行、LLM和MCP服务器配置的指定。

```bash
# 基本使用 - 使用默认配置执行任务
./mcpagent -task "分析网络安全领域的最新研究趋势"

# 自定义配置文件
./mcpagent -config news_config.yaml -task "分析特朗普的一些新政策对中美关系的影响"

# 完整参数示例 - 覆盖配置文件中的设置
./mcpagent \
  -config custom_config.yaml \
  -task "查询最近的用户数据" \
  -llm-type openai \
  -llm-base-url https://api.openai.com/v1 \
  -llm-model gpt-4 \
  -llm-api-key sk-xxx \
  -mcp-config mcp_servers.json \
  -mcp-tools "fetch:fetch,ddg-search:search" \
  -max-step 30 \
  -proxy http://127.0.0.1:8080

# 使用数据库的MCP服务器进行数据查询
./mcpagent -config dbagent_config.yaml -task "最近的用户查询最多的产品是什么"
```

--------------------------------

### Create System Prompt - POST /api/system-prompts

Source: https://context7.com/lubyruffy/mcpagent/llms.txt

Creates a new system prompt template. Requires a JSON payload with name, description, and content. The content can include placeholders like {field} and {date}.

```bash
curl -X POST http://localhost:8081/api/system-prompts \
  -H "Content-Type: application/json" \
  -d '{
    "name": "学术研究助手",
    "description": "用于学术研究和论文撰写的系统提示词",
    "content": "你是一位{field}资深专家,专精于国际顶级期刊的论文撰写标准。\n当前日期：{date}\n\n你可以使用以下工具:\n- sequentialthinking: 进行结构化思考\n- search: 搜索相关信息\n- fetch: 获取网页内容",
    "is_default": false
  }'
```

--------------------------------

### YAML: Configure LLM, MCP Servers, and System Prompts

Source: https://context7.com/lubyruffy/mcpagent/llms.txt

YAML格式的配置文件用于定义LLM、MCP服务器和系统提示词。此配置允许用户指定LLM类型、基础URL、模型、API密钥,以及MCP服务器的连接方式和工具。它还支持代理设置、最大推理步数以及用于系统提示词模板替换的占位符。

```yaml
# config.yaml - 完整配置示例
llm:
  type: ollama              # 支持 openai, ollama
  base_url: http://127.0.0.1:11434
  model: qwen3:14b
  api_key: ollama

mcp:
  config_file: mcp_servers.json  # MCP服务器配置文件路径
  # 或者直接配置mcp_servers
  mcp_servers:
    fetch:
      command: uvx
      args:
        - mcp-server-fetch
    ddg-search:
      command: uvx
      args:
        - duckduckgo-mcp-server
  tools:
    - server: inner           # 内置工具
      name: sequentialthinking
    - server: inner
      name: search
    - server: fetch           # 外部MCP服务器工具
      name: fetch

proxy: "http://127.0.0.1:8080"  # 用于调试的HTTP代理(如burp)
max_step: 20                     # 最大推理步数

# 占位符 - 用于system_prompt模板变量替换
placeholders:
  field: "网络安全研究领域"
  total_thoughts: 20

system_prompt: |
  你是一位{field}资深专家。当前日期：{date}。
  你可以使用提供的工具进行信息收集和分析。

```

--------------------------------

### Go: Programmatic API Calls to MCPAgent

Source: https://context7.com/lubyruffy/mcpagent/llms.txt

使用Go语言直接调用MCPAgent的核心功能。此示例展示了如何加载配置、自定义配置参数(如LLM类型、URL、模型、API密钥和最大步数),配置MCP工具,验证配置,并执行任务。它还演示了如何使用CLI通知处理器。

```go
package main

import (
    "context"
    "log"

    "github.com/LubyRuffy/mcpagent/pkg/config"
    "github.com/LubyRuffy/mcpagent/pkg/mcpagent"
)

func main() {
    // 加载配置
    cfg, err := config.LoadConfig("config.yaml")
    if err != nil {
        log.Fatalf("加载配置失败: %v", err)
    }

    // 也可以创建默认配置并自定义
    cfg = config.NewDefaultConfig()
    cfg.LLM.Type = "openai"
    cfg.LLM.BaseURL = "https://api.openai.com/v1"
    cfg.LLM.Model = "gpt-4"
    cfg.LLM.APIKey = "sk-xxx"
    cfg.MaxStep = 20

    // 配置MCP工具
    cfg.MCP.Tools = []config.MCPToolConfig{
        {Server: "inner", Name: "sequentialthinking"},
        {Server: "fetch", Name: "fetch"},
    }

    // 验证配置
    if err := cfg.Validate(); err != nil {
        log.Fatalf("配置验证失败: %v", err)
    }

    // 创建通知处理器(CLI模式)
    notify := &mcpagent.CliNotifier{}

    // 执行任务
    ctx := context.Background()
    task := "分析网络安全领域的最新研究趋势"

    if err := mcpagent.Run(ctx, cfg, task, notify); err != nil {
        log.Fatalf("执行任务失败: %v", err)
    }

    log.Println("任务执行完成")
}

```

--------------------------------

### Execute MCPAgent with Command-Line Tasks

Source: https://github.com/lubyruffy/mcpagent/blob/main/README.md

Run MCPAgent from the command line with various configuration options and task specifications. Supports default configuration, custom config files, and database MCP servers for direct data queries.

```bash
# Execute with default configuration
./mcpagent -task "分析网络安全领域的最新研究趋势"

# Use custom configuration file
./mcpagent -config news_config.yaml -task "分析特朗普的一些新政策对中美关系的影响"

# Use database MCP server for direct data queries
./mcpagent -config dbagent_config.yaml -task "最近的用户查询最多的产品是什么"
```

--------------------------------

### Sync All Server Tools - POST /api/mcp/tools/sync

Source: https://context7.com/lubyruffy/mcpagent/llms.txt

Initiates a synchronization process to fetch tools from all configured MCP servers.

```bash
curl -X POST http://localhost:8081/api/mcp/tools/sync
```

--------------------------------

### Create LLM Configuration - POST /api/llm/configs

Source: https://context7.com/lubyruffy/mcpagent/llms.txt

Creates a new LLM configuration. Requires a JSON payload with details such as name, provider type, model, and API key. Supported provider types include 'openai'.

```bash
curl -X POST http://localhost:8081/api/llm/configs \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OpenAI GPT-4",
    "description": "OpenAI GPT-4模型配置",
    "provider_type": "openai",
    "base_url": "https://api.openai.com/v1",
    "model": "gpt-4",
    "api_key": "sk-xxx",
    "is_default": false
  }'
```

--------------------------------

### Configure STDIO MCP Servers in JSON - mcp_servers.json

Source: https://github.com/lubyruffy/mcpagent/blob/main/README.md

Define STDIO-type MCP servers that are launched via command-line interface. Supports UV and NPX package managers for running MCP server packages directly.

```json
{
  "mcpServers": {
    "ddg-search": {
      "command": "uvx",
      "args": ["duckduckgo-mcp-server"]
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    },
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}
```

--------------------------------

### Bash CLI to List LLM Configurations

Source: https://context7.com/lubyruffy/mcpagent/llms.txt

Demonstrates how to retrieve a list of all configured Large Language Model (LLM) providers using a `curl` command. This interacts with the `/api/llm/configs` endpoint.

```bash
# 列出所有LLM配置 - GET /api/llm/configs
curl http://localhost:8081/api/llm/configs
```

--------------------------------

### System Prompts API

Source: https://context7.com/lubyruffy/mcpagent/llms.txt

APIs for managing reusable system prompt templates.

```APIDOC
## GET /api/system-prompts

### Description
Lists all system prompts.

### Method
GET

### Endpoint
/api/system-prompts

## POST /api/system-prompts

### Description
Creates a new system prompt.

### Method
POST

### Endpoint
/api/system-prompts

### Parameters
#### Request Body
- **name** (string) - Required - The name of the system prompt.
- **description** (string) - Optional - A description for the system prompt.
- **content** (string) - Required - The content of the system prompt, can include placeholders like {field} and {date}.
- **is_default** (boolean) - Optional - Whether this prompt is the default.

### Request Example
```json
{
  "name": "学术研究助手",
  "description": "用于学术研究和论文撰写的系统提示词",
  "content": "你是一位{field}资深专家,专精于国际顶级期刊的论文撰写标准。\n当前日期：{date}\n\n你可以使用以下工具:\n- sequentialthinking: 进行结构化思考\n- search: 搜索相关信息\n- fetch: 获取网页内容",
  "is_default": false
}
```

## GET /api/system-prompts/{id}

### Description
Retrieves a specific system prompt by its ID.

### Method
GET

### Endpoint
/api/system-prompts/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the system prompt to retrieve.

## PUT /api/system-prompts/{id}

### Description
Updates an existing system prompt.

### Method
PUT

### Endpoint
/api/system-prompts/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the system prompt to update.
#### Request Body
- **name** (string) - Optional - The updated name of the system prompt.
- **content** (string) - Optional - The updated content of the system prompt.

### Request Example
```json
{
  "name": "更新的学术助手",
  "content": "新的提示词内容..."
}
```

## DELETE /api/system-prompts/{id}

### Description
Deletes a specific system prompt by its ID.

### Method
DELETE

### Endpoint
/api/system-prompts/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the system prompt to delete.

## POST /api/system-prompts/{id}/default

### Description
Sets a specific system prompt as the default.

### Method
POST

### Endpoint
/api/system-prompts/{id}/default

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the system prompt to set as default.
```

--------------------------------

### Configure MCPAgent with YAML - config.yaml

Source: https://github.com/lubyruffy/mcpagent/blob/main/README.md

Define LLM provider settings, MCP server configuration, agent parameters, and system prompts in YAML format. Supports Ollama and OpenAI-compatible providers with customizable field context and tool selection.

```yaml
# LLM configuration
llm:
  type: ollama              # Supports: openai, ollama
  base_url: http://127.0.0.1:11434
  model: qwen3:14b
  api_key: ollama

# MCP server configuration
mcp:
  config_file: mcp_servers.json
  # mcp_servers: Can also configure mcp_servers directly
  tools:
    - fetch_fetch
    - ddg-search_search
    - sequential-thinking_sequentialthinking

# Agent configuration
proxy: ""                  # HTTP proxy address (e.g., burp) for debugging
max_step: 20               # Maximum reasoning steps

# System prompt
field: "网络安全领域"     # Used for {field} placeholder in system_prompt
system_prompt: |
  你是一位经验丰富的学术研究员...
```

--------------------------------

### Execute Academic Paper Writing Task with MCPAgent

Source: https://github.com/lubyruffy/mcpagent/blob/main/README.md

Run MCPAgent to generate comprehensive academic papers with literature review, methodology, and case analysis. Demonstrates complex multi-step reasoning task execution.

```bash
./mcphost -task "撰写一篇关于'大语言模型在网络安全中的应用'的学术论文，包含文献综述、方法论和案例分析，字数不少于2000字"
```

--------------------------------

### HTTP API Endpoints

Source: https://github.com/lubyruffy/mcpagent/blob/main/web/README.md

List of available HTTP API endpoints for interacting with the MCP Agent backend. Covers configuration management and task execution.

```http
- GET /api/config - 获取配置
- POST /api/config - 更新配置
- POST /api/task - 执行任务
```

--------------------------------

### LLM Configuration API

Source: https://context7.com/lubyruffy/mcpagent/llms.txt

APIs for creating, retrieving, updating, deleting, and setting default LLM configurations.

```APIDOC
## POST /api/llm/configs

### Description
Creates a new LLM configuration.

### Method
POST

### Endpoint
/api/llm/configs

### Parameters
#### Request Body
- **name** (string) - Required - The name of the LLM configuration.
- **description** (string) - Optional - A description for the LLM configuration.
- **provider_type** (string) - Required - The type of LLM provider (e.g., "openai").
- **base_url** (string) - Optional - The base URL for the LLM provider.
- **model** (string) - Required - The model name.
- **api_key** (string) - Required - The API key for the provider.
- **is_default** (boolean) - Optional - Whether this configuration is the default.

### Request Example
```json
{
  "name": "OpenAI GPT-4",
  "description": "OpenAI GPT-4模型配置",
  "provider_type": "openai",
  "base_url": "https://api.openai.com/v1",
  "model": "gpt-4",
  "api_key": "sk-xxx",
  "is_default": false
}
```

## GET /api/llm/configs/{id}

### Description
Retrieves a specific LLM configuration by its ID.

### Method
GET

### Endpoint
/api/llm/configs/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the LLM configuration to retrieve.

## PUT /api/llm/configs/{id}

### Description
Updates an existing LLM configuration.

### Method
PUT

### Endpoint
/api/llm/configs/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the LLM configuration to update.
#### Request Body
- **name** (string) - Optional - The updated name of the LLM configuration.
- **model** (string) - Optional - The updated model name.

### Request Example
```json
{
  "name": "OpenAI GPT-4 Updated",
  "model": "gpt-4-turbo"
}
```

## DELETE /api/llm/configs/{id}

### Description
Deletes a specific LLM configuration by its ID.

### Method
DELETE

### Endpoint
/api/llm/configs/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the LLM configuration to delete.

## POST /api/llm/configs/{id}/default

### Description
Sets a specific LLM configuration as the default.

### Method
POST

### Endpoint
/api/llm/configs/{id}/default

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the LLM configuration to set as default.

## POST /api/llm/test

### Description
Tests the connection to an LLM.

### Method
POST

### Endpoint
/api/llm/test

### Parameters
#### Request Body
- **type** (string) - Required - The type of LLM provider.
- **base_url** (string) - Optional - The base URL for the LLM provider.
- **model** (string) - Required - The model name.
- **api_key** (string) - Required - The API key for the provider.

### Request Example
```json
{
  "type": "openai",
  "base_url": "https://api.openai.com/v1",
  "model": "gpt-4",
  "api_key": "sk-xxx"
}
```

#### Success Response (200)
- **success** (boolean) - Indicates if the test was successful.
- **message** (string) - A message indicating the result of the test.

### Response Example
```json
{
  "success": true,
  "message": "LLM连接测试成功"
}
```
```

--------------------------------

### Create STDIO MCP Server - POST /api/mcp/servers

Source: https://context7.com/lubyruffy/mcpagent/llms.txt

Creates a new MCP server with 'stdio' transport type. Requires a JSON payload specifying server details like name, command, and arguments.

```bash
curl -X POST http://localhost:8081/api/mcp/servers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "fetch-server",
    "description": "网页抓取工具服务器",
    "transport_type": "stdio",
    "command": "uvx",
    "args": ["mcp-server-fetch"],
    "env": {
      "HTTP_PROXY": "http://127.0.0.1:8080"
    },
    "disabled": false
  }'
```

--------------------------------

### Configuration Management API

Source: https://github.com/lubyruffy/mcpagent/blob/main/web/README.md

These endpoints allow for retrieving and updating the MCP Agent's configuration, including LLM settings, MCP server details, tool selections, and system prompts.

```APIDOC
## Configuration Management API

### Description
APIs for managing the MCP Agent's configuration. This includes fetching current settings and updating them.

### GET /api/config

#### Description
Retrieves the current configuration of the MCP Agent.

#### Method
GET

#### Endpoint
`/api/config`

#### Parameters
None

#### Request Example
None

#### Response
##### Success Response (200 OK)
- **llm** (object) - LLM configuration details.
- **mcp** (object) - MCP server configuration details.
- **system_prompt** (string) - The system prompt for the agent.
- **max_step** (integer) - Maximum number of steps for agent execution.

##### Response Example
```json
{
  "llm": {
    "type": "openai",
    "base_url": "https://api.openai.com/v1",
    "model": "gpt-4",
    "api_key": "sk-..."
  },
  "mcp": {
    "config_file": "mcp_servers.json",
    "tools": [
      "fetch_fetch",
      "ddg-search_search"
    ]
  },
  "system_prompt": "You are an AI assistant...",
  "max_step": 20
}
```

### POST /api/config

#### Description
Updates the configuration of the MCP Agent.

#### Method
POST

#### Endpoint
`/api/config`

#### Parameters
##### Request Body
- **llm** (object) - Optional. LLM configuration details to update.
- **mcp** (object) - Optional. MCP server configuration details to update.
- **system_prompt** (string) - Optional. The system prompt for the agent.
- **max_step** (integer) - Optional. Maximum number of steps for agent execution.

#### Request Example
```json
{
  "llm": {
    "model": "gpt-3.5-turbo"
  },
  "max_step": 30
}
```

#### Response
##### Success Response (200 OK)
- **message** (string) - Confirmation message indicating successful update.

##### Response Example
```json
{
  "message": "Configuration updated successfully."
}
```
```

--------------------------------

### Debug Mode Commands (Frontend and Backend)

Source: https://github.com/lubyruffy/mcpagent/blob/main/web/README.md

Commands to run the frontend and backend in debug mode for enhanced logging and troubleshooting. These are useful during development.

```bash
# 前端调试
npm run dev

# 后端调试
go run cmd/mcpagent-web/main.go -dev -config config.yaml
```

--------------------------------

### Sync Specific Server Tools - POST /api/mcp/tools/sync/{id}

Source: https://context7.com/lubyruffy/mcpagent/llms.txt

Initiates a synchronization process to fetch tools from a specific MCP server identified by its ID.

```bash
curl -X POST http://localhost:8081/api/mcp/tools/sync/1
```

--------------------------------

### Web API - Configuration Management

Source: https://context7.com/lubyruffy/mcpagent/llms.txt

Endpoints for managing the application's global configuration.

```APIDOC
## Web API - Configuration Management

### Description
Manage the global configuration of the application.

### Method
GET, POST

### Endpoint
`/api/config`

### Parameters
#### Request Body (for POST)
- **llm** (object) - LLM configuration.
  - **type** (string) - Type of LLM (e.g., "ollama", "openai").
  - **base_url** (string) - Base URL of the LLM API.
  - **model** (string) - The LLM model to use.
  - **api_key** (string) - API key for the LLM service.
- **mcp** (object) - MCP agent configuration.
  - **mcp_servers** (object) - Configuration for MCP servers.
  - **tools** (array) - List of tools to use.
- **proxy** (string) - Proxy server URL.
- **max_step** (integer) - Maximum number of steps for tasks.
- **system_prompt** (string) - Default system prompt for LLM.
- **placeholders** (object) - Custom placeholders for prompts.

### Request Example (GET)
```bash
curl http://localhost:8081/api/config
```

### Response (GET)
#### Success Response (200)
Returns the current configuration object.
- **llm** (object) - Current LLM configuration.
- **mcp** (object) - Current MCP configuration.
- **proxy** (string) - Current proxy setting.
- **max_step** (integer) - Current max step setting.
- **system_prompt** (string) - Current system prompt.
- **placeholders** (object) - Current placeholders.

#### Response Example (GET)
```json
{
  "llm": {
    "type": "ollama",
    "base_url": "http://127.0.0.1:11434",
    "model": "qwen3:14b",
    "api_key": "ollama"
  },
  "mcp": {
    "mcp_servers": { ... },
    "tools": [ ... ]
  },
  "proxy": "",
  "max_step": 20,
  "system_prompt": "...",
  "placeholders": {
    "field": "网络安全研究领域"
  }
}
```

### Request Example (POST)
```bash
curl -X POST http://localhost:8081/api/config \
  -H "Content-Type: application/json" \
  -d '{
    "llm": {
      "type": "openai",
      "base_url": "https://api.openai.com/v1",
      "model": "gpt-4",
      "api_key": "sk-xxx"
    },
    "mcp": {
      "mcp_servers": {},
      "tools": []
    },
    "max_step": 30,
    "system_prompt": "你是专业的AI助手",
    "placeholders": {}
  }'
```

### Response (POST)
#### Success Response (200)
- **success** (boolean) - Indicates if the configuration update was successful.
- **message** (string) - A message confirming the update.

#### Response Example (POST)
```json
{
  "success": true,
  "message": "配置更新成功并已保存到数据库"
}
```
```