feat(mcp): index struct fields and interface method sets (#1)

Minor release. The indexer named composite types but could not describe
their shape: every declaration was truncated at the first brace, so a
struct symbol carried only its `type X struct` header and an interface
symbol only its `type X interface` header. Field names, field types, and
— most painfully — struct tags such as `env:"EINHERJAR_PG_HOST"` were
dropped, as were the method sets of every port interface. An assistant
could be told that `db-postgres` has a `Config` and a `Provider`, but not
what env vars configure the one or what methods the other requires. This
change captures both.

internal/index (schema):
- Symbol gains two optional fields. `fields` ([]Field) carries a struct's
  field set — name, type, raw struct tag (surrounding backticks stripped),
  doc comment, and an `embedded` marker. `methods` ([]Method) carries an
  interface's method set — name, signature without the leading `func`, and
  doc comment, including embedded interfaces. Both are omitempty and absent
  for every other kind.
- SchemaVersion is deliberately unchanged. The two additions are additive
  and omitempty, so an older consumer parses the new index unchanged; per
  the existing rule the constant only bumps on a breaking format change.

internal/index (builder):
- collectSymbols now inspects each type's TypeSpec and, for a *ast.StructType
  or *ast.InterfaceType, fills the new Symbol members. A grouped field
  declaration (`x, y int`) yields one Field per name; an embedded field or
  interface yields an entry with an empty name.
- New helpers: typeSpecType (underlying type expr of a lone type spec),
  extractFields, extractIfaceMethods, fieldDoc (doc comment or trailing
  line comment), and nodeString — a non-truncating printer used for field
  types, tags, and method signatures, distinct from formatNode which keeps
  truncating to produce the one-line header.

internal/index (search):
- matches() now also tests the query against struct field names, field
  types, and struct tags, and against interface method names and
  signatures. A query like an env-var key or a method name now resolves to
  the type that declares it.

internal/tools:
- get_symbol and search_symbols descriptions updated to advertise the new
  struct-field and interface-method coverage. No input/output schema change
  beyond the additive Symbol fields, which get_symbol already returns whole.

internal/index (tests):
- New builder_test.go — the package previously had no tests. Builds a
  temporary module fixture and asserts capture of struct fields (with tags
  and docs), embedded fields, interface methods (with signatures and docs),
  embedded interfaces, and discovery of a struct by one of its struct tags
  (the failure mode that motivated the change).

Docs:
- CHANGELOG.md gains an [Unreleased] entry; README.md tool table updated to
  state that get_symbol returns struct fields and interface methods and
  that search_symbols matches fields, tags, and methods.

No new dependencies. The committed data/index.json placeholder is untouched
— the index is regenerated at image build (Dockerfile runs cmd/indexer),
so a deployment must be rebuilt to serve the richer index; a server still
running the prior image keeps serving the older, member-less one.

Reviewed-on: #1
Co-authored-by: Rene Nochebuena Guerrero <rene@nochebuena.dev>
Co-committed-by: Rene Nochebuena Guerrero <rene@nochebuena.dev>

internal/index/builder.go

@@ -154,7 +154,14 @@ func collectSymbols(m *Module, sub, modDir string, fset *token.FileSet, p *doc.P
 		if isInterface(t.Decl) {
 			kind = "interface"
 		}
-		m.Symbols = append(m.Symbols, newSymbol(m.Name, sub, kind, t.Name, t.Doc, t.Decl, fset, modDir))
+		sym := newSymbol(m.Name, sub, kind, t.Name, t.Doc, t.Decl, fset, modDir)
+		switch underlying := typeSpecType(t.Decl).(type) {
+		case *ast.StructType:
+			sym.Fields = extractFields(fset, underlying)
+		case *ast.InterfaceType:
+			sym.Methods = extractIfaceMethods(fset, underlying)
+		}
+		m.Symbols = append(m.Symbols, sym)
 		for _, f := range t.Funcs {
 			m.Symbols = append(m.Symbols, newSymbol(m.Name, sub, "func", f.Name, f.Doc, f.Decl, fset, modDir))
 		}
@@ -221,6 +228,95 @@ func isInterface(decl *ast.GenDecl) bool {
 	return false
 }
 
+// typeSpecType returns the underlying type expression of a single-type GenDecl
+// (the RHS of `type X = <expr>`), or nil when the declaration is not a lone
+// type spec. Used to tell struct/interface declarations apart from aliases and
+// defined primitives so their members can be extracted.
+func typeSpecType(decl *ast.GenDecl) ast.Expr {
+	if decl == nil {
+		return nil
+	}
+	for _, spec := range decl.Specs {
+		if ts, ok := spec.(*ast.TypeSpec); ok {
+			return ts.Type
+		}
+	}
+	return nil
+}
+
+// extractFields flattens a struct's field list into index Fields, preserving
+// declaration order, struct tags (backticks stripped), embedded markers, and
+// per-field doc/line comments. A `x, y int` group yields one Field per name.
+func extractFields(fset *token.FileSet, st *ast.StructType) []Field {
+	if st == nil || st.Fields == nil {
+		return nil
+	}
+	var out []Field
+	for _, f := range st.Fields.List {
+		typeStr := nodeString(fset, f.Type)
+		tag := ""
+		if f.Tag != nil {
+			tag = strings.Trim(f.Tag.Value, "`")
+		}
+		fdoc := fieldDoc(f)
+		if len(f.Names) == 0 {
+			// Embedded field: the type name is also the field name.
+			out = append(out, Field{Type: typeStr, Tag: tag, Doc: fdoc, Embedded: true})
+			continue
+		}
+		for _, n := range f.Names {
+			out = append(out, Field{Name: n.Name, Type: typeStr, Tag: tag, Doc: fdoc})
+		}
+	}
+	return out
+}
+
+// extractIfaceMethods flattens an interface's method set into index Methods.
+// Explicit methods carry their name and the signature without the leading
+// `func`; embedded interfaces carry an empty name and the embedded type's name
+// as the signature.
+func extractIfaceMethods(fset *token.FileSet, it *ast.InterfaceType) []Method {
+	if it == nil || it.Methods == nil {
+		return nil
+	}
+	var out []Method
+	for _, f := range it.Methods.List {
+		mdoc := fieldDoc(f)
+		if len(f.Names) == 0 {
+			// Embedded interface (or type constraint element).
+			out = append(out, Method{Signature: nodeString(fset, f.Type), Doc: mdoc})
+			continue
+		}
+		sig := strings.TrimPrefix(nodeString(fset, f.Type), "func")
+		for _, n := range f.Names {
+			out = append(out, Method{Name: n.Name, Signature: n.Name + sig, Doc: mdoc})
+		}
+	}
+	return out
+}
+
+func fieldDoc(f *ast.Field) string {
+	switch {
+	case f.Doc != nil:
+		return strings.TrimSpace(f.Doc.Text())
+	case f.Comment != nil:
+		return strings.TrimSpace(f.Comment.Text())
+	}
+	return ""
+}
+
+// nodeString prints an AST node verbatim with no truncation — unlike
+// formatNode, which deliberately strips type/func bodies for one-line
+// signatures. Used for field types, tags, and interface method signatures.
+func nodeString(fset *token.FileSet, node ast.Node) string {
+	var buf bytes.Buffer
+	cfg := printer.Config{Mode: printer.UseSpaces, Tabwidth: 4}
+	if err := cfg.Fprint(&buf, fset, node); err != nil {
+		return ""
+	}
+	return strings.TrimSpace(buf.String())
+}
+
 var (
 	modulePathRe   = regexp.MustCompile(`(?m)^module\s+(\S+)`)
 	goVersionRe    = regexp.MustCompile(`(?m)^go\s+(\S+)`)

internal/index/builder_test.go

@@ -0,0 +1,149 @@
+package index
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// writeFixture lays down a single-module Einherjar-like repo under a temp root
+// and returns the root path for Build to walk.
+func writeFixture(t *testing.T) string {
+	t.Helper()
+	root := t.TempDir()
+	modDir := filepath.Join(root, "demo")
+	if err := os.MkdirAll(modDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	write := func(name, body string) {
+		if err := os.WriteFile(filepath.Join(modDir, name), []byte(body), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	write("go.mod", "module example.com/demo\n\ngo 1.26\n")
+	write("demo.go", `// Package demo is a build fixture.
+package demo
+
+import "context"
+
+// Config holds settings.
+type Config struct {
+	// Host is the bind address.
+	Host string `+"`"+`env:"DEMO_HOST" envDefault:"0.0.0.0"`+"`"+`
+	Port int    `+"`"+`env:"DEMO_PORT"`+"`"+`
+	Inner
+}
+
+// Inner is embedded into Config.
+type Inner struct {
+	Name string
+}
+
+// Store reads values.
+type Store interface {
+	// Get fetches one value.
+	Get(ctx context.Context, id string) (string, error)
+	context.Context
+}
+`)
+	return root
+}
+
+func findSymbol(t *testing.T, idx *Index, mod, name string) Symbol {
+	t.Helper()
+	m := idx.FindModule(mod)
+	if m == nil {
+		t.Fatalf("module %q not found", mod)
+	}
+	for _, s := range m.Symbols {
+		if s.Name == name {
+			return s
+		}
+	}
+	t.Fatalf("symbol %q not found in module %q", name, mod)
+	return Symbol{}
+}
+
+func TestBuildCapturesStructFields(t *testing.T) {
+	idx, err := Build(writeFixture(t))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	cfg := findSymbol(t, idx, "demo", "Config")
+	if cfg.Kind != "type" {
+		t.Errorf("Config kind = %q, want type", cfg.Kind)
+	}
+	if len(cfg.Fields) != 3 {
+		t.Fatalf("Config has %d fields, want 3: %+v", len(cfg.Fields), cfg.Fields)
+	}
+
+	host := cfg.Fields[0]
+	if host.Name != "Host" || host.Type != "string" {
+		t.Errorf("field[0] = %+v, want Host string", host)
+	}
+	if host.Tag != `env:"DEMO_HOST" envDefault:"0.0.0.0"` {
+		t.Errorf("Host tag = %q, want the env/envDefault tag (backticks stripped)", host.Tag)
+	}
+	if host.Doc != "Host is the bind address." {
+		t.Errorf("Host doc = %q", host.Doc)
+	}
+
+	if port := cfg.Fields[1]; port.Name != "Port" || port.Tag != `env:"DEMO_PORT"` {
+		t.Errorf("field[1] = %+v, want Port with env tag", port)
+	}
+
+	if inner := cfg.Fields[2]; !inner.Embedded || inner.Name != "" || inner.Type != "Inner" {
+		t.Errorf("field[2] = %+v, want embedded Inner", inner)
+	}
+}
+
+func TestBuildCapturesInterfaceMethods(t *testing.T) {
+	idx, err := Build(writeFixture(t))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	store := findSymbol(t, idx, "demo", "Store")
+	if store.Kind != "interface" {
+		t.Errorf("Store kind = %q, want interface", store.Kind)
+	}
+	if len(store.Methods) != 2 {
+		t.Fatalf("Store has %d methods, want 2: %+v", len(store.Methods), store.Methods)
+	}
+
+	get := store.Methods[0]
+	if get.Name != "Get" {
+		t.Errorf("method[0] name = %q, want Get", get.Name)
+	}
+	if get.Signature != "Get(ctx context.Context, id string) (string, error)" {
+		t.Errorf("Get signature = %q", get.Signature)
+	}
+	if get.Doc != "Get fetches one value." {
+		t.Errorf("Get doc = %q", get.Doc)
+	}
+
+	if emb := store.Methods[1]; emb.Name != "" || emb.Signature != "context.Context" {
+		t.Errorf("method[1] = %+v, want embedded context.Context", emb)
+	}
+}
+
+// A struct must be discoverable by one of its struct tags — the failure mode
+// that motivated capturing fields in the first place.
+func TestSearchSymbolsByStructTag(t *testing.T) {
+	idx, err := Build(writeFixture(t))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	got := idx.SearchSymbols("DEMO_HOST", 10)
+	found := false
+	for _, s := range got {
+		if s.Name == "Config" {
+			found = true
+		}
+	}
+	if !found {
+		t.Errorf("searching a struct tag did not surface its type; got %d results", len(got))
+	}
+}

internal/index/index.go

@@ -77,15 +77,46 @@ type SubPackage struct {
 }
 
 // Symbol is one exported declaration (type, func, interface, const, var).
+//
+// For struct types Fields carries the field set (the Signature is only the
+// one-line `type X struct` header, so without Fields the field names, types,
+// and — crucially — struct tags would be lost). For interface types Methods
+// carries the method set for the same reason. Both are empty for every other
+// kind.
 type Symbol struct {
-	Module     string `json:"module"`
-	SubPackage string `json:"subPackage"`
-	Kind       string `json:"kind"`
-	Name       string `json:"name"`
-	Signature  string `json:"signature"`
-	Doc        string `json:"doc"`
-	File       string `json:"file"`
-	Line       int    `json:"line"`
+	Module     string   `json:"module"`
+	SubPackage string   `json:"subPackage"`
+	Kind       string   `json:"kind"`
+	Name       string   `json:"name"`
+	Signature  string   `json:"signature"`
+	Doc        string   `json:"doc"`
+	File       string   `json:"file"`
+	Line       int      `json:"line"`
+	Fields     []Field  `json:"fields,omitempty"`
+	Methods    []Method `json:"methods,omitempty"`
+}
+
+// Field is one field of a struct-type Symbol. Name is empty for an embedded
+// field (its type then appears in Type, with Embedded true). Tag is the raw
+// struct tag with the surrounding backticks stripped (e.g.
+// `env:"EINHERJAR_PG_HOST" envDefault:"postgres"`) — the single most useful
+// thing a config consumer needs and the thing the old index dropped.
+type Field struct {
+	Name     string `json:"name,omitempty"`
+	Type     string `json:"type"`
+	Tag      string `json:"tag,omitempty"`
+	Doc      string `json:"doc,omitempty"`
+	Embedded bool   `json:"embedded,omitempty"`
+}
+
+// Method is one method of an interface-type Symbol. Signature is the method
+// as written without the leading func keyword (e.g.
+// `GetExecutor(ctx context.Context) Executor`). For an embedded interface
+// Name is empty and Signature is the embedded interface's name.
+type Method struct {
+	Name      string `json:"name,omitempty"`
+	Signature string `json:"signature"`
+	Doc       string `json:"doc,omitempty"`
 }
 
 // ADR is one architectural decision record.
@@ -157,8 +188,27 @@ func matches(s Symbol, needle string) bool {
 	if needle == "" {
 		return true
 	}
-	return strings.Contains(strings.ToLower(s.Name), needle) ||
+	if strings.Contains(strings.ToLower(s.Name), needle) ||
 		strings.Contains(strings.ToLower(s.Doc), needle) ||
 		strings.Contains(strings.ToLower(s.SubPackage), needle) ||
-		strings.Contains(strings.ToLower(s.Module), needle)
+		strings.Contains(strings.ToLower(s.Module), needle) {
+		return true
+	}
+	// A struct is also findable by a field name, type, or tag — so a query
+	// like an env-var key or json field resolves to the type that declares it.
+	for _, f := range s.Fields {
+		if strings.Contains(strings.ToLower(f.Name), needle) ||
+			strings.Contains(strings.ToLower(f.Type), needle) ||
+			strings.Contains(strings.ToLower(f.Tag), needle) {
+			return true
+		}
+	}
+	// An interface is findable by a method it requires.
+	for _, mth := range s.Methods {
+		if strings.Contains(strings.ToLower(mth.Name), needle) ||
+			strings.Contains(strings.ToLower(mth.Signature), needle) {
+			return true
+		}
+	}
+	return false
 }