Soma

Soma

CLI、REST、HTTP MCP、プラグイン、スキャフォールドを備えた、プロバイダー対応エージェント向けの RMCP ランタイムです。

API ドキュメント — ワークスペース内のすべてのクレートの rustdoc と、Redoc でレンダリングされた OpenAPI リファレンスです。main から GitHub Pages にデプロイされます。

Soma は、独自の Rust コードをできるだけ少なくして新しいエージェント機能を利用可能にする、必要な機能が一通りそろったサーバーランタイム兼配布バイナリです。サーバー群の各サーバーで繰り返し必要になる本番運用のパターンを標準で備えています。コンパクトな MCP ツール、stdio および Streamable HTTP トランスポート、CLI との機能同等性、直接 REST ルート、認証／OAuth、可観測性、プラグインのパッケージ化、Web フォールバック、Docker／ランタイムのサンプル、生成されたコントラクト、リリース自動化を含みます。

このリポジトリでは、引き続き名前を変更したプロジェクトをスキャフォールドできますが、Soma は今やスキャフォールド元よりも、配布されるランタイムとしての役割を重視しています。標準的な製品の使い方は、明示的なモードで soma を実行し、プロバイダーファイルを providers/ に配置する（または SOMA_PROVIDER_DIR で別の場所を指定する）ことです。プロバイダーレジストリが、それらの機能を MCP、CLI、REST、OpenAPI、Palette の概要、生成ドキュメント、プラグインメタデータに反映します。プロバイダーマニフェストには、レジストリコントラクト向けに、MCP ネイティブのプロンプト、リソース、タスク、エリシテーションのメタデータも含まれます。スキャフォールドは、同じランタイムを標準で備えた新しい配布可能なリポジトリを作成するための手段です。

30 秒で試す： soma バイナリをインストール -> soma status -> MCP クライアントから npx -y @dinglebear/soma mcp を実行 -> {"action":"status"} を指定して tools/call 経由で soma MCP ツールを呼び出します。

ステータス： 本番向け RMCP ランタイムです。書き込みを伴うプロバイダーアクションは、プロバイダーが宣言した場合にのみ許可され、破壊的なアクションには制限が適用されます。

用途の対象外： 認証されていないパブリックゲートウェイ、上流サービスの認可の代替、任意の信頼できないコードの実行、またはそれ単独でのマルチテナント向けセキュリティ境界。

目次

• 命名
• 機能と境界
• インストール
• クイックスタート
• クライアント設定
• ランタイムのインターフェース
• MCP ツールのリファレンス
• CLI リファレンス
• 設定
• 認証
• 安全性と信頼モデル
• アーキテクチャ
• 配布コントラクト
• 開発
• 検証
• デプロイ
• トラブルシューティング
• 関連サーバー
• ドキュメント
• ライセンス

命名

Soma はまずランタイム製品であり、テンプレート／エクスポート元としての役割はその次です。 生成されたプロジェクトでは、スキャフォールドの後処理でこれらの名前が置き換えられますが、配布される soma コマンドが製品の動作の正式な基準です。

項目	Soma の値	生成プロジェクトの命名パターン
リポジトリ	dinglebear-ai/soma（以前は rmcp-template、その後 rtemplate-mcp。どちらも現在もリダイレクトされます）	dinglebear-ai/r<service>、または製品名そのもの。古いサーバーは今も <service>-rmcp という名前をリダイレクト先として使用しています
Rust クレート／パッケージ	soma	サービス固有のクレート名
正式なバイナリ	soma	通常は r<service> または製品名
npm パッケージ	@dinglebear/soma	<service>-rmcp
MCP ツール	soma	通常は <service>
環境変数のプレフィックス	SOMA_*	生成されたサービスのプレフィックス

機能と境界

パス	使用する場面	作成するもの	ランタイムが提供するもの
ドロップインプロバイダー	機能をマニフェスト、スクリプト、WASM モジュール、OpenAPI オペレーション、または上流 MCP 呼び出しとして記述できる場合。	ツール、プロンプト、リソース、環境変数の要件、機能の権限付与、サーフェスオーバーレイを含む providers/ 配下のファイル。	MCP ツールのディスパッチ、動的 CLI コマンド、直接 REST ルート、スキーマ検証、認証ポリシー、更新、OpenAPI／Palette の概要、生成ドキュメント、プラグインメタデータ。
静的 Rust プロバイダー	機能にネイティブ Rust、密接な統合、または再利用可能なクレートが必要な場合。	プロバイダーレジストリに登録された Rust プロバイダー／アクション。	サーフェスごとの書き換えなしで、同じ MCP／CLI／REST／ドキュメント／プラグインへの投影。
スキャフォールド済み製品	リポジトリ名、パッケージ ID、ポート、プラグイン、Docker ラベル、リリースメタデータを変更する場合。	scaffold_intent ペイロード、または cargo xtask scaffold オプション。	コンパイル可能な製品リポジトリ、スキャフォールドレポート、cargo-generate による後処理、スキャフォールド／エクスポート検証チェック。
カスタムプロファイル	より限定的なバイナリやデプロイ形態が必要な場合。	Cargo の機能選択。	local-adapter、server、full プロファイルの背後にある同じランタイムクレート。

必要な機能をすべて搭載

