forgingstack-mandate-check 0.2.0__tar.gz

forgingstack_mandate_check-0.2.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: forgingstack-mandate-check
+Version: 0.2.0
+Summary: Before your agent acts, check its mandate. One call, one receipt.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# ForgingStack Mandate Check
+
+Before your agent acts, check its mandate. One call, one receipt.
+
+This is the **public client** for Mandate Check. The service itself —
+the decision logic, the receipt chain, the key store, and billing —
+runs on ForgingStack's private service and is **not** in this repo.
+Copying this repo does not give you the service: you still need an
+API key and credits, from signup below.
+
+Live API: https://forgingstack-mandate-check.jkbattles.workers.dev
+
+## What it checks, in order
+
+1. Mandate agent matches the calling agent
+2. Mandate principal matches the principal the agent acts for
+3. Mandate expiry is parseable and in the future
+4. Action is in the mandate's allowed actions
+
+Pass or fail, you get a reason and a hash-chained receipt.
+
+What it does **not** do: decide if an action is wise, legal, or
+safe. Mandate fit only.
+
+## Signup (v1)
+
+```bash
+curl -X POST https://forgingstack-mandate-check.jkbattles.workers.dev/v1/signup \
+  -H "Content-Type: application/json" \
+  -d '{"email":"you@example.com"}'
+```
+
+Returns an API key **once** and 100 starter credits. Save the key
+immediately — it is stored only as a hash and cannot be shown again.
+Email verification is pending, and credit-pack billing is not live
+yet, so do not expect a purchase flow in v1.
+
+## Agent sub-keys
+
+A signed-up human creates a key for each agent, capped and revocable:
+
+```bash
+curl -X POST https://forgingstack-mandate-check.jkbattles.workers.dev/v1/keys \
+  -H "X-API-Key: YOUR_PRIMARY_KEY" -H "Content-Type: application/json" \
+  -d '{"agent_name":"my-agent","credits":20}'
+```
+
+List with `GET /v1/keys`, revoke with `DELETE /v1/keys/{id}` —
+revoking returns unused credits to the primary account.
+
+## Use it (MCP, stdio)
+
+Set the key, then run the MCP server in this repo:
+
+```bash
+export FORGINGSTACK_API_KEY="your-key-here"
+python -m app.mcp_server
+```
+
+Tools: `check_mandate`, `get_credits`, `get_receipt`.
+See `SKILL.md` for when to use it and when not to.
+
+## Price
+
+1 credit per check call. A failed decision still costs 1 credit —
+the check was performed. An idempotent replay (same
+`Idempotency-Key`) is free and returns the original receipt.
+
+## Files in this repo
+
+- `app/mcp_server.py` — MCP wrapper client (stdio, stdlib only)
+- `SKILL.md` — when to use it, how to read pass/fail
+- `agent-card.json` — A2A-style discovery card
+- `server.json` — MCP Registry metadata (draft until PyPI publish)
+- `pyproject.toml` — package metadata for the MCP client

forgingstack_mandate_check-0.2.0/README.md

