API 參考文件

開發者文件

OSOP MCP 伺服器、SDK、CLI 及格式轉換器的完整參考文件。

MCP 伺服器
pip install osop-mcp
Python CLI
pip install osop
JS/TS SDK
npm install @osop/sdk
Python SDK
pip install osop-sdk

MCP 工具

透過 Model Context Protocol (MCP) 提供 9 個工具。支援 GitHub Copilot、Cursor、Claude Desktop 及任何 MCP 相容客戶端。

# Install and run the MCP server
$ pip install osop-mcp
$ python -m osop_mcp                    # stdio transport
$ OSOP_MCP_TRANSPORT=sse python -m osop_mcp  # SSE transport (port 8080)

# Or via Docker
$ docker run -i ghcr.io/archie0125/osop-mcp
osop.validate

根據 JSON Schema 驗證 .osop 工作流程

參數
contentstring?要驗證的 YAML 內容
file_pathstring?.osop 檔案路徑
strictboolean將警告視為錯誤(預設:false)
回傳: 含行號的錯誤與警告
osop.risk_assess

分析工作流程的安全風險(0-100 分)

參數
contentstring?要評估的 YAML 內容
file_pathstring?.osop 檔案路徑
回傳: { overall_score, verdict: safe|caution|warning|danger, findings[] }
osop.run

以指定輸入執行工作流程

參數
contentstring?要執行的 YAML 內容
file_pathstring?.osop 檔案路徑
inputsobject?工作流程輸入值
dry_runboolean模擬執行,不產生副作用(預設:false)
timeout_secondsinteger最長執行時間(預設:300)
回傳: 執行結果,包含節點輸出與最終狀態
osop.render

將工作流程渲染為視覺化圖表

參數
contentstring?要渲染的 YAML 內容
file_pathstring?.osop 檔案路徑
formatstring"mermaid" | "ascii" | "svg"(預設:"mermaid")
directionstring"TB" | "LR"(預設:"TB")
回傳: 指定格式的圖表
osop.test

執行工作流程測試案例

參數
contentstring?包含測試案例的 YAML
file_pathstring?.osop 檔案路徑
filterstring?篩選測試的模式
verboseboolean詳細輸出(預設:false)
回傳: 通過/失敗結果與測試詳情
osop.optimize

根據執行歷史建議工作流程改進方案

參數
contentstring?要分析的 YAML
file_pathstring?.osop 檔案路徑
applyboolean回傳優化後的 YAML 或僅建議(預設:false)
回傳: 優化建議或優化後的工作流程 YAML
osop.import

將外部格式轉換為 OSOP

參數
contentstring?來源內容
file_pathstring?來源檔案路徑
source_formatstring"github-actions" | "bpmn" | "airflow" | "temporal" | "postman" | "openapi"
回傳: 有效的 OSOP YAML
osop.export

將 OSOP 轉換為外部格式

參數
contentstring?OSOP YAML
file_pathstring?.osop 檔案路徑
target_formatstring"github-actions" | "bpmn" | "airflow" | "temporal"
回傳: 目標格式的內容
osop.report

從工作流程 + 執行日誌產生 HTML/文字報告

參數
contentstring?OSOP YAML 內容
file_pathstring?.osop 檔案路徑
log_contentstring?OSOPLOG YAML 內容
log_file_pathstring?.osoplog 檔案路徑
formatstring"html" | "text"(預設:"html")
回傳: 獨立的 HTML 或文字報告

MCP 設定

Claude Desktop — claude_desktop_config.json
{
  "mcpServers": {
    "osop": {
      "command": "python",
      "args": ["-m", "osop_mcp"]
    }
  }
}
Claude Code — .mcp.json
{
  "mcpServers": {
    "osop": {
      "command": "python",
      "args": ["-m", "osop_mcp"],
      "env": { "OSOP_LOG_LEVEL": "INFO" }
    }
  }
}

JavaScript / TypeScript SDK

TypeScript 優先,提供完整型別定義。支援 Node.js 與瀏覽器。

import { OsopClient } from "@osop/sdk";

const client = new OsopClient({ baseUrl: "http://localhost:8080" });

// Validate a workflow
const result = await client.validate({ filePath: "deploy.osop.yaml" });
console.log(result.valid); // true

// Run with dry-run
const execution = await client.run({
  filePath: "deploy.osop.yaml",
  inputs: { environment: "staging" },
  dryRun: true,
});
console.log(execution.status); // "completed"

// Render as Mermaid diagram
const diagram = await client.render({
  filePath: "deploy.osop.yaml",
  format: "mermaid",
});
建構函式選項
baseUrlstringOSOP 伺服器 URL(必填)
apiKeystring?驗證用 API 金鑰
timeoutnumber?請求逾時毫秒數(預設:30000)

Python SDK

同步與非同步客戶端。需要 Python 3.11+。

from osop_sdk import OsopClient, AsyncOsopClient

# Synchronous
client = OsopClient(base_url="http://localhost:8080")
result = client.validate(file_path="deploy.osop.yaml")
print(result.valid)  # True

execution = client.run(
    file_path="deploy.osop.yaml",
    inputs={"environment": "staging"},
    dry_run=True,
)
print(execution.status)  # "completed"

# Async
async_client = AsyncOsopClient(base_url="http://localhost:8080")
result = await async_client.validate(file_path="workflow.osop.yaml")

CLI 參考

需要 Python 3.11+。所有指令接受檔案路徑或標準輸入。

$ pip install osop

$ osop validate workflow.osop.yaml        # Validate against schema
$ osop validate workflow.osop.yaml --strict  # Warnings = errors

$ osop render workflow.osop.yaml          # Mermaid diagram
$ osop render workflow.osop.yaml --format ascii  # ASCII art

$ osop run workflow.osop.yaml             # Execute
$ osop run workflow.osop.yaml --dry-run   # Simulate

$ osop risk workflow.osop.yaml            # Security risk score (0-100)

$ osop test workflow.osop.yaml            # Run test cases
$ osop test workflow.osop.yaml --verbose  # Detailed output

$ osop report workflow.osop.yaml --log run.osoplog.yaml -o report.html

格式轉換器(osop-interop)

將現有工作流程匯入 OSOP 或匯出為外部格式。

格式匯入匯出
GitHub Actions
BPMN
Apache Airflow
Temporal
Postman Collections
OpenAPI 3.x
$ pip install osop-interop

# Import
$ osop import deploy.yml --from github-actions -o deploy.osop.yaml
$ osop import process.bpmn --from bpmn -o process.osop.yaml
$ osop import dag.py --from airflow -o pipeline.osop.yaml

# Export
$ osop export workflow.osop.yaml --to github-actions -o .github/workflows/deploy.yml
$ osop export workflow.osop.yaml --to airflow -o dags/pipeline.py

環境變數

變數說明預設值
OSOP_MCP_TRANSPORTMCP 傳輸協定stdio
OSOP_MCP_PORTSSE 傳輸埠號8080
OSOP_LOG_LEVEL日誌等級INFO
OSOP_MCP_URLMCP 伺服器 URL(用於技能)
OSOP_APPROVAL_MODE核准閘道行為manual