chore(deps): pin dependencies

Document the reference column filter support feature.

.github/workflows/build.yaml

@@ -21,7 +21,7 @@ jobs:
         uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
 
       - name: Log in to Container Registry
-        uses: docker/login-action@v3
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
@@ -29,7 +29,7 @@ jobs:
 
       - name: Extract metadata for Docker
         id: meta
-        uses: docker/metadata-action@v5
+        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           tags: |
@@ -38,10 +38,10 @@ jobs:
             type=raw,value=latest,enable=${{ !contains(github.ref, '-alpha') && !contains(github.ref, '-beta') && !contains(github.ref, '-rc') }}
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
 
       - name: Build and push Docker image
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6
         with:
           context: .
           push: true

CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.1] - 2026-01-14
+
+### Added
+
+#### Reference Column Filter Support
+- **Filter normalization**: `get_records` now automatically normalizes filter values to array format
+- Fixes 400 errors when filtering on `Ref:*` (reference/foreign key) columns
+- Single values are wrapped in arrays before sending to Grist API
+
+#### Usage
+```python
+# Before: Failed with 400 Bad Request
+get_records(document="accounting", table="TransactionLines", filter={"Transaction": 44})
+
+# After: Works - filter normalized to {"Transaction": [44]}
+get_records(document="accounting", table="TransactionLines", filter={"Transaction": 44})
+
+# Multiple values also supported
+get_records(document="accounting", table="TransactionLines", filter={"Transaction": [44, 45, 46]})
+```
+
+### Fixed
+- Shell script shebangs updated to `#!/usr/bin/env bash` for portability across environments
+
 ## [1.4.0] - 2026-01-12
 
 ### Added

Dockerfile

@@ -1,8 +1,8 @@
 # Stage 1: Builder
-FROM python:3.14-slim AS builder
+FROM python:3.14-slim@sha256:9b81fe9acff79e61affb44aaf3b6ff234392e8ca477cb86c9f7fd11732ce9b6a AS builder
 
 # Install uv
-COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+COPY --from=ghcr.io/astral-sh/uv:latest@sha256:9a23023be68b2ed09750ae636228e903a54a05ea56ed03a934d00fe9fbeded4b /uv /usr/local/bin/uv
 
 WORKDIR /app
 
@@ -20,7 +20,7 @@ RUN uv sync --frozen --no-dev
 
 
 # Stage 2: Runtime
-FROM python:3.14-slim
+FROM python:3.14-slim@sha256:9b81fe9acff79e61affb44aaf3b6ff234392e8ca477cb86c9f7fd11732ce9b6a
 
 # Create non-root user
 RUN useradd --create-home --shell /bin/bash appuser

deploy/prod/docker-compose.yml

@@ -1,7 +1,7 @@
 # Production environment
 services:
   grist-mcp:
