fix(filters): qualify model columns to avoid ambiguity with joins

Qualify plain model columns with the main table alias in resolvespec
filters so preload joins no longer cause SQLSTATE 42702, and accept
<table>.<column> from clients in resolvespec and restheadspec instead
of silently dropping the filter. Add join/preload tests for
resolvespec, restheadspec and funcspec.

pkg/common/adapters/database/pgsql_integration_test.go

@@ -1,3 +1,4 @@
+//go:build integration
 // +build integration
 
 package database
@@ -18,11 +19,11 @@ import (
 
 // Integration test models
 type IntegrationUser struct {
-	ID        int       `db:"id"`
-	Name      string    `db:"name"`
-	Email     string    `db:"email"`
-	Age       int       `db:"age"`
-	CreatedAt time.Time `db:"created_at"`
+	ID        int                `db:"id"`
+	Name      string             `db:"name"`
+	Email     string             `db:"email"`
+	Age       int                `db:"age"`
+	CreatedAt time.Time          `db:"created_at"`
 	Posts     []*IntegrationPost `bun:"rel:has-many,join:id=user_id"`
 }
 
@@ -46,10 +47,10 @@ func (p IntegrationPost) TableName() string {
 }
 
 type IntegrationComment struct {
-	ID        int       `db:"id"`
-	Content   string    `db:"content"`
-	PostID    int       `db:"post_id"`
-	CreatedAt time.Time `db:"created_at"`
+	ID        int              `db:"id"`
+	Content   string           `db:"content"`
+	PostID    int              `db:"post_id"`
+	CreatedAt time.Time        `db:"created_at"`
 	Post      *IntegrationPost `bun:"rel:belongs-to,join:post_id=id"`
 }
 

pkg/common/adapters/database/pgsql_test.go

@@ -26,11 +26,11 @@ func (u TestUser) TableName() string {
 }
 
 type TestPost struct {
-	ID       int        `db:"id"`
-	Title    string     `db:"title"`
-	Content  string     `db:"content"`
-	UserID   int        `db:"user_id"`
-	User     *TestUser  `bun:"rel:belongs-to,join:user_id=id"`
+	ID       int           `db:"id"`
+	Title    string        `db:"title"`
+	Content  string        `db:"content"`
+	UserID   int           `db:"user_id"`
+	User     *TestUser     `bun:"rel:belongs-to,join:user_id=id"`
 	Comments []TestComment `bun:"rel:has-many,join:id=post_id"`
 }
 

pkg/common/qualify_column.go

@@ -0,0 +1,77 @@
+package common
+
+import (
+	"regexp"
+	"strings"
+
+	"github.com/bitechdev/ResolveSpec/pkg/reflection"
+)
+
+var rePlainIdent = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*$`)
+
+// MainTableAlias returns the alias the main table gets in the SELECT:
+// the model's TableAlias() when provided, otherwise the bare table name.
+func MainTableAlias(model interface{}, tableName string) string {
+	if p, ok := model.(TableAliasProvider); ok {
+		if a := p.TableAlias(); a != "" {
+			return a
+		}
+	}
+	return reflection.ExtractTableNameOnly(tableName)
+}
+
+func isModelSQLColumn(model interface{}, column string) bool {
+	for _, c := range reflection.GetSQLModelColumns(model) {
+		if strings.EqualFold(c, column) {
+			return true
+		}
+	}
+	return false
+}
+
+// QualifyModelColumn returns "alias"."column" when column is a plain identifier
+// that exists on the model, so it stays unambiguous once joins are added.
+// Anything else (expressions, JSON paths, other tables' columns) is returned unchanged.
+func QualifyModelColumn(model interface{}, alias, column string) string {
+	if alias == "" || model == nil || !rePlainIdent.MatchString(column) || !isModelSQLColumn(model, column) {
+		return column
+	}
+	return QuoteIdent(alias) + "." + QuoteIdent(column)
+}
+
+// StripMainTablePrefix turns "<prefix>.<column>" into "<column>" when prefix is
+// one of the main table's names/aliases and column exists on the model.
+// Any other input is returned unchanged.
+func StripMainTablePrefix(model interface{}, column string, prefixes ...string) string {
+	idx := strings.Index(column, ".")
+	if idx <= 0 || model == nil {
+		return column
+	}
+	prefix := strings.Trim(column[:idx], `"`)
+	col := strings.Trim(column[idx+1:], `"`)
+	if !rePlainIdent.MatchString(prefix) || !rePlainIdent.MatchString(col) {
+		return column
+	}
+	for _, p := range prefixes {
+		if p != "" && strings.EqualFold(p, prefix) && isModelSQLColumn(model, col) {
+			return col
+		}
+	}
+	return column
+}
+
+// StripMainTablePrefixFromFilters applies StripMainTablePrefix to every filter column.
+func StripMainTablePrefixFromFilters(model interface{}, filters []FilterOption, prefixes ...string) {
+	for i := range filters {
+		filters[i].Column = StripMainTablePrefix(model, filters[i].Column, prefixes...)
+	}
+}
+
+// NormalizeMainTableFilters rewrites "<main table or alias>.<column>" filter
+// columns on opts to the bare model column (on a copy, never the caller's
+// slice) so the column validator keeps them.
+func NormalizeMainTableFilters(model interface{}, tableName string, opts *RequestOptions) {
+	opts.Filters = append([]FilterOption(nil), opts.Filters...)
+	StripMainTablePrefixFromFilters(model, opts.Filters,
+		MainTableAlias(model, tableName), reflection.ExtractTableNameOnly(tableName))
+}

pkg/common/qualify_column_test.go

@@ -0,0 +1,55 @@
+package common
+
+import "testing"
+
+type qualifyModel struct {
+	ID   int64  `bun:"id,pk"`
+	Name string `bun:"name"`
+}
+
+func TestQualifyModelColumn(t *testing.T) {
+	m := qualifyModel{}
+	cases := []struct{ alias, col, want string }{
+		{"t", "name", `"t"."name"`},
+		{"t", "NAME", `"t"."NAME"`},
+		{"t", "missing", "missing"},
+		{"t", "data->>'x'", "data->>'x'"},
+		{"t", "rel.name", "rel.name"},
+		{"", "name", "name"},
+	}
+	for _, c := range cases {
+		if got := QualifyModelColumn(m, c.alias, c.col); got != c.want {
+			t.Errorf("Qualify(%q,%q) = %q, want %q", c.alias, c.col, got, c.want)
+		}
+	}
+	if got := QualifyModelColumn(nil, "t", "name"); got != "name" {
+		t.Errorf("nil model: %q", got)
+	}
+}
+
+func TestStripMainTablePrefix(t *testing.T) {
+	m := qualifyModel{}
+	cases := []struct{ col, want string }{
+		{"province_state.name", "name"},
+		{`"province_state"."name"`, "name"},
+		{"PROVINCE_STATE.name", "name"},
+		{"rel_rid_country.name", "rel_rid_country.name"},
+		{"province_state.missing", "province_state.missing"},
+		{"name", "name"},
+	}
+	for _, c := range cases {
+		if got := StripMainTablePrefix(m, c.col, "province_state"); got != c.want {
+			t.Errorf("Strip(%q) = %q, want %q", c.col, got, c.want)
+		}
+	}
+}
+
+func TestStripMainTablePrefix_ValidatorKeepsFilter(t *testing.T) {
+	m := qualifyModel{}
+	filters := []FilterOption{{Column: "province_state.name", Operator: "eq", Value: "x"}}
+	StripMainTablePrefixFromFilters(m, filters, "province_state")
+	out := NewColumnValidator(m).FilterRequestOptions(RequestOptions{Filters: filters})
+	if len(out.Filters) != 1 || out.Filters[0].Column != "name" {
+		t.Fatalf("filters = %+v", out.Filters)
+	}
+}

pkg/common/recursive_crud_test.go

@@ -25,10 +25,10 @@ func newMockDatabase() *mockDatabase {
 	}
 }
 
-func (m *mockDatabase) NewSelect() SelectQuery                       { return &mockSelectQuery{} }
-func (m *mockDatabase) NewInsert() InsertQuery                       { return &mockInsertQuery{db: m} }
-func (m *mockDatabase) NewUpdate() UpdateQuery                       { return &mockUpdateQuery{db: m} }
-func (m *mockDatabase) NewDelete() DeleteQuery                       { return &mockDeleteQuery{db: m} }
+func (m *mockDatabase) NewSelect() SelectQuery { return &mockSelectQuery{} }
+func (m *mockDatabase) NewInsert() InsertQuery { return &mockInsertQuery{db: m} }
+func (m *mockDatabase) NewUpdate() UpdateQuery { return &mockUpdateQuery{db: m} }
+func (m *mockDatabase) NewDelete() DeleteQuery { return &mockDeleteQuery{db: m} }
 func (m *mockDatabase) RunInTransaction(ctx context.Context, fn func(Database) error) error {
 	return fn(m)
 }
