Opscotch AI/LLM Overview

Purpose

The Opscotch AI/LLM integration is a comprehensive, portable knowledge artifact designed to equip an LLM with deep operational knowledge of the Opscotch system. It provides explicit, structured technical knowledge that enables an LLM to effectively work with Opscotch configurations, workflows, and operations.

Quick Start

One off:

• Configure Public MCP in your agent
• Configure Local Development MCP in your agent

Each session:

• Run this prompt
• Run this prompt

What's Included

The skill covers:

• Bootstrap Configuration: Understanding and writing bootstrap files for runtime initialization, deployment settings, licensing, and security controls
• Workflow Design: Creating, composing, and debugging workflows with steps, triggers, processors, and data flow
• Runtime Operations: Starting, stopping, and managing the Opscotch runtime environment
• Packaging: Building, signing, encrypting, and deploying workflow packages
• Testing: Writing and running tests for workflow validation
• Administration: Security, licensing, cryptography, and operational best practices

The Public Opscotch MCP tools cover:

• Opscotch thinking guidance
• documentation
• schema and programming API discovery
• workflow and bootstrap validation

The Local Development MCP tools cover:

• resource compilation testing
• executing unit tests
• executing integration tests

How to Use

There are two ways to integrate Opscotch with an AI/LLM.

1. Using the Public Opscotch MCP server (preferred)
2. Using the raw prompts

Public Opscotch MCP

The Public Opscotch MCP server is the canonical MCP server for Opscotch-specific prompt loading, schema access, schema validation, operational-context resolution, and other MCP-exposed assistance.