• action ディスパッチを備えた、コンパクトな MCP サービスツール（soma）を 1 つ提供します。プロバイダーカタログが増えても、エージェントのツール一覧を小さく保てます。
• 唯一のバイナリとして soma を提供します。REST API、Streamable HTTP MCP、stdio MCP、オプションの Web UI、ローカルアクション向けに、serve、mcp、CLI の各モードを明示的に用意しています。
• .json、.ts、.py、.wasm、.md ファイルからの動的なプロバイダー読み込みに加え、ネイティブ Rust プロバイダーや上流 MCP／OpenAPI プロバイダーの種類にも対応します。 providers/{tools,prompts,resources}/ の構造化されたレイアウトと、ルート階層のファイルの両方をサポートしています。パスから導出される MCP リソース（静的ファイルおよび動的な .ts リーダー）にも対応し、パストラバーサルに対する信頼境界を設けています。
• ツール、プロンプト、リソース、タスク、エリシテーションフォーム、環境変数の要件、機能の権限付与、サーフェスオーバーレイに関するプロバイダーマニフェストの契約。
• 共通の検証、破壊的操作の確認、認証／スコープの適用、応答制限、秘匿化、ロギング、メトリクス、生成 OpenAPI、プロバイダーサーフェスの生成ドキュメント、プラグインマニフェスト、セットアップ、診断、リリースツール。

Soma はランタイムへの投影、検証、認証ポリシー、パッケージング、生成メタデータ、スキャフォールドの自動化を担います。プロバイダーコードはサービス固有の動作と認証情報を担います。上流サービスは独自の認可とデータモデルを担います。Soma は、認証情報をツール呼び出しの入力に含めることを意図的に拒否し、プロバイダーマニフェストを無制限のリモート実行境界に変えることもありません。

インストール

MCP クライアントが npx コマンドを必要とする場合は、npm ランチャーを使用してください。postinstall 中に、パッケージは対応する Linux/x64 または Windows/x64 のリリースアーカイブをダウンロードし、SHA256SUMS のエントリと GitHub ビルドアテステーションを検証してから、パッケージ内にネイティブバイナリをインストールします。来歴の検証には GitHub CLI 2.68 以降が必要です。

npx -y @dinglebear/soma mcp

リポジトリの開発中は Cargo を使用してください。

cargo run --bin soma -- mcp
cargo run --bin soma -- serve

リリースビルドでは、GitHub Release バイナリ、Docker／OCI メタデータ、@dinglebear/soma npm ランチャー、MCP レジストリメタデータ、プラグインパッケージファイルが、同じリリースコンポーネントから公開されます。

プロダクトプロファイル

プロバイダーの作成モデルを変えずに、必要な機能の範囲を選べます。

対象	最適な用途	デフォルトプロファイル	含まれるもの
ローカルエージェントアダプター	追加したプロバイダーや上流 API を薄くラップする	local-adapter	1 つのローカルバイナリに CLI と stdio MCP を搭載します。デフォルトでは REST/Web ミラーはありません。
共有 API/MCP サーバー	複数のクライアントやゲートウェイで使うサービス	server	CLI + REST API + Streamable HTTP MCP + stdio MCP + ヘルス／ステータスルート + 認証対応ランタイム。
フルアプリケーションプラットフォーム	アプリが状態、ジョブ、ダッシュボード、ワークフロー、または人間向け UI を管理する	full	server に加え、組み込み Web UI、OAuth、オブザーバビリティ、プラグイン対応。
CLI 専用またはカスタムのローカルツール	スクリプト、運用ユーティリティ、1 台のマシンで使うツール	カスタム機能セット。通常は cli から開始	CLI パーサーと共有サービスレイヤー。標準のパッケージ済みローカルバイナリは local-adapter を使用するため、CLI 専用製品では MCP を取り除いたり、バイナリの機能ゲートを調整したりできます。

カスタム構成が必要な場合は、より低レベルの Cargo 機能を利用できます。

機能	目的
cli	CLI シムとコマンド解析。
mcp	MCP のツール、スキーマ、リソース、プロンプト、スコープの各レイヤー。
mcp-stdio	ローカル stdio MCP トランスポート。
api	REST ハンドラーと OpenAPI に基づくビジネスルート。
auth	共有認証ポリシーとベアラートークンの適用。
oauth	auth による Google、Authelia、GitHub の OAuth/OIDC と JWT の発行。
mcp-http	Axum にマウントされる Streamable HTTP MCP。
web	組み込み静的 Web UI のフォールバック。
observability	メトリクス／トレーシングのフック。
plugin	プラグインのセットアップ／サポート用ヘルパー。
local-adapter	軽量なローカルバイナリ：cli + mcp-stdio。
server	デプロイ可能な HTTP ランタイムプロファイル：cli + api + HTTP MCP + stdio MCP。
full	完全なプラットフォームプロファイル：ローカルアダプター、サーバー、Web、OAuth、オブザーバビリティ、プラグイン対応。

クイックスタート

製品をそのまま実行します。

git clone https://github.com/dinglebear-ai/soma
cd soma

# Full platform mode: REST API + HTTP MCP + web fallback on :40060
cargo run --bin soma -- serve

# Local binary: stdio MCP
cargo run --bin soma -- mcp

# Local binary: CLI
cargo run --bin soma -- greet --name Alice

簡単な動作確認に役立つコマンド：

curl http://localhost:40060/health
cargo run --bin soma -- status
cargo run --bin soma -- doctor

MCP エンドポイントを直接呼び出します。

curl -s -X POST http://localhost:40060/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"soma","arguments":{"action":"greet","name":"Alice"}}}'

プロバイダーを追加する

新しいサーバーを作る最短の方法は、プロバイダーを先に用意することです。プロバイダーのマニフェストまたはモジュールを providers/ に追加して、同じバイナリを実行します。プロバイダーカタログを作業ディレクトリの外に置く場合は、SOMA_PROVIDER_DIR を使用します。

mkdir -p providers
cat > providers/hello-local.json <<'JSON'
{
  "schema_version": 1,
  "provider": {
    "name": "hello-local",
    "kind": "static-rust",
    "title": "Hello Local"
  },
  "tools": [
    {
      "name": "hello_local",
      "description": "Return a deterministic hello payload from a dropped provider.",
      "input_schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "name": { "type": "string" }
        }
      },
      "cli": {
        "enabled": true,
        "command": "hello-local"
      },
      "rest": {
        "enabled": true,
        "method": "POST",
        "path": "/v1/hello-local"
      },
      "meta": {
        "result": {
          "message": "hello from a dropped provider"
        }
      }
    }
  ]
}
JSON

