codeocean-mcp-server 0.7.2__tar.gz → 0.8.0__tar.gz

{codeocean_mcp_server-0.7.2 → codeocean_mcp_server-0.8.0}/CHANGELOG.md

@@ -1,6 +1,10 @@
 CHANGELOG
 =========
 
+## 0.8.0 (2026-01-27)
+
+- [#24](https://github.com/codeocean/codeocean-mcp-server/pull/24) feat: Token efficient search responses
+
 ## 0.7.2 (2025-12-27)
 
 - [#20](https://github.com/codeocean/codeocean-mcp-server/pull/20) feat: custom log formatting

{codeocean_mcp_server-0.7.2 → codeocean_mcp_server-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeocean-mcp-server
-Version: 0.7.2
+Version: 0.8.0
 Summary: Code Ocean MCP Server
 Project-URL: Homepage, https://github.com/codeocean/codeocean-mcp-server
 Project-URL: Issues, https://github.com/codeocean/codeocean-mcp-server/issues

{codeocean_mcp_server-0.7.2 → codeocean_mcp_server-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codeocean-mcp-server"
-version = "0.7.2"
+version = "0.8.0"
 authors = [{ name = "Code Ocean", email = "dev@codeocean.com" }]
 description = "Code Ocean MCP Server"
 readme = "README.md"
@@ -66,3 +66,5 @@ filterwarnings = [
   "ignore:datetime.datetime.utcnow() is deprecated:DeprecationWarning:botocore.auth",
   "ignore::DeprecationWarning:botocore.*",
 ]
+markers = ["integration: requires external services (AWS/Bedrock)"]
+asyncio_mode = "strict"

codeocean_mcp_server-0.8.0/src/codeocean_mcp_server/search.py

@@ -0,0 +1,136 @@
+import re
+from typing import Any, ClassVar, Optional
+
+from pydantic import BaseModel
+
+# Constants
+MAX_DESCRIPTION_LENGTH = 200
+MAX_TAGS_COUNT = 10
+TRUNCATION_SUFFIX = "...(more)"
+TAGS_TRUNCATION_MARKER = "..more.."
+
+
+def truncate_description(description: Optional[str], max_length: int = MAX_DESCRIPTION_LENGTH) -> Optional[str]:
+    """Truncate description with word-boundary-aware cutting."""
+    if not description:
+        return None
+
+    # Light whitespace normalization: collapse 3+ consecutive whitespace to single space.
+    normalized = re.sub(r"\s{3,}", " ", description).strip()
+    if not normalized:
+        return None
+
+    if len(normalized) <= max_length:
+        return normalized
+
+    truncate_at = max_length - len(TRUNCATION_SUFFIX)
+    if truncate_at <= 0:
+        return TRUNCATION_SUFFIX[:max_length]
+
+    last_space = normalized.rfind(" ", 0, truncate_at)
+    cut_at = last_space if last_space > max_length // 2 else truncate_at
+    return normalized[:cut_at].rstrip() + TRUNCATION_SUFFIX
+
+
+def limit_tags(tags: Optional[list[str]], max_count: int = MAX_TAGS_COUNT) -> list[str]:
+    """Limit tags to maximum count with truncation marker."""
+    if not tags:
+        return []
+
+    if len(tags) <= max_count:
+        return list(tags)
+
+    return list(tags[: max_count - 1]) + [TAGS_TRUNCATION_MARKER]
+
+
+class CompactCapsuleItem(BaseModel):
+    """Compact capsule/pipeline item (id kept, other fields shortened)."""
+
+    id: str
+    n: str
+    s: str
+    d: Optional[str] = None
+    t: list[str]
+
+
+class CompactDataAssetItem(BaseModel):
+    """Compact data asset item (id kept, other fields shortened)."""
+
+    id: str
+    n: str
+    d: Optional[str] = None
+    t: list[str]
+
+
+class SearchMeta(BaseModel):
+    """Base model providing search metadata fields."""
+
+    has_more: bool
+    next_token: Optional[str] = None
+    item_count: int
+    field_names: Optional[dict[str, str]] = None
+
+
+class CapsuleSearchResults(SearchMeta):
+    """Compact results: {items: [{id, n, s, d, t}], has_more, next_token, total_count}.
+
+    Fields: id=id, n=name, s=slug, d=description (truncated), t=tags (limited).
+    Set include_field_names=true to add field_names with full labels.
+    Use get_capsule(id) if full details needed.
+    """
+
+    items: list[CompactCapsuleItem]
+    FIELD_NAMES: ClassVar[dict[str, str]] = {"id": "id", "n": "name", "s": "slug", "d": "description", "t": "tags"}
+
+    @classmethod
+    def from_sdk_results(cls, sdk_results: Any, include_field_names: bool = False) -> "CapsuleSearchResults":
+        """Convert SDK search results to compact format."""
+        items = [
+            CompactCapsuleItem(
+                id=c.id,
+                n=c.name,
+                s=c.slug,
+                d=truncate_description(c.description),
+                t=limit_tags(c.tags),
+            )
+            for c in sdk_results.results
+        ]
+        return cls(
+            items=items,
+            has_more=sdk_results.has_more,
+            next_token=getattr(sdk_results, "next_token", None),
+            item_count=len(items),
+            field_names=cls.FIELD_NAMES if include_field_names else None,
+        )
+
+
+class DataAssetSearchResults(SearchMeta):
+    """Compact results: {items: [{id, n, d, t}], has_more, next_token, total_count}.
+
+    Fields: id=id, n=name, d=description (truncated), t=tags (limited).
+    Set include_field_names=true to add field_names with full labels.
+    Use get_data_asset(id) if full details needed.
+    """
+
+    items: list[CompactDataAssetItem]
+    FIELD_NAMES: ClassVar[dict[str, str]] = {"id": "id", "n": "name", "d": "description", "t": "tags"}
+
+    @classmethod
+    def from_sdk_results(cls, sdk_results: Any, include_field_names: bool = False) -> "DataAssetSearchResults":
+        """Convert SDK search results to compact format."""
+        items = [
+            CompactDataAssetItem(
+                id=d.id,
+                n=d.name,
+                d=truncate_description(d.description),
+                t=limit_tags(d.tags),
+            )
+            for d in sdk_results.results
+        ]
+        return cls(
+            items=items,
+            has_more=sdk_results.has_more,
+            next_token=getattr(sdk_results, "next_token", None),
+            item_count=len(items),
+            field_names=cls.FIELD_NAMES if include_field_names else None,
+        )

{codeocean_mcp_server-0.7.2 → codeocean_mcp_server-0.8.0}/src/codeocean_mcp_server/tools/capsules.py

@@ -3,7 +3,6 @@ from codeocean.capsule import (
     AppPanel,
     Capsule,
     CapsuleSearchParams,
-    CapsuleSearchResults,
     Computation,
     DataAssetAttachParams,
     DataAssetAttachResults,
@@ -11,6 +10,7 @@ from codeocean.capsule import (
 from mcp.server.fastmcp import FastMCP
 
 from codeocean_mcp_server.models import dataclass_to_pydantic
+from codeocean_mcp_server.search import CapsuleSearchResults
 
 AppPanelModel = dataclass_to_pydantic(AppPanel)
 CapsuleSearchParamsModel = dataclass_to_pydantic(CapsuleSearchParams)
@@ -20,31 +20,25 @@ DataAssetAttachParamsModel = dataclass_to_pydantic(DataAssetAttachParams)
 def add_tools(mcp: FastMCP, client: CodeOcean):
     """Add capsule tools to the MCP server."""
 
-    @mcp.tool(
-        description=(
-            str(client.capsules.search_capsules.__doc__) + "Use only for capsule searches. "
-            "Provide only the minimal required parameters (e.g. limit=10); "
-            "do not include optional params "
-            "like sort_by or sort_order unless requested."
-        )
-    )
-    def search_capsules(search_params: CapsuleSearchParamsModel) -> CapsuleSearchResults:
+    @mcp.tool(description=(str(client.capsules.search_capsules.__doc__) + " " + str(CapsuleSearchResults.__doc__)))
+    def search_capsules(
+        search_params: CapsuleSearchParamsModel,
+        include_field_names: bool = False,
+    ) -> CapsuleSearchResults:
         """Search for capsules matching specified criteria."""
         params = CapsuleSearchParams(**search_params.model_dump(exclude_none=True))
-        return client.capsules.search_capsules(params)
+        results = client.capsules.search_capsules(params)
+        return CapsuleSearchResults.from_sdk_results(results, include_field_names)
 
-    @mcp.tool(
-        description=(
-            str(client.capsules.search_pipelines.__doc__) + "Use only for pipeline searches. "
-            "Provide only the minimal required parameters (e.g. limit=10); "
-            "do not include optional params "
-            "like sort_by or sort_order unless requested."
-        )
-    )
-    def search_pipelines(search_params: CapsuleSearchParamsModel) -> CapsuleSearchResults:
+    @mcp.tool(description=(str(client.capsules.search_pipelines.__doc__) + " " + str(CapsuleSearchResults.__doc__)))
+    def search_pipelines(
+        search_params: CapsuleSearchParamsModel,
+        include_field_names: bool = False,
+    ) -> CapsuleSearchResults:
         """Search for pipelines matching specified criteria."""
         params = CapsuleSearchParams(**search_params.model_dump(exclude_none=True))
-        return client.capsules.search_pipelines(params)
+        results = client.capsules.search_pipelines(params)
+        return CapsuleSearchResults.from_sdk_results(results, include_field_names)
 
     @mcp.tool(
         description=(

{codeocean_mcp_server-0.7.2 → codeocean_mcp_server-0.8.0}/src/codeocean_mcp_server/tools/data_assets.py

@@ -5,7 +5,6 @@ from codeocean.data_asset import (
     DataAsset,
     DataAssetParams,
     DataAssetSearchParams,
-    DataAssetSearchResults,
     DataAssetUpdateParams,
     FileURLs,
     Folder,
@@ -14,6 +13,7 @@ from mcp.server.fastmcp import FastMCP
 
 from codeocean_mcp_server.file_utils import download_and_read_file
 from codeocean_mcp_server.models import dataclass_to_pydantic
+from codeocean_mcp_server.search import DataAssetSearchResults
 
 DataAssetModel = dataclass_to_pydantic(DataAsset)
 DataAssetParamsModel = dataclass_to_pydantic(DataAssetParams)
@@ -25,17 +25,23 @@ def add_tools(mcp: FastMCP, client: CodeOcean):
     """Add data asset tools to the MCP server."""
 
     @mcp.tool(
-        description=(
-            str(client.data_assets.search_data_assets.__doc__)
-            + "Search for data assets (external or internal). You may filter by "
-            "fields such as `origin`, tags, or other criteria supported by the "
-            "SDK."
-        )
+        description=(str(client.data_assets.search_data_assets.__doc__) + " " + str(DataAssetSearchResults.__doc__))
     )
-    def search_data_assets(search_params: DataAssetSearchParamsModel) -> DataAssetSearchResults:
+    def search_data_assets(
+        search_params: DataAssetSearchParamsModel,
+        include_field_names: bool = False,
+    ) -> DataAssetSearchResults:
         """Retrieve data assets matching search criteria for datasets."""
         params = DataAssetSearchParams(**search_params.model_dump(exclude_none=True))
-        return client.data_assets.search_data_assets(params)
+        results = client.data_assets.search_data_assets(params)
+        return DataAssetSearchResults.from_sdk_results(results, include_field_names)
+
+    @mcp.tool(
+        description=("Get full details for a data asset by ID. Use after compact search to retrieve complete metadata.")
+    )
+    def get_data_asset(data_asset_id: str) -> DataAsset:
+        """Retrieve a data asset by its ID."""
+        return client.data_assets.get_data_asset(data_asset_id)
 
     @mcp.tool(
         description=(

{codeocean_mcp_server-0.7.2 → codeocean_mcp_server-0.8.0}/tests/bedrock_call.py

@@ -7,7 +7,15 @@ from bedrock_tools_converter import convert_tool_format
 
 BEDROCK_MODEL = os.getenv("BEDROCK_MODEL") or "amazon.nova-pro-v1:0"
 
-client = boto3.client("bedrock-runtime")
+_client = None
+
+
+def _get_client():
+    """Lazily initialize the Bedrock client."""
+    global _client
+    if _client is None:
+        _client = boto3.client("bedrock-runtime")
+    return _client
 
 
 def call_bedrock(
@@ -26,4 +34,4 @@ def call_bedrock(
     if tools is not None:
         payload["toolConfig"] = convert_tool_format(tools, model)
 
-    return client.converse(**payload)
+    return _get_client().converse(**payload)

codeocean_mcp_server-0.8.0/tests/conftest.py

@@ -0,0 +1,23 @@
+"""Pytest configuration for codeocean-mcp-server tests."""
+
+import pytest
+
+
+def pytest_addoption(parser):
+    """Add --integration flag to pytest."""
+    parser.addoption(
+        "--integration",
+        action="store_true",
+        default=False,
+        help="Run integration tests (requires AWS/Bedrock setup)",
+    )
+
+
+def pytest_collection_modifyitems(config, items):
+    """Skip integration tests unless --integration flag is passed."""
+    if config.getoption("--integration"):
+        return
+    skip_integration = pytest.mark.skip(reason="need --integration flag to run")
+    for item in items:
+        if "integration" in item.keywords:
+            item.add_marker(skip_integration)

{codeocean_mcp_server-0.7.2 → codeocean_mcp_server-0.8.0}/tests/test_multi_tool_calling.py

@@ -1,3 +1,4 @@
+import pytest
 from bedrock_call import call_bedrock
 from deepdiff import DeepDiff
 from mcp_client import get_tools
@@ -35,6 +36,7 @@ def check_diff(expected_response: dict, response: dict) -> None:
     assert not diff, f"tool_usage diverges from expected:\n\n-----\n{diff!r}\n------"
 
 
+@pytest.mark.integration
 def test_prompt_generates_correct_tool_usage_sequence(
     agentic_prompt_chain: dict = agentic_prompt_chain,
 ):

codeocean_mcp_server-0.8.0/tests/test_search.py

@@ -0,0 +1,275 @@
+"""Unit tests for search module."""
+
+from dataclasses import dataclass
+from typing import Optional
+
+from codeocean_mcp_server.search import (
+    TAGS_TRUNCATION_MARKER,
+    TRUNCATION_SUFFIX,
+    CapsuleSearchResults,
+    DataAssetSearchResults,
+    limit_tags,
+    truncate_description,
+)
+
+
+# Mock dataclasses for SDK results (private to avoid docstring lint rules)
+@dataclass
+class _MockCapsule:
+    id: str
+    name: str
+    slug: str
+    description: Optional[str]
+    tags: Optional[list[str]]
+
+
+@dataclass
+class _MockDataAsset:
+    id: str
+    name: str
+    description: Optional[str]
+    tags: Optional[list[str]]
+
+
+@dataclass
+class _MockCapsuleResults:
+    results: list[_MockCapsule]
+    has_more: bool
+    next_token: Optional[str] = None
+
+
+@dataclass
+class _MockDataAssetResults:
+    results: list[_MockDataAsset]
+    has_more: bool
+    next_token: Optional[str] = None
+
+
+class TestTruncateDescription:
+    """Tests for truncate_description function."""
+
+    def test_none_input(self):
+        """None input returns None."""
+        assert truncate_description(None) is None
+
+    def test_empty_string(self):
+        """Empty string input returns None."""
+        assert truncate_description("") is None
+
+    def test_whitespace_only(self):
+        """Whitespace-only input returns None."""
+        assert truncate_description("   ") is None
+
+    def test_short_description(self):
+        """Under 200 chars returns unchanged text."""
+        text = "This is a short description."
+        assert truncate_description(text) == text
+
+    def test_exact_length(self):
+        """Exactly 200 chars returns unchanged."""
+        text = "a" * 200
+        assert truncate_description(text) == text
+
+    def test_whitespace_preserved_single(self):
+        """Single newlines and spaces are preserved."""
+        text = "Line one\nLine two"
+        assert truncate_description(text) == text
+
+    def test_whitespace_collapsed_multiple(self):
+        """3+ consecutive whitespace chars are collapsed."""
+        text = "Word one   Word two"  # 3 spaces
+        assert truncate_description(text) == "Word one Word two"
+
+        text_newlines = "Line one\n\n\nLine two"  # 3 newlines
+        assert truncate_description(text_newlines) == "Line one Line two"
+
+    def test_truncation_at_word_boundary(self):
+        """Truncation occurs at word boundary when possible."""
+        # Create text that's over 200 chars with spaces
+        text = "word " * 50  # 250 chars
+        result = truncate_description(text)
+
+        assert result is not None
+        assert result.endswith(TRUNCATION_SUFFIX)
+        assert len(result) <= 200
+        # Should end at a word boundary (not mid-word)
+        without_suffix = result[: -len(TRUNCATION_SUFFIX)]
+        assert without_suffix.endswith("word")
+
+    def test_truncation_no_space(self):
+        """Long string without spaces hard-cuts."""
+        text = "a" * 250
+        result = truncate_description(text)
+
+        assert result is not None
+        assert result.endswith(TRUNCATION_SUFFIX)
+        assert len(result) == 200
+
+    def test_truncation_suffix_present(self):
+        """Over 200 chars returns text ending with truncation suffix."""
+        text = "This is a long description. " * 20
+        result = truncate_description(text)
+
+        assert result is not None
+        assert result.endswith(TRUNCATION_SUFFIX)
+
+    def test_unicode_handled(self):
+        """Unicode chars handled correctly."""
+        text = "Hello \u4e16\u754c! " * 30  # "Hello 世界! " repeated
+        result = truncate_description(text)
+
+        assert result is not None
+        # Should be valid UTF-8 string
+        result.encode("utf-8")
+
+    def test_custom_max_length(self):
+        """Custom max_length is respected."""
+        text = "a" * 100
+        result = truncate_description(text, max_length=50)
+
+        assert result is not None
+        assert len(result) == 50
+        assert result.endswith(TRUNCATION_SUFFIX)
+
+
+class TestLimitTags:
+    """Tests for limit_tags function."""
+
+    def test_none_input(self):
+        """None returns empty list."""
+        assert limit_tags(None) == []
+
+    def test_empty_list(self):
+        """Empty list returns empty list."""
+        assert limit_tags([]) == []
+
+    def test_under_limit(self):
+        """Under 10 tags returns unchanged."""
+        tags = ["tag1", "tag2", "tag3"]
+        result = limit_tags(tags)
+        assert result == tags
+        # Should be a copy, not the same object
+        assert result is not tags
+
+    def test_exact_limit(self):
+        """Exactly 10 tags returns unchanged."""
+        tags = [f"tag{i}" for i in range(10)]
+        result = limit_tags(tags)
+        assert result == tags
+
+    def test_over_limit(self):
+        """Over 10 tags returns first 9 + marker."""
+        tags = [f"tag{i}" for i in range(15)]
+        result = limit_tags(tags)
+
+        assert len(result) == 10
+        assert result[:9] == tags[:9]
+        assert result[9] == TAGS_TRUNCATION_MARKER
+
+    def test_custom_max_count(self):
+        """Custom max_count is respected."""
+        tags = [f"tag{i}" for i in range(10)]
+        result = limit_tags(tags, max_count=5)
+
+        assert len(result) == 5
+        assert result[:4] == tags[:4]
+        assert result[4] == TAGS_TRUNCATION_MARKER
+
+
+class TestCapsuleSearchResults:
+    """Tests for CapsuleSearchResults model."""
+
+    def test_from_sdk_results(self):
+        """from_sdk_results converts SDK results correctly."""
+        capsules = [
+            _MockCapsule(id="1", name="Capsule One", slug="capsule-one", description="First", tags=["a", "b"]),
+            _MockCapsule(id="2", name="Capsule Two", slug="capsule-two", description=None, tags=None),
+        ]
+        sdk_results = _MockCapsuleResults(results=capsules, has_more=True, next_token="token123")
+
+        result = CapsuleSearchResults.from_sdk_results(sdk_results, include_field_names=False)
+
+        assert len(result.items) == 2
+        assert result.items[0].id == "1"
+        assert result.items[0].n == "Capsule One"
+        assert result.items[0].s == "capsule-one"
+        assert result.items[0].d == "First"
+        assert result.items[0].t == ["a", "b"]
+        assert result.items[1].d is None
+        assert result.items[1].t == []
+        assert result.has_more is True
+        assert result.next_token == "token123"
+        assert result.item_count == 2
+        assert result.field_names is None
+
+    def test_from_sdk_results_with_field_names(self):
+        """from_sdk_results includes field_names when requested."""
+        sdk_results = _MockCapsuleResults(
+            results=[_MockCapsule(id="1", name="Test", slug="test", description=None, tags=None)],
+            has_more=False,
+        )
+
+        result = CapsuleSearchResults.from_sdk_results(sdk_results, include_field_names=True)
+
+        assert result.field_names == CapsuleSearchResults.FIELD_NAMES
+
+    def test_serializable(self):
+        """Result can be serialized to JSON."""
+        sdk_results = _MockCapsuleResults(
+            results=[_MockCapsule(id="1", name="Test", slug="test", description="Desc", tags=["t"])],
+            has_more=False,
+        )
+
+        result = CapsuleSearchResults.from_sdk_results(sdk_results)
+        json_str = result.model_dump_json()
+
+        assert "items" in json_str
+        assert "has_more" in json_str
+        assert "item_count" in json_str
+
+
+class TestDataAssetSearchResults:
+    """Tests for DataAssetSearchResults model."""
+
+    def test_from_sdk_results(self):
+        """from_sdk_results converts SDK results correctly."""
+        assets = [
+            _MockDataAsset(id="da-1", name="Asset One", description="First asset", tags=["x"]),
+            _MockDataAsset(id="da-2", name="Asset Two", description=None, tags=None),
+        ]
+        sdk_results = _MockDataAssetResults(results=assets, has_more=False, next_token=None)
+
+        result = DataAssetSearchResults.from_sdk_results(sdk_results, include_field_names=False)
+
+        assert len(result.items) == 2
+        assert result.items[0].id == "da-1"
+        assert result.items[0].n == "Asset One"
+        assert result.items[0].d == "First asset"
+        assert result.items[0].t == ["x"]
+        assert result.items[1].d is None
+        assert result.items[1].t == []
+        assert result.has_more is False
+        assert result.next_token is None
+        assert result.item_count == 2
+        assert result.field_names is None
+
+    def test_truncation_applied(self):
+        """Long descriptions and many tags are truncated."""
+        asset = _MockDataAsset(
+            id="da-1",
+            name="Test",
+            description="x" * 300,  # Long description
+            tags=[f"tag{i}" for i in range(20)],  # Many tags
+        )
+        sdk_results = _MockDataAssetResults(results=[asset], has_more=False)
+
+        result = DataAssetSearchResults.from_sdk_results(sdk_results)
+
+        # Description should be truncated
+        assert result.items[0].d is not None
+        assert result.items[0].d.endswith(TRUNCATION_SUFFIX)
+        assert len(result.items[0].d) <= 200
+
+        # Tags should be limited with marker
+        assert len(result.items[0].t) == 10
+        assert result.items[0].t[-1] == TAGS_TRUNCATION_MARKER

{codeocean_mcp_server-0.7.2 → codeocean_mcp_server-0.8.0}/tests/test_tool_calling.py

@@ -438,6 +438,7 @@ test_cases = [(test["prompt"], test["expected"]) for test in test_response]
 ids = [test["id"] for test in test_response]
 
 
+@pytest.mark.integration
 @pytest.mark.parametrize("prompt,expected_response", test_cases, ids=ids)
 def test_prompt_generating_the_right_tool_usage(prompt: str, expected_response: dict):
     """Test that the prompt generates the expected tool usage."""

{codeocean_mcp_server-0.7.2 → codeocean_mcp_server-0.8.0}/uv.lock

@@ -529,7 +529,7 @@ wheels = [
 
 [[package]]
 name = "codeocean-mcp-server"
-version = "0.7.2"
+version = "0.8.0"
 source = { editable = "." }
 dependencies = [
     { name = "codeocean" },