@@ -0,0 +1,75 @@
+# ForgingStack Mandate Check
+
+Before your agent acts, check its mandate. One call, one receipt.
+
+This is the **public client** for Mandate Check. The service itself —
+the decision logic, the receipt chain, the key store, and billing —
+runs on ForgingStack's private service and is **not** in this repo.
+Copying this repo does not give you the service: you still need an
+API key and credits, from signup below.
+
+Live API: https://forgingstack-mandate-check.jkbattles.workers.dev
+
+## What it checks, in order
+
+1. Mandate agent matches the calling agent
+2. Mandate principal matches the principal the agent acts for
+3. Mandate expiry is parseable and in the future
+4. Action is in the mandate's allowed actions
+
+Pass or fail, you get a reason and a hash-chained receipt.
+
+What it does **not** do: decide if an action is wise, legal, or
+safe. Mandate fit only.
+
+## Signup (v1)
+
+```bash
+curl -X POST https://forgingstack-mandate-check.jkbattles.workers.dev/v1/signup \
+  -H "Content-Type: application/json" \
+  -d '{"email":"you@example.com"}'
+```
+
+Returns an API key **once** and 100 starter credits. Save the key
+immediately — it is stored only as a hash and cannot be shown again.
+Email verification is pending, and credit-pack billing is not live
+yet, so do not expect a purchase flow in v1.
+
+## Agent sub-keys
+
+A signed-up human creates a key for each agent, capped and revocable:
+
+```bash
+curl -X POST https://forgingstack-mandate-check.jkbattles.workers.dev/v1/keys \
+  -H "X-API-Key: YOUR_PRIMARY_KEY" -H "Content-Type: application/json" \
+  -d '{"agent_name":"my-agent","credits":20}'
+```
+
+List with `GET /v1/keys`, revoke with `DELETE /v1/keys/{id}` —
+revoking returns unused credits to the primary account.
+
+## Use it (MCP, stdio)
+
+Set the key, then run the MCP server in this repo:
+
+```bash
+export FORGINGSTACK_API_KEY="your-key-here"
+python -m app.mcp_server
+```
+
+Tools: `check_mandate`, `get_credits`, `get_receipt`.
+See `SKILL.md` for when to use it and when not to.
+
+## Price
+
+1 credit per check call. A failed decision still costs 1 credit —
+the check was performed. An idempotent replay (same
+`Idempotency-Key`) is free and returns the original receipt.
+
+## Files in this repo
+
+- `app/mcp_server.py` — MCP wrapper client (stdio, stdlib only)
+- `SKILL.md` — when to use it, how to read pass/fail
+- `agent-card.json` — A2A-style discovery card
+- `server.json` — MCP Registry metadata (draft until PyPI publish)
+- `pyproject.toml` — package metadata for the MCP client

forgingstack_mandate_check-0.2.0/app/mcp_server.py

