workflows-mcp-server

---

概要

ローカルの YAML ファイルを基盤とする、LLM エージェント向けの宣言型ワークフローライブラリです。名前とバージョンが付いた複数ステップのプレイブックを保存、一覧表示、取得できます。各プレイブックは MCP サーバー／ツールの呼び出しを順番に実行し、恒久的な再利用や一度限りの一時実行に利用できます。YAML ファイルへの編集は自動的に反映されます。

ツール

ツール	説明
workflow_list	インデックス内のすべての恒久ワークフローを一覧表示します。キーワード、カテゴリ、タグで絞り込むこともできます。
workflow_get	名前を指定してワークフロー定義全体を取得し、先頭にグローバル指示を追加します。
workflow_create	新しい恒久ワークフロー YAML をライブラリに書き込みます。
workflow_create_temp	一時的なワークフローの下書きを書き込みます。インデックスには登録されますが、一覧表示の結果からは除外され、削除されるまで保持されます。
workflow_delete	解決された対象をユーザーが確認した後、名前と任意のバージョンを指定して、恒久ワークフローまたは一時的な下書きを削除します。

機能のリファレンス

workflow_list _ツール

• query（名前と説明）、category（部分一致）、tags（すべて一致する必要があります）による任意のフィルターに対応しています。大文字と小文字は区別されません。一時的な下書きは一覧表示されません。
• 名前の昇順、次にバージョンの降順で並べ替えられます。結果が空の場合は、適用されたフィルターを示す notice が返されます。
• includeTools: true を指定すると、各ワークフローの一意な server/tool の組み合わせが追加されます。

---

workflow_get _ツール

• name と、任意の semver 形式の version を指定します。version を省略すると、下書きを含む利用可能な最高バージョンが取得されます。
• ワークフロー全体、その source（permanent または temp）、および global_instructions.md の globalInstructions（存在しない場合は null）を返します。not_found または version_not_found で失敗することがあります。
• {{input.foo}} などのテンプレートプレースホルダーはそのまま返されます。サーバーによる補間は行われません。

---

workflow_create _ツール

• name、semver version、description、author、category、steps（および任意の tags）を指定します。categories/<category>/ の下に name@version ごとに1つのファイルとして保存され、作成日と更新日が記録されます
• key（name@version）と filePath を返します。永続ワークフローまたはドラフトがそのキーを保持している場合は already_exists、または invalid_input、write_failed で失敗します

---

workflow_create_temp _ツール

• category を除く workflow_create のフィールドを指定します。temp/ の下に保存され、workflow_get で取得できますが、一覧には表示されません。また、workflow_delete で削除されるまで保持されます
• status は created です。同じキーのドラフトを置き換えた場合は overwritten となり、そのドラフトの created_date が引き継がれます。キーが永続ワークフローに保持されている場合は already_exists で失敗します

---

workflow_delete _ツール

• name と任意の version を指定します（省略時は、永続ワークフローとドラフト全体で最も高いバージョン）。何かを削除する前に、ユーザーが解決された name@version、ソース、ファイルを確認します。そのため、elicitation に対応していないクライアントからは削除できません
• 削除されたワークフローの source を返します。同じキーを宣言する別のファイルが代わりに使用される場合は、notice も返します。cancelled、confirmation_invalid（プロンプトが発行されていない、すでに回答済み、発行から10分以上経過している、または別の呼び出し元に発行された）、target_changed（ユーザーに表示した後でファイルまたは内容が変更された）、not_found で失敗します

機能

@cyanheads/mcp-ts-core を基盤とし、stdio および Streamable HTTP トランスポート、切り替え可能な認証（none / jwt / oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングを備えた構造化ログに対応しています。

ワークフローライブラリ：

• categories/ と temp/ の下にある YAML ファイルはインデックス作成時に検証されます。無効なファイルはスキップされてログに記録されますが、サーバーがクラッシュすることはありません
• name@version をキーとするインメモリインデックスは、ファイル名ではなく各ファイルの内容から読み込まれ、デバウンス付きの再帰ウォッチャーによって最新の状態に保たれます。同じキーの場合は、永続ワークフローがドラフトより優先されます
• バージョンはすべての箇所で正規化された semver です。先頭の v、前後の空白、ビルドメタデータは取り除かれるため、v1.0.0+build.5 は 1.0.0 として保存、キー化、検索されます
• 作成と削除は一度に1件ずつ実行されるため、存在確認の結果は書き込みが完了するまで維持されます。ファイル名には name@version のハッシュが含まれるため、スラッグが一致するキー同士が同じファイルを共有することはありません
• 外部ツールやデバッグ用に、再構築のたびに _index.json スナップショットが書き込まれます

エージェントに適した出力：

• 出力を判別可能な形式にしています。すべての workflow_get 応答に source: "permanent" | "temp" が含まれ、失敗時には型付きの reason コード（not_found、version_not_found、already_exists、cancelled、confirmation_invalid、target_changed、index_unavailable、…）が含まれるため、呼び出し元はエラー文字列を解析せず、データに基づいて分岐できます
• 追加のラウンドトリップは不要です。workflow_get はワークフロー定義とともに、常に同じ応答で globalInstructions を返します
• 応答を整形できます。workflow_list の任意の includeTools フラグは、ワークフローで使用される一意の server/tool ペアを事前に導出します。結果が空の場合は何も返さず、適用されたフィルターと条件を広げるためのヒントを返します