動的 CLI インターフェイスから呼び出します。

cargo run --bin soma -- hello-local --name Alice

サーバーを実行し、同じプロバイダーを REST と MCP 経由で呼び出します。

cargo run --bin soma -- serve

curl -s -X POST http://localhost:40060/v1/hello-local \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice"}'

curl -s -X POST http://localhost:40060/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"soma","arguments":{"action":"hello_local","name":"Alice"}}}'

通常の Python 関数を providers/ に直接追加することもできます。

PROVIDER = {"name": "math-tools", "kind": "python"}

def add(a: int, b: int) -> int:
    """Add two integers."""
    return a + b

TOOLS がない場合、モジュール内で定義された公開関数がツールになります。同期関数と非同期関数がサポートされ、一般的な Python 型アノテーションは入力スキーマに変換されます。

Python プロバイダーファイルは信頼済みコードとして扱われます。Soma はプロバイダーカタログの更新時にこれらをインポートしてツールを検出し、その後、環境をクリアし、宣言されたプロバイダー／ツールの環境変数のみを設定したサイドカーでツール呼び出しを実行します。カタログのインポート時にプロバイダーの環境変数は渡されません。シークレットはモジュールのインポート時ではなく、ツール関数内で読み取ってください。

プロバイダーマニフェストでは、次の項目を宣言できます。

• デフォルトで MCP 経由で公開され、オーバーレイで有効にした場合は CLI／REST 経由でも公開されるツール／アクション
• プロバイダーレジストリ契約に対応する、MCP ネイティブのプロンプト、リソース、タスク、エリシテーションのメタデータ
• 必須環境変数と秘匿化ルール
• ファイルシステム、ネットワーク、ブラウザー、ターミナル、GitHub、環境変数の機能許可
• 制限、破壊的操作のメタデータ、例、生成ドキュメント、プラグイン、UI のメタデータ

サポートされるプロバイダーの種類は static-rust、openapi、ai-sdk、wasm、mcp、python、langchain、llamaindex です。docs/specs/dynamic-provider-runtime.md、docs/contracts/provider-manifest.schema.json、docs/generated/provider-surfaces.md を参照してください。

新しいプロジェクトをスキャフォールドする

プロバイダー優先の方法を、独自のクレート名、バイナリ名、ポート、プラグインパッケージ、Docker メタデータ、リリースメタデータ、ドキュメントを備えた新しいリポジトリにする必要がある場合は、cargo xtask scaffold を使用します。ファイルを変更せずに計画を立てたり、cargo-generate と Rust の後処理ツールを使って生成したり、docs/scaffold-report.md に書き込んだり、生成されたエクスポートの構成を検証したりできます。

短いサービス名から計画を立てます。

cargo xtask scaffold --name myservice --category upstream-client --port auto --plan

MCP scaffold_intent JSON から計画を立てます。

cargo xtask scaffold --intent scaffold-intent.json --plan

出力先の親ディレクトリに生成します。

cargo xtask scaffold --intent scaffold-intent.json --apply ../generated

既存の生成済みプロジェクトを検証します。

cargo xtask scaffold --verify ../generated/myservice-mcp

生成されたスタブを適応させるための、パスを含む後続作業計画を出力します。

cargo xtask scaffold --adapt-plan ../generated/myservice-mcp

アクションマニフェストからスターターアーティファクトを生成します。

cargo xtask scaffold \
  --write-action-starters ../generated/myservice-mcp \
  --actions actions.json

スターターアクションのスニペットを追加します。

cargo xtask scaffold \
  --intent scaffold-intent.json \
  --actions actions.json \
  --plan

アクションマニフェストの例：

{
  "actions": [
    {
      "name": "list_things",
      "description": "List visible things.",
      "scope": "read",
      "params": [
        { "name": "kind", "type": "string", "required": false }
      ]
    }
  ]
}

次のように使用します。

• 既存の API を囲む軽量なローカルアダプターには、--category upstream-client を使用します。
• API + CLI + MCP + Web のデフォルト構成には、--category application-platform を使用します。
• 作業中に高速な静的検証が必要な場合に限り、--no-cargo-check を使用します。

スキャフォールドの契約全体については、docs/SCAFFOLD.md、docs/CARGO_GENERATE.md、 docs/contracts/scaffold-intent.schema.jsonを参照してください。

アーキテクチャ

ランタイムでは、プロダクトの動作をプロバイダーレジストリの背後に置きます。すべての外部インターフェースは、同じプロバイダースナップショットとサービスランタイムを中心とする薄いパーサー／フォーマッターです。そのため、プロバイダーを削除しても、MCP、CLI、REST、OpenAPI、プラグイン、ドキュメントのコードを手作業で編集する必要はありません。

ProviderRegistry
  crates/soma/application/src/provider_registry.rs
  Validates provider manifests, computes snapshots/fingerprints, indexes tools,
  prompts, resources, CLI commands, REST routes, and MCP primitives.

Provider sources
  crates/soma/application/src/providers/
  Static Rust, file-backed JSON manifests, TypeScript AI SDK sidecars, Python
  LangChain/LlamaIndex sidecars, WASM, OpenAPI-backed providers, and upstream
  MCP providers.

SomaService
  crates/soma/application/src/service.rs
  Built-in product/service logic used by the static Rust provider.

Transport shims
  crates/soma/cli/src/lib.rs        CLI parser and output formatting.
  crates/soma/mcp/src/tools.rs      MCP JSON args to service calls.
  crates/soma/api/src/api.rs        REST extractors to service calls.
  apps/soma/src/http.rs             Axum router, auth, MCP, API, web fallback.

Built-in action metadata
  crates/soma/domain/src/actions.rs
  Native action metadata, validation, cached catalog/help, and native dispatch.

薄いシムの原則は厳守します。

