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>

CHANGELOG.md

@@ -6,6 +6,24 @@ This module adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html
 
 ---
 
+## [0.2.0] — 2026-06-10
+
+Minor release. The indexer now captures the *members* of composite types, closing a gap where `get_symbol` and `search_symbols` could name a struct or interface but not describe its shape — most painfully, struct tags (env-var keys, json names) were invisible.
+
+### Added
+
+- **Struct fields in the index.** Each struct-type symbol now carries a `fields` array — field name, type, raw struct tag (backticks stripped), doc comment, and an `embedded` marker. `get_symbol` returns it; previously the signature was truncated to the bare `type X struct` header, so field names, types, and tags (e.g. `env:"EINHERJAR_PG_HOST"`) were dropped entirely.
+- **Interface method sets in the index.** Each interface-type symbol now carries a `methods` array — method name, signature (without the leading `func`), and doc comment, including embedded interfaces. Consumers can now see what a port like `db-postgres` `Provider` actually requires.
+- **Search by field/tag/method.** `search_symbols` now also matches a query against struct field names, field types, and struct tags, and against interface method names/signatures — so an env-var key or a method name resolves to the type that declares it.
+- **`internal/index` test suite** covering field, tag, embedded-field, interface-method, and search-by-tag capture (the package previously had no tests).
+
+### Notes
+
+- The index schema gains two optional (`omitempty`) fields; `SchemaVersion` is unchanged because the change is additive and older consumers parse the new index unchanged.
+- This is a pure indexer/schema change. The live server picks it up on its next image build, which re-runs `cmd/indexer` (see `Dockerfile`). A deployment that has not been rebuilt will still serve the older, member-less index.
+
+---
+
 ## [0.1.1] — 2026-05-29
 
 Patch release. Two changes to `cmd/server` make the binary cleaner to run behind a unix socket on a reverse-proxied host, plus two repository-hygiene changes that follow from the same deployment exercise.

README.md

@@ -45,8 +45,8 @@ Cursor, Zed, and anything else that speaks MCP):
 |---|---|
 | `list_modules` | Enumerate every Einherjar module with its purpose and sub-packages |
 | `get_module` | Package doc, dependencies, sub-packages, key types, compliance counts; optional README |
-| `search_symbols` | Find a type, function, or interface by name, doc text, sub-package, or module |
+| `search_symbols` | Find a type, function, or interface by name, doc text, sub-package, module — or by a struct field/tag or an interface method |
-| `get_symbol` | Full signature, doc comment, and source location for one symbol |
+| `get_symbol` | Full signature, doc comment, and source location for one symbol — plus struct fields (with tags) and interface method sets |
 | `list_adrs` | List architectural decision records, optionally restricted to one module |
 | `get_adr` | Fetch a single ADR's markdown body |
 | `get_example` | Canonical usage snippet — pulled from module READMEs and from the synthetic `wire` conventions |

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"`
+	Module     string   `json:"module"`
-	SubPackage string `json:"subPackage"`
+	SubPackage string   `json:"subPackage"`
-	Kind       string `json:"kind"`
+	Kind       string   `json:"kind"`
-	Name       string `json:"name"`
+	Name       string   `json:"name"`
-	Signature  string `json:"signature"`
+	Signature  string   `json:"signature"`
-	Doc        string `json:"doc"`
+	Doc        string   `json:"doc"`
-	File       string `json:"file"`
+	File       string   `json:"file"`
-	Line       int    `json:"line"`
+	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
 }

internal/tools/get_symbol.go

@@ -21,7 +21,7 @@ type getSymbolOutput struct {
 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.",
+		Description: "Fetch full signature, doc comment, and source location for one symbol. For a struct type the result includes its fields (name, type, struct tag, doc); for an interface type it includes its method set. 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 {

internal/tools/search_symbols.go

@@ -22,7 +22,7 @@ type searchSymbolsOutput struct {
 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.",
+		Description: "Search Einherjar's exported symbols (types, interfaces, funcs, methods, consts, vars) by name or doc text. Structs also match on a field name, field type, or struct tag (e.g. an env-var key); interfaces also match on a required method. Optionally filter by module or kind. Use when you need to find where a type, function, field, or tag 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]