jchristn77/tempo-mcp repository overview

⁠Tempo

Tempo is a workflow automation platform for building, running, and monitoring tenant-scoped data flows. A flow is made of reusable steps, invoked through triggers, persisted with artifacts, and observed through run history, request history, OpenAPI, and MCP.

Tempo ships as:

• Tempo: the core workflow/orchestration library
• Tempo.Core: server-facing persistence, runtime, settings, and management contracts
• Tempo.Server: the REST API host
• Tempo.McpServer: an MCP facade over Tempo.Server built on Voltaic
• dashboard/: a React/Vite operator UI
• sdk/csharp, sdk/js, and sdk/python: artifact runtime SDKs with exhaustive test apps

⁠Highlights

• Tenant-scoped CRUD for data flows, steps, triggers, runs, artifacts, users, credentials, roles, and permissions
• Runtime model that supports Builtin.Class, Builtin.Method, External.Rest, Artifact.Process, Artifact.Python, Artifact.JavaScript, Artifact.DotnetProcess, and Host.Executable
• Source-step creation from the UI or API for Python, JavaScript, and C#
• Mutable artifact packages with dashboard file browsing and in-place editing
• Runtime-aware startup seeding that creates working sample steps for each available runtime type
• OpenAPI-backed API Explorer and MCP server for agent-driven automation
• First-run setup wizard that creates and invokes example flows end to end
• K-sortable PrettyId identifiers with fixed prefixes and a maximum length of 32
• Docker Compose deployment, image build scripts, and NuGet publish script

⁠Quick Start

⁠Docker Compose

From the repository root:

docker compose -f .\docker\compose.yaml up --build

Default endpoints:

• Dashboard: http://localhost:3000
• Tempo.Server: http://localhost:8901
• Tempo.McpServer HTTP RPC: http://127.0.0.1:8910/rpc
• Tempo.McpServer TCP: 127.0.0.1:8911
• Tempo.McpServer WebSocket: ws://127.0.0.1:8912/mcp

Default seeded credentials on an empty database:

• Email: [email protected]
• Password: password

Compose uses named volumes for server config, database, logs, runtime cache, scratch storage, dashboard logs, and MCP configuration. The service images in the compose file are pinned to v0.2.0.

⁠Local Development

Recommended prerequisites:

Tempo.Server does not fail startup when optional runtime commands are unavailable. Instead, those runtimes are surfaced as unavailable in the runtime catalog and their startup template steps are skipped. Configure command names or absolute paths in tempo.json under runtimes.externalExecution.

Build and run:

dotnet build .\src\Tempo.sln
dotnet run --project .\src\Tempo.Server\Tempo.Server.csproj
dotnet run --project .\src\Tempo.McpServer\Tempo.McpServer.csproj

cd .\dashboard
npm install
npm run dev

Helper scripts at the repository root:

• build-server.bat v0.2.0
• build-mcp.bat v0.2.0
• build-dashboard.bat v0.2.0
• publish-nuget.bat <nuget-api-key>

⁠Core Concepts

Flows reference steps by executionKey, not by step record ID. This keeps flow definitions stable even when the step row is edited or replaced.

⁠Runtime Keys

Legacy.InlineRest remains a compatibility read path. New REST steps should use External.Rest.

⁠First-Run Experience

On an empty database, Tempo seeds:

• A default tenant, administrator, tenant user, and credential
• Four protected tenant roles: Administrator, Editor, Operator, and ReadOnly
• Built-in runtime sample steps
• Artifact-backed sample steps and sample artifacts for every available artifact runtime
• A host executable sample only when a host allowlist entry is enabled

The dashboard opens a setup wizard on first access. The wizard explains what Tempo is about to create, then creates:

• An echo step packaged from source
• An echo flow and POST trigger
• A chained flow that generates a random number and doubles it
• A GET trigger for the chained flow
• Sample invocations that show both response bodies and response headers

Every workspace in the dashboard includes a page title and subtitle, and sidebar scrolling is independent from workspace scrolling.

⁠Public HTTP Trigger Response Contract

Public HTTP trigger routes are:

/v1.0/triggers/http/{triggerId}

For successful trigger execution:

• The HTTP response body is the final step output body
• Execution metadata is returned in headers, not mixed into the JSON body

Current response metadata headers include:

• x-tenant-id
• x-run-id
• x-dataflow-id
• x-trigger-id
• x-run-state
• x-run-created-utc
• x-run-started-utc
• x-run-completed-utc
• x-run-last-update-utc
• x-runtime-ms
• x-run-error when applicable

⁠SDKs

Tempo includes SDKs for artifact-backed handlers:

• sdk/csharp/README.md⁠
• sdk/js/README.md⁠
• sdk/python/README.md⁠

Notes:

• The C# SDK targets net8.0 and net10.0
• The server-side projects target net10.0
• Each SDK ships with a test application intended to exercise the public API surface exhaustively

⁠Mutable Artifacts and Source Steps

Artifacts are file packages, not opaque zip-only deployment units. Tempo stores package contents in a way that supports:

• Uploading artifacts and versions
• Editing individual files in the dashboard
• Creating steps directly from pasted Python, JavaScript, or C# source
• Reusing one artifact across multiple steps and versions

For artifact-backed runtimes and manifests, see docs/ARTIFACT_MANIFEST.md⁠.

⁠APIs and Documentation

Primary reference material:

• docs/REST_API.md⁠
• docs/MCP_API.md⁠
• docs/BEST_PRACTICES.md⁠
• Tempo.postman_collection.json⁠

Additional operator and implementation guides:

• docs/RUNTIME_PROVIDER_AUTHORING.md⁠
• docs/ARTIFACT_MANIFEST.md⁠
• docs/PROTOCOL_V1.md⁠
• docs/PYTHON_ARTIFACT_QUICKSTART.md⁠
• docs/EXTERNAL_EXECUTION_OPERATOR_GUIDE.md⁠
• docs/SECURITY_TRUST_BOUNDARIES.md⁠
• docs/INLINE_REST_MIGRATION.md⁠
• docs/DASHBOARD_ARTIFACTS_RUNTIMES.md⁠

OpenAPI is exposed at:

http://localhost:8901/openapi.json

Runtime configuration schemas in OpenAPI use oneOf, which keeps the API Explorer and generated clients aligned with the concrete runtime config being used.

⁠Build, Test, and Pack

Core solution:

dotnet build .\src\Tempo.sln
dotnet run --project .\src\Test.Automated\Test.Automated.csproj
dotnet test .\src\Test.Xunit\Test.Xunit.csproj
dotnet test .\src\Test.Nunit\Test.Nunit.csproj

SDK test applications:

dotnet run --project .\sdk\csharp\Tempo.Sdk.TestApp\Tempo.Sdk.TestApp.csproj
npm.cmd --prefix .\sdk\js test
python .\sdk\python\test_app\test_sdk.py

NuGet packaging:

publish-nuget.bat YOUR_NUGET_API_KEY

That script packs and pushes:

• Tempo
• Tempo.Sdk
• their matching .snupkg symbol packages

⁠Repository Layout

⁠Technology Stack

⁠Contributing

Follow the coding and review rules in CLAUDE.md⁠. Keep README, changelog, API docs, and the Postman collection in sync with code changes.

⁠License

MIT. See LICENSE.md⁠.

⁠Logo

Logo provided by softicons.com⁠.