API 參考文件
開發者文件
OSOP MCP 伺服器、SDK、CLI 及格式轉換器的完整參考文件。
MCP 伺服器
pip install osop-mcpPython CLI
pip install osopJS/TS SDK
npm install @osop/sdkPython SDK
pip install osop-sdkMCP 工具
透過 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 工作流程
參數
| content | string? | 要驗證的 YAML 內容 |
| file_path | string? | .osop 檔案路徑 |
| strict | boolean | 將警告視為錯誤(預設:false) |
回傳: 含行號的錯誤與警告
osop.risk_assess分析工作流程的安全風險(0-100 分)
參數
| content | string? | 要評估的 YAML 內容 |
| file_path | string? | .osop 檔案路徑 |
回傳: { overall_score, verdict: safe|caution|warning|danger, findings[] }
osop.run以指定輸入執行工作流程
參數
| content | string? | 要執行的 YAML 內容 |
| file_path | string? | .osop 檔案路徑 |
| inputs | object? | 工作流程輸入值 |
| dry_run | boolean | 模擬執行,不產生副作用(預設:false) |
| timeout_seconds | integer | 最長執行時間(預設:300) |
回傳: 執行結果,包含節點輸出與最終狀態
osop.render將工作流程渲染為視覺化圖表
參數
| content | string? | 要渲染的 YAML 內容 |
| file_path | string? | .osop 檔案路徑 |
| format | string | "mermaid" | "ascii" | "svg"(預設:"mermaid") |
| direction | string | "TB" | "LR"(預設:"TB") |
回傳: 指定格式的圖表
osop.test執行工作流程測試案例
參數
| content | string? | 包含測試案例的 YAML |
| file_path | string? | .osop 檔案路徑 |
| filter | string? | 篩選測試的模式 |
| verbose | boolean | 詳細輸出(預設:false) |
回傳: 通過/失敗結果與測試詳情
osop.optimize根據執行歷史建議工作流程改進方案
參數
| content | string? | 要分析的 YAML |
| file_path | string? | .osop 檔案路徑 |
| apply | boolean | 回傳優化後的 YAML 或僅建議(預設:false) |
回傳: 優化建議或優化後的工作流程 YAML
osop.import將外部格式轉換為 OSOP
參數
| content | string? | 來源內容 |
| file_path | string? | 來源檔案路徑 |
| source_format | string | "github-actions" | "bpmn" | "airflow" | "temporal" | "postman" | "openapi" |
回傳: 有效的 OSOP YAML
osop.export將 OSOP 轉換為外部格式
參數
| content | string? | OSOP YAML |
| file_path | string? | .osop 檔案路徑 |
| target_format | string | "github-actions" | "bpmn" | "airflow" | "temporal" |
回傳: 目標格式的內容
osop.report從工作流程 + 執行日誌產生 HTML/文字報告
參數
| content | string? | OSOP YAML 內容 |
| file_path | string? | .osop 檔案路徑 |
| log_content | string? | OSOPLOG YAML 內容 |
| log_file_path | string? | .osoplog 檔案路徑 |
| format | string | "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",
});建構函式選項
| baseUrl | string | OSOP 伺服器 URL(必填) |
| apiKey | string? | 驗證用 API 金鑰 |
| timeout | number? | 請求逾時毫秒數(預設: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_TRANSPORT | MCP 傳輸協定 | stdio |
| OSOP_MCP_PORT | SSE 傳輸埠號 | 8080 |
| OSOP_LOG_LEVEL | 日誌等級 | INFO |
| OSOP_MCP_URL | MCP 伺服器 URL(用於技能) | — |
| OSOP_APPROVAL_MODE | 核准閘道行為 | manual |