forge-toolkit/docs/quickstart.md

Быстрый старт: первый инструмент за 10 минут

Сделаем MCP-сервер с одним инструментом echo, который возвращает переданный текст.

1. Модуль

mkdir my-mcp && cd my-mcp
go mod init example.com/my-mcp
export GOPRIVATE=git.totmin.ru
go get git.totmin.ru/en2zmax/forge-toolkit@latest
go get github.com/modelcontextprotocol/go-sdk@latest

2. Инструмент

internal/tools/tools.go:

package tools

import (
	"context"

	"github.com/modelcontextprotocol/go-sdk/mcp"
	"git.totmin.ru/en2zmax/forge-toolkit"
)

func RegisterAll(s *mcp.Server) {
	mcp.AddTool(s, &mcp.Tool{
		Name:        "echo",
		Description: "Возвращает переданный текст. Без побочных эффектов.",
		InputSchema: toolkit.Schema(map[string]any{
			"text": toolkit.StrProps("текст для возврата", true),
		}, []string{"text"}),
	}, handleEcho)
}

func handleEcho(_ context.Context, req *mcp.CallToolRequest, _ struct{}) (*mcp.CallToolResult, any, error) {
	text, err := toolkit.RequireString(toolkit.RequestArgs(req), "text")
	if err != nil {
		return toolkit.Error(err.Error()), nil, nil
	}
	return toolkit.Text(text), nil, nil
}

3. main.go

package main

import (
	"fmt"
	"os"

	"example.com/my-mcp/internal/tools"

	"github.com/modelcontextprotocol/go-sdk/mcp"
	"git.totmin.ru/en2zmax/forge-toolkit"
)

func main() {
	if toolkit.Health() {
		return
	}
	if err := toolkit.Run("my-mcp", func(s *mcp.Server) {
		tools.RegisterAll(s)
	}); err != nil {
		fmt.Fprintf(os.Stderr, "my-mcp: %v\n", err)
		os.Exit(1)
	}
}

4. Сборка и проверка

go mod tidy
go build -o my-mcp .
./my-mcp --health        # → ok

5. Подключение

Любой MCP-клиент (Claude Desktop, Cursor и т.п.) — как обычный stdio-сервер:

{
  "mcpServers": {
    "my-mcp": { "command": "/abs/path/my-mcp" }
  }
}

Агентная платформа Forge — сервер объявляется оператором в конфиге, а агент подключает его по имени. Например, глобально:

{
  "mcp": {
    "servers": {
      "my-mcp": { "command": "/abs/path/my-mcp", "args": [] }
    }
  }
}

и в агенте:

mcp_servers:
  - my-mcp

Инструмент станет доступен модели как my-mcp__echo.

Дальше

• Контракт и правила — ARCHITECTURE.md.
• Формат результата/probe — mcp-contract.md.
• Каркас с конфигом и Makefile — ../template/.