@@ -57,27 +57,31 @@ func (m *mockDatabase) DriverName() string {
 // Mock SelectQuery
 type mockSelectQuery struct{}
 
-func (m *mockSelectQuery) Model(model interface{}) SelectQuery                { return m }
-func (m *mockSelectQuery) Table(name string) SelectQuery                      { return m }
-func (m *mockSelectQuery) Column(columns ...string) SelectQuery               { return m }
-func (m *mockSelectQuery) ColumnExpr(query string, args ...interface{}) SelectQuery { return m }
-func (m *mockSelectQuery) Where(condition string, args ...interface{}) SelectQuery { return m }
-func (m *mockSelectQuery) WhereOr(query string, args ...interface{}) SelectQuery { return m }
-func (m *mockSelectQuery) Join(query string, args ...interface{}) SelectQuery { return m }
-func (m *mockSelectQuery) LeftJoin(query string, args ...interface{}) SelectQuery { return m }
+func (m *mockSelectQuery) Model(model interface{}) SelectQuery                            { return m }
+func (m *mockSelectQuery) Table(name string) SelectQuery                                  { return m }
+func (m *mockSelectQuery) Column(columns ...string) SelectQuery                           { return m }
+func (m *mockSelectQuery) ColumnExpr(query string, args ...interface{}) SelectQuery       { return m }
+func (m *mockSelectQuery) Where(condition string, args ...interface{}) SelectQuery        { return m }
+func (m *mockSelectQuery) WhereOr(query string, args ...interface{}) SelectQuery          { return m }
+func (m *mockSelectQuery) Join(query string, args ...interface{}) SelectQuery             { return m }
+func (m *mockSelectQuery) LeftJoin(query string, args ...interface{}) SelectQuery         { return m }
 func (m *mockSelectQuery) Preload(relation string, conditions ...interface{}) SelectQuery { return m }
-func (m *mockSelectQuery) PreloadRelation(relation string, apply ...func(SelectQuery) SelectQuery) SelectQuery { return m }
-func (m *mockSelectQuery) JoinRelation(relation string, apply ...func(SelectQuery) SelectQuery) SelectQuery { return m }
-func (m *mockSelectQuery) Order(order string) SelectQuery                     { return m }
-func (m *mockSelectQuery) OrderExpr(order string, args ...interface{}) SelectQuery { return m }
-func (m *mockSelectQuery) Limit(n int) SelectQuery                            { return m }
-func (m *mockSelectQuery) Offset(n int) SelectQuery                           { return m }
-func (m *mockSelectQuery) Group(group string) SelectQuery                     { return m }
+func (m *mockSelectQuery) PreloadRelation(relation string, apply ...func(SelectQuery) SelectQuery) SelectQuery {
+	return m
+}
+func (m *mockSelectQuery) JoinRelation(relation string, apply ...func(SelectQuery) SelectQuery) SelectQuery {
+	return m
+}
+func (m *mockSelectQuery) Order(order string) SelectQuery                           { return m }
+func (m *mockSelectQuery) OrderExpr(order string, args ...interface{}) SelectQuery  { return m }
+func (m *mockSelectQuery) Limit(n int) SelectQuery                                  { return m }
+func (m *mockSelectQuery) Offset(n int) SelectQuery                                 { return m }
+func (m *mockSelectQuery) Group(group string) SelectQuery                           { return m }
 func (m *mockSelectQuery) Having(condition string, args ...interface{}) SelectQuery { return m }
-func (m *mockSelectQuery) Scan(ctx context.Context, dest interface{}) error  { return nil }
-func (m *mockSelectQuery) ScanModel(ctx context.Context) error               { return nil }
-func (m *mockSelectQuery) Count(ctx context.Context) (int, error)            { return 0, nil }
-func (m *mockSelectQuery) Exists(ctx context.Context) (bool, error)          { return false, nil }
+func (m *mockSelectQuery) Scan(ctx context.Context, dest interface{}) error         { return nil }
+func (m *mockSelectQuery) ScanModel(ctx context.Context) error                      { return nil }
+func (m *mockSelectQuery) Count(ctx context.Context) (int, error)                   { return 0, nil }
+func (m *mockSelectQuery) Exists(ctx context.Context) (bool, error)                 { return false, nil }
 
 // Mock InsertQuery
 type mockInsertQuery struct {
@@ -98,9 +102,9 @@ func (m *mockInsertQuery) Value(column string, value interface{}) InsertQuery {
 	m.values[column] = value
 	return m
 }
-func (m *mockInsertQuery) OnConflict(action string) InsertQuery { return m }
+func (m *mockInsertQuery) OnConflict(action string) InsertQuery        { return m }
 func (m *mockInsertQuery) ExcludeColumn(columns ...string) InsertQuery { return m }
-func (m *mockInsertQuery) Returning(columns ...string) InsertQuery { return m }
+func (m *mockInsertQuery) Returning(columns ...string) InsertQuery     { return m }
 func (m *mockInsertQuery) Exec(ctx context.Context) (Result, error) {
 	m.db.insertCalls = append(m.db.insertCalls, m.values)
 	m.db.lastID++
@@ -132,8 +136,8 @@ func (m *mockUpdateQuery) SetMap(values map[string]interface{}) UpdateQuery {
 	return m
 }
 func (m *mockUpdateQuery) Where(condition string, args ...interface{}) UpdateQuery { return m }
-func (m *mockUpdateQuery) ExcludeColumn(columns ...string) UpdateQuery { return m }
-func (m *mockUpdateQuery) Returning(columns ...string) UpdateQuery { return m }
+func (m *mockUpdateQuery) ExcludeColumn(columns ...string) UpdateQuery             { return m }
+func (m *mockUpdateQuery) Returning(columns ...string) UpdateQuery                 { return m }
 func (m *mockUpdateQuery) Exec(ctx context.Context) (Result, error) {
 	// Record the update call
 	m.db.updateCalls = append(m.db.updateCalls, m.setValues)
@@ -171,9 +175,13 @@ func (m *mockResult) RowsAffected() int64          { return m.rowsAffected }
 type mockModelRegistry struct{}
 
 func (m *mockModelRegistry) GetModel(name string) (interface{}, error) { return nil, nil }
-func (m *mockModelRegistry) GetModelByEntity(schema, entity string) (interface{}, error) { return nil, nil }
+func (m *mockModelRegistry) GetModelByEntity(schema, entity string) (interface{}, error) {
+	return nil, nil
+}
 func (m *mockModelRegistry) RegisterModel(name string, model interface{}) error { return nil }
-func (m *mockModelRegistry) GetAllModels() map[string]interface{} { return make(map[string]interface{}) }
+func (m *mockModelRegistry) GetAllModels() map[string]interface{} {
+	return make(map[string]interface{})
+}
 
 // Mock RelationshipInfoProvider
 type mockRelationshipProvider struct {
@@ -198,9 +206,9 @@ func (m *mockRelationshipProvider) RegisterRelation(modelTypeName, relationName
 
 // Test Models
 type Department struct {
-	ID        int64        `json:"id" bun:"id,pk"`
-	Name      string       `json:"name"`
-	Employees []*Employee  `json:"employees,omitempty"`
+	ID        int64       `json:"id" bun:"id,pk"`
+	Name      string      `json:"name"`
+	Employees []*Employee `json:"employees,omitempty"`
 }
 
 func (d Department) TableName() string { return "departments" }
@@ -227,9 +235,9 @@ func (t Task) TableName() string { return "tasks" }
 func (t Task) GetIDName() string { return "ID" }
 
 type Comment struct {
-	ID      int64  `json:"id" bun:"id,pk"`
-	Text    string `json:"text"`
-	TaskID  int64  `json:"task_id"`
+	ID     int64  `json:"id" bun:"id,pk"`
+	Text   string `json:"text"`
+	TaskID int64  `json:"task_id"`
 }
 
 func (c Comment) TableName() string { return "comments" }

pkg/funcspec/filter_join_test.go

@@ -0,0 +1,92 @@
+package funcspec
+
+import (
+	"database/sql"
+	"strings"
+	"testing"
+
+	"github.com/uptrace/bun/driver/sqliteshim"
+)
+
+const joinedBaseSQL = "SELECT p.id, p.name, c.name AS country_name FROM province_state p LEFT JOIN country c ON c.id = p.rid_country"
+
+// funcspec filters are appended to author-written SQL with no model, so columns
+// are used verbatim: clients disambiguate by sending "alias.column", and the
+// dot must survive ValidSQL and every filter path.
+func TestApplyFilters_QualifiedColumnsPreservedWithJoin(t *testing.T) {
+	h := NewHandler(&MockDatabase{})
+
+	cases := []struct {
+		name   string
+		params *RequestParameters
+		want   string
+	}{
+		{"field filter", &RequestParameters{FieldFilters: map[string]string{"p.name": "abc"}}, "p.name = abc"},
+		{"search filter", &RequestParameters{SearchFilters: map[string]string{"p.name": "abc"}}, "CAST(p.name AS TEXT) ILIKE '%abc%'"},
+		{"search op eq", &RequestParameters{SearchOps: map[string]FilterOperator{"p.name": {Operator: "eq", Value: "abc", Logic: "AND"}}}, "p.name = 'abc'"},
+		{"search op contains", &RequestParameters{SearchOps: map[string]FilterOperator{"p.name": {Operator: "contains", Value: "abc", Logic: "AND"}}}, "CAST(p.name AS TEXT) ILIKE '%abc%'"},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			got := h.ApplyFilters(joinedBaseSQL, c.params)
+			if !strings.Contains(got, c.want) {
+				t.Fatalf("SQL %q does not contain %q", got, c.want)
+			}
+			if !strings.Contains(got, "LEFT JOIN country") || !strings.Contains(got, " WHERE ") {
+				t.Fatalf("join/where lost: %q", got)
+			}
+		})
+	}
+}
+
+func TestApplyFilters_WithAndWithoutJoin_RealQuery(t *testing.T) {
+	sqldb, err := sql.Open(sqliteshim.ShimName, "file:funcspecjoin?mode=memory&cache=private")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer sqldb.Close()
+	for _, stmt := range []string{
+		"CREATE TABLE country (id INTEGER PRIMARY KEY, name TEXT)",
+		"CREATE TABLE province_state (id INTEGER PRIMARY KEY, name TEXT, rid_country INTEGER)",
+		"INSERT INTO country VALUES (1,'Abcland'),(2,'Other')",
+		"INSERT INTO province_state VALUES (1,'abc one',1),(2,'xyz two',1),(3,'nope',2)",
+	} {
+		if _, err := sqldb.Exec(stmt); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	h := NewHandler(&MockDatabase{})
+	count := func(base string, params *RequestParameters) (int, error) {
+		rows, err := sqldb.Query(h.ApplyFilters(base, params))
+		if err != nil {
+			return 0, err
+		}
+		defer rows.Close()
+		n := 0
+		for rows.Next() {
+			n++
+		}
+		return n, rows.Err()
+	}
+
+	const noJoin = "SELECT p.id, p.name FROM province_state p"
+	params := func(col string) *RequestParameters {
+		return &RequestParameters{SearchOps: map[string]FilterOperator{col: {Operator: "eq", Value: "nope", Logic: "AND"}}}
+	}
+
+	if n, err := count(noJoin, params("name")); err != nil || n != 1 {
+		t.Fatalf("no join, unqualified: n=%d err=%v", n, err)
+	}
+	if n, err := count(joinedBaseSQL, params("p.name")); err != nil || n != 1 {
+		t.Fatalf("join, qualified: n=%d err=%v", n, err)
+	}
+	if n, err := count(joinedBaseSQL, params("c.name")); err != nil || n != 0 {
+		t.Fatalf("join, joined-table column: n=%d err=%v", n, err)
+	}
+	// Documented limit: with a join in the author's SQL, an unqualified shared
+	// column is ambiguous and the client must send "alias.column".
+	if _, err := count(joinedBaseSQL, params("name")); err == nil || !strings.Contains(strings.ToLower(err.Error()), "ambiguous") {
+		t.Fatalf("expected ambiguous error for unqualified shared column, got %v", err)
+	}
+}

pkg/modelregistry/doc.go

@@ -0,0 +1,32 @@
+// Package modelregistry is the shared catalogue of the Go model structs that the
+// ResolveSpec front ends (resolvespec, restheadspec, websocketspec, mqttspec,
+// resolvemcp, ...) expose as database entities.
+//
+// A registry maps a model name ("schema.entity") to a struct type and holds:
+//   - ModelRules: which operations (read/create/update/delete, public or not)
+//     are allowed, and whether security checks are disabled.
+//   - ModelInfo: optional documentation (description, purpose, tags, per-column
+//     descriptions) meant for humans and AI agents. It never affects queries or
+//     permissions.
+//
+// Register models on a registry created with NewModelRegistry, or through the
+// package-level functions that use the default registry:
+//
+//	reg := modelregistry.NewModelRegistry()
+//	_ = reg.RegisterModelWithRules("public.users", User{}, modelregistry.DefaultModelRules())
+//	reg.SetModelInfo("public.users", modelregistry.ModelInfo{
+//		Description: "Application accounts",
+//		Purpose:     "Look up who a person is; never store credentials here",
+//		Columns:     map[string]string{"email": "Login address, unique"},
+//	})
+//
+// Descriptions come from, in priority order:
+//  1. ModelInfo set with SetModelInfo or loaded from an external JSON map with
+//     LoadModelInfoFile (the map can be maintained outside the Go code).
+//  2. The model's Describer (ModelDescription() string) for the description.
+//  3. Struct tags, read per column by FieldComment: comment, note, desc or
+//     description tags, then "comment:" inside the gorm or bun tag.
+//
+// Models must be non-pointer structs; pointers, slices and arrays of structs are
+// unwrapped on registration. All registry methods are safe for concurrent use.
+package modelregistry

pkg/modelregistry/info.go

@@ -0,0 +1,172 @@
+package modelregistry
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+)
+
+// ModelInfo is human/AI-facing documentation for a registered model: what it
+// is for and what its columns mean. It is optional and has no effect on
+// permissions or queries.
+type ModelInfo struct {
+	// Description says what the model/table holds.
+	Description string `json:"description,omitempty"`
+	// Purpose says why it exists / when an agent should use it.
+	Purpose string `json:"purpose,omitempty"`
+	// Tags are free-form labels (e.g. "billing", "pii").
+	Tags []string `json:"tags,omitempty"`
+	// Columns maps a JSON column name to its description.
+	Columns map[string]string `json:"columns,omitempty"`
+}
+
+// IsZero reports whether the info carries no documentation.
+func (i ModelInfo) IsZero() bool {
+	return i.Description == "" && i.Purpose == "" && len(i.Tags) == 0 && len(i.Columns) == 0
+}
+
+// Describer can be implemented by a model to document itself. It is the
+// fallback used when no ModelInfo description was registered or loaded.
+// (The method is not called Description so models may keep a Description field.)
+type Describer interface {
+	ModelDescription() string
+}
+
+// commentTagKeys are the standalone struct tags read as a column description,
+// in priority order.
+var commentTagKeys = []string{"comment", "note", "desc", "description"}
+
+// FieldComment returns the description of a struct field from its tags. Order:
+// standalone comment/note/desc/description tags, then a "comment:" entry inside
+// the gorm tag (semicolon separated), then inside the bun tag (comma separated).
+// It returns "" when the field carries none.
+func FieldComment(sf reflect.StructField) string {
+	for _, key := range commentTagKeys {
+		if v := strings.TrimSpace(sf.Tag.Get(key)); v != "" {
+			return v
+		}
+	}
+	if v := tagOption(sf.Tag.Get("gorm"), ';', "comment:"); v != "" {
+		return v
+	}
+	return tagOption(sf.Tag.Get("bun"), ',', "comment:")
+}
+
+func tagOption(tag string, sep byte, key string) string {
+	for _, part := range strings.Split(tag, string(sep)) {
+		part = strings.TrimSpace(part)
+		if len(part) >= len(key) && strings.EqualFold(part[:len(key)], key) {
+			return strings.Trim(strings.TrimSpace(part[len(key):]), `'"`)
+		}
+	}
+	return ""
+}
+
+// SetModelInfo stores documentation for a model name ("schema.entity"). The
+// model does not have to be registered yet, so descriptions can be loaded
+// before or after registration. Any previous info for the name is replaced.
+func (r *DefaultModelRegistry) SetModelInfo(name string, info ModelInfo) {
+	r.mutex.Lock()
+	defer r.mutex.Unlock()
+	if r.info == nil {
+		r.info = make(map[string]ModelInfo)
+	}
+	r.info[name] = cloneInfo(info)
+}
+
+// GetModelInfo returns the documentation stored with SetModelInfo (or loaded
+// from a descriptions file), without any fallback.
+func (r *DefaultModelRegistry) GetModelInfo(name string) (ModelInfo, bool) {
+	r.mutex.RLock()
+	defer r.mutex.RUnlock()
+	info, ok := r.info[name]
+	return cloneInfo(info), ok
+}
+
+// RegisterModelWithInfo registers a model together with its documentation.
+func (r *DefaultModelRegistry) RegisterModelWithInfo(name string, model interface{}, info ModelInfo) error {
+	if err := r.RegisterModel(name, model); err != nil {
+		return err
+	}
+	r.SetModelInfo(name, info)
+	return nil
+}
+
+// ResolveModelInfo returns the effective documentation for a registered model.
+// Stored/loaded info wins; an empty Description falls back to the model's
+// Describer. Column descriptions are not resolved here: use the stored map and
+// fall back to FieldComment per field.
+func (r *DefaultModelRegistry) ResolveModelInfo(name string) ModelInfo {
+	info, _ := r.GetModelInfo(name)
+	if info.Description == "" {
+		if model, err := r.GetModel(name); err == nil {
+			info.Description = describerText(model)
+		}
+	}
+	return info
+}
+
+func describerText(model interface{}) (text string) {
+	defer func() {
+		if recover() != nil {
+			text = ""
+		}
+	}()
+	if d, ok := model.(Describer); ok {
+		return strings.TrimSpace(d.ModelDescription())
+	}
+	if t := reflect.TypeOf(model); t != nil && t.Kind() != reflect.Pointer {
+		if d, ok := reflect.New(t).Interface().(Describer); ok {
+			return strings.TrimSpace(d.ModelDescription())
+		}
+	}
+	return ""
+}
+
+// LoadModelInfo reads an external descriptions map from r and applies it. The
+// JSON is an object keyed by model name:
+//
+//	{"public.users": {"description": "...", "purpose": "...", "tags": ["x"],
+//	                  "columns": {"email": "Login address"}}}
+//
+// Entries replace any existing info for the same name and take precedence over
+// the model's Describer and its struct-tag comments. It returns the number of
+// models loaded.
+func (r *DefaultModelRegistry) LoadModelInfo(src io.Reader) (int, error) {
+	var m map[string]ModelInfo
+	dec := json.NewDecoder(src)
+	dec.DisallowUnknownFields()
+	if err := dec.Decode(&m); err != nil {
+		return 0, fmt.Errorf("modelregistry: decode model info: %w", err)
+	}
+	for name, info := range m {
+		r.SetModelInfo(name, info)
+	}
+	return len(m), nil
+}
+
+// LoadModelInfoFile is LoadModelInfo reading from a JSON file.
+func (r *DefaultModelRegistry) LoadModelInfoFile(path string) (int, error) {
+	f, err := os.Open(filepath.Clean(path)) //nolint:gosec // operator-supplied descriptions file
+	if err != nil {
+		return 0, fmt.Errorf("modelregistry: %w", err)
+	}
+	defer f.Close()
+	return r.LoadModelInfo(f)
+}
+
+func cloneInfo(in ModelInfo) ModelInfo {
+	out := in
+	out.Tags = append([]string(nil), in.Tags...)
+	if in.Columns != nil {
+		out.Columns = make(map[string]string, len(in.Columns))
+		for k, v := range in.Columns {
+			out.Columns[k] = v
+		}
+	}
+	return out
+}

pkg/modelregistry/info_test.go

@@ -0,0 +1,68 @@
+package modelregistry
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+)
+
+type infoModel struct {
+	ID    int    `json:"id" gorm:"primaryKey;comment:Row id"`
+	Email string `json:"email" bun:"email,comment:Login address"`
+	Name  string `json:"name" note:"Display name"`
+	Plain string `json:"plain"`
+}
+
+func (infoModel) ModelDescription() string { return " From the model " }
+
+func TestFieldComment(t *testing.T) {
+	typ := reflect.TypeOf(infoModel{})
+	want := map[string]string{"ID": "Row id", "Email": "Login address", "Name": "Display name", "Plain": ""}
+	for field, exp := range want {
+		sf, _ := typ.FieldByName(field)
+		if got := FieldComment(sf); got != exp {
+			t.Errorf("%s = %q, want %q", field, got, exp)
+		}
+	}
+}
+
+func TestModelInfoPrecedence(t *testing.T) {
+	r := NewModelRegistry()
+	if err := r.RegisterModel("public.items", infoModel{}); err != nil {
+		t.Fatal(err)
+	}
+	if got := r.ResolveModelInfo("public.items").Description; got != "From the model" {
+		t.Errorf("describer fallback = %q", got)
+	}
+
+	n, err := r.LoadModelInfo(strings.NewReader(
+		`{"public.items":{"description":"From file","tags":["a"],"columns":{"email":"Mail"}},"public.later":{"purpose":"p"}}`))
+	if err != nil || n != 2 {
+		t.Fatalf("load n=%d err=%v", n, err)
+	}
+	info := r.ResolveModelInfo("public.items")
+	if info.Description != "From file" || info.Columns["email"] != "Mail" || len(info.Tags) != 1 {
+		t.Errorf("file info = %+v", info)
+	}
+	if _, ok := r.GetModelInfo("public.later"); !ok {
+		t.Error("info for a not-yet-registered model must be kept")
+	}
+
+	// returned info is a copy
+	info.Columns["email"] = "changed"
+	if got, _ := r.GetModelInfo("public.items"); got.Columns["email"] != "Mail" {
+		t.Error("GetModelInfo leaked internal map")
+	}
+}
+
+func TestLoadModelInfoRejectsBadInput(t *testing.T) {
+	r := NewModelRegistry()
+	for _, in := range []string{`not json`, `{"a":{"descripton":"typo"}}`} {
+		if _, err := r.LoadModelInfo(strings.NewReader(in)); err == nil {
+			t.Errorf("expected error for %q", in)
+		}
+	}
+	if _, err := r.LoadModelInfoFile("/nonexistent/x.json"); err == nil {
+		t.Error("expected error for missing file")
+	}
+}

pkg/modelregistry/model_registry.go

@@ -41,6 +41,7 @@ func DefaultModelRules() ModelRules {
 type DefaultModelRegistry struct {
 	models map[string]interface{}
 	rules  map[string]ModelRules
+	info   map[string]ModelInfo
 	mutex  sync.RWMutex
 }
 

pkg/resolvemcp/README.md

@@ -16,6 +16,8 @@ import (
 handler := resolvemcp.NewHandlerWithGORM(db, resolvemcp.Config{
     BaseURL:  "http://localhost:8080",
     BasePath: "/mcp",
+    // Read-only by default; uncomment to allow writes:
+    // ReadOnly: resolvemcp.Bool(false),
 })
 
 securityList, _ := security.NewSecurityList(provider)
@@ -392,6 +394,85 @@ handler.SetModelRules("public", "users", modelregistry.ModelRules{
 
 ---
 
+## Describing the API for agents
+
+Give agents context about what each table is for:
+
+```go
+// 1. Explicitly, in code
+handler.SetModelDescription("public", "users", modelregistry.ModelInfo{
+    Description: "Application accounts",
+    Purpose:     "Look up who a person is",
+    Tags:        []string{"identity"},
+    Columns:     map[string]string{"email": "Login address, unique"},
+})
+
+// 2. From an external JSON map (keyed by "schema.entity"); entries here win
+n, err := handler.LoadModelDescriptions("docs/model-descriptions.json")
+```
+
+Example `docs/model-descriptions.json` (every key is optional; unknown keys are rejected):
+
+```json
+{
+  "public.users": {
+    "description": "Application accounts, one row per person who can sign in.",
+    "purpose": "Look up who someone is. Use public.orders for what they bought.",
+    "tags": ["identity", "pii"],
+    "columns": {
+      "id": "Internal account id",
+      "email": "Login address, unique and lower-cased",
+      "created_at": "When the account was created (UTC)"
+    }
+  },
+  "public.orders": {
+    "description": "Customer orders.",
+    "columns": {
+      "status": "One of: pending, paid, shipped, cancelled"
+    }
+  }
+}
+```
+
+Keys are `schema.entity` names as registered with `RegisterModel`. Column keys are the JSON column names shown by `describe_table`. An entry replaces any info set earlier for that table, and columns it leaves out still fall back to field tags.
+
+Fallbacks when nothing is set for a table or column, in order: the model's `ModelDescription() string` method (table), then field tags (column): `comment`, `note`, `desc` or `description` tags, then `comment:` inside the `gorm` or `bun` tag.
+
+The text appears in `list_tables` and `describe_table`. The server also sends a short usage guide as MCP `instructions` on connect.
+
+### Catalogue file
+
+`handler.ExportCatalog(path)` writes the usage guide, tools, limits and every table (columns, types, keys, relations, allowed operations, descriptions) to disk, JSON for a `.json` path and Markdown otherwise. The file is replaced atomically. It lists every table with at least one allowed operation, regardless of caller, so keep it out of public directories. Call it after registering models (for example at startup, or from a `go generate` step).
+
+## Read-only mode
+
+The server is **read-only unless you enable writes**: `Config.ReadOnly` is a `*bool` and an unset (nil) value means on. To allow inserts, updates and deletes:
+
+```go
+handler := resolvemcp.NewHandlerWithGORM(db, resolvemcp.Config{ReadOnly: resolvemcp.Bool(false)})
+```
+
+While read-only is on:
+
+- The insert, update, delete and annotation tools are not registered, so the agent never sees them. `list_functions`/`call_function` are off too, because a registered function may change data, unless you set `AllowFunctionCalls` (below).
+- `list_tables` and `describe_table` report only `select`; `describe_table` also sets `read_only: true` and lists no writable columns.
+- The MCP server instructions (and the exported catalogue) say the server is read-only and tell the agent not to attempt writes.
+- A write that reaches a handler anyway is refused with a `forbidden` error ("this server is read-only: writes are disabled").
+
+### Function calls and the allowlist
+
+```go
+// Read-only server that may still run two named functions
+resolvemcp.Config{
+    // ReadOnly is on by default
+    AllowFunctionCalls: true, // keep list_functions / call_function on a read-only server
+    AllowedFunctions:   []string{"report_totals", "search_customers"},
+}
+```
+
+- `AllowFunctionCalls` only matters while read-only is on; with writes enabled (`ReadOnly: resolvemcp.Bool(false)`), functions are always available. Set it only for functions that do not change data.
+- `AllowedFunctions` works in either mode. When empty, every registered function is allowed. When set, only the named functions are listed and callable; any other is reported as `unknown function`, so its existence is not revealed. Per-function `Authorize` still applies on top.
+
 ## MCP Tools
 
 Fixed set, independent of the models. `table` is `schema.entity`. Errors return `{"success":false,"error":{"code","message"}}` with codes `invalid_argument`, `not_found`, `forbidden`, `limit_exceeded`, `internal` (internal details are logged, the client gets a reference id).
@@ -652,6 +733,7 @@ The handler resolves table names in priority order:
 
 ## Breaking changes
 
+- The server is read-only by default. Writes (insert/update/delete), annotations and function calls need `Config{ReadOnly: resolvemcp.Bool(false)}` (function calls can also be kept on a read-only server with `AllowFunctionCalls`).
 - Per-model tools (`read_/create_/update_/delete_{schema}_{entity}`) and per-model resources are gone; use the meta tools.
 - `Setup*` / `NewSSEServer` / `NewStreamableHTTPHandler` take a `*security.SecurityList` and require authentication. `OptionalAuth*` helpers were removed; `*Unauthenticated` variants exist for explicit opt-out.
 - `resolvespec_annotate` is opt-in via `Config.EnableAnnotations`.

pkg/resolvemcp/catalog.go

@@ -0,0 +1,329 @@
+package resolvemcp
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"reflect"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/bitechdev/ResolveSpec/pkg/modelregistry"
+	"github.com/bitechdev/ResolveSpec/pkg/reflection"
+)
+
+// usageGuide is the short agent-facing guide sent as the MCP server instructions and
+// embedded in the exported catalogue. It is generic: it never mentions concrete models.
+const usageGuide = `This server exposes database tables through a fixed set of tools.
+1. Call list_tables to see the tables you may use, what they hold and the operations allowed.
+2. Call describe_table for a table before using it: columns, types, primary key, relations (preloadable), writable columns and limits.
+3. Read with select_table (filters, sort, columns, preloads). Results are paged; use limit/offset or cursors, and include_count only when you need a total.
+4. Write with insert_into_table, update_table, delete_from_table. Address one row by id, or several by filters. A filter-based write first returns a preview; repeat the call with the confirm_token to apply it (dry_run only previews).
+5. Use list_functions / call_function for registered functions.
+Read the error message when a call fails: it says which argument was wrong.`
+
+// readOnlyGuide replaces usageGuide on a read-only server.
+const readOnlyGuide = `This server exposes database tables through a fixed set of tools. It is READ-ONLY: you cannot insert, update or delete data or write annotations, and no tool for that exists. Do not attempt a write; tell the user it is not possible through this server.
+1. Call list_tables to see the tables you may read and what they hold.
+2. Call describe_table for a table before using it: columns, types, primary key, relations (preloadable) and limits.
+3. Read with select_table (filters, sort, columns, preloads). Results are paged; use limit/offset or cursors, and include_count only when you need a total.
+Read the error message when a call fails: it says which argument was wrong.`
+
+// readOnlyFunctionsGuide is the extra step of a read-only server that still allows functions.
+const readOnlyFunctionsGuide = `
+4. Use list_functions / call_function for the registered functions. Only call functions that fit a read-only server; the server decides what is allowed.`
+
+// guideFor returns the usage guide for the server mode.
+func guideFor(readOnly, functions bool) string {
+	if !readOnly {
+		return usageGuide
+	}
+	if functions {
+		return readOnlyGuide + readOnlyFunctionsGuide
+	}
+	return readOnlyGuide
+}
+
+// Catalog is a snapshot of what the server offers: the usage guide, the tools, the limits
+// and every table with its columns, relations, allowed operations and descriptions.
+type Catalog struct {
+	GeneratedAt time.Time      `json:"generated_at"`
+	Server      string         `json:"server"`
+	Version     string         `json:"version"`
+	ReadOnly    bool           `json:"read_only"`
+	Guide       string         `json:"guide"`
+	Limits      CatalogLimits  `json:"limits"`
+	Tools       []CatalogTool  `json:"tools"`
+	Tables      []CatalogTable `json:"tables"`
+}
+
+// CatalogLimits mirrors the configured server limits.
+type CatalogLimits struct {
+	DefaultLimit    int `json:"default_limit"`
+	MaxLimit        int `json:"max_limit"`
+	MaxOffset       int `json:"max_offset"`
+	MaxBatch        int `json:"max_batch"`
+	MaxPreloadDepth int `json:"max_preload_depth"`
+	MaxWriteRows    int `json:"max_write_rows"`
+}
+
+// CatalogTool is one MCP tool.
+type CatalogTool struct {
+	Name        string `json:"name"`
+	Description string `json:"description"`
+}
+
+// CatalogTable is one table in the catalogue.
+type CatalogTable struct {
+	Table       string          `json:"table"`
+	Description string          `json:"description,omitempty"`
+	Purpose     string          `json:"purpose,omitempty"`
+	Tags        []string        `json:"tags,omitempty"`
+	Operations  []string        `json:"operations"`
+	PrimaryKey  string          `json:"primary_key,omitempty"`
+	Columns     []CatalogColumn `json:"columns"`
+	Relations   []string        `json:"relations,omitempty"`
+}
+
+// CatalogColumn is one column of a table.
+type CatalogColumn struct {
+	Name        string `json:"name"`
+	Type        string `json:"type,omitempty"`
+	Nullable    bool   `json:"nullable"`
+	PrimaryKey  bool   `json:"primary_key,omitempty"`
+	Unique      bool   `json:"unique,omitempty"`
+	Writable    bool   `json:"writable"`
+	Description string `json:"description,omitempty"`
+}
+
+// modelDocs returns the effective documentation of a table. Registry info (including a
+// loaded descriptions file) wins, then the model's ModelDescription().
+func (h *Handler) modelDocs(schema, entity string) modelregistry.ModelInfo {
+	if reg, ok := h.registry.(*modelregistry.DefaultModelRegistry); ok {
+		return reg.ResolveModelInfo(buildModelName(schema, entity))
+	}
+	return modelregistry.ModelInfo{}
+}
+
+// columnDescription picks a column's description: the registry/file map first, then the
+// struct-tag comment.
+func columnDescription(docs modelregistry.ModelInfo, c columnInfo) string {
+	if d := docs.Columns[c.jsonName]; d != "" {
+		return d
+	}
+	return c.comment
+}
+
+// SetModelDescription stores documentation for a registered or soon-to-be-registered table.
+// It returns an error when the handler's registry does not keep model info.
+func (h *Handler) SetModelDescription(schema, entity string, info modelregistry.ModelInfo) error {
+	reg, ok := h.registry.(*modelregistry.DefaultModelRegistry)
+	if !ok {
+		return fmt.Errorf("resolvemcp: registry does not support model descriptions (use NewHandlerWithGORM/Bun/DB)")
+	}
+	reg.SetModelInfo(buildModelName(schema, entity), info)
+	return nil
+}
+
+// LoadModelDescriptions loads an external JSON map of descriptions keyed by "schema.entity"
+// (see modelregistry.LoadModelInfo for the format) and returns how many tables it covered.
+// Loaded entries override the model's own comments.
+func (h *Handler) LoadModelDescriptions(path string) (int, error) {
+	reg, ok := h.registry.(*modelregistry.DefaultModelRegistry)
+	if !ok {
+		return 0, fmt.Errorf("resolvemcp: registry does not support model descriptions (use NewHandlerWithGORM/Bun/DB)")
+	}
+	return reg.LoadModelInfoFile(path)
+}
+
+// BuildCatalog snapshots the server's tools and tables. Tables with no allowed operation are
+// left out, exactly as list_tables does.
+func (h *Handler) BuildCatalog() Catalog {
+	cat := Catalog{
+		GeneratedAt: time.Now().UTC(),
+		Server:      h.name,
+		Version:     h.version,
+		ReadOnly:    h.config.readOnly,
+		Guide:       guideFor(h.config.readOnly, h.config.AllowFunctionCalls),
+		Limits: CatalogLimits{
+			DefaultLimit:    h.config.DefaultLimit,
+			MaxLimit:        h.config.MaxLimit,
+			MaxOffset:       h.config.MaxOffset,
+			MaxBatch:        h.config.MaxBatch,
+			MaxPreloadDepth: h.config.MaxPreloadDepth,
+			MaxWriteRows:    h.config.MaxWriteRows,
+		},
+		Tools:  []CatalogTool{},
+		Tables: []CatalogTable{},
+	}
+
+	for name, tool := range h.mcpServer.ListTools() {
+		cat.Tools = append(cat.Tools, CatalogTool{Name: name, Description: tool.Tool.Description})
+	}
+	sort.Slice(cat.Tools, func(i, j int) bool { return cat.Tools[i].Name < cat.Tools[j].Name })
+
+	for name, model := range h.registry.GetAllModels() {
+		schema, entity, _ := splitTable(name)
+		rules := h.modelRules(schema, entity)
+		ops := h.opsFor(rules)
+		if len(ops) == 0 {
+			continue
+		}
+		info := buildModelInfo(schema, entity, model)
+		docs := h.modelDocs(schema, entity)
+
+		writable := map[string]bool{}
+		mt := reflect.TypeOf(model)
+		for mt != nil && (mt.Kind() == reflect.Pointer || mt.Kind() == reflect.Slice) {
+			mt = mt.Elem()
+		}
+		if !h.config.readOnly && mt != nil && mt.Kind() == reflect.Struct {
+			for k := range reflectionJSONColumns(mt) {
+				writable[k] = true
+			}
+		}
+
+		t := CatalogTable{
+			Table:       info.fullName,
+			Description: docs.Description,
+			Purpose:     docs.Purpose,
+			Tags:        docs.Tags,
+			Operations:  ops,
+			PrimaryKey:  info.pkName,
+			Relations:   info.relationNames,
+			Columns:     make([]CatalogColumn, 0, len(info.columns)),
+		}
+		for _, c := range info.columns {
+			typ := c.sqlType
+			if typ == "" {
+				typ = c.goType
+			}
+			t.Columns = append(t.Columns, CatalogColumn{
+				Name: c.jsonName, Type: typ, Nullable: c.nullable, PrimaryKey: c.isPrimary,
+				Unique: c.isUnique, Writable: writable[c.jsonName], Description: columnDescription(docs, c),
+			})
+		}
+		cat.Tables = append(cat.Tables, t)
+	}
+	sort.Slice(cat.Tables, func(i, j int) bool { return cat.Tables[i].Table < cat.Tables[j].Table })
+	return cat
+}
+
+// ExportCatalog writes the catalogue to path. A ".json" extension writes JSON; anything
+// else writes Markdown. The file is replaced atomically (written to a temp file in the same
+// directory, then renamed) and created with mode 0600. It lists every table the registry
+// allows any operation on, regardless of caller, so keep it out of public directories.
+func (h *Handler) ExportCatalog(path string) error {
+	cat := h.BuildCatalog()
+
+	var data []byte
+	if strings.EqualFold(filepath.Ext(path), ".json") {
+		b, err := json.MarshalIndent(cat, "", "  ")
+		if err != nil {
+			return err
+		}
+		data = b
+		data = append(data, '\n')
+	} else {
+		data = []byte(cat.Markdown())
+	}
+
+	dir := filepath.Dir(path)
+	if err := os.MkdirAll(dir, 0o750); err != nil {
+		return fmt.Errorf("resolvemcp: export catalog: %w", err)
+	}
+	tmp, err := os.CreateTemp(dir, ".catalog-*")
+	if err != nil {
+		return fmt.Errorf("resolvemcp: export catalog: %w", err)
+	}
+	tmpName := tmp.Name()
+	_, werr := tmp.Write(data)
+	cerr := tmp.Close()
+	if werr == nil {
+		werr = cerr
+	}
+	if werr == nil {
+		werr = os.Rename(tmpName, path)
+	}
+	if werr != nil {
+		_ = os.Remove(tmpName)
+		return fmt.Errorf("resolvemcp: export catalog: %w", werr)
+	}
+	return nil
+}
+
+// Markdown renders the catalogue as a Markdown document.
+func (c Catalog) Markdown() string {
+	var sb strings.Builder
+	fmt.Fprintf(&sb, "# %s API catalogue\n\nGenerated %s.\n\n", c.Server, c.GeneratedAt.Format(time.RFC3339))
+	if c.ReadOnly {
+		sb.WriteString("**This server is read-only.**\n\n")
+	}
+	sb.WriteString("## How to use\n\n" + c.Guide + "\n\n")
+	fmt.Fprintf(&sb, "## Limits\n\ndefault limit %d, max limit %d, max offset %d, max batch %d, max preload depth %d, max rows per filter write %d.\n\n",
+		c.Limits.DefaultLimit, c.Limits.MaxLimit, c.Limits.MaxOffset, c.Limits.MaxBatch, c.Limits.MaxPreloadDepth, c.Limits.MaxWriteRows)
+
+	sb.WriteString("## Tools\n\n")
+	for _, t := range c.Tools {
+		fmt.Fprintf(&sb, "- `%s`: %s\n", t.Name, oneLine(t.Description))
+	}
+
+	sb.WriteString("\n## Tables\n\n")
+	if len(c.Tables) == 0 {
+		sb.WriteString("No tables are registered.\n")
+	}
+	for i := range c.Tables {
+		t := &c.Tables[i]
+		fmt.Fprintf(&sb, "### %s\n\n", t.Table)
+		if t.Description != "" {
+			sb.WriteString(t.Description + "\n\n")
+		}
+		if t.Purpose != "" {
+			sb.WriteString("Purpose: " + t.Purpose + "\n\n")
+		}
+		if len(t.Tags) > 0 {
+			sb.WriteString("Tags: " + strings.Join(t.Tags, ", ") + "\n\n")
+		}
+		fmt.Fprintf(&sb, "Operations: %s", strings.Join(t.Operations, ", "))
+		if t.PrimaryKey != "" {
+			fmt.Fprintf(&sb, " · Primary key: `%s`", t.PrimaryKey)
+		}
+		sb.WriteString("\n\n| Column | Type | Flags | Description |\n|---|---|---|---|\n")
+		for _, col := range t.Columns {
+			var flags []string
+			if col.PrimaryKey {
+				flags = append(flags, "pk")
+			}
+			if col.Unique {
+				flags = append(flags, "unique")
+			}
+			if col.Nullable {
+				flags = append(flags, "nullable")
+			}
+			if !col.Writable {
+				flags = append(flags, "read-only")
+			}
+			fmt.Fprintf(&sb, "| `%s` | %s | %s | %s |\n", col.Name, mdCell(col.Type), strings.Join(flags, ", "), mdCell(col.Description))
+		}
+		if len(t.Relations) > 0 {
+			sb.WriteString("\nRelations (preloadable): " + strings.Join(t.Relations, ", ") + "\n")
+		}
+		sb.WriteString("\n")
+	}
+	return sb.String()
+}
+
+func oneLine(s string) string {
+	return strings.Join(strings.Fields(s), " ")
+}
+
+func mdCell(s string) string {
+	return strings.ReplaceAll(oneLine(s), "|", `\|`)
+}
+
+// reflectionJSONColumns returns the JSON names of the columns a write may set.
+func reflectionJSONColumns(t reflect.Type) map[string]string {
+	return reflection.BuildJSONToDBColumnMap(t)
+}

pkg/resolvemcp/catalog_test.go

@@ -0,0 +1,126 @@
+package resolvemcp
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/bitechdev/ResolveSpec/pkg/common/adapters/database"
+	"github.com/bitechdev/ResolveSpec/pkg/modelregistry"
+)
+
+type docItem struct {
+	ID    int    `json:"id" bun:"id,pk"`
+	Email string `json:"email" bun:"email,comment:Tag comment"`
+	Name  string `json:"name" bun:"name" note:"Name from tag"`
+}
+
+func (docItem) ModelDescription() string { return "Model-level fallback" }
+
+func newDocHandler(t *testing.T) *Handler {
+	t.Helper()
+	h := NewHandler(database.NewPgSQLAdapter(nil), modelregistry.NewModelRegistry(), Config{})
+	if err := h.RegisterModel("public", "items", &docItem{}); err != nil {
+		t.Fatal(err)
+	}
+	hidden := modelregistry.ModelRules{} // no operation allowed
+	if err := h.RegisterModelWithRules("public", "secret", &docItem{}, hidden); err != nil {
+		t.Fatal(err)
+	}
+	return h
+}
+
+func TestCatalogDescriptionsPrecedence(t *testing.T) {
+	h := newDocHandler(t)
+	cat := h.BuildCatalog()
+	if len(cat.Tables) != 1 || cat.Tables[0].Table != "public.items" {
+		t.Fatalf("tables = %+v (hidden table must be left out)", cat.Tables)
+	}
+	tb := cat.Tables[0]
+	if tb.Description != "Model-level fallback" {
+		t.Errorf("fallback description = %q", tb.Description)
+	}
+	col := map[string]string{}
+	for _, c := range tb.Columns {
+		col[c.Name] = c.Description
+	}
+	if col["email"] != "Tag comment" || col["name"] != "Name from tag" {
+		t.Errorf("tag comments = %v", col)
+	}
+
+	path := filepath.Join(t.TempDir(), "desc.json")
+	if err := os.WriteFile(path, []byte(`{"public.items":{"description":"From file","columns":{"email":"File email"}}}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if n, err := h.LoadModelDescriptions(path); err != nil || n != 1 {
+		t.Fatalf("load n=%d err=%v", n, err)
+	}
+	tb = h.BuildCatalog().Tables[0]
+	if tb.Description != "From file" {
+		t.Errorf("file must win, got %q", tb.Description)
+	}
+	for _, c := range tb.Columns {
+		switch c.Name {
+		case "email":
+			if c.Description != "File email" {
+				t.Errorf("email = %q", c.Description)
+			}
+		case "name":
+			if c.Description != "Name from tag" {
+				t.Errorf("name must fall back to tag, got %q", c.Description)
+			}
+		}
+	}
+}
+
+func TestExportCatalogFiles(t *testing.T) {
+	h := newDocHandler(t)
+	dir := t.TempDir()
+
+	md := filepath.Join(dir, "sub", "catalog.md")
+	if err := h.ExportCatalog(md); err != nil {
+		t.Fatal(err)
+	}
+	b, _ := os.ReadFile(md)
+	for _, want := range []string{"# resolvemcp API catalogue", "### public.items", "Model-level fallback", "`list_tables`", "Tag comment"} {
+		if !strings.Contains(string(b), want) {
+			t.Errorf("markdown missing %q", want)
+		}
+	}
+	if strings.Contains(string(b), "public.secret") {
+		t.Error("table without operations leaked into the catalogue")
+	}
+
+	js := filepath.Join(dir, "catalog.json")
+	if err := h.ExportCatalog(js); err != nil {
+		t.Fatal(err)
+	}
+	var cat Catalog
+	b, _ = os.ReadFile(js)
+	if err := json.Unmarshal(b, &cat); err != nil || len(cat.Tables) != 1 || len(cat.Tools) == 0 {
+		t.Fatalf("json catalog bad: err=%v %+v", err, cat)
+	}
+
+	entries, _ := os.ReadDir(dir)
+	for _, e := range entries {
+		if strings.HasPrefix(e.Name(), ".catalog-") {
+			t.Errorf("temp file left behind: %s", e.Name())
+		}
+	}
+}
+
+func TestDescribeAndListIncludeDescriptions(t *testing.T) {
+	h := newDocHandler(t)
+	res, _ := h.handleListTables(nil, callReq(nil))
+	tables, _ := payload(t, res)["tables"].([]any)
+	if len(tables) != 1 || tables[0].(map[string]any)["description"] != "Model-level fallback" {
+		t.Errorf("list_tables = %v", tables)
+	}
+	res, _ = h.handleDescribeTable(nil, callReq(map[string]any{"table": "public.items"}))
+	p := payload(t, res)
+	if p["description"] != "Model-level fallback" {
+		t.Errorf("describe_table description = %v", p["description"])
+	}
+}

pkg/resolvemcp/doc.go

@@ -0,0 +1,50 @@
+// Package resolvemcp exposes registered database models as Model Context Protocol (MCP)
+// tools over HTTP (SSE and streamable HTTP), so an AI agent can discover, read and
+// change data without a tool per table.
+//
+// # How an agent uses it
+//
+// The tool set is fixed and does not grow with the models:
+//
+//	list_tables      tables the caller may use, their description and allowed operations
+//	describe_table   columns, types, keys, relations, writable fields, limits
+//	select_table     read rows: filters, sort, columns, preloads, paging, cursors
+//	insert_into_table / update_table / delete_from_table
+//	                 writes; filter-based writes are previewed (dry_run) and need the
+//	                 confirm_token from the preview
+//	list_functions / call_function   registered stored functions
+//	resolvespec_annotate             optional free-text notes (Config.EnableAnnotations)
+//
+// The same guide is sent to MCP clients as the server instructions.
+//
+// The server is read-only by default (Config.ReadOnly nil means on); set
+// ReadOnly: resolvemcp.Bool(false) to enable the write tools.
+//
+// # Setting it up
+//
+//	handler := resolvemcp.NewHandlerWithGORM(db, resolvemcp.Config{BaseURL: "http://localhost:8080"})
+//	handler.RegisterModel("public", "users", &User{})
+//
+//	r := mux.NewRouter()
+//	resolvemcp.SetupMuxRoutes(r, handler, securityList) // requires an authenticated caller
+//
+// # Describing the API for agents
+//
+// Models are documented through the model registry (see package modelregistry):
+// SetModelDescription / LoadModelDescriptions on the handler, a ModelDescription()
+// method on the model, or comment tags on its fields (gorm/bun "comment:" or
+// comment/note/desc tags). The descriptions show up in list_tables and
+// describe_table.
+//
+// ExportCatalog writes the whole picture (guide, tools, limits, tables with columns,
+// relations, operations and descriptions) to a JSON or Markdown file on disk, so
+// agents and developers can learn the API without connecting:
+//
+//	handler.ExportCatalog("docs/mcp-catalog.md")
+//
+// # Security
+//
+// Routes must be mounted behind Guard(securityList); the *Unauthenticated setup
+// functions exist only for use behind another trusted layer. Per-entity rules come from
+// modelregistry.ModelRules, and BeforeHandle/AfterHandle hooks can veto or audit any call.
+package resolvemcp

pkg/resolvemcp/functions.go

@@ -108,6 +108,15 @@ func (h *Handler) function(name string) (Function, bool) {
 	return f, ok
 }
 
+// functionAllowed reports whether Config.AllowedFunctions lets the function through.
+func (h *Handler) functionAllowed(name string) bool {
+	if h.allowedFns == nil {
+		return true
+	}
+	_, ok := h.allowedFns[name]
+	return ok
+}
+
 // visibleFunctions returns the functions the caller may call, sorted by name.
 func (h *Handler) visibleFunctions(ctx context.Context) []Function {
 	h.functions.mu.RLock()
@@ -119,6 +128,9 @@ func (h *Handler) visibleFunctions(ctx context.Context) []Function {
 	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
 	visible := out[:0]
 	for _, f := range out {
+		if !h.functionAllowed(f.Name) {
+			continue
+		}
 		if f.Authorize == nil || f.Authorize(ctx) == nil {
 			visible = append(visible, f)
 		}
@@ -236,7 +248,7 @@ func (h *Handler) executeCall(ctx context.Context, name string, rawArgs map[stri
 	defer cancel()
 
 	f, ok := h.function(name)
-	if !ok {
+	if !ok || !h.functionAllowed(name) {
 		return nil, invalidArg("unknown function %q", truncate(name))
 	}
 	hookCtx := &HookContext{Context: ctx, Handler: h, Entity: name, Operation: "call_function", Tx: h.db}

pkg/resolvemcp/handler.go

@@ -24,6 +24,7 @@ import (
 
 // Handler exposes registered database models as MCP tools and resources.
 type Handler struct {
+	allowedFns map[string]struct{} // nil: every function is allowed
 	db         common.Database
 	registry   common.ModelRegistry
 	hooks      *HookRegistry
@@ -43,14 +44,20 @@ func NewHandler(db common.Database, registry common.ModelRegistry, cfg Config) *
 		db:        db,
 		registry:  registry,
 		hooks:     NewHookRegistry(),
-		mcpServer: server.NewMCPServer("resolvemcp", "1.0.0"),
+		mcpServer: server.NewMCPServer("resolvemcp", "1.0.0", server.WithInstructions(guideFor(cfg.withDefaults().readOnly, cfg.AllowFunctionCalls))),
 		config:    cfg.withDefaults(),
 		confirms:  newConfirmStore(),
 		name:      "resolvemcp",
 		version:   "1.0.0",
 	}
+	if len(cfg.AllowedFunctions) > 0 {
+		h.allowedFns = make(map[string]struct{}, len(cfg.AllowedFunctions))
+		for _, n := range cfg.AllowedFunctions {
+			h.allowedFns[n] = struct{}{}
+		}
+	}
 	registerMetaTools(h)
-	if cfg.EnableAnnotations {
+	if cfg.EnableAnnotations && !h.config.readOnly {
 		registerAnnotationTool(h)
 	}
 	return h

pkg/resolvemcp/meta.go

@@ -56,6 +56,16 @@ func registerMetaTools(h *Handler) {
 		mcp.WithBoolean("include_count", mcp.Description("Also return the total number of matching rows (slower on large tables).")),
 	), h.handleSelect)
 
+	if !h.config.readOnly {
+		registerWriteTools(h, tableArg, idArg, filtersArg, dryRunArg, confirmArg)
+	}
+	if !h.config.readOnly || h.config.AllowFunctionCalls {
+		registerFunctionTools(h, readOnly)
+	}
+}
+
+// registerWriteTools adds the tools that change table rows.
+func registerWriteTools(h *Handler, tableArg, idArg, filtersArg, dryRunArg, confirmArg mcp.ToolOption) {
 	h.mcpServer.AddTool(mcp.NewTool("insert_into_table",
 		mcp.WithDescription("Insert one row (object) or several rows (array, one transaction, capped). Unknown or read-only fields are rejected."),
 		tableArg, mcp.WithObject("data", mcp.Required(), mcp.Description("A row object or an array of row objects.")),
@@ -73,7 +83,10 @@ func registerMetaTools(h *Handler) {
 		mcp.WithDestructiveHintAnnotation(true),
 		tableArg, idArg, filtersArg, dryRunArg, confirmArg,
 	), h.handleDelete)
+}
 
+// registerFunctionTools adds list_functions and call_function.
+func registerFunctionTools(h *Handler, readOnly mcp.ToolOption) {
 	h.mcpServer.AddTool(mcp.NewTool("list_functions", readOnly,
 		mcp.WithDescription("List the functions you can call with call_function, with their parameters.")),
 		h.handleListFunctions)
@@ -111,11 +124,15 @@ func (h *Handler) modelRules(schema, entity string) modelregistry.ModelRules {
 	return modelregistry.DefaultModelRules()
 }
 
-func opsFor(r modelregistry.ModelRules) []string {
+// opsFor lists the operations the rules allow. A read-only server allows select only.
+func (h *Handler) opsFor(r modelregistry.ModelRules) []string {
 	var ops []string
 	if r.CanRead {
 		ops = append(ops, opSelect)
 	}
+	if h.config.readOnly {
+		return ops
+	}
 	if r.CanCreate {
 		ops = append(ops, opInsert)
 	}
@@ -140,9 +157,12 @@ func (h *Handler) resolveTable(args map[string]any, op string) (schema, entity s
 	if _, err := h.registry.GetModelByEntity(schema, entity); err != nil {
 		return "", "", invalidArg("unknown table %q; see list_tables", truncate(table))
 	}
+	if op != "" && op != opSelect && h.config.readOnly {
+		return "", "", NewClientError(CodeForbidden, "this server is read-only: writes are disabled")
+	}
 	if op != "" {
 		allowed := false
-		for _, o := range opsFor(h.modelRules(schema, entity)) {
+		for _, o := range h.opsFor(h.modelRules(schema, entity)) {
 			if o == op {
 				allowed = true
 			}
@@ -156,14 +176,15 @@ func (h *Handler) resolveTable(args map[string]any, op string) (schema, entity s
 
 func (h *Handler) handleListTables(ctx context.Context, _ mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 	type table struct {
-		Table      string   `json:"table"`
-		Operations []string `json:"operations"`
+		Table       string   `json:"table"`
+		Description string   `json:"description,omitempty"`
+		Operations  []string `json:"operations"`
 	}
 	var tables []table
 	for name := range h.registry.GetAllModels() {
 		schema, entity, _ := splitTable(name)
-		if ops := opsFor(h.modelRules(schema, entity)); len(ops) > 0 {
-			tables = append(tables, table{Table: name, Operations: ops})
+		if ops := h.opsFor(h.modelRules(schema, entity)); len(ops) > 0 {
+			tables = append(tables, table{Table: name, Description: h.modelDocs(schema, entity).Description, Operations: ops})
 		}
 	}
 	sort.Slice(tables, func(i, j int) bool { return tables[i].Table < tables[j].Table })
@@ -180,17 +201,18 @@ func (h *Handler) handleDescribeTable(_ context.Context, req mcp.CallToolRequest
 		return toolError("describe_table", invalidArg("unknown table")), nil
 	}
 	rules := h.modelRules(schema, entity)
-	if len(opsFor(rules)) == 0 {
+	if len(h.opsFor(rules)) == 0 {
 		return toolError("describe_table", invalidArg("unknown table %q; see list_tables", buildModelName(schema, entity))), nil
 	}
 	info := buildModelInfo(schema, entity, model)
+	docs := h.modelDocs(schema, entity)
 
 	modelType := reflect.TypeOf(model)
 	for modelType != nil && (modelType.Kind() == reflect.Pointer || modelType.Kind() == reflect.Slice) {
 		modelType = modelType.Elem()
 	}
 	writable := map[string]bool{}
-	if modelType != nil && modelType.Kind() == reflect.Struct {
+	if !h.config.readOnly && modelType != nil && modelType.Kind() == reflect.Struct {
 		for jsonKey := range reflection.BuildJSONToDBColumnMap(modelType) {
 			writable[jsonKey] = true
 		}
@@ -203,6 +225,7 @@ func (h *Handler) handleDescribeTable(_ context.Context, req mcp.CallToolRequest
 		PrimaryKey bool   `json:"primary_key,omitempty"`
 		Unique     bool   `json:"unique,omitempty"`
 		Writable   bool   `json:"writable"`
+		Comment    string `json:"description,omitempty"`
 	}
 	cols := make([]column, 0, len(info.columns))
 	var writableNames []string
@@ -212,7 +235,7 @@ func (h *Handler) handleDescribeTable(_ context.Context, req mcp.CallToolRequest
 			typ = c.goType
 		}
 		w := writable[c.jsonName]
-		cols = append(cols, column{Name: c.jsonName, Type: typ, Nullable: c.nullable, PrimaryKey: c.isPrimary, Unique: c.isUnique, Writable: w})
+		cols = append(cols, column{Name: c.jsonName, Type: typ, Nullable: c.nullable, PrimaryKey: c.isPrimary, Unique: c.isUnique, Writable: w, Comment: columnDescription(docs, c)})
 		if w && !c.isPrimary {
 			writableNames = append(writableNames, c.jsonName)
 		}
@@ -220,11 +243,15 @@ func (h *Handler) handleDescribeTable(_ context.Context, req mcp.CallToolRequest
 	return marshalResult(map[string]any{
 		"success":          true,
 		"table":            info.fullName,
+		"description":      docs.Description,
+		"purpose":          docs.Purpose,
+		"tags":             docs.Tags,
 		"primary_key":      info.pkName,
 		"columns":          cols,
 		"relations":        info.relationNames,
 		"writable_columns": writableNames,
-		"operations":       opsFor(rules),
+		"operations":       h.opsFor(rules),
+		"read_only":        h.config.readOnly,
 		"filter_operators": filterOperators,
 		"limits": map[string]any{
 			"default_limit":     h.config.DefaultLimit,

pkg/resolvemcp/readonly_test.go

@@ -0,0 +1,168 @@
+package resolvemcp
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"github.com/bitechdev/ResolveSpec/pkg/common"
+	"github.com/bitechdev/ResolveSpec/pkg/common/adapters/database"
+	"github.com/bitechdev/ResolveSpec/pkg/modelregistry"
+)
+
+func newReadOnlyHandler(t *testing.T) *Handler {
+	t.Helper()
+	h := NewHandler(database.NewPgSQLAdapter(nil), modelregistry.NewModelRegistry(),
+		Config{EnableAnnotations: true})
+	if err := h.RegisterModel("public", "items", &docItem{}); err != nil {
+		t.Fatal(err)
+	}
+	return h
+}
+
+func TestReadOnlyToolSet(t *testing.T) {
+	h := newReadOnlyHandler(t)
+	tools := h.mcpServer.ListTools()
+	for _, name := range []string{"list_tables", "describe_table", "select_table"} {
+		if tools[name] == nil {
+			t.Errorf("read tool %s missing", name)
+		}
+	}
+	for _, name := range []string{"insert_into_table", "update_table", "delete_from_table", "call_function", "list_functions", annotationToolName} {
+		if tools[name] != nil {
+			t.Errorf("tool %s must not be registered on a read-only server", name)
+		}
+	}
+}
+
+func TestReadOnlyRefusesWritesAndReportsIt(t *testing.T) {
+	h := newReadOnlyHandler(t)
+	ctx := context.Background()
+	args := map[string]any{"table": "public.items", "data": map[string]any{"name": "x"}, "id": 1}
+
+	for name, fn := range map[string]func() map[string]any{
+		"insert": func() map[string]any { r, _ := h.handleInsert(ctx, callReq(args)); return payload(t, r) },
+		"update": func() map[string]any { r, _ := h.handleUpdate(ctx, callReq(args)); return payload(t, r) },
+		"delete": func() map[string]any { r, _ := h.handleDelete(ctx, callReq(args)); return payload(t, r) },
+	} {
+		e, _ := fn()["error"].(map[string]any)
+		if e["code"] != CodeForbidden || !strings.Contains(e["message"].(string), "read-only") {
+			t.Errorf("%s: error = %v", name, e)
+		}
+	}
+
+	res, _ := h.handleListTables(ctx, callReq(nil))
+	tb := payload(t, res)["tables"].([]any)[0].(map[string]any)
+	if ops := tb["operations"].([]any); len(ops) != 1 || ops[0] != opSelect {
+		t.Errorf("list_tables operations = %v", ops)
+	}
+
+	res, _ = h.handleDescribeTable(ctx, callReq(map[string]any{"table": "public.items"}))
+	p := payload(t, res)
+	if p["read_only"] != true {
+		t.Errorf("describe_table read_only = %v", p["read_only"])
+	}
+	if w, _ := p["writable_columns"].([]any); len(w) != 0 {
+		t.Errorf("writable_columns = %v", w)
+	}
+
+	cat := h.BuildCatalog()
+	if !cat.ReadOnly || !strings.Contains(cat.Guide, "READ-ONLY") || !strings.Contains(cat.Markdown(), "read-only") {
+		t.Error("catalogue must say the server is read-only")
+	}
+	for _, c := range cat.Tables[0].Columns {
+		if c.Writable {
+			t.Errorf("column %s marked writable", c.Name)
+		}
+	}
+	if !strings.Contains(guideFor(true, false), "READ-ONLY") || strings.Contains(guideFor(false, false), "READ-ONLY") {
+		t.Error("guideFor")
+	}
+}
+
+func newFnHandler(t *testing.T, cfg Config) *Handler {
+	t.Helper()
+	h := NewHandler(database.NewPgSQLAdapter(nil), modelregistry.NewModelRegistry(), cfg)
+	for _, name := range []string{"alpha", "beta"} {
+		name := name
+		err := h.RegisterFunction(Function{Name: name, Handler: func(context.Context, common.Database, map[string]any) (any, error) {
+			return name, nil
+		}})
+		if err != nil {
+			t.Fatal(err)
+		}
+	}
+	return h
+}
+
+func TestReadOnlyAllowFunctionCalls(t *testing.T) {
+	h := newFnHandler(t, Config{AllowFunctionCalls: true})
+	tools := h.mcpServer.ListTools()
+	if tools["list_functions"] == nil || tools["call_function"] == nil {
+		t.Error("function tools must be registered")
+	}
+	if tools["insert_into_table"] != nil || tools["update_table"] != nil {
+		t.Error("write tools must stay off")
+	}
+	if g := guideFor(true, true); !strings.Contains(g, "READ-ONLY") || !strings.Contains(g, "call_function") {
+		t.Error("guide must mention functions")
+	}
+	if h.mcpServer.ListTools()["call_function"] == nil {
+		t.Error("call_function missing")
+	}
+}
+
+func TestAllowedFunctions(t *testing.T) {
+	ctx := context.Background()
+	for name, tc := range map[string]struct {
+		allowed []string
+		visible []string
+	}{
+		"empty allows all": {nil, []string{"alpha", "beta"}},
+		"only listed":      {[]string{"beta"}, []string{"beta"}},
+		"unknown name":     {[]string{"zzz"}, nil},
+	} {
+		h := newFnHandler(t, Config{AllowedFunctions: tc.allowed})
+		var got []string
+		for _, f := range h.visibleFunctions(ctx) {
+			got = append(got, f.Name)
+		}
+		if strings.Join(got, ",") != strings.Join(tc.visible, ",") {
+			t.Errorf("%s: visible = %v, want %v", name, got, tc.visible)
+		}
+		for _, fn := range []string{"alpha", "beta"} {
+			listed := false
+			for _, v := range tc.visible {
+				listed = listed || v == fn
+			}
+			if h.functionAllowed(fn) != listed {
+				t.Errorf("%s: functionAllowed(%s) = %v, want %v", name, fn, !listed, listed)
+			}
+			if !listed {
+				// refused before any database work, and indistinguishable from a missing function
+				if _, err := h.executeCall(ctx, fn, nil); err == nil || !strings.Contains(err.Error(), "unknown function") {
+					t.Errorf("%s: %s must be reported unknown, err=%v", name, fn, err)
+				}
+			}
+		}
+	}
+}
+
+func TestReadOnlyDefaultsOnAndCanBeDisabled(t *testing.T) {
+	if !(Config{}).withDefaults().readOnly {
+		t.Error("ReadOnly must default to on")
+	}
+	if !(Config{ReadOnly: Bool(true)}).withDefaults().readOnly {
+		t.Error("explicit true")
+	}
+	if (Config{ReadOnly: Bool(false)}).withDefaults().readOnly {
+		t.Error("Bool(false) must enable writes")
+	}
+	h := NewHandler(database.NewPgSQLAdapter(nil), modelregistry.NewModelRegistry(), Config{ReadOnly: Bool(false)})
+	if h.mcpServer.ListTools()["insert_into_table"] == nil {
+		t.Error("write tools must register when ReadOnly is Bool(false)")
+	}
+	if strings.Contains(h.BuildCatalog().Guide, "READ-ONLY") {
+		t.Error("guide must not claim read-only")
+	}
+}

pkg/resolvemcp/resolvemcp.go

@@ -1,18 +1,3 @@
-// Package resolvemcp exposes registered database models as Model Context Protocol (MCP) tools
-// and resources over HTTP/SSE transport.
-//
-// It mirrors the resolvespec package patterns:
-//   - Same model registration API
-//   - Same filter, sort, cursor pagination, preload options
-//   - Same lifecycle hook system
-//
-// Usage:
-//
-//	handler := resolvemcp.NewHandlerWithGORM(db, resolvemcp.Config{BaseURL: "http://localhost:8080"})
-//	handler.RegisterModel("public", "users", &User{})
-//
-//	r := mux.NewRouter()
-//	resolvemcp.SetupMuxRoutes(r, handler, securityList) // requires an authenticated caller
 package resolvemcp
 
 import (
@@ -66,6 +51,28 @@ type Config struct {
 	// host, with at most 32 distinct base URLs cached; prefer setting BaseURL.
 	AllowedHosts []string
 
+	// ReadOnly disables every write and is ON when left nil: set it to Bool(false) to allow
+	// writes. When on, the insert, update, delete and annotation tools are not registered,
+	// list_tables and describe_table report only the select operation (no writable columns),
+	// a write attempted anyway is refused with a "forbidden" error, and the server
+	// instructions tell the agent it cannot write. list_functions/call_function are also
+	// off, because a registered function may change data, unless AllowFunctionCalls is set.
+	ReadOnly *bool
+
+	// readOnly is ReadOnly after defaults (nil means true).
+	readOnly bool
+
+	// AllowFunctionCalls keeps list_functions and call_function available on a ReadOnly
+	// server. Only set it for functions that do not change data; pair it with
+	// AllowedFunctions to name them. It has no effect when writes are enabled (ReadOnly set to Bool(false)) (functions are
+	// always available then).
+	AllowFunctionCalls bool
+
+	// AllowedFunctions restricts list_functions and call_function to the named functions.
+	// Empty allows every registered function. A function outside the list is reported as
+	// unknown, so its existence is not revealed.
+	AllowedFunctions []string
+
 	// EnableAnnotations registers the resolvespec_annotate tool. Off by default: annotations
 	// are free text that agents read back, so enabling the tool opens a write channel into
 	// agent-visible text. When on, every call runs the BeforeHandle hooks (operation
@@ -73,6 +80,9 @@ type Config struct {
 	EnableAnnotations bool
 }
 
+// Bool returns a pointer to v, for the optional boolean fields of Config.
+func Bool(v bool) *bool { return &v }
+
 // withDefaults fills the zero limit fields.
 func (c Config) withDefaults() Config {
 	def := func(v *int, d int) {
@@ -89,6 +99,7 @@ func (c Config) withDefaults() Config {
 	if c.DefaultLimit > c.MaxLimit {
 		c.DefaultLimit = c.MaxLimit
 	}
+	c.readOnly = c.ReadOnly == nil || *c.ReadOnly
 	if c.QueryTimeout <= 0 {
 		c.QueryTimeout = 30 * time.Second
 	}

pkg/resolvemcp/security_test.go

@@ -191,7 +191,7 @@ func TestAnnotationToolIsOptIn(t *testing.T) {
 	if h.mcpServer.GetTool(annotationToolName) != nil {
 		t.Fatal("annotation tool must be off by default")
 	}
-	on := NewHandler(h.db, modelregistry.NewModelRegistry(), Config{EnableAnnotations: true})
+	on := NewHandler(h.db, modelregistry.NewModelRegistry(), Config{EnableAnnotations: true, ReadOnly: Bool(false)})
 	if on.mcpServer.GetTool(annotationToolName) == nil {
 		t.Fatal("annotation tool missing when enabled")
 	}

pkg/resolvemcp/tools.go

@@ -9,6 +9,7 @@ import (
 	"github.com/mark3labs/mcp-go/mcp"
 
 	"github.com/bitechdev/ResolveSpec/pkg/common"
+	"github.com/bitechdev/ResolveSpec/pkg/modelregistry"
 	"github.com/bitechdev/ResolveSpec/pkg/reflection"
 )
 
@@ -30,6 +31,7 @@ type columnInfo struct {
 	isUnique  bool
 	isFK      bool
 	nullable  bool
+	comment   string // from struct tags (gorm/bun comment:, comment/note/desc tags)
 }
 
 // buildModelInfo extracts column metadata and pre-builds the schema documentation string.
@@ -100,7 +102,12 @@ func buildModelInfo(schema, entity string, model interface{}) modelInfo {
 		isPrimary := d.SQLKey == "primary_key" ||
 			(info.pkName != "" && (sqlName == info.pkName || jsonName == info.pkName))
 
+		comment := ""
+		if found {
+			comment = modelregistry.FieldComment(fieldType)
+		}
 		ci := columnInfo{
+			comment:   comment,
 			jsonName:  jsonName,
 			sqlName:   sqlName,
 			goType:    goType,

pkg/resolvemcp/tx_test.go

@@ -29,7 +29,7 @@ func newTxHarness(t *testing.T) (*Handler, sqlmock.Sqlmock, context.Context) {
 	// connection and fails on the context timeout.
 	db.SetMaxOpenConns(1)
 	t.Cleanup(func() { _ = db.Close() })
-	h := NewHandler(database.NewPgSQLAdapter(db), modelregistry.NewModelRegistry(), Config{})
+	h := NewHandler(database.NewPgSQLAdapter(db), modelregistry.NewModelRegistry(), Config{ReadOnly: Bool(false)})
 	if err := h.RegisterModel("public", "items", &txItem{}); err != nil {
 		t.Fatal(err)
 	}

pkg/resolvespec/filter_join_sqlite_test.go

@@ -0,0 +1,183 @@
+package resolvespec
+
+import (
+	"context"
+	"database/sql"
+	"strings"
+	"testing"
+
+	"github.com/uptrace/bun"
+	"github.com/uptrace/bun/dialect/sqlitedialect"
+	"github.com/uptrace/bun/driver/sqliteshim"
+
+	"github.com/bitechdev/ResolveSpec/pkg/common"
+	"github.com/bitechdev/ResolveSpec/pkg/common/adapters/database"
+)
+
+type joinCountry struct {
+	bun.BaseModel `bun:"table:country,alias:country"`
+	ID            int64  `bun:"id,pk"`
+	Name          string `bun:"name"`
+}
+
+type joinProvince struct {
+	bun.BaseModel `bun:"table:province_state,alias:province_state"`
+	ID            int64  `bun:"id,pk"`
+	Name          string `bun:"name"`
+	Abbreviation  string `bun:"abbreviation"`
+	RidCountry    int64  `bun:"rid_country"`
+}
+
+// SQLite has no ILIKE; the ilike operator is covered by SQL-string tests, and
+// LIKE here proves the CAST(... AS TEXT) wrapping executes with qualified columns.
+func setupJoinDB(t *testing.T) *bun.DB {
+	t.Helper()
+	sqldb, err := sql.Open(sqliteshim.ShimName, "file:filterjoin?mode=memory&cache=private")
+	if err != nil {
+		t.Fatal(err)
+	}
+	db := bun.NewDB(sqldb, sqlitedialect.New())
+	t.Cleanup(func() { _ = db.Close() })
+	ctx := context.Background()
+	for _, m := range []interface{}{(*joinCountry)(nil), (*joinProvince)(nil)} {
+		if _, err := db.NewCreateTable().Model(m).IfNotExists().Exec(ctx); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if _, err := db.NewInsert().Model(&[]joinCountry{{ID: 1, Name: "Abcland"}, {ID: 2, Name: "Other"}}).Exec(ctx); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := db.NewInsert().Model(&[]joinProvince{
+		{ID: 1, Name: "abc one", Abbreviation: "A1", RidCountry: 1},
+		{ID: 2, Name: "xyz two", Abbreviation: "ABC", RidCountry: 1},
+		{ID: 3, Name: "nope", Abbreviation: "N3", RidCountry: 2},
+	}).Exec(ctx); err != nil {
+		t.Fatal(err)
+	}
+	return db
+}
+
+const joinSQL = "LEFT JOIN country AS rel_rid_country ON rel_rid_country.id = province_state.rid_country"
+
+func countWith(t *testing.T, db *bun.DB, withJoin bool, filters []common.FilterOption, alias string) (int, error) {
+	t.Helper()
+	h := &Handler{}
+	var q common.SelectQuery = database.NewBunAdapter(db).NewSelect().Model(&[]*joinProvince{})
+	if withJoin {
+		q = q.Join(joinSQL)
+	}
+	q = h.applyFilters(q, filters, &joinProvince{}, alias)
+	return q.Count(context.Background())
+}
+
+func TestFilters_AmbiguousColumnWithJoin_RealQuery(t *testing.T) {
+	db := setupJoinDB(t)
+
+	filters := []common.FilterOption{
+		{Column: "name", Operator: "like", Value: "%abc%"},
+		{Column: "abbreviation", Operator: "like", Value: "%abc%", LogicOperator: "OR"},
+	}
+
+	t.Run("unqualified with join is ambiguous (the bug)", func(t *testing.T) {
+		_, err := countWith(t, db, true, filters, "")
+		if err == nil || !strings.Contains(strings.ToLower(err.Error()), "ambiguous") {
+			t.Fatalf("expected ambiguous column error, got %v", err)
+		}
+	})
+
+	t.Run("qualified with join", func(t *testing.T) {
+		n, err := countWith(t, db, true, filters, "province_state")
+		if err != nil {
+			t.Fatal(err)
+		}
+		if n != 2 {
+			t.Fatalf("count = %d, want 2", n)
+		}
+	})
+
+	t.Run("qualified without join", func(t *testing.T) {
+		n, err := countWith(t, db, false, filters, "province_state")
+		if err != nil {
+			t.Fatal(err)
+		}
+		if n != 2 {
+			t.Fatalf("count = %d, want 2", n)
+		}
+	})
+
+	t.Run("unqualified without join still works", func(t *testing.T) {
+		n, err := countWith(t, db, false, filters, "")
+		if err != nil {
+			t.Fatal(err)
+		}
+		if n != 2 {
+			t.Fatalf("count = %d, want 2", n)
+		}
+	})
+}
+
+func TestFilters_AllOperatorsWithJoin_RealQuery(t *testing.T) {
+	db := setupJoinDB(t)
+	cases := []struct {
+		name   string
+		filter common.FilterOption
+		want   int
+	}{
+		{"eq", common.FilterOption{Column: "name", Operator: "eq", Value: "nope"}, 1},
+		{"neq", common.FilterOption{Column: "name", Operator: "neq", Value: "nope"}, 2},
+		{"like", common.FilterOption{Column: "name", Operator: "like", Value: "abc%"}, 1},
+		{"in", common.FilterOption{Column: "name", Operator: "in", Value: []string{"nope", "xyz two"}}, 2},
+		{"gt", common.FilterOption{Column: "id", Operator: "gt", Value: 1}, 2},
+		{"gte", common.FilterOption{Column: "id", Operator: "gte", Value: 2}, 2},
+		{"lt", common.FilterOption{Column: "id", Operator: "lt", Value: 3}, 2},
+		{"lte", common.FilterOption{Column: "id", Operator: "lte", Value: 1}, 1},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			n, err := countWith(t, db, true, []common.FilterOption{c.filter}, "province_state")
+			if err != nil {
+				t.Fatal(err)
+			}
+			if n != c.want {
+				t.Fatalf("count = %d, want %d", n, c.want)
+			}
+		})
+	}
+}
+
+// A filter on the joined table's own column, sent already qualified, must pass through untouched.
+func TestFilters_JoinedTableColumnPassesThrough_RealQuery(t *testing.T) {
+	db := setupJoinDB(t)
+	n, err := countWith(t, db, true, []common.FilterOption{
+		{Column: "rel_rid_country.name", Operator: "eq", Value: "Abcland"},
+	}, "province_state")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if n != 2 {
+		t.Fatalf("count = %d, want 2", n)
+	}
+}
+
+// Client sends "province_state.name": it must survive validation and be applied.
+func TestFilters_ClientQualifiedColumn_NotDropped(t *testing.T) {
+	db := setupJoinDB(t)
+	model := &joinProvince{}
+
+	opts := common.RequestOptions{Filters: []common.FilterOption{
+		{Column: "province_state.name", Operator: "like", Value: "%abc%"},
+	}}
+	common.NormalizeMainTableFilters(model, "public.province_state", &opts)
+	opts = common.NewColumnValidator(model).FilterRequestOptions(opts)
+	if len(opts.Filters) != 1 {
+		t.Fatalf("filter was dropped: %+v", opts.Filters)
+	}
+
+	n, err := countWith(t, db, true, opts.Filters, "province_state")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if n != 1 {
+		t.Fatalf("count = %d, want 1 (filter must narrow the result)", n)
+	}
+}

pkg/resolvespec/filter_qualify_test.go

@@ -0,0 +1,65 @@
+package resolvespec
+
+import (
+	"testing"
+
+	"github.com/bitechdev/ResolveSpec/pkg/common"
+)
+
+func TestBuildFilterConditionAlias_QualifiesModelColumns(t *testing.T) {
+	h := &Handler{}
+	model := jsonColModel{}
+
+	tests := []struct {
+		name   string
+		filter common.FilterOption
+		want   string
+	}{
+		{"eq", common.FilterOption{Column: "name", Operator: "eq", Value: "x"}, `"province_state"."name" = ?`},
+		{"ilike", common.FilterOption{Column: "name", Operator: "ilike", Value: "%a%"}, `CAST("province_state"."name" AS TEXT) ILIKE ?`},
+		{"like", common.FilterOption{Column: "name", Operator: "like", Value: "%a%"}, `CAST("province_state"."name" AS TEXT) LIKE ?`},
+		{"in", common.FilterOption{Column: "name", Operator: "in", Value: []string{"a", "b"}}, `"province_state"."name" IN (?,?)`},
+		{"non-model column untouched", common.FilterOption{Column: "other", Operator: "eq", Value: 1}, `other = ?`},
+		{"already qualified untouched", common.FilterOption{Column: "rel.name", Operator: "eq", Value: 1}, `rel.name = ?`},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, _ := h.buildFilterConditionAlias(tt.filter, model, "province_state")
+			if got != tt.want {
+				t.Fatalf("got %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestBuildFilterConditionAlias_NoAliasUnchanged(t *testing.T) {
+	h := &Handler{}
+	got, _ := h.buildFilterConditionAlias(common.FilterOption{Column: "name", Operator: "ilike", Value: "%a%"}, jsonColModel{}, "")
+	if got != "CAST(name AS TEXT) ILIKE ?" {
+		t.Fatalf("got %q", got)
+	}
+}
+
+func TestApplyFilter_QualifiesWithAlias(t *testing.T) {
+	h := &Handler{}
+	q := &jsonCapQuery{}
+	h.applyFilter(q, common.FilterOption{Column: "name", Operator: "ilike", Value: "%a%"}, jsonColModel{}, "province_state")
+	c := q.only(t)
+	if c.query != `CAST("province_state"."name" AS TEXT) ILIKE ?` {
+		t.Fatalf("query = %q", c.query)
+	}
+}
+
+func TestApplyFilters_OrGroupQualified(t *testing.T) {
+	h := &Handler{}
+	q := &jsonCapQuery{}
+	h.applyFilters(q, []common.FilterOption{
+		{Column: "name", Operator: "ilike", Value: "%a%"},
+		{Column: "id", Operator: "eq", Value: 1, LogicOperator: "OR"},
+	}, jsonColModel{}, "t")
+	c := q.only(t)
+	want := `(CAST("t"."name" AS TEXT) ILIKE ? OR "t"."id" = ?)`
+	if c.query != want {
+		t.Fatalf("query = %q, want %q", c.query, want)
+	}
+}

pkg/resolvespec/handler.go

@@ -172,6 +172,9 @@ func (h *Handler) Handle(w common.ResponseWriter, r common.Request, params map[s
 	// Add request-scoped data to context
 	ctx = WithRequestData(ctx, schema, entity, tableName, model, modelPtr)
 
+	// Accept "<main table or alias>.<column>" for model columns before validation drops them
+	common.NormalizeMainTableFilters(model, tableName, &req.Options)
+
 	// Validate and filter columns in options (log warnings for invalid columns)
 	validator := common.NewColumnValidator(model)
 	req.Options = validator.FilterRequestOptions(req.Options)
@@ -411,7 +414,7 @@ func (h *Handler) handleRead(ctx context.Context, w common.ResponseWriter, id st
 		}
 
 		// Apply filters with proper grouping for OR logic
-		query = h.applyFilters(query, options.Filters, model)
+		query = h.applyFilters(query, options.Filters, model, common.MainTableAlias(model, tableName))
 
 		// Apply custom operators
 		for _, customOp := range options.CustomOperators {
@@ -558,7 +561,7 @@ func (h *Handler) handleRead(ctx context.Context, w common.ResponseWriter, id st
 
 			// Apply the same filters as the main query
 			for _, filter := range options.Filters {
-				rowNumQuery = h.applyFilter(rowNumQuery, filter, model)
+				rowNumQuery = h.applyFilter(rowNumQuery, filter, model, common.MainTableAlias(model, tableName))
 			}
 
 			// Apply custom operators
@@ -1932,7 +1935,7 @@ func (h *Handler) executeDelete(ctx context.Context, tx common.Database, hookCtx
 // applyFilters applies all filters with proper grouping for OR logic
 // Groups consecutive OR filters together to ensure proper query precedence
 // Example: [A, B(OR), C(OR), D(AND)] => WHERE (A OR B OR C) AND D
-func (h *Handler) applyFilters(query common.SelectQuery, filters []common.FilterOption, model interface{}) common.SelectQuery {
+func (h *Handler) applyFilters(query common.SelectQuery, filters []common.FilterOption, model interface{}, alias string) common.SelectQuery {
 	if len(filters) == 0 {
 		return query
 	}
@@ -1952,11 +1955,11 @@ func (h *Handler) applyFilters(query common.SelectQuery, filters []common.Filter
 			}
 
 			// Apply the OR group as a single grouped WHERE clause
-			query = h.applyFilterGroup(query, orGroup, model)
+			query = h.applyFilterGroup(query, orGroup, model, alias)
 			i = j
 		} else {
 			// Single filter with AND logic (or first filter)
-			condition, args := h.buildFilterCondition(filters[i], model)
+			condition, args := h.buildFilterConditionAlias(filters[i], model, alias)
 			if condition != "" {
 				query = query.Where(condition, args...)
 			}
@@ -1969,7 +1972,7 @@ func (h *Handler) applyFilters(query common.SelectQuery, filters []common.Filter
 
 // applyFilterGroup applies a group of filters that should be OR'd together
 // Always wraps them in parentheses and applies as a single WHERE clause
-func (h *Handler) applyFilterGroup(query common.SelectQuery, filters []common.FilterOption, model interface{}) common.SelectQuery {
+func (h *Handler) applyFilterGroup(query common.SelectQuery, filters []common.FilterOption, model interface{}, alias string) common.SelectQuery {
 	if len(filters) == 0 {
 		return query
 	}
@@ -1979,7 +1982,7 @@ func (h *Handler) applyFilterGroup(query common.SelectQuery, filters []common.Fi
 	var args []interface{}
 
 	for _, filter := range filters {
-		condition, filterArgs := h.buildFilterCondition(filter, model)
+		condition, filterArgs := h.buildFilterConditionAlias(filter, model, alias)
 		if condition != "" {
 			conditions = append(conditions, condition)
 			args = append(args, filterArgs...)
@@ -2005,6 +2008,12 @@ func (h *Handler) applyFilterGroup(query common.SelectQuery, filters []common.Fi
 // or the dotted data.x shorthand for a JSON column) resolve to a safe,
 // parameterised expression before the ordinary operator handling below.
 func (h *Handler) buildFilterCondition(filter common.FilterOption, model interface{}) (conditionString string, conditionArgs []interface{}) {
+	return h.buildFilterConditionAlias(filter, model, "")
+}
+
+// buildFilterConditionAlias is buildFilterCondition with plain model columns
+// qualified by the main table alias, so joins from preloads can't make them ambiguous.
+func (h *Handler) buildFilterConditionAlias(filter common.FilterOption, model interface{}, alias string) (conditionString string, conditionArgs []interface{}) {
 	var condition string
 	var args []interface{}
 
@@ -2012,6 +2021,9 @@ func (h *Handler) buildFilterCondition(filter common.FilterOption, model interfa
 		return cond, jargs
 	}
 
+	rawColumn := filter.Column
+	filter.Column = common.QualifyModelColumn(model, alias, filter.Column)
+
 	switch filter.Operator {
 	case "eq", "=":
 		condition = fmt.Sprintf("%s = ?", filter.Column)
@@ -2032,10 +2044,10 @@ func (h *Handler) buildFilterCondition(filter common.FilterOption, model interfa
 		condition = fmt.Sprintf("%s <= ?", filter.Column)
 		args = []interface{}{filter.Value}
 	case "like":
-		condition = fmt.Sprintf("%s LIKE ?", likeColumn(filter.Column, model))
+		condition = fmt.Sprintf("%s LIKE ?", likeColumn(filter.Column, rawColumn, model))
 		args = []interface{}{filter.Value}
 	case "ilike":
-		condition = fmt.Sprintf("%s ILIKE ?", likeColumn(filter.Column, model))
+		condition = fmt.Sprintf("%s ILIKE ?", likeColumn(filter.Column, rawColumn, model))
 		args = []interface{}{filter.Value}
 	case "in":
 		condition, args = common.BuildInCondition(filter.Column, filter.Value)
@@ -2073,14 +2085,14 @@ func (h *Handler) buildFilterCondition(filter common.FilterOption, model interfa
 // CAST(... AS TEXT) would switch to case-sensitive matching and defeat a
 // citext index. Every other column is cast to TEXT so LIKE/ILIKE also works
 // against date/time/timestamp and numeric columns.
-func likeColumn(column string, model interface{}) string {
-	if reflection.IsCitextColumn(model, column) {
+func likeColumn(column, rawColumn string, model interface{}) string {
+	if reflection.IsCitextColumn(model, rawColumn) {
 		return column
 	}
 	return fmt.Sprintf("CAST(%s AS TEXT)", column)
 }
 
-func (h *Handler) applyFilter(query common.SelectQuery, filter common.FilterOption, model interface{}) common.SelectQuery {
+func (h *Handler) applyFilter(query common.SelectQuery, filter common.FilterOption, model interface{}, alias string) common.SelectQuery {
 	// Determine which method to use based on LogicOperator
 	useOrLogic := strings.EqualFold(filter.LogicOperator, "OR")
 
@@ -2094,6 +2106,9 @@ func (h *Handler) applyFilter(query common.SelectQuery, filter common.FilterOpti
 		return query.Where(cond, jargs...)
 	}
 
+	rawColumn := filter.Column
+	filter.Column = common.QualifyModelColumn(model, alias, filter.Column)
+
 	switch filter.Operator {
 	case "eq", "=":
 		condition = fmt.Sprintf("%s = ?", filter.Column)
@@ -2114,10 +2129,10 @@ func (h *Handler) applyFilter(query common.SelectQuery, filter common.FilterOpti
 		condition = fmt.Sprintf("%s <= ?", filter.Column)
 		args = []interface{}{filter.Value}
 	case "like":
-		condition = fmt.Sprintf("%s LIKE ?", likeColumn(filter.Column, model))
+		condition = fmt.Sprintf("%s LIKE ?", likeColumn(filter.Column, rawColumn, model))
 		args = []interface{}{filter.Value}
 	case "ilike":
-		condition = fmt.Sprintf("%s ILIKE ?", likeColumn(filter.Column, model))
+		condition = fmt.Sprintf("%s ILIKE ?", likeColumn(filter.Column, rawColumn, model))
 		args = []interface{}{filter.Value}
 	case "in":
 		condition, args = common.BuildInCondition(filter.Column, filter.Value)
@@ -2523,7 +2538,7 @@ func (h *Handler) applyPreloads(model interface{}, query common.SelectQuery, pre
 
 			if len(preload.Filters) > 0 {
 				for _, filter := range preload.Filters {
-					sq = h.applyFilter(sq, filter, nil)
+					sq = h.applyFilter(sq, filter, nil, "")
 				}
 			}
 			if len(preload.Sort) > 0 {

pkg/resolvespec/integration_test.go

@@ -1,3 +1,4 @@
+//go:build integration
 // +build integration
 
 package resolvespec
@@ -22,12 +23,12 @@ import (
 
 // Test models
 type TestUser struct {
-	ID        uint      `gorm:"primaryKey" json:"id"`
-	Name      string    `gorm:"not null" json:"name"`
-	Email     string    `gorm:"uniqueIndex;not null" json:"email"`
-	Age       int       `json:"age"`
-	Active    bool      `gorm:"default:true" json:"active"`
-	CreatedAt time.Time `json:"created_at"`
+	ID        uint       `gorm:"primaryKey" json:"id"`
+	Name      string     `gorm:"not null" json:"name"`
+	Email     string     `gorm:"uniqueIndex;not null" json:"email"`
+	Age       int        `json:"age"`
+	Active    bool       `gorm:"default:true" json:"active"`
+	CreatedAt time.Time  `json:"created_at"`
 	Posts     []TestPost `gorm:"foreignKey:UserID" json:"posts,omitempty"`
 }
 
@@ -36,13 +37,13 @@ func (TestUser) TableName() string {
 }
 
 type TestPost struct {
-	ID        uint      `gorm:"primaryKey" json:"id"`
-	UserID    uint      `gorm:"not null" json:"user_id"`
-	Title     string    `gorm:"not null" json:"title"`
-	Content   string    `json:"content"`
-	Published bool      `gorm:"default:false" json:"published"`
-	CreatedAt time.Time `json:"created_at"`
-	User      *TestUser  `gorm:"foreignKey:UserID" json:"user,omitempty"`
+	ID        uint          `gorm:"primaryKey" json:"id"`
+	UserID    uint          `gorm:"not null" json:"user_id"`
+	Title     string        `gorm:"not null" json:"title"`
+	Content   string        `json:"content"`
+	Published bool          `gorm:"default:false" json:"published"`
+	CreatedAt time.Time     `json:"created_at"`
+	User      *TestUser     `gorm:"foreignKey:UserID" json:"user,omitempty"`
 	Comments  []TestComment `gorm:"foreignKey:PostID" json:"comments,omitempty"`
 }
 
@@ -55,7 +56,7 @@ type TestComment struct {
 	PostID    uint      `gorm:"not null" json:"post_id"`
 	Content   string    `gorm:"not null" json:"content"`
 	CreatedAt time.Time `json:"created_at"`
-	Post      *TestPost  `gorm:"foreignKey:PostID" json:"post,omitempty"`
+	Post      *TestPost `gorm:"foreignKey:PostID" json:"post,omitempty"`
 }
 
 func (TestComment) TableName() string {

pkg/resolvespec/json_column_test.go

@@ -142,7 +142,7 @@ func TestApplyFilter_JSONColumn(t *testing.T) {
 	q := &jsonCapQuery{}
 	h.applyFilter(q, common.FilterOption{
 		Column: "data->>'tier'", Operator: "in", Value: []string{"a", "b"}, LogicOperator: "OR",
-	}, model)
+	}, model, "")
 	c := q.only(t)
 	if c.method != "WhereOr" || c.query != `("data" #>> ?::text[]) IN (?,?)` {
 		t.Fatalf("call = %+v", c)

pkg/restheadspec/filter_join_sqlite_test.go

@@ -0,0 +1,180 @@
+package restheadspec
+
+import (
+	"context"
+	"database/sql"
+	"testing"
+
+	"github.com/uptrace/bun"
+	"github.com/uptrace/bun/dialect/sqlitedialect"
+	"github.com/uptrace/bun/driver/sqliteshim"
+
+	"github.com/bitechdev/ResolveSpec/pkg/common"
+	"github.com/bitechdev/ResolveSpec/pkg/common/adapters/database"
+)
+
+type joinCountry struct {
+	bun.BaseModel `bun:"table:country,alias:country"`
+	ID            int64  `bun:"id,pk"`
+	Name          string `bun:"name"`
+}
+
+type joinProvince struct {
+	bun.BaseModel `bun:"table:province_state,alias:province_state"`
+	ID            int64  `bun:"id,pk"`
+	Name          string `bun:"name"`
+	Abbreviation  string `bun:"abbreviation"`
+	RidCountry    int64  `bun:"rid_country"`
+}
+
+func setupJoinDB(t *testing.T) *bun.DB {
+	t.Helper()
+	sqldb, err := sql.Open(sqliteshim.ShimName, "file:rhsfilterjoin?mode=memory&cache=private")
+	if err != nil {
+		t.Fatal(err)
+	}
+	db := bun.NewDB(sqldb, sqlitedialect.New())
+	t.Cleanup(func() { _ = db.Close() })
+	ctx := context.Background()
+	for _, m := range []interface{}{(*joinCountry)(nil), (*joinProvince)(nil)} {
+		if _, err := db.NewCreateTable().Model(m).IfNotExists().Exec(ctx); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if _, err := db.NewInsert().Model(&[]joinCountry{{ID: 1, Name: "Abcland"}, {ID: 2, Name: "Other"}}).Exec(ctx); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := db.NewInsert().Model(&[]joinProvince{
+		{ID: 1, Name: "abc one", Abbreviation: "A1", RidCountry: 1},
+		{ID: 2, Name: "xyz two", Abbreviation: "ABC", RidCountry: 1},
+		{ID: 3, Name: "nope", Abbreviation: "N3", RidCountry: 2},
+	}).Exec(ctx); err != nil {
+		t.Fatal(err)
+	}
+	return db
+}
+
+const joinSQL = "LEFT JOIN country AS rel_rid_country ON rel_rid_country.id = province_state.rid_country"
+
+// countFilters applies filters the way handleRead does (single AND filters via
+// applyFilter, consecutive OR filters via applyOrFilterGroup) and counts.
+func countFilters(t *testing.T, db *bun.DB, withJoin bool, filters []common.FilterOption) (int, error) {
+	t.Helper()
+	h := &Handler{}
+	model := &joinProvince{}
+	var q common.SelectQuery = database.NewBunAdapter(db).NewSelect().Model(&[]*joinProvince{})
+	if withJoin {
+		q = q.Join(joinSQL)
+	}
+	for i := 0; i < len(filters); {
+		f := filters[i]
+		castInfo := h.ValidateAndAdjustFilterForColumnType(&f, model)
+		if f.LogicOperator == "OR" {
+			group := []*common.FilterOption{&f}
+			info := []ColumnCastInfo{castInfo}
+			j := i + 1
+			for j < len(filters) && filters[j].LogicOperator == "OR" {
+				g := filters[j]
+				info = append(info, h.ValidateAndAdjustFilterForColumnType(&g, model))
+				group = append(group, &g)
+				j++
+			}
+			q = h.applyOrFilterGroup(q, group, info, "public.province_state", model)
+			i = j
+			continue
+		}
+		q = h.applyFilter(q, f, "public.province_state", castInfo.NeedsCast, "AND", model)
+		i++
+	}
+	return q.Count(context.Background())
+}
+
+func TestRHSFilters_WithAndWithoutJoin_RealQuery(t *testing.T) {
+	db := setupJoinDB(t)
+	cases := []struct {
+		name    string
+		filters []common.FilterOption
+		want    int
+	}{
+		{"eq", []common.FilterOption{{Column: "name", Operator: "eq", Value: "nope"}}, 1},
+		{"neq", []common.FilterOption{{Column: "name", Operator: "neq", Value: "nope"}}, 2},
+		{"like", []common.FilterOption{{Column: "name", Operator: "like", Value: "%abc%"}}, 1},
+		{"in", []common.FilterOption{{Column: "name", Operator: "in", Value: []string{"nope", "xyz two"}}}, 2},
+		{"gt", []common.FilterOption{{Column: "id", Operator: "gt", Value: 1}}, 2},
+		{"between", []common.FilterOption{{Column: "id", Operator: "between", Value: []interface{}{0, 3}}}, 2},
+		{"between_inclusive", []common.FilterOption{{Column: "id", Operator: "between_inclusive", Value: []interface{}{1, 3}}}, 3},
+		{"is_not_null", []common.FilterOption{{Column: "name", Operator: "is_not_null"}}, 3},
+		{"or group", []common.FilterOption{
+			{Column: "name", Operator: "like", Value: "%abc%", LogicOperator: "OR"},
+			{Column: "abbreviation", Operator: "like", Value: "%abc%", LogicOperator: "OR"},
+		}, 2},
+		{"or group then and", []common.FilterOption{
+			{Column: "name", Operator: "like", Value: "%abc%", LogicOperator: "OR"},
+			{Column: "abbreviation", Operator: "like", Value: "%abc%", LogicOperator: "OR"},
+			{Column: "id", Operator: "eq", Value: 2},
+		}, 1},
+	}
+	for _, c := range cases {
+		for _, withJoin := range []bool{false, true} {
+			name := c.name + "/no_join"
+			if withJoin {
+				name = c.name + "/join"
+			}
+			t.Run(name, func(t *testing.T) {
+				n, err := countFilters(t, db, withJoin, c.filters)
+				if err != nil {
+					t.Fatalf("query failed (ambiguous column?): %v", err)
+				}
+				if n != c.want {
+					t.Fatalf("count = %d, want %d", n, c.want)
+				}
+			})
+		}
+	}
+}
+
+func TestRHSFilters_JoinedTableColumnPassesThrough(t *testing.T) {
+	db := setupJoinDB(t)
+	n, err := countFilters(t, db, true, []common.FilterOption{
+		{Column: "rel_rid_country.name", Operator: "eq", Value: "Abcland"},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if n != 2 {
+		t.Fatalf("count = %d, want 2", n)
+	}
+}
+
+// Client sends "province_state.name": it must survive validation and be applied.
+func TestRHSFilters_ClientQualifiedColumn_NotDropped(t *testing.T) {
+	db := setupJoinDB(t)
+	h := &Handler{}
+	model := &joinProvince{}
+
+	opts := ExtendedRequestOptions{}
+	opts.Filters = []common.FilterOption{{Column: "province_state.name", Operator: "like", Value: "%abc%"}}
+	common.NormalizeMainTableFilters(model, "public.province_state", &opts.RequestOptions)
+	opts = h.filterExtendedOptions(common.NewColumnValidator(model), opts, model)
+	if len(opts.Filters) != 1 || opts.Filters[0].Column != "name" {
+		t.Fatalf("filter was dropped or not normalised: %+v", opts.Filters)
+	}
+
+	n, err := countFilters(t, db, true, opts.Filters)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if n != 1 {
+		t.Fatalf("count = %d, want 1", n)
+	}
+}
+
+func TestRHSFilters_ILikeSQLQualified(t *testing.T) {
+	h := &Handler{}
+	q := &jsonCapQuery{}
+	f := common.FilterOption{Column: "name", Operator: "ilike", Value: "%abc%"}
+	h.applyFilter(q, f, "info.province_state", false, "AND", jsonColModel{})
+	if got := q.only(t).query; got != "CAST(province_state.name AS TEXT) ILIKE ?" {
+		t.Fatalf("query = %q", got)
+	}
+}

pkg/restheadspec/handler.go

@@ -164,6 +164,9 @@ func (h *Handler) Handle(w common.ResponseWriter, r common.Request, params map[s
 	// Parse options from headers - this now includes relation name resolution
 	options := h.parseOptionsFromHeaders(r, model)
 
+	// Accept "<main table or alias>.<column>" for model columns before validation drops them
+	common.NormalizeMainTableFilters(model, tableName, &options.RequestOptions)
+
 	// Validate and filter columns in options (log warnings for invalid columns)
 	validator := common.NewColumnValidator(model)
 	options = h.filterExtendedOptions(validator, options, model)