MCP Tools (rai-workspace)¶

The rai-workspace MCP server exposes 36 tools across 10 domains. These tools are available to any MCP-capable client (Claude Code, Hermes Agent, etc.) when the server is running.

Transport: stdio only

The server runs over stdio only, launched by your AI client (e.g. via .mcp.json). There is no hosted or HTTP MCP endpoint in 3.1.0. 15 of the 36 tools are marked @local_only and are concealed from any future HTTP transport — if you introspect the server over HTTP in a later release, expect a smaller tool list.

Pipeline orchestration runs exclusively through MCP tools. See Pipelines for the tool reference and Pipeline Quickstart for a hands-on walkthrough.

Starting the server¶

The server starts automatically when Claude Code loads .claude/settings.json. To start manually:

python -m raise_cli.pipeline.mcp_server

Pipeline domain¶

Tools for orchestrating the story/epic/bugfix pipeline lifecycle.

`pipeline_list`¶

List available pipelines with their phases.

pipeline_list() → str

Returns a JSON list of pipeline definitions found in .raise/pipelines/. Use to discover available pipeline names before calling pipeline_start.

`pipeline_start`¶

Start a pipeline run. Returns the first phase to execute.

pipeline_start(pipeline_name: str, issue_id: str) → str

Parameter	Description
`pipeline_name`	Pipeline name (e.g., `"story"`, `"epic"`, `"bugfix"`)
`issue_id`	Issue key for traceability (e.g., `"RAISE-1281"`)

Returns a JSON object with run_id, current_phase, instruction, and skill for the first phase. Pass run_id to subsequent pipeline_advance calls.

`pipeline_advance`¶

Mark current phase as done and get the next phase.

pipeline_advance(run_id: str, approve: bool = False, cwd: str = "") → str

