Metadata-Version: 2.5
Name: trace2mcp
Version: 0.2.0
Summary: Compile successful AI-agent traces into reusable MCP workflows.
Project-URL: Homepage, https://huggingface.co/spaces/warenterprise/trace2mcp
Project-URL: Repository, https://huggingface.co/spaces/warenterprise/trace2mcp
Project-URL: Live demo, https://warenterprise-trace2mcp.static.hf.space
Author: War Enterprise
License-Expression: MIT
License-File: LICENSE
Keywords: agents,mcp,optimization,tracing,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Requires-Dist: twine>=6.0; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp<3,>=2.0.0; extra == 'mcp'
Provides-Extra: space
Requires-Dist: gradio<7,>=5.0; extra == 'space'
Description-Content-Type: text/markdown

# Trace2MCP

**Teach once. Run forever.**

Trace2MCP compiles a successful AI-agent tool-call trace into a deterministic,
inspectable, MCP-ready workflow.

An agent can discover a useful procedure once. Trace2MCP then validates the
trace, infers data dependencies, deduplicates safe reads, builds a directed
acyclic graph (DAG), and identifies work that can run concurrently.

## Install

```bash
pip install trace2mcp
```

To run generated MCP servers, install the optional MCP dependency:

```bash
pip install "trace2mcp[mcp]"
```

Python 3.10 or newer is required.

## Try it

```bash
trace2mcp demo
trace2mcp inspect trace.json
trace2mcp compile trace.json --out build/my-workflow
trace2mcp verify build/my-workflow/workflow.json
trace2mcp replay build/my-workflow/workflow.json --frozen
trace2mcp benchmark trace.json --repetitions 3
```

`trace2mcp demo` runs the complete offline path: teach, compile, verify, frozen
replay, and a visible safety-gate example. It uses no model, API key, or network.

Or use the Python API:

```python
from trace2mcp import compile_trace, load_trace

trace = load_trace("trace.json")
workflow = compile_trace(trace, allow_side_effects=False)

print(workflow.to_dict())
```

The `compile` command produces a portable `workflow.json`, inert handler stubs,
and a minimal MCP server skeleton. You provide the real tool implementations;
observed trace outputs are never converted into executable code.

## Why compile traces?

- **Lower orchestration overhead:** reuse a discovered procedure instead of
  planning the same tool path on every run.
- **Dependency-aware execution:** independent read-only calls can run in
  parallel.
- **Fail-closed safety:** unknown and destructive operations are denied; consequential
  operations need a reviewed contract and explicit approval.
- **Auditability:** tool calls, references, dependencies, and scheduling remain
  visible as portable JSON.
- **Provider-neutral design:** the core compiler does not require a model or an
  API key.

## Live demo

Use the free, browser-only [Trace2MCP interactive demo](https://warenterprise-trace2mcp.static.hf.space)
or visit the [Hugging Face Space](https://huggingface.co/spaces/warenterprise/trace2mcp).

The included demo uses synthetic outputs and recorded durations to explain the
scheduler. Its speedup is educational, not a production performance claim.

## Safety

Trace2MCP is an alpha research tool. Version 0.2 verifies structure and integrity,
supports deterministic frozen replay, and runs reviewed local handlers with bounded
concurrency, timeouts, and safe retries. It does not provide distributed durability,
sandboxing, live remote replay, or a proof of semantic equivalence.

Licensed under the MIT License.
