mockworld-mcp 0.2.0__tar.gz

mockworld_mcp-0.2.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,13 @@
+---
+name: Bug report
+about: Something behaves incorrectly
+labels: bug
+---
+
+**What happened**
+
+**Expected**
+
+**Minimal reproduction**
+
+**Environment** (OS, Python version, model/provider)

mockworld_mcp-0.2.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,11 @@
+---
+name: Feature request
+about: Suggest an idea
+labels: enhancement
+---
+
+**Problem / motivation**
+
+**Proposed solution**
+
+**Alternatives considered**

mockworld_mcp-0.2.0/.github/good-first-issues.md

@@ -0,0 +1,8 @@
+# Seeded good-first-issues for mockworld
+
+> Filed as real GitHub issues (label: `good-first-issue`) once the org repo exists.
+
+1. Add a mock:sms service
+2. Document the mock definition YAML format
+3. Add a fault-injection (rate limit) example to the README
+4. Seed a mock:shopify community template

mockworld_mcp-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  gates:
+    # The determinism (G-DET), lint (G-LINT), isolation (G-ISO), and fault
+    # (G-FLT) gates from docs/TEST-PLAN.md §8 — must be green to merge.
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install
+        run: uv pip install --system -e ".[dev]"
+      - name: G-LINT — every built-in mock lints clean (entropy smells, schema)
+        run: |
+          for m in payments crm exchange email files; do mockworld validate mock:$m; done
+      - name: G-DET / G-ISO / G-FLT / G-E2E — full suite
+        run: python -m pytest -q
+      - name: G-DET (cross-run) — determinism demo reproduces
+        run: mockworld demo mock:payments

