Skip to content

README.md

Latest commit

 

History

History
122 lines (89 loc) · 7.02 KB

README.md

File metadata and controls

122 lines (89 loc) · 7.02 KB
Raw

mcp-tool-provenance

Provenance envelopes for tool results, plus an anti-inflation gate for the tool surface itself.

Two small, composable pieces for any tool surface — an MCP server, an RPC layer, an agent tool-call loop:

  1. Stamp every tool result with a provenance envelope so the answer travels with its reasoning and its trust level:

    Envelope key Contents
    _toulmin a Toulmin argument — claim / grounds / warrant / qualifier / rebuttal
    _tags four provenance dimensions — scope / signal_type / attribution / uncertainty

  2. Triage the surface MECE into {real_dispatch, read_only, native_only} and gate it with drift_check, so no exposed tool is ever unclassified or double-counted.

The moat

A tool surface returns answers; a governed tool surface returns answers plus the reasoning and the trust level that let a caller filter, escalate, or audit them — and it never overstates what it can do. This library makes both structural with one ~250-line, zero-dependency package:

  • Every result self-describes. stamp(result, toulmin=…, tags=…) is non-destructive — the payload passes through untouched and the envelope is added — so retrofitting provenance onto an existing surface is a one-line wrap, not a schema migration.
  • The surface can't inflate. drift_check(registry, classification) fails CI the moment a tool is exposed but unclassified, or appears in two buckets. The honest "how many tools actually execute" count (real_dispatch + read_only) is derived, not asserted — so "we expose N tools" can never quietly mean "N tools that look like they do something." The three buckets are a fixed contract; the tools are entirely yours.

Install

pip install -e .

Zero runtime dependencies — pure standard library, Python 3.9+. The envelope value objects (a Toulmin argument and a four-dimension tag block) are vendored under _vendor/ (see KERNEL_SYNC.md).

Quickstart

from mcp_tool_provenance import (
    stamp, make_tags, ToulminArgument, QualifierLevel, DataAvailability,
    triage, drift_check, assert_no_drift, surface_summary,
)

# 1) Stamp a tool result — non-destructive.
out = stamp(
    {"records": [1, 2], "count": 2},
    tool_name="read-records",
    toulmin=ToulminArgument(
        claim="Two records matched", grounds="Key resolved to two rows",
        warrant="A key matching N rows returns them", qualifier=QualifierLevel.CERTAIN,
        rebuttal="A row could be soft-deleted after this read",
        data_availability=DataAvailability.SUFFICIENT,
    ),
    tags=make_tags(scope="tenant_specific", signal_type="operational",
                   attribution="read-records-tool", uncertainty="low"),
)
out["_toulmin"]  # 5 keys   out["_tags"]  # 4 keys   out["records"]  # untouched

# 2) Triage the surface and gate it.
registry = ("create-record", "read-record", "list-records", "draft-guidance")
surface = triage(
    real_dispatch=("create-record",),
    read_only=("read-record", "list-records"),
    native_only=("draft-guidance",),
)
assert_no_drift(registry, surface)            # raises if any tool is mis/unclassified
surface_summary(registry, surface)["executes_server_side"]  # honest "really does something" count

What's here

  • stamp(result, *, toulmin, tags, tool_name="") / is_stamped(result) — the non-destructive envelope
  • ToulminArgument, QualifierLevel, DataAvailability, ArtifactTags, make_tags — vendored envelope value objects, re-exported
  • triage(real_dispatch=, read_only=, native_only=) — build a MECE surface map
  • drift_check(registry, classification) / assert_no_drift(...) — the anti-inflation gate (report / raise)
  • surface_summary(registry, classification) — the honest, reportable split
  • BUCKETS, DriftReport, DriftError

Full reference: docs/API.md. Adapting it to your surface: docs/FORKING.md. Why it matters: docs/MOAT.md.

License

MIT — see LICENSE.

About Powerweave Skunkworks

Powerweave Skunkworks is the AI R&D division of Powerweave Software Services — a rapid-innovation lab that turns real-world product feedback into working, reusable, open-source building blocks. Working in parallel to the main engineering backlog, a lean, cross-functional team of product and technology specialists (UX, data, software engineering, and AI) fast-tracks high-priority ideas into validated modules ready for full-scale build-out.

mcp-tool-provenance is one such building block — a de-domained, MIT-licensed, dependency-light component extracted from Powerweave's internal R&D and engineered to be forked into any SaaS or enterprise product.

About Powerweave

Powerweave Software Services Pvt. Ltd. is a digital-transformation company founded in 2001 and headquartered in Mumbai, India. With 25+ years of experience, 1,700+ professionals, and 350+ global customers, Powerweave builds platforms, processes, and teams across enterprise eCommerce, AI-powered procurement, Microsoft Dynamics ERP, business services, and sustainability — with a strong focus on cutting-edge AI automation that streamlines workflows, reduces manual errors, and accelerates decision-making. Powerweave is ISO 27001:2013 certified.

Explore Powerweave

Maintainers — Powerweave Skunkworks

Keywords: mcp · provenance · tool · governance · audit · toulmin · tagging · drift · Powerweave · Powerweave Skunkworks · AI R&D · open source · MIT · Python · forkable.