From 0adcbc3a6fea9deaaef888f57a47b6028eba93df Mon Sep 17 00:00:00 2001
From: Fox <infoaosoficial@gmail.com>
Date: Sat, 6 Jun 2026 11:49:37 +0200
Subject: [PATCH] Add MCP schemas for proof and ledger lookups

---
 app/mcp.py            | 36 ++++++++++++++++++++++++++++++++++--
 docs/agent-guide.md   |  4 ++++
 tests/test_api_mcp.py | 12 ++++++++++++
 3 files changed, 50 insertions(+), 2 deletions(-)

diff --git a/app/mcp.py b/app/mcp.py
index 74fc2763..d80883ad 100644
--- a/app/mcp.py
+++ b/app/mcp.py
@@ -194,8 +194,40 @@
         "name": "submit_wallet_transfer",
         "description": "Submit a signed MRWK wallet transfer",
     },
-    {"name": "get_ledger_entry", "description": "Get a ledger entry"},
-    {"name": "get_proof", "description": "Get a public proof by hash"},
+    {
+        "name": "get_ledger_entry",
+        "description": "Get a ledger entry by immutable ledger sequence",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "sequence": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "description": "Immutable public ledger sequence number.",
+                },
+            },
+            "required": ["sequence"],
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "get_proof",
+        "description": "Get a public proof by hash",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "hash": {
+                    "type": "string",
+                    "pattern": "^[0-9a-fA-F]{64}$",
+                    "description": (
+                        "Public proof hash returned by ledger, activity, or bounty APIs."
+                    ),
+                },
+            },
+            "required": ["hash"],
+            "additionalProperties": False,
+        },
+    },
     {
         "name": "submit_work_proof",
         "description": (
diff --git a/docs/agent-guide.md b/docs/agent-guide.md
index 7eea54d1..77756c64 100644
--- a/docs/agent-guide.md
+++ b/docs/agent-guide.md
@@ -316,6 +316,10 @@ Tools:
 - `submit_work_proof` (`format: "json"` returns structuredContent; `tools/list`
   advertises the selector and format schema)
 
+`tools/list` advertises required selector schemas for proof and ledger lookups:
+`get_proof` requires a 64-character proof `hash`, and `get_ledger_entry`
+requires a positive integer `sequence`.
+
 Successful MCP tools that return JSON objects or lists include both the
 backward-compatible JSON string in `result.content[0].text` and parsed
 `result.structuredContent`. Prefer `structuredContent` when present, and fall
diff --git a/tests/test_api_mcp.py b/tests/test_api_mcp.py
index d78bc7d9..59f1b894 100644
--- a/tests/test_api_mcp.py
+++ b/tests/test_api_mcp.py
@@ -377,6 +377,18 @@ def test_mcp_tools_list_and_call(sqlite_url: str) -> None:
     assert balance_schema["additionalProperties"] is False
     assert balance_schema["properties"]["account"]["minLength"] == 1
     assert "github:<login>" in balance_schema["properties"]["account"]["description"]
+    ledger_tool = next(
+        tool for tool in tools["result"]["tools"] if tool["name"] == "get_ledger_entry"
+    )
+    ledger_schema = ledger_tool["inputSchema"]
+    assert ledger_schema["required"] == ["sequence"]
+    assert ledger_schema["additionalProperties"] is False
+    assert ledger_schema["properties"]["sequence"]["minimum"] == 1
+    proof_tool = next(tool for tool in tools["result"]["tools"] if tool["name"] == "get_proof")
+    proof_schema = proof_tool["inputSchema"]
+    assert proof_schema["required"] == ["hash"]
+    assert proof_schema["additionalProperties"] is False
+    assert proof_schema["properties"]["hash"]["pattern"] == "^[0-9a-fA-F]{64}$"
 
     balance = client.post(
         "/mcp",