---

はじめに

API キーは不要です。デフォルトでは、サーバーはローカルの workflows-yaml/ ディレクトリから読み込みます。

MCP クライアントの設定ファイルに、次の内容を追加してください：

{
  "mcpServers": {
    "workflows-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/workflows-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "WORKFLOWS_DIR": "/absolute/path/to/your/workflows-yaml"
      }
    }
  }
}

または npx を使用する場合（Bun は不要です）：

{
  "mcpServers": {
    "workflows-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/workflows-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "WORKFLOWS_DIR": "/absolute/path/to/your/workflows-yaml"
      }
    }
  }
}

または Docker を使用する場合：

{
  "mcpServers": {
    "workflows-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-v", "/absolute/path/to/your/workflows-yaml:/workflows-yaml",
        "-e", "WORKFLOWS_DIR=/workflows-yaml",
        "ghcr.io/cyanheads/workflows-mcp-server:latest"
      ]
    }
  }
}

Streamable HTTP を使用するには、トランスポートを設定してサーバーを起動します：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

ワークフローの初期投入

このリポジトリには、categories/ の下に整理されたサンプルワークフローを含む workflows-yaml/ ディレクトリが付属しています。これらは、すぐにベースとして使用できます。workflows-yaml/global_instructions.md ファイルには、サーバーがすべての workflow_get 応答に先頭付加する指示が含まれています。編集して、エージェント向けの全体的なガイダンスを設定してください。

前提条件

• Bun v1.4.0 以降（または Node.js v24 以降）。
• YAML ワークフローファイルを含むローカルディレクトリ（または同梱の workflows-yaml/ シードを使用）。

インストール

1. リポジトリをクローンします：

git clone https://github.com/cyanheads/workflows-mcp-server.git

2. ディレクトリに移動します：

cd workflows-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env if needed — most settings have defaults

---

設定

変数	説明	デフォルト
WORKFLOWS_DIR	ワークフローのルートディレクトリへの絶対パスまたは相対パス。	./workflows-yaml
GLOBAL_INSTRUCTIONS_PATH	グローバル指示を記述した Markdown ファイルへのパス。設定されていない場合は WORKFLOWS_DIR から導出されます。	<WORKFLOWS_DIR>/global_instructions.md
WATCHER_DEBOUNCE_MS	インデックスを再構築する前にファイルシステムの変更イベントをデバウンスする時間（ミリ秒）。整数で、範囲は 0～2147483647 です。	500
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_SESSION_MODE	HTTP セッション：auto または stateful。workflow_delete の確認プロンプトには有効なセッションが必要なため、stateless で HTTP を起動すると設定エラーになります。stdio では無視されます。	src/index.ts で宣言されている stateful
MCP_AUTH_MODE	認証モード：none、jwt、または oauth。	none
MCP_REQUEST_STATE_KEY	確認ラウンドが持つ requestState を署名します（32 バイト以上、全インスタンスで同一の値。例：openssl rand -base64 32）。サーバーが署名していない状態は、ハンドラーの実行前に拒否されます。workflow_delete のラウンドには確認 ID が含まれるため、HTTP 環境で設定してください。	未設定
MCP_LOG_LEVEL	ログレベル（RFC 5424）。	info
LOG_TOOL_FAILURE_PAYLOADS	失敗したツール呼び出しごとに、引数と結果をログに記録します。キー名に基づいて機密情報をマスキングし、LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（デフォルトは 16384）で上限を設定します。自由形式の値に含まれる機密情報はマスキングされません。	false
OTEL_ENABLED	OpenTelemetry インストルメンテーション（スパン、メトリクス、完了ログ）を有効にします。	false

オプションの上書き設定の全一覧は .env.example を参照してください。

---

サーバーの実行

ローカル開発

• ビルドして実行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• チェックとテストを実行：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t workflows-mcp-server .
docker run --rm \
  -v /path/to/workflows-yaml:/workflows-yaml \
  -e WORKFLOWS_DIR=/workflows-yaml \
  -p 3010:3010 \
  workflows-mcp-server

Dockerfile のデフォルトは HTTP トランスポート、ステートフルセッションモード（必須。上記の MCP_SESSION_MODE を参照）、および /var/log/workflows-mcp-server へのログ出力です。OpenTelemetry のピア依存関係はデフォルトでインストールされます。省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

---

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() エントリーポイント。ツールを登録し、ワークフローインデックスサービスを初期化します。
src/config/	Zod を使った、サーバー固有の環境変数の解析と検証。
src/mcp-server/tools/	ツール定義（*.tool.ts）。
src/services/workflow-index/	WorkflowIndexService — YAML の解析、インデックスの構築、ウォッチャー、semver による検索、書き込みヘルパー。
tests/	src/ に対応する単体テストと統合テスト。
workflows-yaml/	ワークフローライブラリのシード。永続ワークフロー用の categories/、一時的な下書き用の temp/、エージェント全体に適用される指示用の global_instructions.md が含まれます。

---

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジック内で try/catch を使わないでください。
• リクエスト単位のログ記録には ctx.log を使用します。
• 新しいツールは src/mcp-server/tools/definitions/index.ts のバレルを通じて登録します。
• ファイルシステム操作は、ツールハンドラーから直接行わず、WorkflowIndexService を通じて行います。

---

コントリビューション

Issue を歓迎します。提出する前にチェックとテストを実行してください：

bun run devcheck
bun run test

---

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。