feat(mcp): initial implementation — MCP server, framework indexer, 10 tools, 8 validation rules (v0.1.0)

Introduces code.nochebuena.dev/einherjar/mcp — the Einherjar Model Context Protocol
server. A remote, streamable-HTTP service that teaches AI assistants about every
other module of the framework: which package exposes which type, what each module
guarantees through its compliance tests, the canonical wiring shape for a service,
and whether a Go snippet follows the conventions. Indexes the framework on disk at
build time and ships a self-contained binary via go:embed; imports nothing from
other einherjar/* modules at compile time.

server (cmd/server):
- Streamable-HTTP MCP server built on github.com/modelcontextprotocol/go-sdk v1.0.0
- mcp.NewServer + mcp.NewStreamableHTTPHandler, served via net/http on EINHERJAR_MCP_ADDR
  (default :8080) and EINHERJAR_MCP_PATH (default /mcp)
- /healthz liveness endpoint; structured JSON logging via log/slog
- Loads the embedded data/index.json once at startup; in-memory for the process lifetime

indexer (cmd/indexer):
- Walks an Einherjar repository checkout (default ../), parses every sibling
  module's go.mod, README.md, CHANGELOG.md, docs/adr/ADR-*.md, doc.go package
  comments, every exported type/interface/func/method/const/var (via go/doc on
  go/parser ASTs), and compliance_test.go
- Captures module dependency edges by regex over each go.mod's require lines
  (einherjar/* paths only; self-reference filtered)
- Appends a synthetic "wire" module documenting canonical application wiring
  conventions, authored at internal/index/builtins/README.md and embedded via
  go:embed; participates in list_modules / get_module / get_example like a real module

internal/index:
- Schema einherjar.mcp/index/v1; types: Index, Module, SubPackage, Symbol, ADR,
  Example, Compliance, InterfaceAssert, ComplianceTest
- Build(repoRoot) → *Index walks the repo; BuildBuiltins() returns the synthetic
  wire module from the embedded markdown
- Load([]byte) → *Index validates the schema version on read
- FindModule, SearchSymbols helpers used by tools

internal/tools (10 tools):
- list_modules — enumerate every module with purpose + sub-packages
- get_module — package doc, dependencies, sub-packages, key symbols, ADRs,
  compliance counts; optional embedded README
- search_symbols — full-text across name, doc, sub-package, module; filterable by
  module and kind
- get_symbol — full signature, doc comment, source file:line for one symbol
- list_adrs — list ADRs across the framework or within one module
- get_adr — fetch one ADR's markdown body
- get_example — canonical usage snippets extracted from module READMEs and from
  the synthetic wire conventions
- get_compliance — interface assertions (var _ Iface = impl) and structural test
  names from a module's compliance_test.go
- get_changelog — full CHANGELOG.md markdown for one module
- validate_snippet — pattern-match a Go snippet against framework conventions

internal/rules (8 rules, registered via init() against a single registered slice):
- launcher.missing-run — launcher constructed but Run() never called
- launcher.no-components — launcher.New() called without any .Append(...)
- launcher.run-error-discarded — lc.Run() invoked as an ExprStmt (return ignored)
- logz.direct-env-read — os.Getenv("EINHERJAR_LOG_*") bypassing logz config
- web.server-not-appended — web/server constructed but not added to the launcher
- wire.hook-bad-signature — with<Feature>(...) first param is not launcher.Launcher
- wire.hook-outside-beforestart — repo/service/handler construction or route
  registration at the top level of a hook (outside lc.BeforeStart)
- wire.route-specific-after-param — /users/{id} registered before a sibling
  /users/me of the same length and method (chi would shadow the literal route)

Synthetic wire module (internal/index/builtins/README.md):
- Project layout (cmd/<app>/main.go + internal/wire/*.go + per-feature domain dirs)
- Canonical Run() shape: config → logger → infra (db, cache, pool, mc, srv) → cross-
  cutting (validator, permission provider) → launcher.New → lc.Append(infra...) →
  withMigrations / withSuperAdminSeed / withHealth / withFeature hooks → return lc.Run()
- Canonical with<Feature> hook shape: signature (launcher.Launcher first, server.Server
  second, deps last), single lc.BeforeStart closure containing all construction +
  route registration
- chi route ordering, srv.With(authz(...)) authorization, middleware helpers
  (authz / skipPublicPaths / skipMethodPath), tokenSignerAdapter pattern showing
  that the framework exposes Signer.Sign as a primitive and the application owns
  the access/refresh response shape

Packaging:
- Multi-stage Dockerfile that builds from the einherjar repository root
  (docker build -f mcp/Dockerfile .) so cmd/indexer can walk every sibling module
  at image-build time; runtime layer is gcr.io/distroless/static-debian12:nonroot
- 86-byte placeholder data/index.json committed once with `git add -f`; subsequent
  indexer runs overwrite it locally but the file is .gitignored
- .gitea/CODEOWNERS and pull_request_template.md mirror the sibling layout

Design notes:
- mcp depends on nothing in einherjar/* — it reads the framework via the filesystem
  at index time. This keeps mcp outside the framework dependency graph and lets it
  index any version of einherjar without versioning itself in lock-step.
- All structured-output tool responses initialise empty slices ([]Type{}) rather
  than relying on Go's nil-marshals-to-null default, so the SDK's JSON-schema
  output validator never rejects a tools/call result.

internal/tools/get_adr.go

@@ -0,0 +1,40 @@
+package tools
+
+import (
+	"context"
+	"strings"
+
+	"code.nochebuena.dev/einherjar/mcp/internal/index"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+type getADRInput struct {
+	Module string `json:"module" jsonschema:"the module name owning the ADR, e.g. core"`
+	ID     string `json:"id" jsonschema:"the ADR identifier, e.g. ADR-001"`
+}
+
+type getADROutput struct {
+	Module string `json:"module"`
+	ID     string `json:"id"`
+	Title  string `json:"title"`
+	Body   string `json:"body"`
+}
+
+func registerGetADR(s *mcp.Server, idx *index.Index) {
+	mcp.AddTool(s, &mcp.Tool{
+		Name:        "get_adr",
+		Description: "Fetch the full markdown body of one architectural decision record by module and ID.",
+	}, func(ctx context.Context, req *mcp.CallToolRequest, args getADRInput) (*mcp.CallToolResult, getADROutput, error) {
+		m := idx.FindModule(args.Module)
+		if m == nil {
+			return errorResult("module not found: " + args.Module), getADROutput{}, nil
+		}
+		for _, a := range m.ADRs {
+			if strings.EqualFold(a.ID, args.ID) {
+				out := getADROutput{Module: m.Name, ID: a.ID, Title: a.Title, Body: a.Body}
+				return jsonText(out), out, nil
+			}
+		}
+		return errorResult("ADR not found: " + args.ID + " in module " + args.Module), getADROutput{}, nil
+	})
+}

internal/tools/get_changelog.go

@@ -0,0 +1,31 @@
+package tools
+
+import (
+	"context"
+
+	"code.nochebuena.dev/einherjar/mcp/internal/index"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+type getChangelogInput struct {
+	Module string `json:"module" jsonschema:"the module name, e.g. core"`
+}
+
+type getChangelogOutput struct {
+	Module    string `json:"module"`
+	Changelog string `json:"changelog"`
+}
+
+func registerGetChangelog(s *mcp.Server, idx *index.Index) {
+	mcp.AddTool(s, &mcp.Tool{
+		Name:        "get_changelog",
+		Description: "Return the CHANGELOG.md markdown for one Einherjar module. Use to learn what changed in recent releases and to advise on upgrade-relevant differences.",
+	}, func(ctx context.Context, req *mcp.CallToolRequest, args getChangelogInput) (*mcp.CallToolResult, getChangelogOutput, error) {
+		m := idx.FindModule(args.Module)
+		if m == nil {
+			return errorResult("module not found: " + args.Module), getChangelogOutput{}, nil
+		}
+		out := getChangelogOutput{Module: m.Name, Changelog: m.Changelog}
+		return jsonText(out), out, nil
+	})
+}

internal/tools/get_compliance.go

@@ -0,0 +1,44 @@
+package tools
+
+import (
+	"context"
+
+	"code.nochebuena.dev/einherjar/mcp/internal/index"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+type getComplianceInput struct {
+	Module string `json:"module" jsonschema:"the module name, e.g. core"`
+}
+
+type getComplianceOutput struct {
+	Module           string                  `json:"module"`
+	InterfaceAsserts []index.InterfaceAssert `json:"interfaceAsserts"`
+	Tests            []index.ComplianceTest  `json:"tests"`
+}
+
+func registerGetCompliance(s *mcp.Server, idx *index.Index) {
+	mcp.AddTool(s, &mcp.Tool{
+		Name:        "get_compliance",
+		Description: "Return a module's machine-checked conventions from compliance_test.go: every `var _ Iface = impl` interface assertion (the contracts the module promises to satisfy) and every Test* function (the structural rules the module enforces on itself). Use this before writing or reviewing code in a module to learn which conventions are actively guarded.",
+	}, func(ctx context.Context, req *mcp.CallToolRequest, args getComplianceInput) (*mcp.CallToolResult, getComplianceOutput, error) {
+		m := idx.FindModule(args.Module)
+		if m == nil {
+			return errorResult("module not found: " + args.Module), getComplianceOutput{}, nil
+		}
+		asserts := m.Compliance.InterfaceAsserts
+		if asserts == nil {
+			asserts = []index.InterfaceAssert{}
+		}
+		tests := m.Compliance.Tests
+		if tests == nil {
+			tests = []index.ComplianceTest{}
+		}
+		out := getComplianceOutput{
+			Module:           m.Name,
+			InterfaceAsserts: asserts,
+			Tests:            tests,
+		}
+		return jsonText(out), out, nil
+	})
+}

internal/tools/get_example.go

@@ -0,0 +1,39 @@
+package tools
+
+import (
+	"context"
+	"strings"
+
+	"code.nochebuena.dev/einherjar/mcp/internal/index"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+type getExampleInput struct {
+	Module string `json:"module" jsonschema:"the module name, e.g. core"`
+	Topic  string `json:"topic,omitempty" jsonschema:"optional substring matched against the example title (case-insensitive)"`
+}
+
+type getExampleOutput struct {
+	Examples []index.Example `json:"examples"`
+}
+
+func registerGetExample(s *mcp.Server, idx *index.Index) {
+	mcp.AddTool(s, &mcp.Tool{
+		Name:        "get_example",
+		Description: "Return canonical usage examples for a module, extracted from its README. Filter by topic substring (e.g. 'Logger', 'Launcher') to narrow the result.",
+	}, func(ctx context.Context, req *mcp.CallToolRequest, args getExampleInput) (*mcp.CallToolResult, getExampleOutput, error) {
+		m := idx.FindModule(args.Module)
+		if m == nil {
+			return errorResult("module not found: " + args.Module), getExampleOutput{}, nil
+		}
+		needle := strings.ToLower(args.Topic)
+		out := getExampleOutput{Examples: []index.Example{}}
+		for _, ex := range m.Examples {
+			if needle != "" && !strings.Contains(strings.ToLower(ex.Title), needle) {
+				continue
+			}
+			out.Examples = append(out.Examples, ex)
+		}
+		return jsonText(out), out, nil
+	})
+}

internal/tools/get_module.go

@@ -0,0 +1,103 @@
+package tools
+
+import (
+	"context"
+
+	"code.nochebuena.dev/einherjar/mcp/internal/index"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+type getModuleInput struct {
+	Name          string `json:"name" jsonschema:"the module name, e.g. core, web, auth-jwt"`
+	IncludeReadme bool   `json:"includeReadme,omitempty" jsonschema:"when true, embed the full README markdown in the response"`
+}
+
+type getModuleOutput struct {
+	Name        string             `json:"name"`
+	ImportPath  string             `json:"importPath"`
+	Purpose     string             `json:"purpose"`
+	Doc         string             `json:"doc"`
+	GoVersion   string             `json:"goVersion"`
+	DependsOn   []string           `json:"dependsOn"`
+	SubPackages []index.SubPackage `json:"subPackages"`
+	KeySymbols  []symbolHeader     `json:"keySymbols"`
+	ADRs        []adrHeader        `json:"adrs"`
+	Compliance  complianceSummary  `json:"compliance"`
+	Readme      string             `json:"readme,omitempty"`
+}
+
+type complianceSummary struct {
+	InterfaceAssertCount int `json:"interfaceAssertCount"`
+	TestCount            int `json:"testCount"`
+}
+
+type symbolHeader struct {
+	Kind       string `json:"kind"`
+	Name       string `json:"name"`
+	SubPackage string `json:"subPackage"`
+	Signature  string `json:"signature"`
+}
+
+type adrHeader struct {
+	ID    string `json:"id"`
+	Title string `json:"title"`
+}
+
+func registerGetModule(s *mcp.Server, idx *index.Index) {
+	mcp.AddTool(s, &mcp.Tool{
+		Name:        "get_module",
+		Description: "Describe one Einherjar module: sub-packages, key exported symbols (types/interfaces/funcs), and ADRs. Set includeReadme=true to also receive the README markdown.",
+	}, func(ctx context.Context, req *mcp.CallToolRequest, args getModuleInput) (*mcp.CallToolResult, getModuleOutput, error) {
+		m := idx.FindModule(args.Name)
+		if m == nil {
+			return errorResult("module not found: " + args.Name), getModuleOutput{}, nil
+		}
+
+		key := make([]symbolHeader, 0, len(m.Symbols))
+		for _, sym := range m.Symbols {
+			if sym.Kind == "type" || sym.Kind == "interface" || sym.Kind == "func" {
+				key = append(key, symbolHeader{
+					Kind: sym.Kind, Name: sym.Name, SubPackage: sym.SubPackage, Signature: sym.Signature,
+				})
+			}
+		}
+
+		adrs := make([]adrHeader, 0, len(m.ADRs))
+		for _, a := range m.ADRs {
+			adrs = append(adrs, adrHeader{ID: a.ID, Title: a.Title})
+		}
+
+		subs := make([]index.SubPackage, 0, len(m.SubPackages))
+		for _, sp := range m.SubPackages {
+			if sp.Name == "" {
+				continue
+			}
+			subs = append(subs, sp)
+		}
+
+		deps := m.DependsOn
+		if deps == nil {
+			deps = []string{}
+		}
+
+		out := getModuleOutput{
+			Name:        m.Name,
+			ImportPath:  m.ImportPath,
+			Purpose:     m.Purpose,
+			Doc:         m.Doc,
+			GoVersion:   m.GoVersion,
+			DependsOn:   deps,
+			SubPackages: subs,
+			KeySymbols:  key,
+			ADRs:        adrs,
+			Compliance: complianceSummary{
+				InterfaceAssertCount: len(m.Compliance.InterfaceAsserts),
+				TestCount:            len(m.Compliance.Tests),
+			},
+		}
+		if args.IncludeReadme {
+			out.Readme = m.Readme
+		}
+		return jsonText(out), out, nil
+	})
+}

internal/tools/get_symbol.go

@@ -0,0 +1,42 @@
+package tools
+
+import (
+	"context"
+	"strings"
+
+	"code.nochebuena.dev/einherjar/mcp/internal/index"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+type getSymbolInput struct {
+	Module     string `json:"module" jsonschema:"the module name, e.g. core"`
+	Name       string `json:"name" jsonschema:"the symbol name; for methods use Type.Method"`
+	SubPackage string `json:"subPackage,omitempty" jsonschema:"narrow to a specific sub-package, e.g. launcher"`
+}
+
+type getSymbolOutput struct {
+	Matches []index.Symbol `json:"matches"`
+}
+
+func registerGetSymbol(s *mcp.Server, idx *index.Index) {
+	mcp.AddTool(s, &mcp.Tool{
+		Name:        "get_symbol",
+		Description: "Fetch full signature, doc comment, and source location for one symbol. Returns every match across sub-packages — use the subPackage filter when ambiguous.",
+	}, func(ctx context.Context, req *mcp.CallToolRequest, args getSymbolInput) (*mcp.CallToolResult, getSymbolOutput, error) {
+		m := idx.FindModule(args.Module)
+		if m == nil {
+			return errorResult("module not found: " + args.Module), getSymbolOutput{}, nil
+		}
+		out := getSymbolOutput{Matches: []index.Symbol{}}
+		for _, sym := range m.Symbols {
+			if !strings.EqualFold(sym.Name, args.Name) {
+				continue
+			}
+			if args.SubPackage != "" && sym.SubPackage != args.SubPackage {
+				continue
+			}
+			out.Matches = append(out.Matches, sym)
+		}
+		return jsonText(out), out, nil
+	})
+}

internal/tools/list_adrs.go

@@ -0,0 +1,40 @@
+package tools
+
+import (
+	"context"
+
+	"code.nochebuena.dev/einherjar/mcp/internal/index"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+type listADRsInput struct {
+	Module string `json:"module,omitempty" jsonschema:"restrict to one module by name"`
+}
+
+type listADRsOutput struct {
+	ADRs []adrSummary `json:"adrs"`
+}
+
+type adrSummary struct {
+	Module string `json:"module"`
+	ID     string `json:"id"`
+	Title  string `json:"title"`
+}
+
+func registerListADRs(s *mcp.Server, idx *index.Index) {
+	mcp.AddTool(s, &mcp.Tool{
+		Name:        "list_adrs",
+		Description: "List architectural decision records across Einherjar. Optionally restrict to one module. Use to discover the rationale behind framework design choices.",
+	}, func(ctx context.Context, req *mcp.CallToolRequest, args listADRsInput) (*mcp.CallToolResult, listADRsOutput, error) {
+		out := listADRsOutput{ADRs: []adrSummary{}}
+		for _, m := range idx.Modules {
+			if args.Module != "" && m.Name != args.Module {
+				continue
+			}
+			for _, a := range m.ADRs {
+				out.ADRs = append(out.ADRs, adrSummary{Module: m.Name, ID: a.ID, Title: a.Title})
+			}
+		}
+		return jsonText(out), out, nil
+	})
+}

internal/tools/list_modules.go

@@ -0,0 +1,47 @@
+package tools
+
+import (
+	"context"
+
+	"code.nochebuena.dev/einherjar/mcp/internal/index"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+type listModulesInput struct{}
+
+type moduleSummary struct {
+	Name        string   `json:"name"`
+	ImportPath  string   `json:"importPath"`
+	Purpose     string   `json:"purpose"`
+	GoVersion   string   `json:"goVersion"`
+	SubPackages []string `json:"subPackages"`
+}
+
+type listModulesOutput struct {
+	Modules []moduleSummary `json:"modules"`
+}
+
+func registerListModules(s *mcp.Server, idx *index.Index) {
+	mcp.AddTool(s, &mcp.Tool{
+		Name:        "list_modules",
+		Description: "List every module of the Einherjar framework with its purpose, import path, Go version, and sub-packages. Use this first to discover what the framework offers.",
+	}, func(ctx context.Context, req *mcp.CallToolRequest, _ listModulesInput) (*mcp.CallToolResult, listModulesOutput, error) {
+		out := listModulesOutput{Modules: make([]moduleSummary, 0, len(idx.Modules))}
+		for _, m := range idx.Modules {
+			subs := make([]string, 0, len(m.SubPackages))
+			for _, sp := range m.SubPackages {
+				if sp.Name != "" {
+					subs = append(subs, sp.Name)
+				}
+			}
+			out.Modules = append(out.Modules, moduleSummary{
+				Name:        m.Name,
+				ImportPath:  m.ImportPath,
+				Purpose:     m.Purpose,
+				GoVersion:   m.GoVersion,
+				SubPackages: subs,
+			})
+		}
+		return jsonText(out), out, nil
+	})
+}

internal/tools/search_symbols.go

@@ -0,0 +1,48 @@
+package tools
+
+import (
+	"context"
+
+	"code.nochebuena.dev/einherjar/mcp/internal/index"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+type searchSymbolsInput struct {
+	Query  string `json:"query" jsonschema:"text to match against symbol name, doc comment, sub-package, or module"`
+	Limit  int    `json:"limit,omitempty" jsonschema:"max results (default 25)"`
+	Module string `json:"module,omitempty" jsonschema:"restrict to one module by name"`
+	Kind   string `json:"kind,omitempty" jsonschema:"restrict to one kind: type, interface, func, method, const, var"`
+}
+
+type searchSymbolsOutput struct {
+	Results []index.Symbol `json:"results"`
+	Total   int            `json:"total"`
+}
+
+func registerSearchSymbols(s *mcp.Server, idx *index.Index) {
+	mcp.AddTool(s, &mcp.Tool{
+		Name:        "search_symbols",
+		Description: "Search Einherjar's exported symbols (types, interfaces, funcs, methods, consts, vars) by name or doc text. Optionally filter by module or kind. Use when you need to find where a type or function lives.",
+	}, func(ctx context.Context, req *mcp.CallToolRequest, args searchSymbolsInput) (*mcp.CallToolResult, searchSymbolsOutput, error) {
+		all := idx.SearchSymbols(args.Query, args.Limit*4+25)
+		filtered := all[:0]
+		for _, sym := range all {
+			if args.Module != "" && sym.Module != args.Module {
+				continue
+			}
+			if args.Kind != "" && sym.Kind != args.Kind {
+				continue
+			}
+			filtered = append(filtered, sym)
+		}
+		limit := args.Limit
+		if limit <= 0 {
+			limit = 25
+		}
+		if len(filtered) > limit {
+			filtered = filtered[:limit]
+		}
+		out := searchSymbolsOutput{Results: filtered, Total: len(filtered)}
+		return jsonText(out), out, nil
+	})
+}

internal/tools/tools.go

@@ -0,0 +1,48 @@
+// Package tools wires Einherjar MCP tools to a server. Each tool lives in its
+// own file alongside its input and output types.
+package tools
+
+import (
+	"encoding/json"
+
+	"code.nochebuena.dev/einherjar/mcp/internal/index"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+// Register binds every tool implemented in this package to s, sharing the
+// provided index as their backing knowledge.
+func Register(s *mcp.Server, idx *index.Index) {
+	registerListModules(s, idx)
+	registerGetModule(s, idx)
+	registerSearchSymbols(s, idx)
+	registerGetSymbol(s, idx)
+	registerListADRs(s, idx)
+	registerGetADR(s, idx)
+	registerGetExample(s, idx)
+	registerValidateSnippet(s, idx)
+	registerGetCompliance(s, idx)
+	registerGetChangelog(s, idx)
+}
+
+// jsonText returns a CallToolResult whose single text block is the JSON
+// encoding of v. The same value is also returned as the structured output,
+// so hosts that surface structured outputs get a typed payload.
+func jsonText(v any) *mcp.CallToolResult {
+	b, err := json.MarshalIndent(v, "", "  ")
+	if err != nil {
+		return &mcp.CallToolResult{
+			IsError: true,
+			Content: []mcp.Content{&mcp.TextContent{Text: "encode error: " + err.Error()}},
+		}
+	}
+	return &mcp.CallToolResult{
+		Content: []mcp.Content{&mcp.TextContent{Text: string(b)}},
+	}
+}
+
+func errorResult(msg string) *mcp.CallToolResult {
+	return &mcp.CallToolResult{
+		IsError: true,
+		Content: []mcp.Content{&mcp.TextContent{Text: msg}},
+	}
+}

internal/tools/validate_snippet.go

@@ -0,0 +1,82 @@
+package tools
+
+import (
+	"context"
+
+	"code.nochebuena.dev/einherjar/mcp/internal/index"
+	"code.nochebuena.dev/einherjar/mcp/internal/rules"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+type validateSnippetInput struct {
+	Code string `json:"code" jsonschema:"Go source code to validate against Einherjar conventions. A full file is preferred; a partial body will be wrapped automatically."`
+}
+
+type validateSnippetOutput struct {
+	Findings []rules.Finding `json:"findings"`
+	Summary  string          `json:"summary"`
+}
+
+func registerValidateSnippet(s *mcp.Server, _ *index.Index) {
+	mcp.AddTool(s, &mcp.Tool{
+		Name:        "validate_snippet",
+		Description: "Validate a Go snippet against Einherjar wiring conventions: lifecycle setup, logger configuration, env-var handling, server registration. Findings are advisory, not a substitute for go vet or the project's tests.",
+	}, func(ctx context.Context, req *mcp.CallToolRequest, args validateSnippetInput) (*mcp.CallToolResult, validateSnippetOutput, error) {
+		findings := rules.Run(args.Code)
+		if findings == nil {
+			findings = []rules.Finding{}
+		}
+		summary := summarise(findings)
+		out := validateSnippetOutput{Findings: findings, Summary: summary}
+		return jsonText(out), out, nil
+	})
+}
+
+func summarise(fs []rules.Finding) string {
+	if len(fs) == 0 {
+		return "No issues found — snippet follows Einherjar conventions."
+	}
+	var errs, warns, infos int
+	for _, f := range fs {
+		switch f.Severity {
+		case rules.SeverityError:
+			errs++
+		case rules.SeverityWarning:
+			warns++
+		case rules.SeverityInfo:
+			infos++
+		}
+	}
+	return pluralise(errs, "error", "errors") + ", " +
+		pluralise(warns, "warning", "warnings") + ", " +
+		pluralise(infos, "note", "notes")
+}
+
+func pluralise(n int, singular, plural string) string {
+	if n == 1 {
+		return "1 " + singular
+	}
+	return itoa(n) + " " + plural
+}
+
+func itoa(n int) string {
+	if n == 0 {
+		return "0"
+	}
+	neg := n < 0
+	if neg {
+		n = -n
+	}
+	var buf [20]byte
+	i := len(buf)
+	for n > 0 {
+		i--
+		buf[i] = byte('0' + n%10)
+		n /= 10
+	}
+	if neg {
+		i--
+		buf[i] = '-'
+	}
+	return string(buf[i:])
+}