raposa-mcp 0.1.0__tar.gz

raposa_mcp-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.pytest_cache/

raposa_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DC ESCRYPT SL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

raposa_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: raposa-mcp
+Version: 0.1.0
+Summary: MCP server for Raposa Aval: give your agent a request_human_approval tool with a signed audit trail.
+Project-URL: Homepage, https://raposa.group
+Project-URL: Documentation, https://raposa.group/docs/
+Project-URL: Source, https://github.com/agentlabbusiness/raposa-mcp
+Author-email: DC ESCRYPT SL <contact@raposa.group>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,approval,audit,human-in-the-loop,mcp
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<2,>=1.2
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-asyncio; extra == 'test'
+Description-Content-Type: text/markdown
+
+# raposa-mcp
+
+An MCP server that gives your agent one honest tool: **ask a human**.
+
+```
+request_human_approval(action, context, risk) -> { approved: true|false, decided_by, ... }
+```
+
+`approved` is `true` only when a named person pressed Approve. A timeout, an expiry or a rejection all
+return `approved: false` — silence is not consent. Every decision is sealed in Raposa's hash-chained
+audit log, exportable for an auditor. EU-hosted, DPA available.
+
+## Install
+
+```json
+{
+  "mcpServers": {
+    "raposa": {
+      "command": "uvx",
+      "args": ["raposa-mcp"],
+      "env": { "RAPOSA_API_KEY": "<your key>" }
+    }
+  }
+}
+```
+
+Claude Code: `claude mcp add raposa -e RAPOSA_API_KEY=<your key> -- uvx raposa-mcp`
+
+Until the PyPI release lands, install straight from GitHub (identical code):
+
+```bash
+claude mcp add raposa -e RAPOSA_API_KEY=<your key> -- uvx --from git+https://github.com/agentlabbusiness/raposa-mcp raposa-mcp
+```
+
+Get a free sandbox key (100 approvals a month) at https://raposa.group/start/ — it arrives by email in a minute.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `request_human_approval(action, context, risk, requested_by?, wait_sec=600, expires_in_sec?)` | creates the request and waits for a human; returns `approved` |
+| `create_approval(action, context, risk, requested_by?, expires_in_sec?, webhook_url?)` | returns the id at once; decision arrives on the HMAC-signed webhook or via `get_approval` |
+| `get_approval(approval_id)` | reads one approval |
+
+`risk` is `low | medium | high`. The API key is read from `RAPOSA_API_KEY` only and never appears in tool
+inputs or outputs. Base URL override: `RAPOSA_API_BASE` (default `https://dcescrypt.com/api`).
+
+## Who approves
+
+The people on your team who hold the approve button get a scoped console login and, if you give us their
+email, every request also reaches them as a mail with signed Approve / Reject links. Their name is recorded on
+the decision. Docs: https://raposa.group/docs/#approvers
+
+## Develop
+
+```bash
+pip install -e ".[test]" && pytest -q
+```
+
+MIT · DC ESCRYPT SL · contact@raposa.group

raposa_mcp-0.1.0/README.md

@@ -0,0 +1,60 @@
+# raposa-mcp
+
+An MCP server that gives your agent one honest tool: **ask a human**.
+
+```
+request_human_approval(action, context, risk) -> { approved: true|false, decided_by, ... }
+```
+
+`approved` is `true` only when a named person pressed Approve. A timeout, an expiry or a rejection all
+return `approved: false` — silence is not consent. Every decision is sealed in Raposa's hash-chained
+audit log, exportable for an auditor. EU-hosted, DPA available.
+
+## Install
+
+```json
+{
+  "mcpServers": {
+    "raposa": {
+      "command": "uvx",
+      "args": ["raposa-mcp"],
+      "env": { "RAPOSA_API_KEY": "<your key>" }
+    }
+  }
+}
+```
+
+Claude Code: `claude mcp add raposa -e RAPOSA_API_KEY=<your key> -- uvx raposa-mcp`
+
+Until the PyPI release lands, install straight from GitHub (identical code):
+
+```bash
+claude mcp add raposa -e RAPOSA_API_KEY=<your key> -- uvx --from git+https://github.com/agentlabbusiness/raposa-mcp raposa-mcp
+```
+
+Get a free sandbox key (100 approvals a month) at https://raposa.group/start/ — it arrives by email in a minute.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `request_human_approval(action, context, risk, requested_by?, wait_sec=600, expires_in_sec?)` | creates the request and waits for a human; returns `approved` |
+| `create_approval(action, context, risk, requested_by?, expires_in_sec?, webhook_url?)` | returns the id at once; decision arrives on the HMAC-signed webhook or via `get_approval` |
+| `get_approval(approval_id)` | reads one approval |
+
+`risk` is `low | medium | high`. The API key is read from `RAPOSA_API_KEY` only and never appears in tool
+inputs or outputs. Base URL override: `RAPOSA_API_BASE` (default `https://dcescrypt.com/api`).
+
+## Who approves
+
+The people on your team who hold the approve button get a scoped console login and, if you give us their
+email, every request also reaches them as a mail with signed Approve / Reject links. Their name is recorded on
+the decision. Docs: https://raposa.group/docs/#approvers
+
+## Develop
+
+```bash
+pip install -e ".[test]" && pytest -q
+```
+
+MIT · DC ESCRYPT SL · contact@raposa.group