@@ -0,0 +1,173 @@
+"""MCP wrapper client for ForgingStack Mandate Check, v0.2.0.
+
+An agent-native service must be usable by agents, not just by humans
+with curl. MCP is the standard interface agents already speak, so the
+wrapper exposes the same live REST API as MCP tools, with no duplicated
+decision logic: every tool call goes through the REST API, so metering
+and receipts stay in one place. The service itself is private; this
+file is only a client.
+
+Protocol: JSON-RPC 2.0 over stdio, no new dependencies (stdlib only).
+Supported methods: initialize, ping, tools/list, tools/call.
+Notifications (no id, e.g. notifications/initialized) get no response.
+
+Environment:
+  FORGINGSTACK_API_BASE  default https://forgingstack-mandate-check.jkbattles.workers.dev
+  FORGINGSTACK_API_KEY   required; sign up via POST /v1/signup (key shown once)
+
+Run:  python -m app.mcp_server
+"""
+
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+
+BASE = os.environ.get(
+    "FORGINGSTACK_API_BASE",
+    "https://forgingstack-mandate-check.jkbattles.workers.dev",
+)
+API_KEY = os.environ.get("FORGINGSTACK_API_KEY", "")
+
+TOOLS = [
+    {
+        "name": "check_mandate",
+        "description": "Check an agent action against its mandate. Returns a "
+        "pass/fail decision and a receipt. Costs 1 credit per call; "
+        "an idempotency key replay is free.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "agent_id": {"type": "string"},
+                "principal": {"type": "string"},
+                "action": {"type": "string"},
+                "mandate": {
+                    "type": "object",
+                    "properties": {
+                        "agent_id": {"type": "string"},
+                        "principal": {"type": "string"},
+                        "allowed_actions": {
+                            "type": "array", "items": {"type": "string"}
+                        },
+                        "expires_at": {"type": "string"},
+                        "scope": {"type": "string"},
+                    },
+                    "required": [
+                        "agent_id", "principal", "allowed_actions", "expires_at"
+                    ],
+                },
+                "idempotency_key": {"type": "string"},
+            },
+            "required": ["agent_id", "principal", "action", "mandate"],
+        },
+    },
+    {
+        "name": "get_credits",
+        "description": "Remaining credit balance for the configured API key.",
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+    {
+        "name": "get_receipt",
+        "description": "Fetch a past mandate-check receipt by id.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {"receipt_id": {"type": "integer"}},
+            "required": ["receipt_id"],
+        },
+    },
+]
+
+
+def _http(method, path, body=None, idempotency_key=None):
+    req = urllib.request.Request(
+        BASE + path,
+        data=json.dumps(body).encode() if body is not None else None,
+        method=method,
+    )
+    req.add_header("X-API-Key", API_KEY)
+    req.add_header("Content-Type", "application/json")
+    # A User-Agent is required: the default Python urllib agent is
+    # rejected (Cloudflare 1010) through some egress paths.
+    req.add_header("User-Agent", "ForgingStack-Mandate-Check/0.2.0")
+    if idempotency_key:
+        req.add_header("Idempotency-Key", idempotency_key)
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            return resp.status, json.loads(resp.read().decode() or "{}")
+    except urllib.error.HTTPError as e:
+        try:
+            return e.code, json.loads(e.read().decode() or "{}")
+        except Exception:
+            return e.code, {"detail": "api error"}
+
+
+def _text(payload, is_error=False):
+    return {
+        "content": [{"type": "text", "text": json.dumps(payload)}],
+        "isError": is_error,
+    }
+
+
+def handle(msg):
+    method = msg.get("method")
+    params = msg.get("params") or {}
+    if method == "initialize":
+        return {
+            "protocolVersion": "2024-11-05",
+            "capabilities": {"tools": {}},
+            "serverInfo": {"name": "forgingstack-mandate-check", "version": "0.2.0"},
+        }
+    if method == "ping":
+        return {}
+    if method == "tools/list":
+        return {"tools": TOOLS}
+    if method == "tools/call":
+        name = params.get("name")
+        args = params.get("arguments") or {}
+        if name == "check_mandate":
+            body = {k: args[k] for k in
+                    ("agent_id", "principal", "action", "mandate")}
+            status, data = _http(
+                "POST", "/v1/check-mandate", body,
+                args.get("idempotency_key"),
+            )
+            return _text(data, is_error=status >= 400)
+        if name == "get_credits":
+            status, data = _http("GET", "/v1/credits")
+            return _text(data, is_error=status >= 400)
+        if name == "get_receipt":
+            status, data = _http(
+                "GET", f"/v1/receipts/{args['receipt_id']}"
+            )
+            return _text(data, is_error=status >= 400)
+        raise ValueError(f"unknown tool: {name}")
+    raise ValueError(f"unknown method: {method}")
+
+
+def main():
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            msg = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        # Notifications carry no id and get no response.
+        if "id" not in msg:
+            continue
+        try:
+            result = handle(msg)
+            out = {"jsonrpc": "2.0", "id": msg["id"], "result": result}
+        except Exception as exc:  # noqa: BLE001 - MCP error surface
+            out = {
+                "jsonrpc": "2.0", "id": msg["id"],
+                "error": {"code": -32603, "message": str(exc)},
+            }
+        sys.stdout.write(json.dumps(out) + "\n")
+        sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    main()

