API Reference

Developer Documentation

Complete reference for the OSOP MCP server, SDKs, CLI, and format converters.

MCP Server

pip install osop-mcp

Python CLI

pip install osop

JS/TS SDK

npm install @osop/sdk

Python SDK

pip install osop-sdk

MCP Tools

9 tools exposed via Model Context Protocol (MCP). Works with GitHub Copilot, Cursor, Claude Desktop, and any MCP-compatible client.

# 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

Validate .osop workflow against JSON Schema

Parameters

content	string?	YAML content to validate
file_path	string?	Path to .osop file
strict	boolean	Treat warnings as errors (default: false)

Returns: Errors and warnings with line numbers

osop.risk_assess

Analyze workflow for security risks (0-100 score)

Parameters

content	string?	YAML content to assess
file_path	string?	Path to .osop file

Returns: { overall_score, verdict: safe|caution|warning|danger, findings[] }

osop.run

Execute workflow with given inputs

Parameters

content	string?	YAML content to execute
file_path	string?	Path to .osop file
inputs	object?	Workflow input values
dry_run	boolean	Simulate without side effects (default: false)
timeout_seconds	integer	Max execution time (default: 300)

Returns: Execution results with node outputs and final state

osop.render

Render workflow as visual diagram

Parameters

content	string?	YAML content to render
file_path	string?	Path to .osop file
format	string	"mermaid" \| "ascii" \| "svg" (default: "mermaid")
direction	string	"TB" \| "LR" (default: "TB")

Returns: Diagram in specified format

osop.test

Run workflow test cases

Parameters

content	string?	YAML with test cases
file_path	string?	Path to .osop file
filter	string?	Pattern to filter tests
verbose	boolean	Detailed output (default: false)

Returns: Pass/fail results with test details

osop.optimize

Suggest workflow improvements from execution history

Parameters

content	string?	YAML to analyze
file_path	string?	Path to .osop file
apply	boolean	Return optimized YAML vs suggestions only (default: false)

Returns: Optimization suggestions or optimized workflow YAML

osop.import

Convert external formats to OSOP

Parameters

content	string?	Source content
file_path	string?	Path to source file
source_format	string	"github-actions" \| "bpmn" \| "airflow" \| "temporal" \| "postman" \| "openapi"

Returns: Valid OSOP YAML

osop.export

Convert OSOP to external formats

Parameters

content	string?	OSOP YAML
file_path	string?	Path to .osop file
target_format	string	"github-actions" \| "bpmn" \| "airflow" \| "temporal"

Returns: Content in target format

osop.report

Generate HTML/text report from workflow + execution log

Parameters

content	string?	OSOP YAML content
file_path	string?	Path to .osop file
log_content	string?	OSOPLOG YAML content
log_file_path	string?	Path to .osoplog file
format	string	"html" \| "text" (default: "html")

Returns: Self-contained HTML or text report

MCP Configuration

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-first with full type definitions. Works in Node.js and browsers.

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",
});

Constructor Options

baseUrl	string	OSOP server URL (required)
apiKey	string?	API key for authentication
timeout	number?	Request timeout ms (default: 30000)

Python SDK

Sync and async clients. 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 Reference

Python 3.11+. All commands accept file paths or stdin.

$ 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

Format Converters (osop-interop)

Import existing workflows into OSOP or export to external formats.

Format	Import	Export
GitHub Actions	Yes	Yes
BPMN	Yes	Yes
Apache Airflow	Yes	Yes
Temporal	Yes	Yes
Postman Collections	Yes	—
OpenAPI 3.x	Yes	—

$ 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

Environment Variables

Variable	Description	Default
OSOP_MCP_TRANSPORT	MCP transport protocol	stdio
OSOP_MCP_PORT	SSE transport port	8080
OSOP_LOG_LEVEL	Logging level	INFO
OSOP_MCP_URL	MCP server URL (for skills)	—
OSOP_APPROVAL_MODE	Approval gate behavior	manual