用 Go 官方 SDK 造首个 MCP 工具：从零到接入 Claude Code

// Input 结构体 = 工具的入参契约
type ProbeInput struct {
    Host    string `json:"host"    jsonschema:"the hostname or IP to probe"`
    Port    int    `json:"port"    jsonschema:"the TCP port number (1-65535)"`
    Timeout int    `json:"timeout" jsonschema:"timeout in milliseconds, default 3000"`
}

func TCPProbe(ctx context.Context, req *mcp.CallToolRequest, in ProbeInput) (*mcp.CallToolResult, ProbeOutput, error) {
    // in 已经是反序列化好的强类型结构体，直接用
    ...
    return nil, ProbeOutput{...}, nil   // 第一个返回值通常是 nil
}

mkdir netcheck-mcp && cd netcheck-mcp
go mod init github.com/yourname/netcheck-mcp
go get github.com/modelcontextprotocol/go-sdk/mcp@latest

package main

import (
    "context"
    "log"

    "github.com/modelcontextprotocol/go-sdk/mcp"
)

// ---- 第一个工具：问候 ----
type HelloInput struct {
    Name string `json:"name" jsonschema:"the name of the person to greet"`
}

type HelloOutput struct {
    Greeting string `json:"greeting" jsonschema:"the greeting text returned to the user"`
}

func SayHi(ctx context.Context, req *mcp.CallToolRequest, in HelloInput) (*mcp.CallToolResult, HelloOutput, error) {
    return nil, HelloOutput{Greeting: "你好，" + in.Name + "！我是用 Go 写的 MCP 工具。"}, nil
}

func main() {
    server := mcp.NewServer(&mcp.Implementation{Name: "netcheck", Version: "v0.1.0"}, nil)

    // 注册工具：传入 server、工具元数据、handler
    mcp.AddTool(server, &mcp.Tool{
        Name:        "greet",
        Description: "向指定的人打招呼，用于验证 MCP 链路是否通畅",
    }, SayHi)

    // 通过 stdin/stdout 运行，直到客户端断开
    if err := server.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
        log.Fatal(err)
    }
}

go build -o netcheck-mcp .
./netcheck-mcp        # 会卡住等待输入，按 Ctrl+C 退出 —— 这是正常的

claude mcp add netcheck -- /absolute/path/to/netcheck-mcp

claude mcp list        # 应该看到 netcheck
claude mcp get netcheck   # 查看完整配置

claude

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"
    "net"
    "net/http"
    "time"

    "github.com/modelcontextprotocol/go-sdk/mcp"
)

const defaultTimeout = 3000 // 毫秒

// ========== 工具 1：DNS 解析 ==========
type DNSInput struct {
    Host string `json:"host" jsonschema:"the hostname to resolve, e.g. example.com"`
}

type DNSOutput struct {
    Host string   `json:"host"`
    IPs  []string `json:"ips" jsonschema:"resolved IP addresses"`
}

func DNSLookup(ctx context.Context, req *mcp.CallToolRequest, in DNSInput) (*mcp.CallToolResult, DNSOutput, error) {
    ips, err := net.LookupHost(in.Host)
    if err != nil {
        // 业务失败：返回带 IsError 的结果，而不是 protocol error
        return &mcp.CallToolResult{
            Content: []mcp.Content{&mcp.TextContent{Text: fmt.Sprintf("DNS 解析失败: %v", err)}},
            IsError: true,
        }, DNSOutput{}, nil
    }
    return nil, DNSOutput{Host: in.Host, IPs: ips}, nil
}

// ========== 工具 2：TCP 端口探测 ==========
type ProbeInput struct {
    Host    string `json:"host"    jsonschema:"hostname or IP to probe"`
    Port    int    `json:"port"    jsonschema:"TCP port, 1-65535"`
    Timeout int    `json:"timeout" jsonschema:"timeout in ms, optional, default 3000"`
}

type ProbeOutput struct {
    Host     string `json:"host"`
    Port     int    `json:"port"`
    Reachable bool  `json:"reachable" jsonschema:"whether the port accepted a connection"`
    RTTMs    int64  `json:"rtt_ms" jsonschema:"round-trip time in milliseconds, -1 if unreachable"`
}

