soma

name	soma
description	Use when the user asks to run or inspect Soma through its MCP tool, local stdio runtime, HTTP runtime, scaffold intent flow, setup checks, or action-dispatch surface.

Soma Skill

Soma RMCP runtime. Exposes a single soma MCP tool with action-based dispatch for interacting with a Soma runtime. The plugin default is local stdio MCP (soma mcp from PATH); for platform deployments the local adapter calls the deployed API configured by soma_api_url.

Tool

A single MCP tool, mcp__soma__soma, dispatches on a required action argument:

action	purpose	parameters
greet	Return a greeting.	name (optional string)
echo	Echo a message back unchanged.	message (required string)
status	Return server status and configuration info.	none
python_environment_status	Inspect immutable Python environment cache state without executing provider code.	none
python_environment_prune_plan	Plan a bounded prune of stale non-ready Python environment cache entries.	stale_before_unix_seconds (required integer), max_entries (optional integer)
python_environment_prune	Apply a bounded prune of stale non-ready Python environment cache entries.	stale_before_unix_seconds (required integer), max_entries (optional integer), confirm (required boolean)
python_environment_repair	Repair the immutable environment for one managed Python provider.	provider_path (required string), confirm (required boolean)
python_environment_update	Resolve, prepare, validate, and atomically activate an immutable update for one managed Python provider.	provider_path (required string), confirm (required boolean)
python_worker_status	Inspect persistent Python worker health, quarantine, restart counts, and bounded redacted logs.	none
python_worker_cancel	Cancel one active persistent Python invocation by terminating its process tree.	provider (required string), confirm (required boolean)
python_worker_reset	Clear one persistent Python worker crash-loop quarantine.	provider (required string), confirm (required boolean)
python_generation_status	Inspect the active Python provider generation and bounded rollback history.	none
python_generation_rollback	Atomically reactivate a retained Python provider generation.	generation_id (required integer), confirm (required boolean)
python_graduation_status	Inspect digest-bound Python graduation, conformance, activation, and rollback state.	workspace (required string)
python_graduation_apply	Scaffold, componentize, build, verify, compare, activate, or roll back a Python graduation workspace.	operation (required string), workspace (required string), source (optional string), component (optional string), fixtures (optional string), wheelhouse (optional string), confirm (required boolean)
elicit_name	Ask the MCP client to collect a name, then return a personalised greeting.	none
scaffold_intent	Collect scaffold setup intent through MCP elicitation and return JSON for the scaffold-project skill.	none
help	Show the action reference.	none

Python provider lifecycle administration uses the same tool:

• environment cache: python_environment_status, python_environment_prune_plan, python_environment_prune, python_environment_repair, and python_environment_update;
• persistent workers: python_worker_status, python_worker_cancel, and python_worker_reset;
• provider generations: python_generation_status and python_generation_rollback;
• Python-to-component graduation: python_graduation_status and confirmed python_graduation_apply.

Always prefer the MCP tool. The default plugin path is stdio. Fall back to HTTP curl only when MCP is unavailable or when explicitly debugging a remote HTTP deployment.

---

Action Reference

action="greet" — Return a greeting

param	type	description
name	string	Optional. Name to greet. Defaults to "World".

Examples:

mcp__soma__soma(action="greet")
mcp__soma__soma(action="greet", name="Alice")

Response shape:

{
  "greeting": "Hello, Alice!",
  "target": "Alice",
  "server": ""
}

---

action="echo" — Echo a message

param	type	description
message	string	Required. Message to echo back.

mcp__soma__soma(action="echo", message="Hello, world!")

Response shape:

{
  "echo": "Hello, world!"
}

---

action="status" — Server status

No parameters. Returns status from the local stub or from the deployed API when soma_api_url / SOMA_API_URL is configured.

mcp__soma__soma(action="status")

Response shape:

{
  "status": "ok",
  "note": "stub — replace with real health endpoint"
}

---

action="elicit_name" — Ask the user for a name

Uses MCP elicitation so the server can ask the client to show a small input form to the user. Clients without elicitation support return a graceful fallback message instead of failing the tool call.

No parameters.

mcp__soma__soma(action="elicit_name")

Response shape:

{
  "greeting": "Hello, Alice! Welcome to the Soma MCP server.",
  "name": "Alice"
}

---

action="scaffold_intent" — Create scaffold intent JSON

Uses MCP elicitation to collect what kind of project the user is building, then returns JSON for the scaffold-project skill. This action does not mutate files. The skill reads the JSON and creates an approval-first plan that the user can accept, edit, or reject.

This is intentionally MCP-only: it depends on MCP elicitation plus plugin skill handoff, which has no true CLI equivalent inside the user's agent/editor permission model.

No parameters.

mcp__soma__soma(action="scaffold_intent")

Response shape:

{
  "kind": "soma_scaffold_intent",
  "schema_version": 1,
  "server_category": "upstream-client",
  "required_surfaces": ["mcp", "cli"],
  "project": {
    "display_name": "unraid-rmcp",
    "crate_name": "unraid-rmcp",
    "binary_name": "runraid",
    "service_name": "unraid",
    "env_prefix": "UNRAID"
  },
  "upstream": {
    "base_url_env": "UNRAID_API_URL",
    "auth_kind": "api-key"
  },
   
     
     
     
     
  
      
   
    
   
   
     
     
     
  
   
     
     
  
   
      
      
        
     
       
       
       
    
  

---

action="help" — Canonical reference

Returns the authoritative in-tree action documentation. Use as ground truth if this skill document appears stale.

mcp__soma__soma(action="help")

---

HTTP Fallback Mode

Use only when the stdio MCP tool is unavailable or when debugging a remote HTTP deployment. The plugin default launches soma mcp and passes:

• CLAUDE_PLUGIN_OPTION_SOMA_API_URL — deployed platform API or upstream URL
• CLAUDE_PLUGIN_OPTION_SOMA_API_KEY — deployed API bearer token or upstream key

For HTTP fallback, configure:

• CLAUDE_PLUGIN_OPTION_SERVER_URL — HTTP MCP base URL (e.g. http://localhost:40060)
• CLAUDE_PLUGIN_OPTION_API_TOKEN — HTTP MCP bearer token

Sensitive value handling: api_token is declared sensitive: true in plugin.json. It is never substituted into skill content — only the env var path above is valid.

Health check (no auth required)

curl -s "$CLAUDE_PLUGIN_OPTION_SERVER_URL/health"

Call the soma tool

# Greet action
curl -s -X POST "$CLAUDE_PLUGIN_OPTION_SERVER_URL/mcp" \
  -H "Authorization: Bearer $CLAUDE_PLUGIN_OPTION_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"soma","arguments":{"action":"greet","name":"Alice"}}}'

# Status action
curl -s -X POST "$CLAUDE_PLUGIN_OPTION_SERVER_URL/mcp" \
  -H "Authorization: Bearer $CLAUDE_PLUGIN_OPTION_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"soma","arguments":{"action":"status"}}}'

---

Example Workflows

Quick health check

mcp__soma__soma(action="status")

Verify the service is responding correctly

# 1. Check server status
mcp__soma__soma(action="status")

# 2. Test the API connection with a greeting
mcp__soma__soma(action="greet", name="test")

# 3. Verify echo round-trip
mcp__soma__soma(action="echo", message="ping")

Scaffold a new project plan

# 1. Collect scaffold intent JSON through MCP elicitation
mcp__soma__soma(action="scaffold_intent")

# 2. Invoke/use the scaffold-project skill with the returned JSON
# 3. Review the generated plan before approving any file mutations