fairspec-mcp-server 0.3.0__tar.gz

fairspec_mcp_server-0.3.0/.gitignore

@@ -0,0 +1,239 @@
+# Git worktrees (agent isolation)
+/.worktrees/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer,
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Node
+node_modules/
+jspm_packages/
+.lock-wscript
+build/Release
+.node_repl_history
+*.tgz
+.npm
+*.so
+
+# Livemark
+.livemark/build/
+.tanstack/
+.content-collections/
+
+# User
+/.claude/
+/.cursor/
+/coverage.json

fairspec_mcp_server-0.3.0/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.5
+Name: fairspec-mcp-server
+Version: 0.3.0
+Summary: Fairspec Python is a fast data management framework built on top of the Fairspec standard and Polars DataFrames
+Project-URL: homepage, https://fairspec.org/python/
+Project-URL: repository, https://github.com/datisthq/fairspec
+Author: Evgeny Karev
+License-Expression: MIT
+Keywords: ai,data,dataframe,fair,fairspec,jsonschema,llm,mcp,polars,python,quality,tableschema,validation
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: fairspec-library
+Requires-Dist: mcp>=2.3
+Description-Content-Type: text/markdown
+
+# fairspec-mcp-server
+
+Fairspec Python is a fast data management framework built on top of the Fairspec standard and Polars DataFrames. It supports various formats like CSV, JSON, and Parquet and integrates with data platforms such as CKAN, Zenodo, and GitHub. For more information, please read the [project's documentation](https://fairspec.org/python/).

fairspec_mcp_server-0.3.0/README.md

@@ -0,0 +1,3 @@
+# fairspec-mcp-server
+
+Fairspec Python is a fast data management framework built on top of the Fairspec standard and Polars DataFrames. It supports various formats like CSV, JSON, and Parquet and integrates with data platforms such as CKAN, Zenodo, and GitHub. For more information, please read the [project's documentation](https://fairspec.org/python/).

fairspec_mcp_server-0.3.0/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-0.3.0/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-0.3.0/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-0.3.0/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-0.3.0/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-0.3.0/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-0.3.0/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-0.3.0/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-0.3.0/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-0.3.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-0.3.0/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-0.3.0/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