Merge pull request #44 from okfn/refactor-module-to-results

Rename module: responses -> results

Author: pdelboca

README.md

@@ -129,6 +129,34 @@ npx @modelcontextprotocol/inspector
 
 7. Navigate to the MCP Inspector webpage and connect to `http://127.0.0.1:8063` (no `/mcp`) using `Streamable HTTP` transport type
 
+## Tool return values
+
+Using the `python-sdk` cannonical way of building results (this is, the `CallToolResult` object) can get quite verbose quite fast. For
+that reason, the `mcp_server` provides an optional set of functions to use.
+
+The two following tools and return values are possible:
+
+```python
+@registry.tool()
+def hello_world() -> DataToolOutput:
+    """Return a hello world value. """
+    source = "https://example.org/link/to/data"
+    return CallToolResult(
+        content=[TextContent(type="text", text="Hello world!!")],
+        structuredContent={"sources": [source]},
+    )
+```
+
+```python
+from mcp_server.results import text_result
+
+@registry.tool()
+def hello_world() -> DataToolOutput:
+    """Return a hello world value. """
+    source = "https://example.org/link/to/data"
+    return text_result("Hello world!!", source=source)
+```
+
 ## DataToolOutput
 
 This MCP Server uses a `DataToolOutput` annotation and a `ValidationModel` to enforce a standardized contract between plugins and the server. The schema is still in development so changes are expected.

src/mcp_server/engines/aggregate_engine.py

@@ -45,7 +45,7 @@
 
 from mcp_server import DataToolOutput
 from mcp_server.engines.filters import build_filter_params, apply_filters, build_filter_doc
-from mcp_server.responses import text_result, force_result
+from mcp_server.results import text_result, force_result
 
 
 AGGREGATIONS = {

src/mcp_server/engines/row_list_engine.py

@@ -55,7 +55,7 @@
 import pandas as pd
 from mcp_server import DataToolOutput
 from mcp_server.engines.filters import build_filter_params, apply_filters, build_filter_doc
-from mcp_server.responses import text_result, force_result
+from mcp_server.results import text_result, force_result
 
 
 def load_row_list_dataset(mcp, config, yaml_path):

src/mcp_server/engines/top_row_engine.py

@@ -56,7 +56,7 @@
 
 from mcp_server import DataToolOutput
 from mcp_server.engines.filters import build_filter_params, apply_filters, build_filter_doc
-from mcp_server.responses import text_result, force_result
+from mcp_server.results import text_result, force_result
 
 
 def load_top_row_dataset(mcp, config, yaml_path):

src/mcp_server/engines/unique_values_engine.py

@@ -41,7 +41,7 @@
 
 from mcp_server import DataToolOutput
 from mcp_server.engines.filters import build_filter_params, apply_filters, build_filter_doc
-from mcp_server.responses import text_result
+from mcp_server.results import text_result
 
 
 def load_unique_values_dataset(mcp, config, yaml_path):