raposa_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "raposa-mcp"
+version = "0.1.0"
+description = "MCP server for Raposa Aval: give your agent a request_human_approval tool with a signed audit trail."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "DC ESCRYPT SL", email = "contact@raposa.group" }]
+keywords = ["mcp", "human-in-the-loop", "approval", "ai-agents", "audit"]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = ["mcp>=1.2,<2", "httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://raposa.group"
+Documentation = "https://raposa.group/docs/"
+Source = "https://github.com/agentlabbusiness/raposa-mcp"
+
+[project.scripts]
+raposa-mcp = "raposa_mcp.server:main"
+
+[project.optional-dependencies]
+test = ["pytest", "pytest-asyncio"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

raposa_mcp-0.1.0/raposa_mcp/__init__.py

@@ -0,0 +1,2 @@
+"""raposa-mcp: MCP server for Raposa Aval human approvals."""
+__version__ = "0.1.0"

raposa_mcp-0.1.0/raposa_mcp/server.py

@@ -0,0 +1,145 @@
+"""raposa-mcp — an MCP server that gives an agent one honest tool: ask a human.
+
+    request_human_approval(action, context, risk) -> {approved: bool, ...}
+
+`approved` is True only when a named human approved. A timeout, an expiry or
+a rejection all come back with approved=False — silence is not consent.
+The API key lives in RAPOSA_API_KEY and is never part of tool inputs or
+outputs. Spec: raposa/docs/specs/R6-mcp-server.md
+"""
+import asyncio
+import json
+import os
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+DEFAULT_BASE = "https://dcescrypt.com/api"
+POLL_SEC = 5.0
+RISKS = ("low", "medium", "high")
+
+mcp = FastMCP(
+    "raposa",
+    instructions=("Raposa Aval: pause a high-stakes action until an authorised human approves it. "
+                  "Call request_human_approval before payments, deploys, deletions or customer-facing "
+                  "commitments. Proceed only when the result has approved=true."),
+)
+
+_transport = None   # tests inject an httpx.MockTransport
+
+
+def configure(transport=None):
+    global _transport
+    _transport = transport
+
+
+class ToolError(Exception):
+    pass
+
+
+def _client() -> httpx.AsyncClient:
+    key = os.environ.get("RAPOSA_API_KEY", "").strip()
+    if not key:
+        raise ToolError("RAPOSA_API_KEY is not set. Get a free sandbox key at https://raposa.group/start/ "
+                        "and put it in the MCP server's environment.")
+    base = os.environ.get("RAPOSA_API_BASE", DEFAULT_BASE).rstrip("/")
+    return httpx.AsyncClient(base_url=base, transport=_transport, timeout=20.0,
+                             headers={"Authorization": f"Bearer {key}",
+                                      "User-Agent": "raposa-mcp/0.1 (+https://raposa.group)"})
+
+
+async def _request(method: str, path: str, **kw) -> dict:
+    async with _client() as c:
+        r = await c.request(method, path, **kw)
+        if r.status_code == 429:
+            await asyncio.sleep(min(float(r.headers.get("Retry-After", "1") or 1), 10))
+            r = await c.request(method, path, **kw)
+        if r.status_code >= 400:
+            raise ToolError(f"Raposa API {r.status_code} on {method} {path}: {r.text[:300]}")
+        return r.json()
+
+
+def _shape(a: dict) -> dict:
+    status = a.get("status")
+    return {"id": a.get("id"), "status": status, "approved": status == "approved",
+            "decided_by": a.get("decided_by") or None, "decided_at": a.get("decided_at"),
+            "comment": a.get("decision_comment"),
+            "message": {"approved": "Approved by a human — proceed.",
+                        "rejected": "Rejected by a human — do not proceed.",
+                        "expired": "Not approved — the request expired before anyone decided.",
+                        "pending": "Still waiting for a human."}.get(status, "Not approved.")}
+
+
+def _validate(action: str, context: str, risk: str):
+    if risk not in RISKS:
+        raise ToolError(f"risk must be one of {RISKS}, got {risk!r}")
+    if not action or not context:
+        raise ToolError("action and context are required")
+
+
+def _create_body(action, context, risk, requested_by, expires_in_sec, webhook_url):
+    body = {"action": action[:200], "context": context[:4000], "risk": risk,
+            "requested_by": (requested_by or "mcp-agent")[:200]}
+    if expires_in_sec:
+        body["expires_in_sec"] = int(expires_in_sec)
+    if webhook_url:
+        body["webhook_url"] = webhook_url
+    return body
+
+
+@mcp.tool()
+async def create_approval(action: str, context: str, risk: str, requested_by: str = "mcp-agent",
+                          expires_in_sec: int | None = None, webhook_url: str | None = None) -> str:
+    """Create an approval request and return its id immediately (no waiting).
+    Use with a webhook_url, or poll with get_approval. risk: low | medium | high."""
+    try:
+        _validate(action, context, risk)
+        out = await _request("POST", "/v1/approvals",
+                             json=_create_body(action, context, risk, requested_by, expires_in_sec, webhook_url))
+        return json.dumps({"id": out.get("id"), "status": out.get("status")})
+    except ToolError as exc:
+        raise RuntimeError(str(exc))
+
+
+@mcp.tool()
+async def get_approval(approval_id: str) -> str:
+    """Read an approval by id. Look at `approved` — it is true only when a human approved."""
+    try:
+        return json.dumps(_shape(await _request("GET", f"/v1/approvals/{approval_id}")))
+    except ToolError as exc:
+        raise RuntimeError(str(exc))
+
+
+@mcp.tool()
+async def request_human_approval(action: str, context: str, risk: str, requested_by: str = "mcp-agent",
+                                 wait_sec: int = 600, expires_in_sec: int | None = None) -> str:
+    """Ask an authorised human to approve an action and wait for the answer.
+    Returns {approved: bool, status, decided_by, ...}. Proceed ONLY if approved is true —
+    a timeout, an expiry or a rejection means do not proceed. risk: low | medium | high."""
+    try:
+        _validate(action, context, risk)
+        created = await _request("POST", "/v1/approvals",
+                                 json=_create_body(action, context, risk, requested_by, expires_in_sec, None))
+        aid = created.get("id")
+        loop = asyncio.get_event_loop()
+        deadline = loop.time() + max(0, int(wait_sec))
+        while True:
+            a = await _request("GET", f"/v1/approvals/{aid}")
+            if a.get("status") != "pending":
+                return json.dumps(_shape(a))
+            if loop.time() >= deadline:
+                return json.dumps({"id": aid, "status": "timeout", "approved": False,
+                                   "decided_by": None, "decided_at": None, "comment": None,
+                                   "message": f"Not approved — nobody answered in {wait_sec}s. "
+                                              "The request is still open; check later with get_approval."})
+            await asyncio.sleep(POLL_SEC)
+    except ToolError as exc:
+        raise RuntimeError(str(exc))
+
+
+def main():
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

raposa_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,142 @@
+"""R6 — contract tests for the raposa-mcp server. Spec: raposa/docs/specs/R6-mcp-server.md
+
+Written before the implementation. The Raposa API is faked with an httpx
+MockTransport; the MCP side is exercised through the SDK's in-memory
+client/server session, i.e. exactly what a real MCP client would see.
+"""
+import json
+
+import httpx
+import pytest
+from mcp.shared.memory import create_connected_server_and_client_session as client_session
+
+from raposa_mcp import server as srv
+
+
+class FakeApi:
+    """Minimal Raposa API: create → pending; decided after `decide_after` reads."""
+
+    def __init__(self, decide_after=1, final="approved", status_code=200):
+        self.decide_after, self.final, self.status_code = decide_after, final, status_code
+        self.reads, self.calls, self.auth = 0, [], []
+
+    def handler(self, request: httpx.Request) -> httpx.Response:
+        self.calls.append((request.method, request.url.path))
+        self.auth.append(request.headers.get("authorization"))
+        if self.status_code != 200:
+            return httpx.Response(self.status_code, json={"detail": f"faked {self.status_code}"})
+        if request.method == "POST" and request.url.path.endswith("/v1/approvals"):
+            body = json.loads(request.content)
+            assert body["risk"] in ("low", "medium", "high")
+            return httpx.Response(200, json={"id": "ap-1", "status": "pending"})
+        if request.method == "GET" and "/v1/approvals/ap-1" in request.url.path:
+            self.reads += 1
+            decided = self.reads >= self.decide_after
+            return httpx.Response(200, json={
+                "id": "ap-1", "action": "payout", "status": self.final if decided else "pending",
+                "decided_by": "approver:finance-lead" if decided else "",
+                "decided_at": "2026-09-03T10:00:00.000000Z" if decided else None,
+                "decision_comment": "ok" if decided else None})
+        return httpx.Response(404, json={"detail": "no"})
+
+
+@pytest.fixture
+def api(monkeypatch):
+    fake = FakeApi()
+    monkeypatch.setenv("RAPOSA_API_KEY", "test-key-value")
+    monkeypatch.setattr(srv, "POLL_SEC", 0)          # no real sleeping in tests
+    srv.configure(transport=httpx.MockTransport(fake.handler))
+    return fake
+
+
+async def _call(name, args):
+    async with client_session(srv.mcp._mcp_server) as client:
+        return await client.call_tool(name, args)
+
+
+def _payload(result):
+    text = "".join(c.text for c in result.content if getattr(c, "text", None))
+    try:
+        return json.loads(text)
+    except ValueError:
+        return {"_text": text}
+
+
+async def test_tools_are_listed_with_schemas(api):
+    async with client_session(srv.mcp._mcp_server) as client:
+        tools = {t.name: t for t in (await client.list_tools()).tools}
+    assert set(tools) >= {"request_human_approval", "create_approval", "get_approval"}
+    props = tools["request_human_approval"].inputSchema["properties"]
+    assert {"action", "context", "risk"} <= set(props)
+    assert "api_key" not in props and "key" not in props
+
+
+async def test_request_waits_and_returns_approved(api):
+    api.decide_after = 3
+    r = await _call("request_human_approval",
+                    {"action": "payout", "context": "invoice 7", "risk": "high", "wait_sec": 30})
+    out = _payload(r)
+    assert out["status"] == "approved" and out["approved"] is True
+    assert out["decided_by"] == "approver:finance-lead" and out["id"] == "ap-1"
+    assert api.reads == 3
+
+
+async def test_reject_is_not_approved(api):
+    api.final = "rejected"
+    out = _payload(await _call("request_human_approval",
+                               {"action": "payout", "context": "x", "risk": "low"}))
+    assert out["status"] == "rejected" and out["approved"] is False
+
+
+async def test_timeout_is_not_approval(api):
+    api.decide_after = 10 ** 6
+    out = _payload(await _call("request_human_approval",
+                               {"action": "payout", "context": "x", "risk": "low", "wait_sec": 0}))
+    assert out["status"] == "timeout" and out["approved"] is False
+    assert "not approved" in out["message"].lower()
+
+
+async def test_expired_is_not_approval(api):
+    api.final = "expired"
+    out = _payload(await _call("request_human_approval",
+                               {"action": "payout", "context": "x", "risk": "low"}))
+    assert out["status"] == "expired" and out["approved"] is False
+
+
+async def test_create_returns_id_without_waiting(api):
+    out = _payload(await _call("create_approval", {"action": "deploy", "context": "v2", "risk": "medium"}))
+    assert out == {"id": "ap-1", "status": "pending"}
+    assert api.reads == 0
+
+
+async def test_get_approval(api):
+    api.decide_after = 1
+    out = _payload(await _call("get_approval", {"approval_id": "ap-1"}))
+    assert out["status"] == "approved" and out["approved"] is True
+
+
+async def test_api_error_is_reported_not_swallowed(api):
+    api.status_code = 401
+    r = await _call("create_approval", {"action": "x", "context": "y", "risk": "low"})
+    assert r.isError
+    assert "401" in _payload(r).get("_text", "")
+
+
+async def test_bad_risk_never_hits_the_api(api):
+    r = await _call("create_approval", {"action": "x", "context": "y", "risk": "critical"})
+    assert r.isError and api.calls == []
+
+
+async def test_missing_key_is_a_clear_error_and_server_still_lists_tools(monkeypatch):
+    monkeypatch.delenv("RAPOSA_API_KEY", raising=False)
+    srv.configure(transport=httpx.MockTransport(lambda r: httpx.Response(500)))
+    async with client_session(srv.mcp._mcp_server) as client:
+        assert (await client.list_tools()).tools
+        r = await client.call_tool("create_approval", {"action": "x", "context": "y", "risk": "low"})
+    assert r.isError and "RAPOSA_API_KEY" in _payload(r).get("_text", "")
+
+
+async def test_key_is_sent_as_bearer_and_never_returned(api):
+    r = await _call("create_approval", {"action": "x", "context": "y", "risk": "low"})
+    assert api.auth[-1] == "Bearer test-key-value"
+    assert "test-key-value" not in json.dumps(_payload(r))