Skip to content

BRIC-18: Add MCP tool docstring warnings and simplify publish_section_version #38

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Kaiohz merged 2 commits into from
May 21, 2026
Merged

BRIC-18: Add MCP tool docstring warnings and simplify publish_section_version #38

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f288bb2
BRIC-18: add docstring warnings to MCP tools and simplify publish_sec…
Kaiohz May 21, 2026
2b2f103
BRIC-18: update unit tests for simplified publish_section_version sig…
Kaiohz May 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 16 additions & 15 deletions src/application/api/mcp_bricks_tools.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,9 @@ class DocumentSummary(BaseModel):
async def list_bricks_documents(project_unique_id: str) -> list[DocumentSummary]:
"""Liste les documents d'un projet Bricks.

IMPORTANT: This tool ONLY accepts project_unique_id.
Do NOT pass any other parameters (e.g., limit, offset, etc.) — they are not supported.

Args:
project_unique_id: L'identifiant unique du projet Bricks

Expand Down Expand Up @@ -63,6 +66,9 @@ async def read_bricks_document(

Résoud automatiquement l'URL pré-signée à partir du document_id et project_unique_id.

IMPORTANT: This tool ONLY accepts document_id and project_unique_id.
Do NOT pass any other parameters (e.g., limit, offset, etc.) — they are not supported.

Args:
document_id: L'identifiant du document (champ 'id' de list_bricks_documents)
project_unique_id: L'identifiant du projet Bricks
Expand All @@ -86,21 +92,16 @@ async def read_bricks_document(
@mcp_bricks.tool()
async def publish_section_version(
project_unique_id: str,
section_key: str,
content: dict,
workflow_id: str = "agent-haiku-files-v1",
workflow_name: str = "agent-haiku-files-v1",
workflow_metadata: dict | None = None,
content: dict

@Kaiohz Kaiohz May 21, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 L'exemple (e.g., limit, offset, etc.) est générique. Pour ce tool spécifiquement, mentionner les params retirés serait plus précis pour le LLM :

IMPORTANT: This tool ONLY accepts project_unique_id and content.
Do NOT pass section_key, workflow_id, workflow_name, or workflow_metadata — they are handled internally and are not supported as parameters.

) -> dict:
"""Publie la réponse structurée d'une section d'un projet Bricks.

@Kaiohz Kaiohz May 21, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📌 Ce hardcoding est la bonne décision pour réduire la surface d'erreur LLM, mais un commentaire expliquant pourquoi serait utile pour les devs futurs :

# Hardcoded: MCP tool only publishes consolidated data sections.
# These params are internal implementation details, not caller-facing.


IMPORTANT: This tool ONLY accepts project_unique_id and content.
Do NOT pass any other parameters (e.g., limit, offset, etc.) — they are not supported.

Args:
project_unique_id: L'identifiant unique du projet
section_key: La clé de la section à publier
content: Le contenu structuré de la section
workflow_id: L'identifiant du workflow
workflow_name: Le nom du workflow
workflow_metadata: Métadonnées additionnelles du workflow
content: Le contenu structuré de la section à publier, typiquement un dict avec les données extraites et analysées

Returns:
Résultat de la publication avec statut et aperçu du payload
Expand All @@ -109,14 +110,14 @@ async def publish_section_version(
try:
return await use_case.execute(
project_unique_id=project_unique_id,
section_key=section_key,
section_key="consolidated_data",
content=content,
workflow_id=workflow_id,
workflow_name=workflow_name,
workflow_metadata=workflow_metadata,
workflow_id="agent-haiku-files-v1",
workflow_name="agent-haiku-files-v1",
workflow_metadata=None,
)
except Exception:
logger.exception(
"Failed to publish section version for project %s", project_unique_id
)
raise ToolError("Failed to publish section version") from None
raise ToolError("Failed to publish section version") from None
38 changes: 11 additions & 27 deletions tests/unit/test_mcp_bricks_tools.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -203,7 +203,7 @@ async def test_returns_section_version_result(self) -> None:
success=True,
message="Dry run — no API call made",
dry_run=True,
payload_preview={"section_key": "intro", "content": "Hello"},
payload_preview={"section_key": "consolidated_data", "content": "Hello"},
)

with patch(
Expand All @@ -212,17 +212,14 @@ async def test_returns_section_version_result(self) -> None:
):
result = await publish_section_version(
project_unique_id="proj-123",
section_key="intro",
content="Hello world",
workflow_id="wf-1",
workflow_name="draft",
)

assert result.success is True
assert result.dry_run is True

async def test_forward_all_params_to_use_case(self) -> None:
"""Should forward all parameters to the use case."""
"""Should forward all parameters to the use case with hardcoded defaults."""
mock_use_case = AsyncMock()
mock_use_case.execute.return_value = SectionVersionResult(success=True)

Expand All @@ -232,20 +229,16 @@ async def test_forward_all_params_to_use_case(self) -> None:
):
await publish_section_version(
project_unique_id="proj-abc",
section_key="summary",
content="Summary content",

@Kaiohz Kaiohz May 21, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Le nom du test test_forward_all_params_to_use_case est devenu trompeur — il ne forward plus "all params" mais vérifie les defaults hardcodés. Suggestion : renommer en test_forward_params_with_hardcoded_defaults.

workflow_id="wf-final",
workflow_name="final_review",
workflow_metadata={"approved": True},
)

mock_use_case.execute.assert_called_once_with(
project_unique_id="proj-abc",
section_key="summary",
section_key="consolidated_data",
content="Summary content",
workflow_id="wf-final",
workflow_name="final_review",
workflow_metadata={"approved": True},
workflow_id="agent-haiku-files-v1",
workflow_name="agent-haiku-files-v1",
workflow_metadata=None,
)

async def test_raises_tool_error_for_api_failure(self) -> None:
Expand All @@ -262,10 +255,7 @@ async def test_raises_tool_error_for_api_failure(self) -> None:
):
await publish_section_version(
project_unique_id="proj-123",
section_key="intro",
content="Hello",
workflow_id="wf-1",
workflow_name="draft",
)

async def test_raises_tool_error_for_generic_failure(self) -> None:
Expand All @@ -282,10 +272,7 @@ async def test_raises_tool_error_for_generic_failure(self) -> None:
):
await publish_section_version(
project_unique_id="proj-123",
section_key="intro",
content="Hello",
workflow_id="wf-1",
workflow_name="draft",
)

async def test_returns_dry_run_result_with_preview(self) -> None:
Expand All @@ -297,11 +284,11 @@ async def test_returns_dry_run_result_with_preview(self) -> None:
dry_run=True,
payload_preview={
"project_unique_id": "proj-123",
"section_key": "intro",
"section_key": "consolidated_data",
"content": "Hello",
"workflow_id": "wf-1",
"workflow_name": "draft",
"workflow_metadata": {},
"workflow_id": "agent-haiku-files-v1",
"workflow_name": "agent-haiku-files-v1",
"workflow_metadata": None,
},
)

Expand All @@ -311,12 +298,9 @@ async def test_returns_dry_run_result_with_preview(self) -> None:
):
result = await publish_section_version(
project_unique_id="proj-123",
section_key="intro",
content="Hello",
workflow_id="wf-1",
workflow_name="draft",
)

assert result.dry_run is True
assert result.payload_preview is not None
assert result.payload_preview["section_key"] == "intro"
assert result.payload_preview["section_key"] == "consolidated_data"
Loading