mockworld_mcp-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,59 @@
+name: release
+
+# Cut a release by pushing a version tag: `git tag v0.1.0 && git push origin v0.1.0`.
+# Builds + smoke-tests the wheel, creates a GitHub release, and publishes to PyPI
+# via Trusted Publishing (OIDC — no API token stored). See docs/RELEASING.md for
+# the one-time PyPI setup.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Smoke-test the wheel (clean install → run)
+        run: |
+          python -m venv /tmp/v
+          /tmp/v/bin/pip install dist/*.whl
+          /tmp/v/bin/mockworld list
+          /tmp/v/bin/mockworld demo mock:payments
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+
+  pypi-publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1

mockworld_mcp-0.2.0/.gitignore

@@ -0,0 +1,225 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+
+# project
+*.db
+stampede-report.html
+.env
+.venv/

mockworld_mcp-0.2.0/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to mockworld are documented here. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/); versions follow SemVer.
+
+## [0.2.0] — 2026-09-02
+
+Distribution renamed to **`mockworld-mcp`** on PyPI (`import mockworld` and the
+`mockworld` CLI are unchanged) — the plain name is reserved by an unrelated project.
+
+### Added
+- **OTLP trace export** (REQ-OBS-3): `mockworld run --otlp <collector-url>` POSTs
+  target-side spans as OTLP/HTTP JSON to `<url>/v1/traces` — dependency-free, so
+  mockworld traces drop into any OpenTelemetry backend. Best-effort and
+  self-disabling if the collector is down.
+- **MCP resources** (REQ-MCP-4): each server exposes read-only reference data —
+  `mockworld://mock` (tools + state shape + fidelity), `mockworld://faults`
+  (declared fault catalog + profiles), and `mockworld://state/<collection>`
+  (the session's current data).
+- **Ambiguous tool-description variants** (REQ-MCP-6): a tool can declare an
+  `ambiguous_description`; `--descriptions ambiguous` serves it. The swarm is
+  clarity-sensitive, so the misuse map can A/B description quality — e.g.
+  crm delete-vs-archive misuse rises from ~33% (clear) to ~46% (ambiguous),
+  reproducibly.
+
+## [0.1.0] — 2026-09-01
+
+First public release — the deterministic, LLM-free MCP mock engine plus the full
+v0.1–v0.4 feature surface.
+
+### Engine
+- Seeded `DeterministicContext` (clock/ids/rng/fault-dice on independent
+  substreams); byte-identical replay across runs, hosts, and both state stores.
+- Copy-on-write per-session isolation keyed on `Mcp-Session-Id` (50+ parallel
+  sessions, zero cross-talk).
+- Declarative `mock.yaml` schema + Python handler ABI; Memory and SQLite stores.
+- Business-logic fault injector: probabilistic + conditional (`when:`) faults,
+  profiles (`none`/`realistic`/`hostile`), realistic vendor-shaped error bodies.
+- Target-side trace emission as an OpenTelemetry GenAI profile.
+
+### Surface
+- MCP over stdio and Streamable HTTP; out-of-band control plane; stampede
+  `Target` protocol.
+- CLI: `run`, `list`, `inspect`, `validate`, `reset`, `demo`, `new`, `add`,
+  `search`, `pack`, `record`, `swarm`, `verify`, `snapshot`.
+
+### Built-in mocks
+- `payments` (Stripe-shaped), `crm` (delete-vs-archive misuse map), `exchange`,
+  `email`, `files`, and `hello` (the authoring example).
+
+### Ecosystem
+- Registry (`add`/`search`/`pack`) with checksum + safety gate.
+- World composition with a shared identity namespace.
+- Record-mode: scaffold a mock from an OpenAPI spec **or** a HAR capture.
+- Scenario snapshots (portable `.mw.json` + migration).
+- Swarm harness → Agent Readiness Report (the misuse map).
+- Contract-verify against an OpenAPI for fidelity-drift governance.
+
+### Developer experience
+- A `mockworld` pytest fixture (via the `pytest11` entry point).
+- `mockworld new` scaffold and `docs/AUTHORING.md`.
+
+### Fixed
+- Wheel build no longer double-includes built-in mock data (removed a redundant
+  `force-include`); `pip install mockworld` now ships the mocks correctly.

mockworld_mcp-0.2.0/CITATION.cff

@@ -0,0 +1,16 @@
+cff-version: 1.2.0
+message: "If you use this software or dataset, please cite it as below."
+title: "mockworld"
+abstract: "A synthetic internet for agents. Part of the Swarm Proof toolkit."
+authors:
+  - family-names: Boudoukha
+    given-names: Maroua
+repository-code: "https://github.com/swarmproof/mockworld"
+url: "https://github.com/swarmproof/mockworld"
+license: Apache-2.0
+type: software
+keywords:
+  - ai-agents
+  - agent-reliability
+  - llm
+  - mcp

mockworld_mcp-0.2.0/CLAUDE.md

@@ -0,0 +1,60 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this repo is
+
+**mockworld** — "a synthetic internet for agents": deterministic, LLM-free fake services (fake Stripe, Gmail, exchange, CRM, S3) exposed as MCP servers so agents can be built and tested without touching production. Part of the Swarm Proof toolkit; companion to [stampede](https://github.com/swarmproof/stampede) (stampede simulates the *agents*, mockworld simulates the *world* they act on). Apache-2.0.
+
+**Current state: v0.1 + v0.2 implemented** (on feature branches; see git). Python 3.11+, official `mcp` SDK, pydantic v2, click, httpx; packaged with hatchling. Dev loop: `uv venv && uv pip install -e ".[dev]"`, then `python -m pytest -q` (53 tests, ~1s) and `mockworld <cmd>`.
+
+### Module map (`src/mockworld/`)
+- `determinism.py` — the seeded entropy funnel (clock/ids/rng/fault-dice). The root of all guarantees.
+- `state.py` — `StateStore` (Memory/SQLite) + copy-on-write `StateView`; session isolation lives here.
+- `session.py` — per-session logical counters. `schema.py` — pydantic `mock.yaml` models. `errors.py` — error library + `Result`.
+- `faults.py` — fault injector (probabilistic + `when:` conditional). `dispatch.py` — CRUD + handler ABI. `handler_ctx.py` — the `ctx` handed to handlers.
+- `loader.py` — load a mock dir (+ registry-installed resolution). `engine.py` — the transport-free call path (start here to trace a request).
+- `trace.py` — OTel-GenAI-profile spans + NDJSON sink + OTLP/HTTP JSON exporter (`--otlp`). `server.py` — MCP stdio+HTTP adapter, also exposes read-only `mockworld://` resources. `control.py` — control plane + stampede `Target`. `cli.py` — commands. `validate.py` — the entropy linter.
+- `registry.py` (v0.2) — `add`/`search`, checksum + safety gate. `world.py` (v0.2) — compose mocks with a shared identity pool. `record.py` (v0.2) — OpenAPI → scaffold.
+- `snapshot.py` (v0.3) — portable `.mw.json` artifacts + migration. `swarm.py` (v0.3) — persona swarm → Agent Readiness Report (misuse map). `verify.py` (v0.3) — contract-drift vs OpenAPI.
+- `mocks/<name>/` — the five built-ins (`mock.yaml` + `handlers.py` + `seed.py` + `fidelity.md`).
+
+CLI: `run` (stdio/http, also `run world:<file>`), `list`, `inspect`, `validate`, `reset`, `demo`, `add`, `search`, `pack`, `record`. The engine is deliberately MCP-free; server/control/CLI are thin adapters (keeps determinism/isolation tests pure).
+
+## Document map
+
+- `SPEC.md` — the original v1.0 spec/PRD (root-level, high-level).
+- `docs/PRD.md` — detailed requirements; **the source of REQ-IDs** (`REQ-DET-*`, `REQ-ISO-*`, `REQ-FAULT-*`, …) that every other doc cross-references.
+- `docs/ARCHITECTURE.md` — authoritative design: engine components, the `mock.yaml` schema, handler ABI, session isolation, the stampede integration contract (§7), and ADRs 1–7.
+- `docs/DELIVERY-PLAN.md` — milestones (v0.1/0.2/0.3), work breakdown (epics A–I), mock build order, definition of done, launch checklist.
+- `docs/TEST-PLAN.md` — test pyramid, E2E scenarios (Given/When/Then), and the CI gates (G-DET, G-ISO, …) that define "green to merge/release".
+- `docs/RESEARCH.md` — competitive landscape and open questions.
+
+Doc conventions: `⊕ Beyond original spec` marks design that extends `SPEC.md`; keep REQ-ID cross-references intact when editing; keep the "Last updated" line current on `docs/*` edits.
+
+## Architecture (the invariants all future code must serve)
+
+1. **Determinism is a hard contract, not a mode** (ADR-4). All entropy — clock, RNG, IDs, fault dice — flows through one seeded `DeterministicContext`. Handlers may only use `ctx.clock` / `ctx.ids` / `ctx.rng`; importing `time`, `random`, `uuid` in a handler is a lint violation. Fault dice draw from a *separate* PRNG substream so adding a tool call doesn't shift unrelated faults. `reset(seed)` must be indistinguishable from a fresh boot at that seed. **No LLM in the response path, ever — that's the moat.**
+2. **Session isolation rides MCP** (ADR-2). Sessions are keyed on MCP's `Mcp-Session-Id` (stdio = one implicit session), implemented as copy-on-write overlays over an immutable seeded base state — 50+ parallel sessions share one base dataset with no cross-talk.
+3. **Declarative-first, Python escape hatch** (ADR-5). A mock is a directory: `mock.yaml` (authoritative), optional `handlers.py` (ABI: `handler(ctx, params) -> Result`, pure w.r.t. injected entropy), optional `seed.py`, and `fidelity.md` documenting what it does/doesn't model. Simple CRUD needs no code.
+4. **Fault split with stampede** (ADR-6): mockworld owns *business-logic* faults only (`card_declined`, `insufficient_funds`, `rate_limited`, latency, partial outage) as first-class objects with realistic error bodies. Transport chaos (connection kills, socket timeouts, malformed frames) belongs to stampede/Toxiproxy — never implement it here. When a `MockworldTarget` is in use, stampede suppresses its transport rate_limit in favor of mockworld's semantic 429.
+5. **State store**: `MemoryStore` default, `SQLiteStore` for persistence/snapshots, behind one `StateStore` API (ADR-3) — both must pass a shared conformance suite.
+6. **Consume siblings' primitives, never redefine them.** Tracing uses stampede's trace-format, which is an **OpenTelemetry GenAI profile** — mockworld emits standard `gen_ai.*` attributes plus the shared `swarmproof.*` extension (`swarmproof.span.side="target"`, `swarmproof.fault.{type,injected,source}`). No `mockworld.*` namespace. Target spans are `span.kind=SERVER`, parented to stampede's `execute_tool` CLIENT span, joined on echoed `gen_ai.tool.call.id`; `traceparent` is read from HTTP headers or MCP `_meta.traceparent` on stdio.
+
+### The stampede contract (confirmed 2026-07-13, ARCHITECTURE §7)
+
+mockworld implements stampede's full `Target` protocol: `discover / invoke / reset(seed) / health / isolation() → per_agent / safety_descriptor() → {sandboxed: True}`, plus a control plane (`boot / reset / set_faults / snapshot / restore / session_reset`). `reset(seed)` means state is a *pure function* of the seed. Changes to this seam must stay consistent with stampede's side of the contract.
+
+### v0.1 mock build order (stampede-demo-driven, not SPEC order)
+
+`payments` (marquee) → `crm` (misuse-map demo) → `exchange` → `email` → `files`. Each mock must enforce its stateful invariants (e.g. refund ≤ captured, balance conservation, soft-delete ≠ hard-delete) and declare ≥3 seeded faults — see TEST-PLAN §7 for the per-mock acceptance table.
+
+## Testing philosophy (when code lands)
+
+Determinism/replay tests are the load-bearing acceptance gates, not an afterthought. Merge-blocking CI gates: G-DET (byte-identical transcripts across runs/hosts/both stores, DT-1..6), G-LINT (ambient-entropy lint + `mockworld validate`), G-ISO (isolation incl. 50 parallel sessions), G-UNIT (≥90% on engine core). E2E scenarios in TEST-PLAN §4 are the release gates.
+
+## Conventions
+
+- Conventional Commits (`feat:`, `fix:`, `docs:`, …); branches `feat/<short-name>`; atomic commits.
+- Scope discipline: mocks are "realistic enough to break agents correctly," never vendor-exact clones (non-goal NG2) — resist fidelity scope creep; `fidelity.md` is where coverage boundaries live.
+- Toolkit principles: provider-agnostic, honest over impressive, watchable & reproducible (seedable outputs).

mockworld_mcp-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,21 @@
+# Contributing to mockworld
+
+Thanks for helping build **mockworld** — part of the [Swarm Proof toolkit](https://github.com/swarmproof).
+
+## Ways to contribute
+- **Good first issues** — look for the `good-first-issue` label. A few are seeded to get you started.
+- **Bug reports** — open an issue with a minimal reproduction.
+- **Features & discussion** — open an issue before a large PR so we can align on direction.
+
+## Development
+1. Fork and clone.
+2. Create a branch: `git checkout -b feat/<short-name>`.
+3. Keep commits atomic and use [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, ...).
+4. Open a PR describing *what* changed and *why*.
+
+## Principles (shared across the toolkit)
+- **Provider-agnostic** — no hard dependency on a single model vendor.
+- **Honest over impressive** — we don't overpromise guarantees; we document boundaries.
+- **Watchable & reproducible** — outputs should be seedable and screenshot-worthy.
+
+By contributing you agree your work is licensed under this repo's LICENSE.