soma

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
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

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"
  },
  "runtime": {
    "host": "127.0.0.1",
    "port": 40060,
    "binary_profile": "cli-mcp",
    "mcp_transport": "dual"
  },
  "mcp_primitives": ["tools", "resources", "prompts", "elicitation"],
  "deployment": "none",
  "plugins": ["claude", "codex"],
  "publish_mcp": true,
  "crawl_docs": {
    "urls": ["https://docs.unraid.net/"],
    "repos": [],
    "search_topics": ["Unraid API authentication"]
  },
  "handoff": {
    "recommended_skill": "scaffold-project",
    "instructions": "Create an approval-first scaffold plan from this JSON. Do not mutate files until the user approves the plan."
  },
  "policy": {
    "business_action_minimum_surfaces": ["mcp", "cli"],
    "upstream_client_surfaces": ["mcp", "cli"],
    "application_platform_surfaces": ["api", "cli", "mcp", "web"],
    "binary_profiles": {
      "upstream_client_default": "cli-mcp",
      "application_platform_default": "server-full",
      "gateway_shared_default": "server-full"
    }
  }
}

---

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