03. 行动篇：Agent 与 MCP 协议实战

1. 从 Chatbot 到 Agent

单纯的 LLM 只能“说话”。要让它帮你“干活”（如查数据库、写文件、部署服务），就需要 Agent（智能体）。

1.1 Agent 的核心公式

Agent = LLM + Tools + Planning (ReAct) + Memory

• Tools: 函数/API，给 AI 提供的工具箱。
• Planning: AI 思考“先用什么工具，再用什么工具”的过程。
• ReAct: Reasoning (推理) + Acting (行动) 的循环。

1.2 Tool Calling (Function Calling)

这是 Agent 的基石。OpenAI 等模型原生支持 tools 参数。 你定义一个 JSON Schema 描述函数，模型返回 JSON 告诉你要调用哪个函数及参数，你执行完后将结果返给模型。

2. 什么是 MCP (Model Context Protocol)?

在 Agent 开发中，最大的痛点是工具碎片化。Claude Desktop 想读你的本地文件，ChatGPT 想连你的 PostgreSQL，每个都要写专门的 Adapter。

MCP (Model Context Protocol) 是 Anthropic 推出的开放标准，旨在标准化 LLM 应用与外部数据/工具的连接。

• MCP Server: 提供资源（Resources）、工具（Tools）或提示词（Prompts）。
• MCP Client: 调用 Server 的 LLM 应用（如 Claude Desktop, Cursor, 自研 Agent）。

一句话总结：MCP 就像 AI 时代的 USB 接口。你只要用 Go 写一个 MCP Server，任何支持 MCP 的 AI（如 Claude）都能直接使用你的工具。

3. 实战：用 Go 开发第一个 MCP Server

我们将构建一个 FileSystem MCP Server，允许 AI 读取我们电脑上的文件。

3.1 环境准备

go get github.com/mark3labs/mcp-go

3.2 代码实现

创建 main.go:

package main

import (
	"context"
	"fmt"
	"os"
	"path/filepath"

	"github.com/mark3labs/mcp-go/mcp"
	"github.com/mark3labs/mcp-go/server"
)

func main() {
	// 1. 创建 MCP Server
	s := server.NewMCPServer(
		"Go-File-Agent",
		"1.0.0",
		server.WithToolCapabilities(true),
	)

	// 2. 定义工具: list_files
	listFilesTool := mcp.NewTool("list_files",
		mcp.WithDescription("列出指定目录下的文件"),
		mcp.WithString("path", mcp.Required(), mcp.Description("绝对路径")),
	)

	// 3. 注册工具实现
	s.AddTool(listFilesTool, func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
		dirPath, err := request.Params.GetString("path")
		if err != nil {
			return mcp.NewToolResultError("path is required"), nil
		}

		files, err := os.ReadDir(dirPath)
		if err != nil {
			return mcp.NewToolResultError(fmt.Sprintf("无法读取目录: %v", err)), nil
		}

		var result string
		for _, f := range files {
			typeStr := "File"
			if f.IsDir() {
				typeStr = "Dir "
			}
			result += fmt.Sprintf("[%s] %s\n", typeStr, f.Name())
		}

		return mcp.NewToolResultText(result), nil
	})

	// 4. 定义工具: read_file
	readFileTool := mcp.NewTool("read_file",
		mcp.WithDescription("读取文件内容"),
		mcp.WithString("path", mcp.Required(), mcp.Description("文件的绝对路径")),
	)

	s.AddTool(readFileTool, func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
		filePath, err := request.Params.GetString("path")
		if err != nil {
			return mcp.NewToolResultError("path is required"), nil
		}

		content, err := os.ReadFile(filePath)
		if err != nil {
			return mcp.NewToolResultError(fmt.Sprintf("无法读取文件: %v", err)), nil
		}

		return mcp.NewToolResultText(string(content)), nil
	})

	// 5. 启动服务 (标准输入输出模式，供 Claude Desktop 调用)
	fmt.Fprintln(os.Stderr, "MCP Server running on stdio...")
	if err := server.ServeStdio(s); err != nil {
		fmt.Fprintf(os.Stderr, "Server error: %v\n", err)
	}
}

3.3 编译与安装

go build -o mcp-server.exe main.go

3.4 连接到 Claude Desktop

1. 下载并安装 Claude Desktop。
2. 打开配置文件 (Windows: %APPDATA%\Claude\claude_desktop_config.json)。
3. 添加你的 Go Server 配置：

{
  "mcpServers": {
    "my-go-agent": {
      "command": "C:\\path\\to\\your\\mcp-server.exe",
      "args": []
    }
  }
}

4. 重启 Claude Desktop。现在，你可以直接在 Claude 对话框里说：“请帮我看看 D:\Project\src 目录下有哪些文件？”，Claude 就会自动调用你写的 Go 代码！

4. 为什么这对 Go 开发者很重要？

• 后端能力暴露: 你现有的 Go 微服务（查库存、重启 Pod、查日志）可以通过 MCP 瞬间变成 AI 的工具。
• 本地隐私: 数据不需要上传到云端，AI 通过本地 MCP Server 操作本地数据。
• 开发体验: 相比于 Python，Go 编译出的单文件 Server 分发给用户（或集成到 Desktop App）极其方便。

5. 进阶作业

1. 添加一个 write_file 工具，让 AI 能帮你写代码。
2. 实现一个 search_db 工具，连接 MySQL 数据库并执行 SQL 查询。