-    image: ghcr.io/xe138/grist-mcp-server:latest
+    image: ghcr.io/xe138/grist-mcp-server:latest@sha256:f7e1463b319c398c39be4444ac73a7426849e3edfddf2f0510c9cea61495db01
     ports:
       - "${PORT:-3000}:3000"
     volumes:

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "grist-mcp"
-version = "1.4.0"
+version = "1.4.1"
 description = "MCP server for AI agents to interact with Grist documents"
 requires-python = ">=3.14"
 dependencies = [

scripts/get-test-instance-id.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # scripts/get-test-instance-id.sh
 # Generate a unique instance ID from git branch for parallel test isolation
 

scripts/run-integration-tests.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # scripts/run-integration-tests.sh
 # Run integration tests with branch isolation and dynamic port discovery
 set -e

src/grist_mcp/tools/filters.py

@@ -0,0 +1,37 @@
+"""Filter normalization for Grist API queries."""
+
+from typing import Any
+
+
+def normalize_filter_value(value: Any) -> list:
+    """Ensure a filter value is a list.
+
+    Grist API expects filter values to be arrays.
+
+    Args:
+        value: Single value or list of values.
+
+    Returns:
+        Value wrapped in list, or original list if already a list.
+    """
+    if isinstance(value, list):
+        return value
+    return [value]
+
+
+def normalize_filter(filter: dict | None) -> dict | None:
+    """Normalize filter values to array format for Grist API.
+
+    Grist expects all filter values to be arrays. This function
+    wraps single values in lists.
+
+    Args:
+        filter: Filter dict with column names as keys.
+
+    Returns:
+        Normalized filter dict, or None if input was None.
+    """
+    if not filter:
+        return filter
+
+    return {key: normalize_filter_value(value) for key, value in filter.items()}

src/grist_mcp/tools/read.py

@@ -2,6 +2,7 @@
 
 from grist_mcp.auth import Agent, Authenticator, Permission
 from grist_mcp.grist_client import GristClient
+from grist_mcp.tools.filters import normalize_filter
 
 
 async def list_tables(
@@ -56,7 +57,10 @@ async def get_records(
         doc = auth.get_document(document)
         client = GristClient(doc)
 
-    records = await client.get_records(table, filter=filter, sort=sort, limit=limit)
+    # Normalize filter values to array format for Grist API
+    normalized_filter = normalize_filter(filter)
+
+    records = await client.get_records(table, filter=normalized_filter, sort=sort, limit=limit)
     return {"records": records}
 
 

tests/integration/mock_grist/Dockerfile

@@ -1,4 +1,4 @@
-FROM python:3.14-slim
+FROM python:3.14-slim@sha256:9b81fe9acff79e61affb44aaf3b6ff234392e8ca477cb86c9f7fd11732ce9b6a
 
 WORKDIR /app
 

tests/integration/mock_grist/server.py

@@ -35,6 +35,18 @@ MOCK_TABLES = {
             {"id": 2, "fields": {"Title": "Deploy", "Done": False}},
         ],
     },
+    "Orders": {
+        "columns": [
+            {"id": "OrderNum", "fields": {"type": "Int"}},
+            {"id": "Customer", "fields": {"type": "Ref:People"}},
+            {"id": "Amount", "fields": {"type": "Numeric"}},
+        ],
+        "records": [
+            {"id": 1, "fields": {"OrderNum": 1001, "Customer": 1, "Amount": 100.0}},
+            {"id": 2, "fields": {"OrderNum": 1002, "Customer": 2, "Amount": 200.0}},
+            {"id": 3, "fields": {"OrderNum": 1003, "Customer": 1, "Amount": 150.0}},
+        ],
+    },
 }
 
 # Track requests for test assertions
@@ -93,12 +105,40 @@ async def get_records(request):
     """GET /api/docs/{doc_id}/tables/{table_id}/records"""
     doc_id = request.path_params["doc_id"]
     table_id = request.path_params["table_id"]
-    log_request("GET", f"/api/docs/{doc_id}/tables/{table_id}/records")
+    filter_param = request.query_params.get("filter")
+    log_request("GET", f"/api/docs/{doc_id}/tables/{table_id}/records?filter={filter_param}")
 
     if table_id not in MOCK_TABLES:
         return JSONResponse({"error": "Table not found"}, status_code=404)
 
-    return JSONResponse({"records": MOCK_TABLES[table_id]["records"]})
+    records = MOCK_TABLES[table_id]["records"]
+
+    # Apply filtering if provided
+    if filter_param:
+        try:
+            filters = json.loads(filter_param)
+            # Validate filter format: all values must be arrays (Grist API requirement)
+            for key, values in filters.items():
+                if not isinstance(values, list):
+                    return JSONResponse(
+                        {"error": f"Filter values must be arrays, got {type(values).__name__} for '{key}'"},
+                        status_code=400
+                    )
+            # Apply filters: record matches if field value is in the filter list
+            filtered_records = []
+            for record in records:
+                match = True
+                for key, allowed_values in filters.items():
+                    if record["fields"].get(key) not in allowed_values:
+                        match = False
+                        break
+                if match:
+                    filtered_records.append(record)
+            records = filtered_records
+        except json.JSONDecodeError:
+            return JSONResponse({"error": "Invalid filter JSON"}, status_code=400)
+
+    return JSONResponse({"records": records})
 
 
 async def add_records(request):

tests/integration/test_tools_integration.py

@@ -90,6 +90,36 @@ async def test_all_tools(services_ready):
         log = get_mock_request_log()
         assert any("/records" in entry["path"] and entry["method"] == "GET" for entry in log)
 
+        # Test get_records with Ref column filter
+        # This tests that single values are normalized to arrays for the Grist API
+        clear_mock_request_log()
+        result = await client.call_tool(
+            "get_records",
+            {"document": "test-doc", "table": "Orders", "filter": {"Customer": 1}}
+        )
+        data = json.loads(result.content[0].text)
+        assert "records" in data
+        # Should return only orders for Customer 1 (orders 1 and 3)
+        assert len(data["records"]) == 2
+        for record in data["records"]:
+            assert record["Customer"] == 1
+        log = get_mock_request_log()
+        # Verify the filter was sent as array format
+        filter_requests = [e for e in log if "/records" in e["path"] and "filter=" in e["path"]]
+        assert len(filter_requests) >= 1
+        # The filter value should be [1] not 1
+        assert "[1]" in filter_requests[0]["path"]
+
+        # Test get_records with multiple filter values
+        clear_mock_request_log()
+        result = await client.call_tool(
+            "get_records",
+            {"document": "test-doc", "table": "Orders", "filter": {"Customer": [1, 2]}}
+        )
+        data = json.loads(result.content[0].text)
+        assert "records" in data
+        assert len(data["records"]) == 3  # All 3 orders (customers 1 and 2)
+
         # Test sql_query
         clear_mock_request_log()
         result = await client.call_tool(

tests/unit/test_filters.py

@@ -0,0 +1,89 @@
+"""Unit tests for filter normalization."""
+
+import pytest
+
+from grist_mcp.tools.filters import normalize_filter, normalize_filter_value
+
+
+class TestNormalizeFilterValue:
+    """Tests for normalize_filter_value function."""
+
+    def test_int_becomes_list(self):
+        assert normalize_filter_value(5) == [5]
+
+    def test_string_becomes_list(self):
+        assert normalize_filter_value("foo") == ["foo"]
+
+    def test_float_becomes_list(self):
+        assert normalize_filter_value(3.14) == [3.14]
+
+    def test_list_unchanged(self):
+        assert normalize_filter_value([1, 2, 3]) == [1, 2, 3]
+
+    def test_empty_list_unchanged(self):
+        assert normalize_filter_value([]) == []
+
+    def test_single_item_list_unchanged(self):
+        assert normalize_filter_value([42]) == [42]
+
+    def test_mixed_type_list_unchanged(self):
+        assert normalize_filter_value([1, "foo", 3.14]) == [1, "foo", 3.14]
+
+
+class TestNormalizeFilter:
+    """Tests for normalize_filter function."""
+
+    def test_none_returns_none(self):
+        assert normalize_filter(None) is None
+
+    def test_empty_dict_returns_empty_dict(self):
+        assert normalize_filter({}) == {}
+
+    def test_single_int_value_wrapped(self):
+        result = normalize_filter({"Transaction": 44})
+        assert result == {"Transaction": [44]}
+
+    def test_single_string_value_wrapped(self):
+        result = normalize_filter({"Status": "active"})
+        assert result == {"Status": ["active"]}
+
+    def test_list_value_unchanged(self):
+        result = normalize_filter({"Transaction": [44, 45, 46]})
+        assert result == {"Transaction": [44, 45, 46]}
+
+    def test_mixed_columns_all_normalized(self):
+        """Both ref and non-ref columns are normalized to arrays."""
+        result = normalize_filter({
+            "Transaction": 44,  # Ref column (int)
+            "Debit": 500,       # Non-ref column (int)
+            "Memo": "test",     # Non-ref column (str)
+        })
+        assert result == {
+            "Transaction": [44],
+            "Debit": [500],
+            "Memo": ["test"],
+        }
+
+    def test_multiple_values_list_unchanged(self):
+        """Filter with multiple values passes through."""
+        result = normalize_filter({
+            "Status": ["pending", "active"],
+            "Priority": [1, 2, 3],
+        })
+        assert result == {
+            "Status": ["pending", "active"],
+            "Priority": [1, 2, 3],
+        }
+
+    def test_mixed_single_and_list_values(self):
+        """Mix of single values and lists."""
+        result = normalize_filter({
+            "Transaction": 44,            # Single int
+            "Status": ["open", "closed"],  # List
+            "Amount": 100.50,             # Single float
+        })
+        assert result == {
+            "Transaction": [44],
+            "Status": ["open", "closed"],
+            "Amount": [100.50],
+        }

tests/unit/test_tools_read.py

@@ -75,6 +75,45 @@ async def test_get_records(agent, auth, mock_client):
     assert result == {"records": [{"id": 1, "Name": "Alice"}]}
 
 
+@pytest.mark.asyncio
+async def test_get_records_normalizes_filter(agent, auth, mock_client):
+    """Test that filter values are normalized to array format for Grist API."""
+    mock_client.get_records.return_value = [{"id": 1, "Customer": 5}]
+
+    await get_records(
+        agent, auth, "budget", "Orders",
+        filter={"Customer": 5, "Status": "active"},
+        client=mock_client,
+    )
+
+    # Verify filter was normalized: single values wrapped in lists
+    mock_client.get_records.assert_called_once_with(
+        "Orders",
+        filter={"Customer": [5], "Status": ["active"]},
+        sort=None,
+        limit=None,
+    )
+
+
+@pytest.mark.asyncio
+async def test_get_records_preserves_list_filter(agent, auth, mock_client):
+    """Test that filter values already in list format are preserved."""
+    mock_client.get_records.return_value = []
+
+    await get_records(
+        agent, auth, "budget", "Orders",
+        filter={"Customer": [5, 6, 7]},
+        client=mock_client,
+    )
+
+    mock_client.get_records.assert_called_once_with(
+        "Orders",
+        filter={"Customer": [5, 6, 7]},
+        sort=None,
+        limit=None,
+    )
+
+
 @pytest.mark.asyncio
 async def test_sql_query(agent, auth, mock_client):
     result = await sql_query(agent, auth, "budget", "SELECT * FROM Table1", client=mock_client)

uv.lock

@@ -153,7 +153,7 @@ wheels = [
 
 [[package]]
 name = "grist-mcp"
-version = "1.3.0"
+version = "1.4.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },