fairspec-mcp-server 0.3.0__py3-none-any.whl

fairspec_mcp_server/__init__.py

@@ -0,0 +1,2 @@
+from .server import server as server
+from .server import start_server as start_server

fairspec_mcp_server/_test/server_unit.py

@@ -0,0 +1,93 @@
+import pytest
+from fairspec_library import write_temp_file
+from mcp import Client
+
+from ..server import server
+
+pytestmark = pytest.mark.anyio
+
+
+@pytest.fixture
+def anyio_backend():
+    return "asyncio"
+
+
+class TestServer:
+    async def test_should_list_tools_with_typescript_names(self):
+        async with Client(server) as client:
+            result = await client.list_tools()
+
+        assert sorted(tool.name for tool in result.tools) == sorted(
+            [
+                "inferDataSchemaTool",
+                "inferDatasetTool",
+                "inferFileDialectTool",
+                "inferTableSchemaTool",
+                "previewFileTool",
+                "queryDatasetTool",
+                "queryTableTool",
+                "validateDataSchemaTool",
+                "validateDatasetTool",
+                "validateDataTool",
+                "validateTableSchemaTool",
+                "validateTableTool",
+            ]
+        )
+        for tool in result.tools:
+            assert tool.description
+            assert tool.output_schema
+
+    async def test_should_call_tool_with_structured_output(self, capfd):
+        path = write_temp_file("id,name\n1,alice\n2,bob\n", format="csv")
+
+        async with Client(server) as client:
+            result = await client.call_tool(
+                "inferTableSchemaTool", {"resource": {"data": path}}
+            )
+
+        assert not result.is_error
+        assert capfd.readouterr().out == ""
+        assert result.structured_content == {
+            "tableSchema": {
+                "properties": {"id": {"type": "integer"}, "name": {"type": "string"}}
+            }
+        }
+
+    async def test_should_report_tool_failure_as_error(self):
+        async with Client(server) as client:
+            result = await client.call_tool(
+                "queryTableTool", {"resource": {}, "query": "SELECT * FROM self"}
+            )
+
+        assert result.is_error
+
+    async def test_should_report_real_message_of_failed_query(self):
+        path = write_temp_file("id,name\n1,alice\n", format="csv")
+
+        async with Client(server) as client:
+            result = await client.call_tool(
+                "queryTableTool",
+                {"resource": {"data": path}, "query": "SELEC nonsense"},
+            )
+
+        assert result.is_error
+        assert "sql" in str(result.content).lower()
+
+    async def test_should_report_real_message_of_missing_file(self):
+        async with Client(server) as client:
+            result = await client.call_tool(
+                "validateDatasetTool", {"source": "missing/dataset.json"}
+            )
+
+        assert result.is_error
+        assert "missing" in str(result.content)
+
+    async def test_should_reject_response_over_budget(self):
+        async with Client(server) as client:
+            result = await client.call_tool(
+                "inferDatasetTool",
+                {"dataset": {"resources": [{"data": [{"text": "x" * 60_000}]}]}},
+            )
+
+        assert result.is_error
+        assert "exceeds 50000 characters" in str(result.content)

fairspec_mcp_server/_test/start_unit.py

@@ -0,0 +1,29 @@
+from unittest.mock import patch
+
+import pytest
+from fairspec_library import get_host_policy, set_host_policy
+
+from ..server import start_server
+
+
+@pytest.fixture(autouse=True)
+def reset_host_policy(monkeypatch):
+    monkeypatch.delenv("FAIRSPEC_HOST_POLICY", raising=False)
+    yield
+    set_host_policy(None)
+
+
+class TestStartServer:
+    def test_should_block_non_public_hosts_by_default(self):
+        with patch("fairspec_mcp_server.server.server.run") as run:
+            start_server()
+
+        run.assert_called_once_with("stdio")
+        assert get_host_policy() == "public"
+
+    def test_should_keep_host_policy_from_env(self, monkeypatch):
+        monkeypatch.setenv("FAIRSPEC_HOST_POLICY", "any")
+        with patch("fairspec_mcp_server.server.server.run"):
+            start_server()
+
+        assert get_host_policy() == "any"

fairspec_mcp_server/helpers/limit.py

@@ -0,0 +1,34 @@
+from collections.abc import Sequence
+
+from fairspec_library import Report
+from pydantic_core import to_json
+
+DEFAULT_LIMIT = 100
+MAX_LIMIT = 1000
+MAX_RESPONSE_CHARS = 50_000
+
+# room for the object a trimmed list is wrapped in
+MAX_ITEMS_CHARS = MAX_RESPONSE_CHARS - 1_000
+
+
+def limit_items[T](items: Sequence[T], *, limit: int) -> tuple[list[T], bool]:
+    """Cut a list to `limit` items, then to as many as fit the response budget.
+
+    Pass one item more than the limit to learn whether the list was truncated.
+    """
+    chars = 0
+    count = 0
+    for item in items[:limit]:
+        chars += len(to_json(item, by_alias=True, exclude_none=True)) + 1
+        if chars > MAX_ITEMS_CHARS:
+            break
+        count += 1
+
+    return list(items[:count]), count < len(items)
+
+
+def limit_report(report: Report, *, max_errors: int | None) -> tuple[Report, bool]:
+    """Cut a report's errors to `max_errors`, then to the response budget."""
+    limit = max_errors if max_errors is not None else DEFAULT_LIMIT
+    errors, truncated = limit_items(report.errors, limit=limit)
+    return Report(valid=report.valid, errors=errors), truncated

fairspec_mcp_server/helpers/tool.py

@@ -0,0 +1,38 @@
+import functools
+from collections.abc import Callable
+
+from mcp.server.mcpserver.exceptions import ToolError
+from mcp.shared.exceptions import MCPError
+from mcp.types import CallToolResult, TextContent
+
+from ..models.tool import ToolResult
+from .limit import MAX_RESPONSE_CHARS
+
+
+def guard_tool[**P](tool: Callable[P, ToolResult]) -> Callable[P, CallToolResult]:
+    """Pass a tool's failure to the client with its message, and cap its response size."""
+
+    # MCPServer reads the signature through `__wrapped__`, so the schemas stay the tool's
+    @functools.wraps(tool)
+    def guarded_tool(*args: P.args, **kwargs: P.kwargs) -> CallToolResult:
+        try:
+            result = tool(*args, **kwargs)
+        except (ToolError, MCPError):
+            raise
+        except Exception as exc:
+            # The SDK hides the message of anything but a ToolError
+            raise ToolError(str(exc)) from exc
+
+        text = result.model_dump_json(by_alias=True)
+        if len(text) > MAX_RESPONSE_CHARS:
+            raise ToolError(
+                f"The response exceeds {MAX_RESPONSE_CHARS} characters; narrow the input"
+            )
+
+        # The SDK would indent the text copy, doubling its size against the budget
+        return CallToolResult(
+            content=[TextContent(type="text", text=text)],
+            structured_content=result.model_dump(mode="json", by_alias=True),
+        )
+
+    return guarded_tool

fairspec_mcp_server/models/tool.py

@@ -0,0 +1,15 @@
+from fairspec_library import FairspecModel
+from pydantic import SerializationInfo, SerializerFunctionWrapHandler, model_serializer
+
+
+class ToolResult(FairspecModel):
+    """The structured output of a tool, serialized without unset optional fields."""
+
+    # mcp dumps tool output without exclude_none, so every unset field would reach the client as null
+    @model_serializer(mode="wrap")
+    def serialize_tool_result(
+        self, handler: SerializerFunctionWrapHandler, info: SerializationInfo
+    ):
+        if info.exclude_none:
+            return handler(self)
+        return self.model_dump(mode=info.mode, by_alias=info.by_alias, exclude_none=True)

fairspec_mcp_server/server.py

@@ -0,0 +1,41 @@
+import os
+from importlib.metadata import version
+
+from fairspec_library import set_host_policy
+from mcp.server.mcpserver import MCPServer
+
+from .helpers.tool import guard_tool
+from .tools.data.validate import validate_data_tool
+from .tools.data_schema.infer import infer_data_schema_tool
+from .tools.data_schema.validate import validate_data_schema_tool
+from .tools.dataset.infer import infer_dataset_tool
+from .tools.dataset.query import query_dataset_tool
+from .tools.dataset.validate import validate_dataset_tool
+from .tools.file.preview import preview_file_tool
+from .tools.file_dialect.infer import infer_file_dialect_tool
+from .tools.table.query import query_table_tool
+from .tools.table.validate import validate_table_tool
+from .tools.table_schema.infer import infer_table_schema_tool
+from .tools.table_schema.validate import validate_table_schema_tool
+
+server = MCPServer(name="fairspec", version=version("fairspec-mcp-server"))
+
+server.add_tool(guard_tool(infer_data_schema_tool), name="inferDataSchemaTool")
+server.add_tool(guard_tool(infer_dataset_tool), name="inferDatasetTool")
+server.add_tool(guard_tool(infer_file_dialect_tool), name="inferFileDialectTool")
+server.add_tool(guard_tool(infer_table_schema_tool), name="inferTableSchemaTool")
+server.add_tool(guard_tool(preview_file_tool), name="previewFileTool")
+server.add_tool(guard_tool(query_dataset_tool), name="queryDatasetTool")
+server.add_tool(guard_tool(query_table_tool), name="queryTableTool")
+server.add_tool(guard_tool(validate_data_schema_tool), name="validateDataSchemaTool")
+server.add_tool(guard_tool(validate_dataset_tool), name="validateDatasetTool")
+server.add_tool(guard_tool(validate_data_tool), name="validateDataTool")
+server.add_tool(guard_tool(validate_table_schema_tool), name="validateTableSchemaTool")
+server.add_tool(guard_tool(validate_table_tool), name="validateTableTool")
+
+
+def start_server() -> None:
+    """Serve over stdio; remote fetches reach only public hosts unless FAIRSPEC_HOST_POLICY is set."""
+    if not os.environ.get("FAIRSPEC_HOST_POLICY"):
+        set_host_policy("public")
+    server.run("stdio")

fairspec_mcp_server/tools/_shared/schemas.py

@@ -0,0 +1,20 @@
+from typing import Annotated
+
+from pydantic import Field
+
+from ...helpers.limit import DEFAULT_LIMIT, MAX_LIMIT
+
+# Tool parameters carry their wire name (`maxErrors`): the SDK passes an alias as the
+# keyword, so a snake_case parameter cannot be aliased to match the TypeScript server
+MaxErrors = Annotated[
+    int | None,
+    Field(
+        ge=1,
+        le=MAX_LIMIT,
+        description=f"Maximum number of errors to return (default {DEFAULT_LIMIT})",
+    ),
+]
+
+Truncated = Annotated[
+    bool, Field(description="Whether errors were left out of the report")
+]

fairspec_mcp_server/tools/data/_test/validate_unit.py

@@ -0,0 +1,26 @@
+from fairspec_library import Resource
+
+from ..validate import validate_data_tool
+
+
+class TestValidateDataTool:
+    def test_should_validate_data_against_schema(self):
+        resource = Resource(
+            data={"name": "alice"},
+            dataSchema={"type": "object", "properties": {"name": {"type": "string"}}},
+        )
+
+        result = validate_data_tool(resource)
+
+        assert result.report.valid is True
+
+    def test_should_detect_invalid_data(self):
+        resource = Resource(
+            data={"name": 1},
+            dataSchema={"type": "object", "properties": {"name": {"type": "string"}}},
+        )
+
+        result = validate_data_tool(resource)
+
+        assert result.report.valid is False
+        assert len(result.report.errors) > 0

fairspec_mcp_server/tools/data/validate.py

@@ -0,0 +1,22 @@
+from typing import Annotated
+
+from fairspec_library import Report, Resource, validate_data
+from pydantic import Field
+
+from ...helpers.limit import limit_report
+from ...models.tool import ToolResult
+from .._shared.schemas import MaxErrors, Truncated
+
+
+class ValidateDataResult(ToolResult):
+    report: Report
+    truncated: Truncated
+
+
+def validate_data_tool(
+    resource: Annotated[Resource, Field(description="The data resource to validate")],
+    maxErrors: MaxErrors = None,
+) -> ValidateDataResult:
+    """Validate data against a data schema (JSON Schema). Returns a validation report with errors if any."""
+    report, truncated = limit_report(validate_data(resource), max_errors=maxErrors)
+    return ValidateDataResult(report=report, truncated=truncated)

fairspec_mcp_server/tools/data_schema/_test/infer_unit.py

@@ -0,0 +1,20 @@
+from fairspec_library import Resource
+
+from ..infer import infer_data_schema_tool
+
+
+class TestInferDataSchemaTool:
+    def test_should_infer_schema_from_inline_data(self):
+        resource = Resource(data={"name": "alice", "age": 25})
+
+        result = infer_data_schema_tool(resource)
+
+        assert result.dataSchema is not None
+        assert result.dataSchema["type"] == "object"
+        assert set(result.dataSchema["properties"]) == {"name", "age"}
+
+    def test_should_return_none_for_resource_without_data(self):
+        result = infer_data_schema_tool(Resource())
+
+        assert result.dataSchema is None
+        assert result.model_dump(mode="json", by_alias=True) == {}

fairspec_mcp_server/tools/data_schema/_test/validate_unit.py

@@ -0,0 +1,31 @@
+import json
+
+from fairspec_library import Report, write_temp_file
+
+from ..validate import validate_data_schema_tool
+
+
+class TestValidateDataSchemaTool:
+    def test_should_validate_valid_descriptor(self):
+        result = validate_data_schema_tool({"type": "object"})
+
+        assert result.report.valid is True
+        assert result.report.errors == []
+
+    def test_should_detect_invalid_descriptor(self):
+        result = validate_data_schema_tool({"type": 123})
+
+        assert result.report.valid is False
+        assert len(result.report.errors) > 0
+
+    def test_should_validate_descriptor_from_path(self):
+        path = write_temp_file(json.dumps({"type": "object"}), format="json")
+
+        result = validate_data_schema_tool(path)
+
+        assert result.report.valid is True
+
+    def test_should_return_plain_report(self):
+        result = validate_data_schema_tool({"type": "object"})
+
+        assert type(result.report) is Report

fairspec_mcp_server/tools/data_schema/infer.py

@@ -0,0 +1,19 @@
+from typing import Annotated
+
+from fairspec_library import DataSchema, Resource, infer_data_schema
+from pydantic import Field
+
+from ...models.tool import ToolResult
+
+
+class InferDataSchemaResult(ToolResult):
+    dataSchema: DataSchema | None = None
+
+
+def infer_data_schema_tool(
+    resource: Annotated[
+        Resource, Field(description="The data resource to infer schema from")
+    ],
+) -> InferDataSchemaResult:
+    """Infer a data schema (JSON Schema) from data. Analyzes the data structure to determine types and properties."""
+    return InferDataSchemaResult(dataSchema=infer_data_schema(resource))

fairspec_mcp_server/tools/data_schema/validate.py

@@ -0,0 +1,25 @@
+from typing import Annotated
+
+from fairspec_library import Descriptor, Report, validate_data_schema
+from pydantic import Field
+
+from ...helpers.limit import limit_report
+from ...models.tool import ToolResult
+from .._shared.schemas import MaxErrors, Truncated
+
+
+class ValidateDataSchemaResult(ToolResult):
+    report: Report
+    truncated: Truncated
+
+
+def validate_data_schema_tool(
+    source: Annotated[
+        Descriptor | str,
+        Field(description="The data schema to validate (descriptor object or file path)"),
+    ],
+    maxErrors: MaxErrors = None,
+) -> ValidateDataSchemaResult:
+    """Validate a data schema (JSON Schema) against the Fairspec Data Schema specification. Returns validation report with errors if any."""
+    report, truncated = limit_report(validate_data_schema(source), max_errors=maxErrors)
+    return ValidateDataSchemaResult(report=report, truncated=truncated)

fairspec_mcp_server/tools/dataset/_test/infer_unit.py

@@ -0,0 +1,23 @@
+from fairspec_library import Dataset, Resource, write_temp_file
+
+from ..infer import infer_dataset_tool
+
+
+class TestInferDatasetTool:
+    def test_should_infer_resource_metadata(self):
+        path = write_temp_file("id,name\n1,alice\n2,bob\n", format="csv")
+        dataset = Dataset(resources=[Resource(data=path)])
+
+        result = infer_dataset_tool(dataset)
+
+        assert result.dataset.resources
+        resource = result.dataset.resources[0]
+        assert resource.fileDialect is not None
+        assert resource.tableSchema is not None
+
+    def test_should_preserve_dataset_metadata(self):
+        dataset = Dataset(version="1.0.0", resources=[])
+
+        result = infer_dataset_tool(dataset)
+
+        assert result.dataset.version == "1.0.0"

fairspec_mcp_server/tools/dataset/_test/query_unit.py

@@ -0,0 +1,39 @@
+from fairspec_library import Dataset
+
+from ..query import query_dataset_tool
+
+
+class TestQueryDatasetTool:
+    def test_should_join_two_resources_by_name(self):
+        source = Dataset.model_validate(
+            {
+                "resources": [
+                    {
+                        "name": "users",
+                        "data": [{"id": 1, "name": "alice"}, {"id": 2, "name": "bob"}],
+                    },
+                    {
+                        "name": "posts",
+                        "data": [{"id": 1, "user_id": 2}, {"id": 2, "user_id": 2}],
+                    },
+                ]
+            }
+        )
+
+        result = query_dataset_tool(
+            source,
+            "SELECT users.name, COUNT(*) AS n FROM posts "
+            "JOIN users ON posts.user_id = users.id GROUP BY users.name",
+        )
+
+        assert result.records == [{"name": "bob", "n": 2}]
+
+    def test_should_return_at_most_limit_records(self):
+        source = Dataset.model_validate(
+            {"resources": [{"name": "items", "data": [{"id": i} for i in range(10)]}]}
+        )
+
+        result = query_dataset_tool(source, "SELECT * FROM items", limit=5)
+
+        assert len(result.records) == 5
+        assert result.truncated is True

fairspec_mcp_server/tools/dataset/_test/validate_unit.py

@@ -0,0 +1,53 @@
+import json
+
+from fairspec_library import Dataset, Resource, TableSchema, write_temp_file
+
+from ..validate import validate_dataset_tool
+
+
+class TestValidateDatasetTool:
+    def test_should_validate_valid_dataset(self):
+        dataset = Dataset(
+            resources=[
+                Resource(
+                    name="people",
+                    data=[{"id": 1}, {"id": 2}],
+                    tableSchema=TableSchema.model_validate(
+                        {"properties": {"id": {"type": "integer"}}}
+                    ),
+                )
+            ]
+        )
+
+        result = validate_dataset_tool(dataset)
+
+        assert result.report.valid is True
+        assert result.report.errors == []
+
+    def test_should_detect_invalid_resource_data(self):
+        dataset = Dataset(
+            resources=[
+                Resource(
+                    name="people",
+                    data=[{"id": "one"}],
+                    tableSchema=TableSchema.model_validate(
+                        {"properties": {"id": {"type": "integer"}}}
+                    ),
+                )
+            ]
+        )
+
+        result = validate_dataset_tool(dataset)
+
+        assert result.report.valid is False
+        assert len(result.report.errors) > 0
+
+    def test_should_validate_dataset_from_path(self):
+        path = write_temp_file(
+            json.dumps({"resources": [{"name": "people", "data": [{"id": 1}]}]}),
+            format="json",
+        )
+
+        result = validate_dataset_tool(path)
+
+        assert result.report.valid is True

fairspec_mcp_server/tools/dataset/infer.py

@@ -0,0 +1,17 @@
+from typing import Annotated
+
+from fairspec_library import Dataset, infer_dataset
+from pydantic import Field
+
+from ...models.tool import ToolResult
+
+
+class InferDatasetResult(ToolResult):
+    dataset: Dataset
+
+
+def infer_dataset_tool(
+    dataset: Annotated[Dataset, Field(description="The dataset to infer metadata for")],
+) -> InferDatasetResult:
+    """Infer metadata for all resources in a dataset. Analyzes each resource to determine schemas and dialects."""
+    return InferDatasetResult(dataset=infer_dataset(dataset))

fairspec_mcp_server/tools/dataset/query.py

@@ -0,0 +1,38 @@
+import json
+from typing import Annotated
+
+import polars as pl
+from fairspec_library import Dataset, query_dataset
+from pydantic import Field, JsonValue
+
+from ...helpers.limit import DEFAULT_LIMIT, MAX_LIMIT, limit_items
+from ...models.tool import ToolResult
+
+
+class QueryDatasetResult(ToolResult):
+    records: list[dict[str, JsonValue]]
+    truncated: Annotated[bool, Field(description="Whether records were left out")]
+
+
+def query_dataset_tool(
+    source: Annotated[
+        Dataset | str,
+        Field(description="The dataset to query (dataset object or file path)"),
+    ],
+    query: Annotated[
+        str, Field(description="SQL query to execute (use resource names as table names)")
+    ],
+    limit: Annotated[
+        int,
+        Field(
+            ge=1,
+            le=MAX_LIMIT,
+            description=f"Maximum number of records to return (default {DEFAULT_LIMIT})",
+        ),
+    ] = DEFAULT_LIMIT,
+) -> QueryDatasetResult:
+    """Query a dataset using SQL. Each table resource is available under its name, so a query can join several resources. Returns the results as an array of records. Returns at most `limit` records; `truncated` is true when more were left out."""
+    frame = query_dataset(source, query).head(limit + 1).collect()
+    assert isinstance(frame, pl.DataFrame)
+    records, truncated = limit_items(json.loads(frame.write_json()), limit=limit)
+    return QueryDatasetResult(records=records, truncated=truncated)

fairspec_mcp_server/tools/dataset/validate.py

@@ -0,0 +1,25 @@
+from typing import Annotated
+
+from fairspec_library import Dataset, Report, validate_dataset
+from pydantic import Field
+
+from ...helpers.limit import limit_report
+from ...models.tool import ToolResult
+from .._shared.schemas import MaxErrors, Truncated
+
+
+class ValidateDatasetResult(ToolResult):
+    report: Report
+    truncated: Truncated
+
+
+def validate_dataset_tool(
+    source: Annotated[
+        Dataset | str,
+        Field(description="The dataset to validate (dataset object or file path)"),
+    ],
+    maxErrors: MaxErrors = None,
+) -> ValidateDatasetResult:
+    """Validate a dataset including all its resources and foreign keys. Returns a validation report with errors if any."""
+    report, truncated = limit_report(validate_dataset(source), max_errors=maxErrors)
+    return ValidateDatasetResult(report=report, truncated=truncated)