func TCPProbe(ctx context.Context, req *mcp.CallToolRequest, in ProbeInput) (*mcp.CallToolResult, ProbeOutput, error) {
    timeout := in.Timeout
    if timeout <= 0 {
        timeout = defaultTimeout
    }
    addr := fmt.Sprintf("%s:%d", in.Host, in.Port)
    start := time.Now()
    conn, err := net.DialTimeout("tcp", addr, time.Duration(timeout)*time.Millisecond)
    rtt := time.Since(start).Milliseconds()
    if err != nil {
        return nil, ProbeOutput{Host: in.Host, Port: in.Port, Reachable: false, RTTMs: -1}, nil
    }
    conn.Close()
    return nil, ProbeOutput{Host: in.Host, Port: in.Port, Reachable: true, RTTMs: rtt}, nil
}

// ========== 工具 3：HTTP 探测 ==========
type HTTPInput struct {
    URL     string `json:"url"     jsonschema:"full URL including scheme, e.g. https://example.com"`
    Timeout int    `json:"timeout" jsonschema:"timeout in ms, optional, default 3000"`
}

type HTTPOutput struct {
    URL        string `json:"url"`
    StatusCode int    `json:"status_code"`
    RTTMs      int64  `json:"rtt_ms"`
    Server     string `json:"server,omitempty"`
    FinalURL   string `json:"final_url,omitempty"`
}

func HTTPProbe(ctx context.Context, req *mcp.CallToolRequest, in HTTPInput) (*mcp.CallToolResult, HTTPOutput, error) {
    timeout := in.Timeout
    if timeout <= 0 {
        timeout = defaultTimeout
    }
    client := &http.Client{Timeout: time.Duration(timeout) * time.Millisecond}
    start := time.Now()
    resp, err := client.Get(in.URL)
    rtt := time.Since(start).Milliseconds()
    if err != nil {
        return &mcp.CallToolResult{
            Content: []mcp.Content{&mcp.TextContent{Text: fmt.Sprintf("HTTP 请求失败: %v", err)}},
            IsError: true,
        }, HTTPOutput{}, nil
    }
    defer resp.Body.Close()
    return nil, HTTPOutput{
        URL:        in.URL,
        StatusCode: resp.StatusCode,
        RTTMs:      rtt,
        Server:     resp.Header.Get("Server"),
        FinalURL:   resp.Request.URL.String(),
    }, nil
}

// ========== 主函数：注册并运行 ==========
func main() {
    server := mcp.NewServer(&mcp.Implementation{Name: "netcheck", Version: "v0.2.0"}, nil)

    mcp.AddTool(server, &mcp.Tool{
        Name:        "dns_lookup",
        Description: "解析主机名到 IP 地址列表。当用户想知道某个域名解析到哪些 IP 时使用。",
    }, DNSLookup)

    mcp.AddTool(server, &mcp.Tool{
        Name:        "tcp_probe",
        Description: "探测目标主机的 TCP 端口是否可达并测量连接耗时（毫秒）。用于检查服务端口是否开放。",
    }, TCPProbe)

    mcp.AddTool(server, &mcp.Tool{
        Name:        "http_probe",
        Description: "对目标 URL 发起 HTTP GET，返回状态码、耗时、Server 头。用于快速检查网站是否在线。",
    }, HTTPProbe)

    log.Printf("netcheck MCP server starting, %d tools registered", 3) // 走 stderr，不污染协议
    if err := server.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
        log.Fatal(err)
    }
}

go build -o netcheck-mcp .

{
  "mcpServers": {
    "netcheck": {
      "command": "/opt/tools/netcheck-mcp",
      "args": [],
      "env": {}
    }
  }
}

flowchart LR
    U[用户在 Claude Code<br/>输入排障指令] --> CC[Claude Code<br/>模型推理+编排]
    CC -->|读取 .mcp.json<br/>发现工具列表| REG[工具注册表]
    REG --> T1[dns_lookup]
    REG --> T2[tcp_probe]
    REG --> T3[http_probe]
    CC -->|JSON-RPC over stdio<br/>fork 进程| BIN[/netcheck-mcp<br/>Go 二进制/]
    BIN --> T1
    BIN --> T2
    BIN --> T3
    T1 -->|net.LookupHost| NET[(真实网络)]
    T2 -->|net.DialTimeout| NET
    T3 -->|http.Client| NET
    T1 & T2 & T3 -->|结构化 Output| CC
    CC -->|自然语言结论| U
    style BIN fill:#00ADD8,color:#fff
    style CC fill:#d97706,color:#fff