src.marcus_mcp.tools.attachment module#

Artifact management tools with prescriptive storage locations.

This module provides tools to help agents store and track design artifacts in organized locations while allowing flexibility when needed.

async src.marcus_mcp.tools.attachment.log_artifact(task_id, filename, content, artifact_type, project_root=None, description=None, location=None, artifact_role=None, state=None, force=False)[source]#

Store an artifact with prescriptive location management.

By default, artifacts are stored in standard locations based on their type. Marcus accepts ANY artifact type, making it domain-agnostic.

Standard types (with predefined locations): - specification → docs/specifications/ - api → docs/api/ - design → docs/design/ - architecture → docs/architecture/ - documentation → docs/ - reference → docs/references/ - temporary → tmp/artifacts/

Custom types: - Any other type → docs/artifacts/ (default fallback) - You can use domain-specific types like “podcast-script”, “research”,

“video-storyboard”, “marketing-copy”, etc.

Parameters:

  • task_id (str) – The current task ID

  • filename (str) – Name for the artifact file

  • content (Union[str, Dict[str, Any], List[Any]]) – The artifact content to store. A dict or list is serialized to a pretty-printed JSON string before being written; a str is stored verbatim. Accepting structured input lets agents log parsed JSON (e.g. tsconfig.json) directly without pre-stringifying it (issue #595 Fix 1).

  • artifact_type (str) – Type of artifact (determines default location)

  • project_root (Optional[str]) – Absolute path to the project root directory where artifacts will be created. All agents should use the same path.

  • description (Optional[str]) – Optional description of the artifact

  • location (Optional[str]) – Optional override for storage location (relative path)

  • artifact_role (Optional[str]) – Semantic role of the artifact — "interface_contract", "implementation_spec", or "design_guide". Stored on the artifact entry so _collect_task_artifacts can inject role-aware usage_guidance for dependent agents (Option C). When None, guidance falls back to label-based detection (Option B).

  • state (Any) – MCP state object

  • force (bool) – Bypass the size-downgrade guard. When False, writing content that is smaller than 50 % of an existing docs/ file whose size exceeds 8 KB is rejected to prevent accidental stub overwrites. Pass True only when an intentional downsize is desired.

Returns:

Dict with artifact location and storage details

Return type:

Dict[str, Any]