Parameter	Description
`run_id`	Run ID returned by `pipeline_start`
`approve`	Set to `True` to approve an HITL gate on the current phase
`cwd`	Working directory for artifact resolution. Required when calling from a git worktree (the MCP server CWD differs from the session's CWD). Defaults to server CWD.

Call after completing the skill for the current phase. If the phase has an HITL gate, the first call returns gate_pending — call again with approve=True to pass.

`pipeline_pause`¶

Pause a pipeline run. The run can be resumed by calling pipeline_advance.

pipeline_pause(run_id: str) → str

`pipeline_cancel`¶

Cancel a pipeline run. Cancelled runs cannot be resumed.

pipeline_cancel(run_id: str) → str

`pipeline_restore`¶

Restore full pipeline state after compaction or session restart.

pipeline_restore(run_id: str) → str

Returns the current run state and context for the current phase. Use when resuming work after a context compaction or Claude Code restart.

`pipeline_status`¶

Get current status of a pipeline run.

pipeline_status(run_id: str) → str

Returns run_id, status, current_phase, total_phases, and phase history.

`pipeline_runs`¶

List all active and recent pipeline runs.

pipeline_runs() → str

Returns runs ordered by last activity. Use to find a run_id when resuming after compaction.

`pipeline_decision`¶

Persist a directional human decision into the run's journal.

pipeline_decision(run_id: str, decision: str, phase: str = "", cwd: str = "") → str

Parameter	Description
`run_id`	Run ID returned by `pipeline_start`
`decision`	Free-text summary of the directional decision (truncated at 2000 chars)
`phase`	Phase id to attribute the decision to. Defaults to the run's current phase
`cwd`	Caller's checkout path. Required in community stdio mode

Display-only governance trail: appends to metadata.hitl_decisions with source="agent". Has no control effect — it cannot advance, pause, or cancel the run, and deliberately does not require the advance_token.

Artifact domain¶

Tools for persisting and querying structured story artifacts (design, plan, retrospective).

`raise_artifact_emit`¶

Validate and persist a structured story artifact.

raise_artifact_emit(
    artifact_type: str,
    story_id: str,
    content: str,
    session_id: str = ""
) → str

Parameter	Description
`artifact_type`	One of `"design"`, `"plan"`, `"implement"`, `"review"`, `"retro"`
`story_id`	Story identifier (e.g., `"RAISE-1281"`)
`content`	JSON string with artifact fields (see skill docs for schema per type)
`session_id`	Optional session ID for correlation

`raise_artifact_query`¶

Query artifacts by story and optionally by type.

raise_artifact_query(story_id: str, artifact_type: str = "") → str

Parameter	Description
`story_id`	Story identifier
`artifact_type`	Optional filter: `"design"`, `"plan"`, `"implement"`, `"review"`, `"retro"`

Backlog domain¶

Tools for reading and updating backlog items (Jira, filesystem adapter).

`raise_backlog_context`¶

Get issue details from the backlog for context.

raise_backlog_context(issue_key: str, adapter: str = "jira", cwd: str = "") → str

Parameter	Type	Default	Description
`issue_key`	`str`	required	Issue key (e.g., `"RAISE-1310"`)
`adapter`	`str`	`"jira"`	Adapter name (e.g., `"jira"`, `"filesystem"`)
`cwd`	`str`	`""`	Working directory override for worktree contexts

Returns title, description, status, labels, parent, and story points.

`raise_backlog_transition`¶

Transition a backlog issue to a new status.

raise_backlog_transition(
    issue_key: str,
    status: str,
    adapter: str = "jira",
    cwd: str = ""
) → str

Parameter	Type	Default	Description
`issue_key`	`str`	required	Issue key (e.g., `"RAISE-1438"`)
`status`	`str`	required	Target status slug (e.g., `"implement"`, `"done"`)
`adapter`	`str`	`"jira"`	Adapter name
`cwd`	`str`	`""`	Working directory override for worktree contexts

`raise_backlog_create`¶

Create a new backlog issue.

raise_backlog_create(
    summary: str,
    project: str,
    issue_type: str = "Story",
    description: str = "",
    labels: str = "",
    parent: str = "",
    adapter: str = "jira",
    cwd: str = ""
) → str

Parameter	Type	Default	Description
`summary`	`str`	required	Issue summary/title
`project`	`str`	required	Project key (e.g., `"RAISE"`)
`issue_type`	`str`	`"Story"`	Issue type (e.g., `"Story"`, `"Task"`, `"Bug"`)
`description`	`str`	`""`	Issue description
`labels`	`str`	`""`	Comma-separated labels
`parent`	`str`	`""`	Parent issue key for sub-tasks
`adapter`	`str`	`"jira"`	Adapter name
`cwd`	`str`	`""`	Working directory override for worktree contexts

`raise_backlog_update`¶

Update fields on an existing backlog issue.

raise_backlog_update(
    issue_key: str,
    summary: str = "",
    labels: str = "",
    priority: str = "",
    assignee: str = "",
    custom_fields: str = "",
    adapter: str = "jira",
    cwd: str = ""
) → str

Parameter	Type	Default	Description
`issue_key`	`str`	required	Issue key (e.g., `"RAISE-1234"`)
`summary`	`str`	`""`	New summary/title
`labels`	`str`	`""`	Comma-separated labels
`priority`	`str`	`""`	Priority name (e.g., `"High"`)
`assignee`	`str`	`""`	Assignee email
`custom_fields`	`str`	`""`	JSON string of custom fields to update
`adapter`	`str`	`"jira"`	Adapter name
`cwd`	`str`	`""`	Working directory override for worktree contexts

Updates fields on a Jira issue. Only non-empty parameters are applied. Returns confirmation or error.

Docs domain¶

`raise_docs_write`¶

Write a document artifact to the local filesystem and optionally publish to the docs adapter (Confluence).

raise_docs_write(
    doc_type: str,
    title: str,
    content: str,
    output_path: str,
    parent: str = "",
    cwd: str = ""
) → str

Parameter	Type	Default	Description
`doc_type`	`str`	required	Document type (e.g., `"story"`, `"epic-scope"`, `"adr"`, `"research"`)
`title`	`str`	required	Document title
`content`	`str`	required	Markdown content
`output_path`	`str`	required	Relative path for local file
`parent`	`str`	`""`	Parent page identifier for the docs adapter
`cwd`	`str`	`""`	Working directory override for worktree contexts

Writes the content to output_path and publishes to the configured docs adapter. Returns the local path and adapter result.

`raise_docs_search`¶

Search documentation pages on the remote target.

raise_docs_search(query: str, limit: int = 10, target: str = "", cwd: str = "") → str

Parameter	Description
`query`	Search query
`limit`	Max results to return (default 10)
`target`	Optional docs target name (e.g., `"confluence"`). Empty = default
`cwd`	Caller's absolute checkout path. Required in community stdio mode

Returns a JSON list of matching pages, or a structured error if no docs target is available.

`raise_docs_get`¶

Retrieve a page from the documentation target.

raise_docs_get(identifier: str, target: str = "", cwd: str = "") → str

Parameter	Description
`identifier`	Page ID on the remote target
`target`	Optional docs target name (e.g., `"confluence"`). Empty = default
`cwd`	Caller's absolute checkout path. Required in community stdio mode

Returns the page content as JSON, or a structured error if no docs target is available.

Gate domain¶

`raise_gate_check`¶

Run quality gate checks.

raise_gate_check(gate_id: str | None = None) → str

Parameter	Description
`gate_id`	Specific gate to check (e.g., `"gate-lint"`, `"gate-tests"`). Pass `None` or omit to run all gates.

Returns pass/fail per gate with output. Commands are read from .raise/manifest.yaml — null keys skip automatically.

Graph domain¶

Tools for querying the RaiSE knowledge graph (symbols, patterns, governance nodes).

`raise_graph_query`¶

Search the RaiSE knowledge graph for relevant nodes.

raise_graph_query(query: str, limit: int = 5) → str

Parameter	Description
`query`	Search terms (e.g., `"pipeline session start"`, `"storage SQLite"`)
`limit`	Maximum results to return (default 5)

`raise_graph_context`¶

Get context for a specific module from the knowledge graph.

raise_graph_context(module_id: str) → str

Parameter	Description
`module_id`	Module identifier (e.g., `"mod-session"`, `"mod-storage"`)

Pattern domain¶

Tools for querying, adding, and reinforcing behavioral patterns.

`raise_pattern_query`¶

Search RaiSE patterns by keywords.

raise_pattern_query(keywords: str, limit: int = 10) → str

Parameter	Description
`keywords`	Search terms against pattern content and context tags
`limit`	Maximum results (default 10)

`raise_pattern_add`¶

Add a new pattern to memory.

raise_pattern_add(
    content: str,
    context: str = "",
    pattern_type: str = "technical",
    from_story: str = ""
) → str

Parameter	Description
`content`	Pattern description text
`context`	Comma-separated context tags (e.g., `"testing,mocks,integration"`)
`pattern_type`	One of `"technical"`, `"process"`, `"architecture"`, `"approach"`, `"risk"`, `"codebase"`
`from_story`	Story that produced this pattern (e.g., `"RAISE-1281"`)

`raise_pattern_reinforce`¶

Reinforce a pattern with a vote signal.

raise_pattern_reinforce(
    pattern_id: str,
    vote: int = 1,
    from_story: str = ""
) → str

Parameter	Description
`pattern_id`	Pattern ID (e.g., `"PAT-E-1713"`)
`vote`	`1` = followed, `0` = not relevant, `-1` = contradicted
`from_story`	Story context for the vote

Called at story review to record whether a pattern was applied. 0 does not count toward evaluations — use for patterns that weren't relevant.

Session domain¶

Tools for emitting lifecycle signals, loading context, and querying session history.

`raise_signal_emit`¶

Emit a work lifecycle signal for tracking.

raise_signal_emit(
    work_type: str,
    work_id: str,
    event: str,
    phase: str = "init",
    task: str = ""
) → str

Parameter	Description
`work_type`	`"epic"` or `"story"`
`work_id`	Work identifier (e.g., `"RAISE-1281"`, `"E3978"`)
`event`	`"start"`, `"complete"`, or `"blocked"`
`phase`	Workflow phase: `"init"`, `"design"`, `"plan"`, `"implement"`, `"review"`, `"close"`
`task`	Task identity within a phase (e.g., `"Task 1: add schema fields"`)

`raise_session_context`¶

Load RaiSE session context sections for AI consumption.

raise_session_context(sections: str = "progress,coaching") → str

Parameter	Description
`sections`	Comma-separated sections: `"progress"`, `"coaching"`, `"governance"`, `"behavioral"`

Returns ~200 tokens of governance context for injection into LLM turns.

`raise_session_history`¶

Query recent session records with narratives and outcomes.

raise_session_history(
    limit: int = 10,
    epic: str = "",
    project_path: str = ""
) → str

Parameter	Description
`limit`	Maximum sessions to return (default 10)
`epic`	Filter to sessions for a specific epic (e.g., `"E2780"`). Empty = all epics.
`project_path`	Project root path. Defaults to `Path.cwd()`.

Returns sessions ordered by closed_at DESC with narrative, next_session_prompt, outcomes, and pattern IDs.

`raise_session_topic`¶

Emit a session topic event for tracking the current phase and sub-step.

raise_session_topic(kind: str, topic: str) → str

Parameter	Description
`kind`	Skill phase kind (e.g., `"design"`, `"implement"`, `"close"`)
`topic`	Sub-step within the phase (e.g., `"gemba"`, `"examples"`, `"merge"`)

Used by skills as token markers to keep session focus visible and feed session history.

`raise_session_bind`¶

Bind a key-value pair to the current session context file.

raise_session_bind(key: str, value: str) → str

Parameter	Description
`key`	Context key (e.g., `RAISE_SESSION_JIRA_KEY`, `RAISE_SESSION_MISSION_ID`)
`value`	Value to bind

Persists the binding in .raise/rai/sessions/$RAISE_CC_SESSION_ID/context.env. Uses line-replace semantics — existing keys are updated, other keys are preserved. Used by /rai-story-start and /rai-session-start to late-bind Jira keys and mission IDs.

`raise_session_open`¶

Composite session open: hygiene, drift, DB, mission, bundle, MCP.

raise_session_open(cwd: str = "", include_bundle: bool = True) → str

Parameter	Description
`cwd`	Caller's absolute checkout path. Required in community stdio mode
`include_bundle`	Also run the start flow and embed the orientation bundle (set `False` to re-check without starting a session)

One call replaces the deterministic sequence of the /rai-session-start skill. Statuses are ok/warn/blocked — blocked requires a human decision (the tool never auto-resolves).

`raise_session_close_full`¶

Composite session close: atomic structured close via CloseInput JSON.

raise_session_close_full(state_json: str, cwd: str = "", agent_session_id: str | None = None) → str

Parameter	Description
`state_json`	JSON object matching CloseInput (`summary`, `session_type`, `patterns`, `corrections`, `next_session_prompt`, ...)
`cwd`	Caller's absolute checkout path. Required in community stdio mode
`agent_session_id`	Explicit session ID from pipeline context. Overrides env discovery when the MCP server env is frozen (subagent)

Parity with rai session close --state-file — patterns, corrections, journal and state are written by the CLI service in one operation.

`raise_ledger_add`¶

Upsert a row in the session ledger — cross-project self-surfacing store.

raise_ledger_add(
    kind: str,
    natural_key: str,
    fields: str = "{}",
    cwd: str = "",
    agent_session_id: str | None = None
) → str

Parameter	Description
`kind`	LedgerKind value (`meta`, `project`, `cartridge`, `issue`, `branch`, `artifact`, `mission`, `open_thread`, `friction`)
`natural_key`	Upsert key within the session (e.g., `"RAISE-13146"`)
`fields`	JSON object of per-kind columns (e.g., `'{"status":"In Progress"}'`)
`cwd`	Caller's absolute checkout path. Required in community stdio mode
`agent_session_id`	Explicit session ID from pipeline context. Overrides env discovery when the MCP server env is frozen (subagent)

Keyed by discover_agent_session_id() (env-resolved, worktree-proof) and persisted to the global ~/.rai/raise.db (session_ledger_entries). A second call with the same natural_key UPSERTs (rewrites the row) rather than duplicating it.

Story domain¶

Tools for opening and closing story work, and for creating epic stories atomically.

`raise_story_open`¶

Composite story open: epic check, branch, docs, commit, transition, bind.

raise_story_open(
    story_id: str,
    slug: str,
    epic_dir: str,
    story_content: str,
    scope_content: str,
    jira_key: str = "",
    cwd: str = "",
    commit_message: str = ""
) → str

Parameter	Description
`story_id`	Story identifier (e.g., `"S7884.3"`)
`slug`	Branch slug (e.g., `"story-bookends-mcp"`)
`epic_dir`	Epic directory under `work/epics/` (empty = standalone)
`story_content`	Markdown for the story doc (LLM judgment)
`scope_content`	Markdown for the scope doc (LLM judgment)
`jira_key`	Backlog issue key (empty skips transition + bind)
`cwd`	Caller's absolute checkout path. Required in community stdio mode
`commit_message`	Override for the scope commit message

One call replaces the deterministic sequence of the /rai-story-start skill. Statuses are ok/warn/blocked — blocked requires a human decision (the tool never auto-resolves); steps after a block are skipped.

`raise_story_close_full`¶

Composite story close: retro gate, hygiene, merge, cleanup, Done.

raise_story_close_full(
    story_id: str,
    slug: str,
    epic_dir: str,
    merge_summary: str,
    jira_key: str = "",
    cwd: str = ""
) → str

Parameter	Description
`story_id`	Story identifier (e.g., `"S7884.3"`)
`slug`	Branch slug used at open
`epic_dir`	Epic directory under `work/epics/`
`merge_summary`	One-line summary for the merge commit body
`jira_key`	Backlog issue key (empty skips Done transition)
`cwd`	Caller's absolute checkout path. Required in community stdio mode

One call replaces the deterministic close sequence of the /rai-story-close skill. Merge target resolves worktree DB → epic branch → dev. Conflicts abort and block; a missing retro blocks. AR review and epic-scope updates stay with the skill (judgment).

`raise_epic_story_create`¶

Create a Jira story AND register it in work_items atomically.

raise_epic_story_create(
    summary: str,
    project: str,
    epic_jira_key: str,
    cwd: str = ""
) → str

Parameter	Description
`summary`	Issue summary/title
`project`	Project key (e.g., `"RAISE"`)
`epic_jira_key`	Parent epic's Jira key
`cwd`	Caller's absolute checkout path. Required in community stdio mode

Returns {status: ok, jira_key, work_item_id, local_key} when both are created, {status: already_registered, ...} on idempotent re-run, or {status: error, reason, ...} with failure context.

Task domain¶

Tool for the per-task implementation ritual (gates, branch assert, commit, signal).

`raise_task_complete`¶

Collapse the inner task loop: gates + branch-assert + add + commit + signal.

raise_task_complete(
    work_id: str,
    task_name: str,
    expected_branch: str,
    commit_message: str,
    gate_scope: str = "",
    files: str = "",
    cwd: str = ""
) → str

Parameter	Description
`work_id`	Story/bugfix identifier (e.g., `"S8370.1"`) for signal correlation
`task_name`	Free-text task name (e.g., `"T2: step functions"`) — used in the WorkLifecycle signal `task` field
`expected_branch`	Branch that must be current before any git mutation
`commit_message`	Full commit message (LLM judgment, including Co-Author)
`gate_scope`	Bare scope path for a scoped gate run; empty = full suite
`files`	Space-separated file paths to stage; empty = `git add -u`
`cwd`	Caller's absolute checkout path. Required in community stdio mode

One call replaces the deterministic per-task sequence of the /rai-story-implement skill. Statuses are ok/warn/blocked — blocked requires a human decision (the tool never auto-resolves). Read committed (never per-step status) to know whether a commit sha was produced; blocking_gate and remediation tell you what to fix.

Tool count summary¶

Domain	Tools
Pipeline	9 (`pipeline_list`, `pipeline_start`, `pipeline_advance`, `pipeline_pause`, `pipeline_cancel`, `pipeline_restore`, `pipeline_status`, `pipeline_runs`, `pipeline_decision`)
Artifact	2 (`raise_artifact_emit`, `raise_artifact_query`)
Backlog	4 (`raise_backlog_context`, `raise_backlog_transition`, `raise_backlog_create`, `raise_backlog_update`)
Docs	3 (`raise_docs_write`, `raise_docs_get`, `raise_docs_search`)
Gate	1 (`raise_gate_check`)
Graph	2 (`raise_graph_query`, `raise_graph_context`)
Pattern	3 (`raise_pattern_query`, `raise_pattern_add`, `raise_pattern_reinforce`)
Session	8 (`raise_signal_emit`, `raise_session_context`, `raise_session_history`, `raise_session_topic`, `raise_session_bind`, `raise_session_open`, `raise_session_close_full`, `raise_ledger_add`)
Story	3 (`raise_story_open`, `raise_story_close_full`, `raise_epic_story_create`)
Task	1 (`raise_task_complete`)
Total	36

MCP Tools (rai-workspace)¶

Starting the server¶

Pipeline domain¶

pipeline_list¶

pipeline_start¶

pipeline_advance¶

pipeline_pause¶

pipeline_cancel¶

pipeline_restore¶

pipeline_status¶

pipeline_runs¶

pipeline_decision¶

Artifact domain¶

raise_artifact_emit¶

raise_artifact_query¶

Backlog domain¶

raise_backlog_context¶

raise_backlog_transition¶

raise_backlog_create¶

raise_backlog_update¶

Docs domain¶

raise_docs_write¶

raise_docs_search¶

raise_docs_get¶

Gate domain¶

raise_gate_check¶

Graph domain¶

raise_graph_query¶

raise_graph_context¶