Metadata-Version: 2.5
Name: trace2mcp
Version: 0.2.1
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,
unreviewed contract candidates, and a minimal MCP server skeleton. You provide and
review the real implementations and contracts; 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.1 routes supported direct and nested
capability calls through one dispatcher, verifies structure and integrity, enforces
reviewed generated contracts and schemas, and runs local handlers with bounded
concurrency, timeouts, and safe retries. It does not sandbox trusted Python handlers or
provide distributed durability, live remote replay, or proof of semantic equivalence.

Licensed under the MIT License.
