forge-toolkit

Хелперы для разработки MCP-серверов на Go: разбор аргументов, JSON-Schema, результаты, stdio-lifecycle, ${VAR}-экспансия, live-reload конфигов и протокол эмитированных permission-паттернов (probe).

Подходит для написания своих MCP-инструментов (файлы, БД, HTTP, DevOps и т.д.) и совместим с любым MCP-клиентом.

Состав

Пакет	Назначение
git.totmin.ru/en2zmax/forge-toolkit	args / schema / result / env / probe / server
git.totmin.ru/en2zmax/forge-toolkit/validate	валидаторы синтаксиса (JSON/YAML/TOML/XML/INI/ENV/Dockerfile)
git.totmin.ru/en2zmax/forge-toolkit/configreload	live-reload конфига по контент-хэшу

Зависимости тулкита намеренно минимальны: stdlib + официальный modelcontextprotocol/go-sdk (+ yaml.v3/toml в подпакете validate). Это фиксируется в CI (make toolkit-deps).

Установка

Модуль размещён на self-hosted Gitea, поэтому go get идёт напрямую, мимо proxy.golang.org:

export GOPRIVATE=git.totmin.ru
go get git.totmin.ru/en2zmax/forge-toolkit@latest

Быстрый старт

package main

import (
	"context"
	"time"

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

func main() {
	if toolkit.Health() {
		return
	}
	_ = toolkit.Run("my-server", func(s *mcp.Server) {
		mcp.AddTool(s, &mcp.Tool{
			Name:        "get_time",
			Description: "Текущее время сервера (UTC). Read-only.",
			InputSchema: toolkit.Schema(nil, nil),
		}, func(context.Context, *mcp.CallToolRequest, struct{}) (*mcp.CallToolResult, any, error) {
			return toolkit.Text(time.Now().UTC().Format(time.RFC3339)), nil, nil
		})
	})
}

Документация

• docs/ARCHITECTURE.md — контракт и правила сервера.
• docs/quickstart.md — первый инструмент за 10 минут.
• docs/mcp-contract.md — формат результата и probe на проводе.
• template/ — готовый каркас сервера.
• examples/hello-tool/ — минимальный рабочий пример.

Разработка

make test    # go test -race ./...
make lint    # golangci-lint + gofmt
make tidy    # go mod tidy

Лицензия

Apache-2.0 — см. LICENSE.