Add the Public Opscotch MCP server to your coding agent - this is different for each AI ecosystem (you'll need to do this yourself). The official endpoint is https://mcp.opscotch.ai/mcp (no authentication required because it is public).

Here is an example of adding it to OpenAI Codex:

Public MCP Skill Prompt

Once the MCP server is added to your agent, copy and paste this prompt:

We are working on an Opscotch app. It may be new and require planning, or it may be an existing app where we are adding a feature. 

This is a skill-priming prompt: comprehend it completely before starting. 

Always use the configured Public Opscotch MCP server at https://mcp.opscotch.ai/mcp, and prefer the configured MCP connection over ad hoc `curl` (or similar) commands when MCP access is available. The MCP server must already be configured in this agent; if it is not, stop and tell the operator. You may probe the url for liveliness, but don't fall back to using the non-MCP-configured mode.

At session start, call the MCP JSON-RPC `ping` method (method, not tool) and wait for the server to wake up; it may take a few tries. Then call `tools/list` and use tools (not resources) for capability discovery. 

Bootstrap your understanding with tool calls in this order: 
- `opscotch_get_guidance(role=system)`
- `opscotch_get_guidance(role=architect)`
- `opscotch_get_guidance(role=engineer)`. 

Use the Public Opscotch MCP whenever it can answer, inspect, resolve, or validate a question more directly than unsupported reasoning. 

After guidance is loaded, tell the operator: "Opscotch planning and designing skills are loaded and ready. What are we working on?" The operator may not know much about Opscotch, so provide a few suggestions for what they can ask next. If the operator starts talking about implementation, ask them to prime the Local Development MCP (reference: https://docs.opscotch.co/docs/current/llm/overview/#local-development-mcp)

Local Development MCP

The Local Development MCP is your AI execution bridge into your real local project.
The Public Opscotch MCP helps the AI reason correctly about architecture, schemas, and validation rules. The Local Development MCP lets the AI run local checks against your mounted code, tests, and fixtures.

In practice, this means your AI can do more than suggest changes. It can validate paths, run resource unit tests, run workflow integration tests, and execute resource scripts in a controlled runtime that matches your mounted workspace.

For a reliable development loop, treat Local Development MCP as part of initial setup, not as an optional add-on. Configure it at the start of a session so the AI can move directly from design decisions to verified execution results.

What it is:

• local-only MCP server running in Docker
• image: ghcr.io/opscotch/opscotch-local-development-mcp:latest
• endpoint inside the container: GET /mcp and POST /mcp

Required environment:

• OPSCOTCH_LEGAL_ACCEPTED (use the base64 acceptance blob as described in Running the runtime in Docker)

Start the local MCP server

Here is a minimal command that uses the default root mapping.

export OPSCOTCH_LEGAL_ACCEPTED='<base64-acceptance-blob>'

docker run --rm -p 18080:8080 \
  -e OPSCOTCH_LEGAL_ACCEPTED \
  -v /home/jeremy/dev/opscotch:/workspace:ro \
  -v /home/jeremy/dev/opscotch/community/opscotch-community/license-local.txt:/license/license.txt:ro \
  ghcr.io/opscotch/opscotch-local-development-mcp:latest

Then configure your AI client to use http://localhost:18080/mcp.

Optional configuration

Optional environment:

• OPSCOTCH_LOCAL_MCP_ROOTS_JSON (override logical roots to container paths)
• OPSCOTCH_LOCAL_MCP_LICENSE_FILE (override the single license file path; default /license/license.txt)

Default root mapping:

• "workspace": "/workspace"
• "artifacts": "/artifacts"

Override example:

-e OPSCOTCH_LOCAL_MCP_ROOTS_JSON='{"workspace":"/workspace","artifacts":"/artifacts"}'

Artifacts directory:

• artifacts is the local MCP output area for run logs, test output, and run metadata.
• In normal operation this can remain inside Docker at /artifacts; no host mount is required.
• If you want to inspect artifacts on the host, add:

-v /tmp/opscotch-local-mcp-artifacts:/artifacts

If you want the AI to generate a ready-to-run Docker command for your machine, copy and paste this prompt:

Generate a `docker run` command to start `ghcr.io/opscotch/opscotch-local-development-mcp:latest` on my machine.

Requirements:
- expose port 8080 or a port specified
- include `OPSCOTCH_LEGAL_ACCEPTED` as the base64 acceptance blob described in [Running the runtime in Docker](../administrating/agent#running-the-runtime-in-docker)
- mount my workspace directory to `/workspace` (read-only) - the workspace must contain all the files the operator wants to work with.
- mount my license file to `/license/license.txt` (read-only)

Return:
1. the exact `export OPSCOTCH_LEGAL_ACCEPTED=...` line I should run first, using the base64 acceptance blob
2. one complete `docker run` command I can copy and paste
3. a short example of what to set as workspace, license file, and artifacts paths

Do not return placeholders like `/path/to/...` in the final command unless I have not provided a path.
Ask me only for missing paths.

Here is an minimal example:
Here is an example:
docker run --rm -p 8080:8080 \
  -e OPSCOTCH_LEGAL_ACCEPTED='<base64-acceptance-blob>' \
  -v /path/to/users/workspace:/workspace:ro \
  -v /path/to/license-file.txt:/license/license.txt:ro \
  ghcr.io/opscotch/opscotch-local-development-mcp:latest 


Here is an fuller example:
docker run --rm -p 8080:8080 \
  -e OPSCOTCH_LEGAL_ACCEPTED='<base64-acceptance-blob>' \
  -e OPSCOTCH_LOCAL_MCP_ROOTS_JSON='{"workspace":"/workspace","artifacts":"/artifacts"}' \
  -e OPSCOTCH_LOCAL_MCP_LICENSE_FILE='/license/license.txt' \
  -v /path/to/users/workspace:/workspace:ro \
  -v /path/to/license-file.txt:/license/license.txt:ro \
  -v /tmp/opscotch-local-mcp-artifacts:/artifacts \
  ghcr.io/opscotch/opscotch-local-development-mcp:latest

If you expose a different host port, use that port in your MCP URL. This is different for each AI ecosystem (you'll need to do this yourself)

Here is an example of adding it to OpenAI Codex:

Local Development MCP Skill Prompt

Once your local development server is up and running, prime your agent with this skill prompt:

We are working on an Opscotch app in a local development environment. This is a skill priming prompt: comprehend it completely before starting.

Always use the configured Opscotch Local Development MCP server for execution-time work (tests, script execution, and local path diagnostics). Prefer the configured MCP connection over ad hoc shell commands when MCP tools can do the job. If the local MCP server is not configured in this agent, stop and tell the operator.

The Opscotch Local Development MCP server requires the Public Opscotch MCP server at https://mcp.opscotch.ai/mcp - check to see if this has been configured as a MCP server first. If it has not, refer the operator to https://docs.opscotch.co/docs/current/llm/overview/#public-opscotch-mcp

At session start, call the MCP JSON-RPC `ping` method (method, not tool), then call `tools/list` and use tools (not resources) for capability discovery.

At session start, bootstrap with local MCP tools in this order:
1) `get_guidance(role=system)`
2) `check_local_test_capabilities()`
3) `get_guidance(role=workflow)` or `get_guidance(role=resource)` based on the task

Before running execution tools, verify paths and mounts:
- Use logical roots from `OPSCOTCH_LOCAL_MCP_ROOTS_JSON` (typically `workspace`, `artifacts`)
- Use `OPSCOTCH_LOCAL_MCP_LICENSE_FILE` for the single license file path (default `/license/license.txt`)
- Prefer root-relative tool paths
- Include `hostMounts` in tool input so host absolute paths can be translated reliably
- If paths are unclear, call `diagnose_resource_unit_test_path` first

Execution rules:
- Run exactly one execution tool at a time
- Use `run_resource_unit_tests` for resource unit tests (`unit-tests/*.test.ts`)
- Use `run_workflow_integration_test` for workflow integration tests
- Use `run_resource_script` only when script probing/execution is explicitly needed

Use the Public Opscotch MCP (https://mcp.opscotch.ai/mcp) for design-time reasoning (architecture, schemas, and validation strategy), and the Local Development MCP for execution against mounted local files.

After loading local guidance and checking capabilities, tell the operator:
"Local Opscotch development tools are loaded and ready. What should we run first?"

How tool paths work (important)

When paths are passed to tools, they are resolved from logical roots configured in OPSCOTCH_LOCAL_MCP_ROOTS_JSON, not from host filesystem assumptions.

Example root mapping:

OPSCOTCH_LOCAL_MCP_ROOTS_JSON='{"workspace":"/workspace","artifacts":"/artifacts"}'

If your container mount is:

-v /path/to/project:/workspace:ro

Use root-relative references:

• {"root":"workspace","path":"unit-tests/general/debug-print-body.test.ts"}
• {"root":"workspace","path":"tests/general/httpserver.test.json"}

Do not prefix with host repository segments when the directory is already mounted as /workspace.

If instead you mount the full opscotch repository root, for example:

-v /home/jeremy/dev/opscotch:/workspace:ro

then include community/opscotch-community/ in tool paths, for example:

• {"root":"workspace","path":"community/opscotch-community/unit-tests/general/debug-print-body.test.ts"}
• {"root":"workspace","path":"community/opscotch-community/tests/general/httpserver.test.json"}

Host absolute paths are supported when hostMounts is provided. The server will map matching host paths into the corresponding logical root.

Example:

{
  "workspaceRoot": { "root": "workspace", "path": "." },
  "unitTestPath": {
    "root": "workspace",
    "path": "/Users/alex/code/project/unit-tests/apps/github/poll.test.ts"
  },
  "hostMounts": [
    {
      "root": "workspace",
      "hostPath": "/Users/alex/code/project"
    }
  ]
}

Path diagnostics can also run in discovery mode:

• Call diagnose_resource_unit_test_path with no unitTestPath to inspect the resolved workspace root.
• Use browsePath (starting with /) to list files under the resolved workspace root.

Local MCP tools

• get_guidance (role: system, workflow, or resource)
• check_local_test_capabilities
• diagnose_resource_unit_test_path
• run_workflow_integration_test
• run_resource_unit_tests
• run_resource_script

Recommended call order:

1. get_guidance(role=system)
2. check_local_test_capabilities()
3. get_guidance(role=workflow) or get_guidance(role=resource)
4. diagnose_resource_unit_test_path(...) when unsure about paths
5. run one execution tool at a time

Execution constraints:

• run_resource_unit_tests expects test files under unit-tests/ matching *.test.ts (also supports .js, .mts, .cts)
• run_workflow_integration_test expects a valid workflow test file under mounted roots and uses the server-configured OPSCOTCH_LOCAL_MCP_LICENSE_FILE

Direct skill files

The skill files are designed to be dropped into an LLM as a system-level skill or knowledge file. They provide:

• Explicit field definitions and requirements
• Schema-backed structural guidance
• Operational procedures and examples
• Architectural reasoning patterns
• Guidance for using the Public Opscotch MCP as the canonical source of MCP-exposed Opscotch resources and tools

Skill File Structure

• opscotch-llm-skill.md - The complete public skill document
• opscotch-architect-skill.md - A complementary design-focused skill for architectural thinking
• opscotch-operations-skill.md - A complementary operations-focused skill for start/run/execute questions
• /llm/apireference-index.json - The public API reference index for normal workflow execution
• /llm/apireference.json - The public API reference detail for normal workflow execution
• /llm/patterns.json - The public pattern reference detail

Schema Files

JSON schema files define the structure and validation rules for Opscotch configuration files. These schemas provide explicit field definitions and requirements for configuration authoring:

• Bootstrap schema - Configuration for runtime initialization, deployment settings, licensing, and security controls
• Workflow schema - Structure for workflow definitions including steps, triggers, processors, and data flow
• Test Runner schema - Configuration for test execution and validation