MCP Tools Reference

Complete reference for every MCP tool available to AI agents connecting to Supaspec.

Section Tools

`list_projects`

Returns all projects the authenticated user has access to.

Parameters: None

Response:

[
  {
    "id": "uuid",
    "name": "Optimus",
    "slug": "optimus",
    "description": "Main product spec"
  }
]

`list_sections`

Returns all sections in a project (without content).

Parameters:

Param	Type	Required	Description
`project`	string	Yes	Project name or slug

Response:

[
  {
    "id": "uuid",
    "title": "Architecture Overview",
    "slug": "architecture-overview",
    "status": "approved",
    "sort_order": 1
  }
]

`get_section`

Returns full content and metadata for a single section.

Parameters:

Param	Type	Required	Description
`project`	string	Yes	Project name or slug
`section`	string	Yes	Section title or slug

Response:

{
  "id": "uuid",
  "title": "Architecture Overview",
  "content": "## Architecture Overview\n...",
  "status": "approved",
  "version": 5,
  "last_message": "Add caching strategy",
  "last_changed_by": "claude_code",
  "updated_at": "2026-02-17T14:22:00Z"
}

`get_plan`

Returns all sections with their full content. Large response.

Parameters:

Param	Type	Required	Description
`project`	string	Yes	Project name or slug
`status_filter`	string	No	Filter by status (e.g., "draft", "approved")

`update_section`

Updates a section's content. Creates a new version.

Parameters:

Param	Type	Required	Description
`project`	string	Yes	Project name or slug
`section`	string	Yes	Section title or slug
`content`	string	Yes	New markdown content
`message`	string	Yes	Short commit summary
`description`	string	No	Longer explanation of what changed
`prompt`	string	No	What the user asked the agent to do
`mode`	string	No	`"commit"` (default) or `"propose"`
`agent_name`	string	Yes	Self-identification (e.g., `claude_code`)

Modes:

commit — updates section content immediately
propose — creates a proposal (pending review). Section content is NOT updated until accepted.

`create_section`

Creates a new section in a project.

Parameters:

Param	Type	Required	Description
`project`	string	Yes	Project name or slug
`title`	string	Yes	Section title
`content`	string	Yes	Markdown content
`status`	string	No	Initial status (default: `"draft"`)
`after_section`	string	No	Place after this section (title or slug)
`message`	string	Yes	Commit message
`description`	string	No	Longer explanation
`prompt`	string	No	User's original prompt
`agent_name`	string	Yes	Self-identification

`set_status`

Changes a section's status.

Parameters:

Param	Type	Required	Description
`project`	string	Yes	Project name or slug
`section`	string	Yes	Section title or slug
`status`	string	Yes	New status: `draft`, `approved`, `implementing`, `implemented`
`message`	string	No	Defaults to "Status changed to {status}"
`agent_name`	string	Yes	Self-identification

`diff_section`

Returns a unified diff between two versions of a section.

Parameters:

Param	Type	Required	Description
`project`	string	Yes	Project name or slug
`section`	string	Yes	Section title or slug
`from_version`	number	Yes	Starting version number
`to_version`	number	Yes	Ending version number

`search`

Full-text search across all sections in a project.

Parameters:

Param	Type	Required	Description
`project`	string	Yes	Project name or slug
`query`	string	Yes	Search query

Revision History Tools

`log`

Returns the commit log for a section or entire project.

Parameters:

Param	Type	Required	Description
`project`	string	Yes	Project name or slug
`section`	string	No	If omitted, returns log across all sections

Response:

[
  {
    "version": 5,
    "section": "Architecture Overview",
    "message": "Suggest WebSocket layer",
    "description": "...",
    "prompt": "Review Architecture and suggest improvements",
    "type": "proposal",
    "proposal_status": "pending",
    "changed_by": "cursor",
    "created_at": "2026-02-17T16:00:00Z"
  }
]

`show_version`

Returns the full content at a specific version.

Parameters:

Param	Type	Required	Description
`project`	string	Yes	Project name or slug
`section`	string	Yes	Section title or slug
`version`	number	Yes	Version number

`accept_proposal`

Accepts a pending proposal — applies its content to the section.

Parameters:

Param	Type	Required	Description
`project`	string	Yes	Project name or slug
`section`	string	Yes	Section title or slug
`version`	number	Yes	Version number of the proposal

`reject_proposal`

Rejects a pending proposal.

Parameters:

Param	Type	Required	Description
`project`	string	Yes	Project name or slug
`section`	string	Yes	Section title or slug
`version`	number	Yes	Version number of the proposal
`reason`	string	No	Explanation for the rejection

`list_proposals`

Returns all pending proposals across all sections in a project.

Parameters:

Param	Type	Required	Description
`project`	string	Yes	Project name or slug

Meta Tools

`whoami`

Returns the authenticated user's identity and accessible projects.

Parameters: None

Response:

{
  "user": "Yurii",
  "email": "yurii@example.com",
  "projects": ["optimus", "another-project"]
}