1. インターフェースで入力を解析します。
2. プロバイダーレジストリまたはサービスランタイムを呼び出します。
3. 結果を返すか、出力します。

CLI、MCP、REST ハンドラー、またはバイナリエントリーポイント（apps/soma/src/bin/soma.rs / apps/soma/src/bootstrap.rs）にビジネスルールを置かないでください。

ランタイムインターフェース

標準バイナリは、1 つの実行ファイルからアプリ全体を実行できます。

soma serve       # HTTP server: REST API + Streamable HTTP MCP + web fallback
soma mcp         # stdio MCP transport
soma status      # CLI command through the same binary

ローカルアダプターモードは、プラグイン／ローカルでの使用に最適化されています。

soma mcp                # stdio MCP transport
soma greet --name Alice # CLI command
soma doctor             # operator pre-flight checks
soma watch              # poll /health and emit state changes
soma setup check        # plugin/appdata setup checks

明示的な各ランタイムモードは、プロバイダーレジストリを読み込みます。ファイルプロバイダーのデフォルトは ./providers で、SOMA_PROVIDER_DIR を使って変更できます。CLI の起動、MCP のディスパッチ、動的 REST ルートは、実行前にファイルプロバイダーを更新し、その後、アクティブなプロバイダースナップショットのスキーマ、インターフェース、スコープ、機能、破壊的アクション、レスポンス上限に関するルールを適用します。

サーバープロファイルの HTTP ルート：

