Skip to main content
Spruce

Spruce

Docs

Discord

Reference

MCP Tool Reference

Spruce exposes a set of tools over the Model Context Protocol. Agents (like Claude Code) call these tools to read and write artifacts, manage comments, and query templates. All tools are namespaced under mcp__spruce__.

Artifact tools

artifact_get

Fetch an artifact by ID.

Parameters:

  • id (string, required): artifact ID, e.g. SPR-abc123.

Returns: { id, type, title, fields, body }

artifact_search

Search artifacts by text, type, or field filters.

Parameters:

  • query (string, optional): text match on title, body, or ID.
  • template_type (string, optional): e.g. feature, task.
  • field_filters (object, optional): { status: "Done", priority: "High" }.
  • limit (number, optional, default 50).
  • offset (number, optional, default 0).

Returns: array of match summaries { id, type, title, status, snippet }

artifact_create

Create a new artifact from a template.

Parameters:

  • template_type (string, required).
  • title (string, required).
  • fields (object, optional): auto-converted from strings.
  • body (string, optional).

Returns: the created artifact

artifact_update

Update fields or replace the body.

Parameters:

  • id (string, required).
  • fields (object, optional).
  • body (string, optional).

At least one of fields or body is required.

artifact_body_edit

Targeted string replacement in the body.

Parameters:

  • id (string, required).
  • old_string (string, required): must be unique unless replace_all: true.
  • new_string (string, required).
  • replace_all (boolean, optional).

Returns: diff of the changes.

Comment tools

artifact_comment_list

List comments on an artifact (or all comments if no artifact_id is passed).

Parameters:

  • artifact_id (string, optional).

artifact_comment_add

Add a top-level comment.

Parameters:

  • artifact_id (string, required).
  • body (string, required).
  • anchor (object, optional): for block-anchored comments.

artifact_comment_claim

Claim a comment for the agent's session. Stamps processingBy and returns the full comment.

Parameters:

  • comment_id (string, required).
  • session_id (string, required).
  • note (string, optional): short description of the work the agent is doing.

artifact_comment_reply

Reply to a comment. Auto-releases any claim.

Parameters:

  • comment_id (string, required).
  • body (string, required).
  • author (string, optional).

artifact_comment_resolve

Mark a comment resolved.

Parameters:

  • comment_id (string, required).

Template tools

template_list

List all templates in the project.

template_get

Fetch a template's schema.

Parameters:

  • name (string, optional): template name.
  • artifact_id (string, optional): look up a template by its artifact.

One of name or artifact_id is required.

Reference

Artifact and Template Schema

Reference

Spruce CLI