# 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`](https://github.com/modelcontextprotocol/go-sdk)
(+ `yaml.v3`/`toml` в подпакете `validate`). Это фиксируется в CI
(`make toolkit-deps`).

## Установка

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

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

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

```go
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/ARCHITECTURE.md) — контракт и правила сервера.
- [`docs/quickstart.md`](docs/quickstart.md) — первый инструмент за 10 минут.
- [`docs/mcp-contract.md`](docs/mcp-contract.md) — формат результата и probe на проводе.
- [`template/`](template/) — готовый каркас сервера.
- [`examples/hello-tool/`](examples/hello-tool/) — минимальный рабочий пример.

## Разработка

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

## Лицензия

Apache-2.0 — см. [`LICENSE`](LICENSE).