ルート	用途
/mcp	ストリーミング可能な HTTP MCP トランスポート。
/health	認証なしの稼働状態確認。
/readyz	レディネスチェック。
/status	公開される、機密情報を除去したランタイム状態。
/openapi.json	生成された REST OpenAPI スキーマ。
/metrics	observability を有効にしてビルドした場合の Prometheus メトリクス。
/v1/capabilities	REST ルート一覧。
/v1/greet, /v1/echo, /v1/status, /v1/help	直接呼び出す REST ビジネスルート。
/v1/tools/{action}	ドロップされたプロバイダーツール向けの汎用 REST 実行ルート。
/v1/{provider-route}	ツールがカスタム REST オーバーレイを提供する場合の、プロバイダー宣言による任意の REST ルート。
/mcp/.well-known/*	OAuth が有効な場合の OAuth メタデータ。
/*	web を有効にしてビルドした場合の、埋め込み Web UI フォールバック。

REST は直接ルートのみです。/v1/soma アクションエンベロープはありません。MCP は引き続き、action 引数を持つ 1 つの soma ツールを使用します。

MCP ツールリファレンス

ランタイムは、action 引数を持つ簡潔な MCP ツール soma を 1 つ公開します。組み込みアクションとドロップされたプロバイダーツールは、同じディスパッチ経路を共有します。これにより、プロバイダーカタログを単一のツールの背後で拡張しながら、MCP の検出対象を小さく保てます。

アクション	スコープ	コスト	トランスポート	REST ルート	CLI	パラメーター	説明
greet	soma:read	cheap	MCP + CLI + REST	POST /v1/greet	soma greet [--name NAME]	name（任意の文字列）	あいさつを返します。
echo	soma:read	cheap	MCP + CLI + REST	POST /v1/echo	soma echo --message MSG	message（必須の文字列）	メッセージを変更せずにそのまま返します。
status	soma:read	cheap	MCP + CLI + REST	GET /v1/status	soma status	なし	サーバーの状態と設定情報を返します。
python_environment_status	soma:write	cheap	MCP + CLI + REST	GET /v1/python/environments	soma python_environment_status	なし	プロバイダーのコードを実行せずに、不変の Python 環境キャッシュの状態を確認します。
python_environment_prune_plan	soma:write	moderate	MCP + CLI + REST	POST /v1/python/environments/prune-plan	soma python_environment_prune_plan --json '{\	stale_before_unix_seconds（必須の整数）、max_entries（任意の整数）	古くなった未準備状態の Python 環境キャッシュエントリーを、上限付きで削除する計画を立てます。
python_environment_prune	soma:write	write	MCP + CLI + REST	POST /v1/python/environments/prune	soma python_environment_prune --json '{\	stale_before_unix_seconds（必須の整数）、max_entries（任意の整数）、confirm（必須のブール値）	古くなった未準備状態の Python 環境キャッシュエントリーを、上限付きで削除します。
python_environment_repair	soma:write	write	MCP + CLI + REST	POST /v1/python/environments/repair	soma python_environment_repair --json '{\	provider_path（必須の文字列）、confirm（必須のブール値）	管理対象の Python プロバイダー 1 つの不変環境を修復します。
python_environment_update	soma:write	write	MCP + CLI + REST	POST /v1/python/environments/update	soma python_environment_update --json '{\	provider_path（必須の文字列）、confirm（必須のブール値）	管理対象の Python プロバイダー 1 つの不変な更新を解決、準備、検証し、アトミックに有効化します。
python_worker_status	soma:write	cheap	MCP + CLI + REST	GET /v1/python/workers	soma python_worker_status	なし	永続的な Python ワーカーの健全性、隔離状態、再起動回数、上限付きの秘匿化ログを確認します。
python_worker_cancel	soma:write	write	MCP + CLI + REST	POST /v1/python/workers/cancel	soma python_worker_cancel --json '{\	provider（必須の文字列）、confirm（必須のブール値）	プロセスツリーを終了して、実行中の永続的な Python 呼び出しを 1 つキャンセルします。
python_worker_reset	soma:write	write	MCP + CLI + REST	POST /v1/python/workers/reset	soma python_worker_reset --json '{\	provider（必須の文字列）、confirm（必須のブール値）	永続的な Python ワーカー 1 つのクラッシュループ隔離を解除します。
python_generation_status	soma:read	cheap	MCP + CLI + REST	GET /v1/python/generations	soma python_generation_status	なし	アクティブな Python プロバイダー世代と、上限付きのロールバック履歴を確認します。
python_generation_rollback	soma:write	write	MCP + CLI + REST	POST /v1/python/generations/rollback	soma python_generation_rollback --json '{\	generation_id（必須の整数）、confirm（必須のブール値）	保持されている Python プロバイダー世代をアトミックに再有効化します。
python_graduation_status	soma:read	cheap	MCP + CLI + REST	POST /v1/python/graduation/status	soma python_graduation_status --json '{\	workspace（必須の文字列）	ダイジェストに紐付いた Python の昇格、適合性、有効化、ロールバックの状態を確認します。
python_graduation_apply	soma:write	write	MCP + CLI + REST	POST /v1/python/graduation/apply	soma python_graduation_apply --json '{\	operation（必須の文字列）、workspace（必須の文字列）、source（任意の文字列）、component（任意の文字列）、fixtures（任意の文字列）、wheelhouse（任意の文字列）、confirm（必須のブール値）	Python の昇格ワークスペースのひな形作成、コンポーネント化、ビルド、検証、比較、有効化、またはロールバックを行います。
elicit_name	soma:read	cheap	MCP のみ	-	_MCP-only_	なし	MCP クライアントに名前の入力を求め、名前を使ったあいさつを返します。
scaffold_intent	soma:read	moderate	MCP のみ	-	_MCP-only_	なし	MCP エリシテーションを通じてひな形のセットアップ意図を収集し、scaffold-project スキル用の JSON を返します。
help	public	cheap	MCP + CLI + REST	GET /v1/help	soma help	なし	アクションのリファレンスを表示します。
Python プロバイダーのライフサイクル管理は、以下の明示的なアクションを持つ同じ簡潔なツールを通じて利用できます。

• 環境キャッシュ：python_environment_status、 python_environment_prune_plan、python_environment_prune、 python_environment_repair、python_environment_update。
• 永続ワーカー：python_worker_status、python_worker_cancel、 python_worker_reset。
• プロバイダーの世代：python_generation_status、 python_generation_rollback。
• Python からコンポーネントへの昇格：python_graduation_status と、確認を伴う python_graduation_apply。

組み込みのビジネスアクションは、プロトコル上の理由で不可能な場合を除き、MCP、CLI、REST で同等に利用できます。elicit_name と scaffold_intent は MCP のエリシテーションに依存するため、MCP 専用です。serve、mcp、doctor、watch、setup、package は CLI の運用者向けコマンドであり、ビジネスアクションではありません。

取り込まれたプロバイダーツールは、デフォルトで MCP が有効になり、ツールで明示的に rest.enabled=false が設定されていない限り、POST /v1/tools/{action} を通じて REST から実行できます。rest オーバーレイでは、カスタムルート、メソッド、OpenAPI メタデータを追加できます。汎用ルートは、ウェブ／アダプターから安全に実行できる形式のままです。CLI への公開は、各ツールの cli オーバーレイでオプトインします。プロバイダーのプロンプト、リソース、タスク、エリシテーションフォームはプロバイダーマニフェストの契約とレジストリインデックスの一部であり、デフォルトでは CLI や REST には反映されません。

CLI リファレンス

soma バイナリは、MCP と同じレジストリスナップショットを使用して、運用者向けコマンドとプロバイダーを利用するアクションを公開します。

soma greet --name Alice
soma echo --message hello
soma status
soma help
soma providers validate
soma providers inspect
soma providers test status
soma providers list --dir ./examples/providers
soma providers lint --dir ./examples/providers
soma providers status --dir ./examples/providers
soma doctor
soma setup check
soma package generate --check

プロバイダーツールは、cli オーバーレイで CLI への公開をオプトインします。動的な CLI フラグはプロバイダーの入力スキーマから生成されるため、生成されたプロバイダーカタログが、現在のアクション形式の信頼できる情報源となります。

安全性と信頼モデル

MCP の呼び出し元が、ツールの引数に API キー、OAuth シークレット、ベアラートークン、パスワード、その他の認証情報を指定することはありません。認証情報は環境変数、設定ファイル、appdata、または上流プロバイダーのランタイムに保存されます。

プロバイダーマニフェストは、ディスパッチ前に検証されます。レジストリは、サーフェスへのオプトイン、JSON Schema による入力検証、認証スコープ、宣言されたホスト機能、破壊的アクションの確認、応答サイズの上限、構造化されたプロバイダーエラーを適用します。Python、LangChain、LlamaIndex、TypeScript のプロバイダーファイルは、信頼されたローカルコードです。WASM プロバイダーはサンドボックス化された WASM プロバイダーパスを通じて実行されます。OpenAPI プロバイダーと MCP プロバイダーは、設定された上流サービスに信頼を委ねます。

認証

HTTP サーバーは、次の 4 つの認証ポリシーをサポートしています。

ポリシー	条件	動作
ループバック開発	ループバックへのバインド、またはループバックでの SOMA_MCP_NO_AUTH=true	認証ミドルウェアとスコープチェックは行いません。
ベアラートークン	SOMA_MCP_TOKEN が設定されている	/mcp と /v1/* で Authorization: Bearer <token> が必要です。
OAuth	SOMA_MCP_AUTH_MODE=oauth で、プロバイダーが 1 つ以上設定されている	ブラウザー経由の Google、Authelia、または GitHub ログインにより、JWT ベアラートークンが発行されます。
信頼されたゲートウェイ	ループバック以外で SOMA_NOAUTH=true が設定されている	上流ゲートウェイが責任を担うため、ローカル認証とスコープチェックは無効になります。

起動時のガードは、ベアラートークン、OAuth、または信頼されたゲートウェイのいずれかが設定されていない場合、ループバック以外への未認証バインドを拒否します。/health、/readyz、/status、/openapi.json は設計上公開されており、安全なランタイムメタデータのみを返します。

認証モデルの詳細については、docs/AUTH.md を参照してください。

設定

値は config.toml、ローカルの appdata ファイル、環境変数から読み込まれます。 明示的に設定された環境変数が優先されます。組み込みのオフラインプロバイダーは 実際の認証情報なしで動作しますが、生成されるプロジェクトでは、実際の アップストリーム／プラットフォームの認証情報を必須として指定してください。

変数	必須	デフォルト	説明
SOMA_API_URL	いいえ	空	デプロイされたプラットフォーム API またはアップストリームサービスの URL です。空の場合はスタブ／オフライン動作になります。
SOMA_API_KEY	いいえ	空	ベアラートークンまたはアップストリームサービスの API キーです。
SOMA_PROVIDER_DIR	いいえ	providers	ドロップインプロバイダーファイルを検索するディレクトリです。相対パスは現在の作業ディレクトリを基準に解決されます。
SOMA_MCP_HOST	いいえ	127.0.0.1	HTTP サーバーのバインド先ホストです。
SOMA_MCP_PORT	いいえ	40060	HTTP サーバーのバインド先ポートです。
SOMA_MCP_SERVER_NAME	いいえ	soma	クライアントに通知される MCP サーバー名です。
SOMA_MCP_NO_AUTH	いいえ	false	ループバック開発用に認証を無効にします。
SOMA_NOAUTH	いいえ	false	信頼されたゲートウェイ向けの、非ループバックでの認証なしモードです。
SOMA_MCP_TOKEN	ベアラー	空	静的ベアラートークンです。
SOMA_MCP_ALLOWED_HOSTS	いいえ	空	Host ヘッダーに追加で許可する値をカンマ区切りで指定します。
SOMA_MCP_ALLOWED_ORIGINS	いいえ	空	CORS で追加許可するオリジンをカンマ区切りで指定します。
SOMA_MCP_TRACE_HEADERS	いいえ	off	信頼された受信 HTTP トレースの抽出です。off、trusted、trusted-with-baggage のいずれかを指定します。
SOMA_MCP_AUTH_MODE	いいえ	bearer	bearer または oauth です。
SOMA_MCP_PUBLIC_URL	OAuth	空	OAuth メタデータおよびコールバック用の公開 URL です。
SOMA_MCP_GOOGLE_CLIENT_ID	OAuth	空	Google OAuth クライアント ID です。
SOMA_MCP_GOOGLE_CLIENT_SECRET	OAuth	空	Google OAuth クライアントシークレットです。
SOMA_MCP_AUTHELIA_ISSUER_URL	Authelia	空	HTTPS の Authelia OIDC 発行者 URL です。
SOMA_MCP_AUTHELIA_CLIENT_ID	Authelia	空	Authelia OIDC クライアント ID です。
SOMA_MCP_AUTHELIA_CLIENT_SECRET	Authelia	空	Authelia OIDC クライアントシークレットです。
SOMA_MCP_GITHUB_CLIENT_ID	GitHub	空	GitHub OAuth App のクライアント ID です。
SOMA_MCP_GITHUB_CLIENT_SECRET	GitHub	空	GitHub OAuth App のクライアントシークレットです。
SOMA_MCP_AUTH_DEFAULT_PROVIDER	いいえ	最初に設定されたプロバイダー	リクエストで provider が省略された場合に使用するプロバイダーです。自動選択の優先順位は Google、Authelia、GitHub です。
SOMA_MCP_AUTH_ADMIN_EMAIL	OAuth	空	初期／管理者 OAuth メールアドレスです。
RUST_LOG	いいえ	info	ログフィルターです。Stdio モードでは JSON-RPC が破損しないよう、ノイズの多いログを抑制します。

サーバーがループバックにバインドされているか、信頼されたゲートウェイが 信頼されていないクライアントからのトレースヘッダーを削除または上書きする場合を除き、 SOMA_MCP_TRACE_HEADERS=off のままにしてください。 ベアラー／OAuth 認証だけでは、その信頼境界にはなりません。受信専用の トレースヘッダー契約の詳細については、docs/TRACE_CONTEXT.md を参照してください。

サンプル：

• シークレット、URL、実行時環境変数については .env.example を参照してください。
• シークレットではないデフォルト値については config.soma.toml を参照してください。

プロバイダーのコールバックパスは、デフォルトで /auth/google/callback、 /auth/authelia/callback、/auth/github/callback です。コールバックとスコープの 上書き設定については docs/ENV.md に記載されています。GitHub OAuth App は アップストリームのリフレッシュトークンを提供しないため、GitHub 認証済みのセッションには ローカルのリフレッシュトークンが付与されず、アクセストークンの有効期限が切れた後は 再度サインインする必要があります。プロバイダーの選択とセキュリティの詳細については、 docs/AUTH.md を参照してください。

開発

# Build profiles
cargo build --bin soma --no-default-features --features local-adapter
cargo build --bin soma --no-default-features --features server
cargo build --bin soma --features full

# Run checks
cargo fmt -- --check
cargo clippy --all-targets -- -D warnings
cargo nextest run
cargo xtask contract-audit
cargo xtask generate-provider-surfaces --check

# Common just recipes
just dev                 # loopback HTTP server with local no-auth
just mcp                 # stdio MCP
just greet               # CLI smoke test
just doctor              # pre-flight check
just build-local         # local adapter binary
just build-full          # web assets + full platform binary
just verify              # fmt, lint, check, test
just check-docs          # generated docs/metadata current
just scaffold-contract-check
just validate-plugin

cargo xtask ci は、ローカル CI の主要な一連の処理を実行します。 cargo-nextest、taplo、cargo-audit などのオプションツールは、 インストールされている場合に使用されます。

ワークスペースのレイアウト

Cargo メンバーは 41 個です。

パス	内容
crates/soma/*	このサーバーの製品コード — ドメイン、アプリケーション、設定、クライアント、API、CLI、MCP、ランタイム、インテグレーション、パレット、Web、テストサポート
crates/shared/*	他のサーバーが利用する再利用可能なエンジンクレート — 認証、MCP（クライアント／サーバー／プロキシ／ゲートウェイ）、provider-core、provider-adapters、http-api、http-server、オブザーバビリティ、openapi、セルフアップデート、トレース、codemode、cli-core、および cortex/ingest-core などの名前空間付き再利用可能ファミリー
crates/integrations/*	上流サービスとのブリッジ — gotify、unifi
apps/soma	soma バイナリとそのインテグレーションテスト。apps/ 配下で唯一の Cargo メンバーです — apps/web（Next.js）と apps/palette（アセット）は Rust クレートではありません。
packages/python	pyo3 Python プロバイダープラットフォーム（abi3-py311）
xtask	リポジトリ内のすべての自動化。scripts/*.py は xtask を呼び出す薄いラッパーです

rmcp は厳密に固定されています — [workspace.dependencies] 内の rmcp = { version = "=3.1.0", default-features = false } で指定し、 TOML では相互参照できないため、rmcp-client エイリアスのエントリーにも 重複して指定しています。両方をまとめて更新してください。

[workspace.package] が Rust エディションと MSRV の信頼できる情報源です。新しい メンバーは edition.workspace = true と rust-version.workspace = true により、 edition = "2024" と rust-version = "1.97.1" を継承します。共有クレートも ワークスペースの lint を継承するため、アーキテクチャとモジュールレイアウトに関する ポリシーを全体で一貫させられます。

クライアント設定

Streamable HTTP：

{
  "mcpServers": {
    "soma": {
      "url": "http://localhost:40060/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Stdio：

{
  "mcpServers": {
    "soma": {
      "command": "/path/to/soma",
      "args": ["mcp"],
      "env": {
        "SOMA_API_URL": "https://api.example.com",
        "SOMA_API_KEY": "YOUR_API_KEY",
        "RUST_LOG": "warn"
      }
    }
  }
}

プロジェクトを生成する場合は、soma、SOMA_*、ツール名、スコープ、 パスを生成されたサービス名に置き換えてください。

プラグインのインターフェース

このリポジトリには、Claude Code、Codex、Gemini 向けに、共有 Soma プラグインパッケージが plugins/soma に 1 つ含まれています。プラグインのマニフェストにはバージョンがなく、 リリースツールが git の状態からバージョンの識別情報を導き出します。このプラグインパッケージは ローカル stdio アダプターを利用でき、appdata と環境ファイルのセットアップ／診断機能を備えています。

主なドキュメント：

• docs/PLUGINS.md
• plugins/soma/.codex-plugin/README.md
• plugins/soma/skills/soma/SKILL.md
• plugins/soma/skills/scaffold-project/SKILL.md

配布契約

soma リリースコンポーネントは release/components.toml で定義されています。バージョンを含む 成果物は、Rust パッケージ、Cargo.lock、server.json、npm パッケージ、 生成された OpenAPI メタデータ、OCI イメージ識別子、変更履歴の間で バージョンを一致させる必要があります。

プラグインのマニフェストにはバージョンを記載しません。マーケットプレイスとプラグインの リリース識別情報は git／パッケージのメタデータから導き出されます。一方、server.json と 生成されたプロバイダーインターフェースのドキュメントには、現在出荷されているランタイムの インターフェースが記載されます。リリースメタデータを公開する前に、 cargo xtask check-version-sync、cargo xtask generate-provider-surfaces --check、 cargo xtask check-docs を実行してください。

Web UI

web 機能は、soma-web にバンドルされた静的エクスポートを提供します。 編集可能なフロントエンドのソースは apps/web にあり、 cargo xtask sync-web-source がそのソースを Rust クレートのバンドルにコピーします。

便利なコマンド：

cargo xtask build-web
cargo xtask sync-web-source
cargo xtask check-web-source-sync
pnpm -C apps/web validate

人間向けの UI が不要な生成プロジェクトでは、web を含まない local-adapter、server、またはカスタム機能セットを使用してください。

デプロイ

フルプラットフォームプロファイルは、デプロイ可能な単一の soma バイナリを想定して設計されています。 このリポジトリには、Docker と Compose のサンプルも含まれています。

• config/Dockerfile
• docker-compose.prod.yml
• entrypoint.sh

生成したプロジェクトを調整する際は、標準バイナリ名、公開ポート、ヘルスチェックのポート、 イメージラベル、サービスのユーザー／グループ、データボリューム、必須の環境変数を 確認してください。スキャフォールド検証ツールではスキャフォールド固有の成果物をいくつか検出できますが、 イメージを公開する前に、デプロイ用ファイルをサービス固有の観点で確認する必要があります。

ドロップインプロバイダーだけでは不十分な場合

新しい機能の多くは、まずプロバイダーファイルとして実装してください。再利用可能なクレート境界、より豊富なサービス状態、カスタムクライアント、バックグラウンドジョブ、専用のパッケージ識別情報、または細かく調整したトランスポート動作が必要な場合は、ネイティブ Rust またはスキャフォールドされたプロダクトを選択してください。

生成されたプロダクトでは、まずプロファイル対応のチェックリストを出力してください。

cargo xtask scaffold --adapt-plan ../generated/myservice-mcp

次に、繰り返し発生するアクションの配線に使える、レビュー可能なスターター成果物を生成してください。

cargo xtask scaffold \
  --write-action-starters ../generated/myservice-mcp \
  --actions actions.json

これにより、生成されたプロジェクトに docs/action-starters/ が作成され、アクションのメタデータ、MCP ディスパッチ、CLI のバリエーション、サービスのスタブ、テストカバレッジのスニペットが格納されます。

1. プロバイダーファイルの方法では不十分な場合に限り、crates/soma/client/src/client.rs のスタブクライアントを置き換えてください。
2. ドメインロジックは crates/soma/application/src/service.rs または用途に特化したサービスモジュールに配置してください。
3. ネイティブのプロバイダー／アクションのメタデータを登録し、MCP、CLI、REST、ドキュメント、プラグインがレジストリ駆動のままになるようにしてください。
4. MCP スキーマドキュメント、プロバイダーサーフェスドキュメント、OpenAPI を再生成し、生成される各サーフェスにプロバイダーレジストリが反映されるようにしてください。
5. REST ハンドラーを追加するのはインフラストラクチャのルートに限り、ビジネスアクションはレジストリに基づく直接ルートのままにしてください。
6. crates/soma/config/src/config.rs の設定フィールドと環境変数のプレフィックスを更新してください。
7. .env.example、config.soma.toml、プラグインのオプション、セットアップのマッピングを更新してください。
8. server.json、プラグインのメタデータ、リポジトリの URL、Docker ラベル、リリースのメタデータを更新してください。
9. MCP ディスパッチ、CLI の解析、REST ルート、プロバイダーの読み込み、サービスの動作に関するテストを追加してください。
10. 生成／エクスポートされたプロジェクトでは、スキャフォールドの検証に加えて、 プロジェクト固有の品質チェックも実行してください。

公開リポジトリでは、公開前に、追跡対象のドキュメント、生成されたメタデータ、CI ランナーの設定、シークレットスキャンの許可リストも確認してください。

トラブルシューティング

• soma doctor は、ローカル設定、appdata、接続状態を確認します。
• soma providers validate は、読み込み済みの実行中レジストリに対して、プロバイダーマニフェストとコンパイル済みスキーマを検証します。
• soma providers inspect は、プロバイダーサーフェス、機能の状態、生成されたアクション一覧を表示します。
• soma providers list|lint|status は、レジストリを読み込まず、ハンドラーも実行せずに、ディスク上のドロップインプロバイダーファイルを調べます。ランタイムが TS/WASM/MCP/OpenAPI プロバイダーに触れる前に安全に実行できます。詳しくは docs/PROVIDERS.md を参照してください。
• Stdio モードでは、JSON-RPC が破損しないようログが抑制されます。起動時の大量のエラーを調査する場合は、HTTP モードまたはファイルログを使用してください。
• 生成されたドキュメントにずれがある場合は、cargo xtask generate-provider-surfaces --write を実行してから、--check コマンドを再実行してください。

関連サーバー

• runifi - UniFi コントローラーの REST API ブリッジです。
• rtailscale - デバイス、ユーザー、テールネット操作向けの Tailscale API ブリッジです。
• unraid - Unraid モノレポです。Python および Rust の GraphQL MCP サーバーと Unraid プラグインを含みます。
• rapprise - 多数の配信バックエンドに対応した Apprise 通知ファンアウトブリッジです。
• rgotify - 送信、メッセージ、アプリ、クライアント向けの Gotify プッシュ通知ブリッジです。
• rarcane - コンテナーおよび関連リソース向けの Arcane Docker 管理ブリッジです。
• yarr - Sonarr、Radarr、Prowlarr、Plex、および関連サービス向けのメディアスタックブリッジです。
• rytdl - メディアのダウンロードとメタデータのワークフローサーバーです。
• synapse - スカウトおよびフラックスアクション向けのローカル Synapse ワークフローサーバーです。
• cortex - Syslog とホームラボのログ集約用 MCP サーバーです。
• axon - RAG、クロール、スクレイピング、抽出、セマンティック検索のプロジェクトです。
• labby - ホームラボのコントロールプレーンおよび MCP ゲートウェイのプロジェクトです。
• lumen - ローカルでセマンティックコード検索を行う MCP サーバーです。

ドキュメント

トピック	ドキュメント
アーキテクチャとレイヤー構成	docs/ARCHITECTURE.md, docs/PATTERNS.md
Cortex 共有クレートの抽出	docs/cortex-extraction/README.md, ADR 0014
動的プロバイダーランタイム	docs/specs/dynamic-provider-runtime.md, docs/generated/provider-surfaces.md
プロバイダーマニフェストの契約	docs/contracts/provider-manifest.schema.json, docs/contracts/examples/provider-manifests
スキャフォールドのワークフロー	docs/SCAFFOLD.md, docs/CARGO_GENERATE.md
スキャフォールドのインテント契約	docs/specs/scaffold-intent-handoff.md, docs/contracts/scaffold-intent.schema.json
MCP アクションスキーマ	docs/MCP_SCHEMA.md
REST OpenAPI	docs/generated/openapi.json
認証	docs/AUTH.md
プラグイン	docs/PLUGINS.md
リリース／バージョン管理	release/components.toml, docs/MCP-REGISTRY-PUBLISH-GUIDE.md
自動化	xtask/README.md, scripts/README.md
テスト	apps/soma/tests/README.md

検証

製品ランタイムのゲート：

cargo xtask check-docs
cargo xtask generate-provider-surfaces --check
cargo xtask check-schema-docs --check
cargo xtask check-openapi --check
cargo xtask validate-plugin-layout
cargo xtask check-version-sync
just verify

スキャフォールド／テンプレートのゲートは別のレーンです。変更がスキャフォールドの契約、cargo-generate の後処理、または生成されたプロジェクトの出力に関わる場合は、実行してください。

cargo xtask check-scaffold-intent-contract
cargo xtask scaffold --verify ../generated/myservice-mcp
cargo xtask check-cargo-generate

反復作業では対象を絞ったチェックを使用し、その後、リリース前に製品全体と影響を受けるスキャフォールドのゲートを実行してください。

ライセンス

このプロジェクトの Dinglebear が著作権を有する部分は、AGPL-3.0-only の下でライセンスされています。AGPL 以外の条件が必要な組織向けに、別途商用ライセンスを利用できます。サードパーティの素材は、それぞれ元のライセンスが適用されます。LICENSING.md を参照してください。