forgingstack_mandate_check-0.2.0/forgingstack_mandate_check.egg-info/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: forgingstack-mandate-check
+Version: 0.2.0
+Summary: Before your agent acts, check its mandate. One call, one receipt.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# ForgingStack Mandate Check
+
+Before your agent acts, check its mandate. One call, one receipt.
+
+This is the **public client** for Mandate Check. The service itself —
+the decision logic, the receipt chain, the key store, and billing —
+runs on ForgingStack's private service and is **not** in this repo.
+Copying this repo does not give you the service: you still need an
+API key and credits, from signup below.
+
+Live API: https://forgingstack-mandate-check.jkbattles.workers.dev
+
+## What it checks, in order
+
+1. Mandate agent matches the calling agent
+2. Mandate principal matches the principal the agent acts for
+3. Mandate expiry is parseable and in the future
+4. Action is in the mandate's allowed actions
+
+Pass or fail, you get a reason and a hash-chained receipt.
+
+What it does **not** do: decide if an action is wise, legal, or
+safe. Mandate fit only.
+
+## Signup (v1)
+
+```bash
+curl -X POST https://forgingstack-mandate-check.jkbattles.workers.dev/v1/signup \
+  -H "Content-Type: application/json" \
+  -d '{"email":"you@example.com"}'
+```
+
+Returns an API key **once** and 100 starter credits. Save the key
+immediately — it is stored only as a hash and cannot be shown again.
+Email verification is pending, and credit-pack billing is not live
+yet, so do not expect a purchase flow in v1.
+
+## Agent sub-keys
+
+A signed-up human creates a key for each agent, capped and revocable:
+
+```bash
+curl -X POST https://forgingstack-mandate-check.jkbattles.workers.dev/v1/keys \
+  -H "X-API-Key: YOUR_PRIMARY_KEY" -H "Content-Type: application/json" \
+  -d '{"agent_name":"my-agent","credits":20}'
+```
+
+List with `GET /v1/keys`, revoke with `DELETE /v1/keys/{id}` —
+revoking returns unused credits to the primary account.
+
+## Use it (MCP, stdio)
+
+Set the key, then run the MCP server in this repo:
+
+```bash
+export FORGINGSTACK_API_KEY="your-key-here"
+python -m app.mcp_server
+```
+
+Tools: `check_mandate`, `get_credits`, `get_receipt`.
+See `SKILL.md` for when to use it and when not to.
+
+## Price
+
+1 credit per check call. A failed decision still costs 1 credit —
+the check was performed. An idempotent replay (same
+`Idempotency-Key`) is free and returns the original receipt.
+
+## Files in this repo
+
+- `app/mcp_server.py` — MCP wrapper client (stdio, stdlib only)
+- `SKILL.md` — when to use it, how to read pass/fail
+- `agent-card.json` — A2A-style discovery card
+- `server.json` — MCP Registry metadata (draft until PyPI publish)
+- `pyproject.toml` — package metadata for the MCP client

forgingstack_mandate_check-0.2.0/forgingstack_mandate_check.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+app/__init__.py
+app/mcp_server.py
+forgingstack_mandate_check.egg-info/PKG-INFO
+forgingstack_mandate_check.egg-info/SOURCES.txt
+forgingstack_mandate_check.egg-info/dependency_links.txt
+forgingstack_mandate_check.egg-info/entry_points.txt
+forgingstack_mandate_check.egg-info/top_level.txt

forgingstack_mandate_check-0.2.0/forgingstack_mandate_check.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

forgingstack_mandate_check-0.2.0/forgingstack_mandate_check.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+forgingstack-mandate-check = app.mcp_server:main

forgingstack_mandate_check-0.2.0/forgingstack_mandate_check.egg-info/top_level.txt

@@ -0,0 +1 @@
+app

forgingstack_mandate_check-0.2.0/pyproject.toml

@@ -0,0 +1,24 @@
+# DRAFT packaging for the MCP server only (stdlib, no FastAPI dependency).
+# Do not publish to PyPI until: (1) the GitHub repo exists and is public,
+# (2) the live API endpoint exists (the MCP server calls it over HTTP),
+# (3) the maintainer approves the PyPI name and licence.
+# The REST API itself (app/main.py) is a separate service, not this package.
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "forgingstack-mandate-check"
+version = "0.2.0"
+description = "Before your agent acts, check its mandate. One call, one receipt."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = []
+
+
+[project.scripts]
+forgingstack-mandate-check = "app.mcp_server:main"
+
+[tool.setuptools.packages.find]
+include = ["app*"]

forgingstack_mandate_check-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+