dero-mcp-server 0.1.1 → 0.2.2

package/docs/example-agent-flows.md

@@ -1,236 +0,0 @@
-# Example Agent Flows
-
-How to use DERO MCP tools in multi-step conversations. These examples work in Cursor, Claude Desktop, or any MCP client with `dero-mcp-server` configured.
-
----
-
-## Flow 1: Network Health Check
-
-**User prompt:**
-> "Is my DERO node synced?"
-
-**Agent steps:**
-
-1. `dero_daemon_ping` — confirm daemon is reachable
-2. `dero_get_info` — get version, network, topoheight, difficulty
-3. `dero_get_height` — get height, stableheight, topoheight
-
-**What to look for:**
-- Ping returns `"Pong"` → daemon is up
-- `topoheight` is increasing over time → node is syncing
-- `stableheight` close to `topoheight` → node is caught up
-- Compare `topoheight` to a block explorer to verify sync status
-
-**Example response:**
-> Your node is reachable and synced. Current topoheight: 4,521,307. Network: mainnet. Daemon version: 3.5.1-1.DERO.STARGATE+05.
-
----
-
-## Flow 2: Smart Contract Inspection
-
-**User prompt:**
-> "Show me the stored variables for SCID abc123..."
-
-**Agent steps:**
-
-1. `dero_get_sc` with `scid`, `variables: true`, `code: false`
-2. Parse the `stringkeys` and `balances` from the response
-3. Interpret Uint64/String values using DVM-BASIC conventions
-
-**What to look for:**
-- `stringkeys` contains stored state (key-value pairs)
-- Keys starting with lowercase are typically private state
-- `balances` shows token holdings if the contract manages assets
-- `code` field contains DVM-BASIC source if `code: true`
-
-**Example prompt:**
-> "What's stored in the name registry contract?"
-
-```
-dero_get_sc({
-  scid: "0000000000000000000000000000000000000000000000000000000000000001",
-  variables: true,
-  code: false
-})
-```
-
----
-
-## Flow 3: Transaction Lookup
-
-**User prompt:**
-> "What happened in transaction 7f3a...?"
-
-**Agent steps:**
-
-1. `dero_get_transaction` with `txs_hashes: ["7f3a..."]`, `decode_as_json: 1`
-2. Summarize transaction type, transfers, and SC invocations
-3. Link to block height from response metadata
-
-**What to look for:**
-- `txs` array contains transaction details
-- `sc_args` shows smart contract function calls
-- `as_hex` is the raw transaction (skip unless debugging)
-- `block_height` and `in_pool` indicate confirmation status
-
-**Example:**
-> Transaction 7f3a... was confirmed at block 4,521,200. It invoked the "Register" function on the name registry with argument "myname".
-
----
-
-## Flow 4: Name Resolution
-
-**User prompt:**
-> "What address owns the name 'dero'?"
-
-**Agent steps:**
-
-1. `dero_name_to_address` with `name: "dero"`, `topoheight: -1`
-2. Return the resolved address
-
-**What to look for:**
-- `address` field contains the DERO address (starts with `dero1` or `deto1`)
-- If name is not registered, the RPC returns an error
-- `topoheight: -1` means "latest chain state"
-
-**Example:**
-> The name "dero" resolves to `dero1qy...` (truncated). This is public on-chain data visible to anyone.
-
----
-
-## Flow 5: Block Exploration
-
-**User prompt:**
-> "Show me block 4,500,000"
-
-**Agent steps:**
-
-1. `dero_get_block` with `height: 4500000`
-2. Summarize: timestamp, miner reward, transaction count, hash
-
-**Alternative — by hash:**
-1. `dero_get_block_header_by_hash` with `hash: "abc123..."`
-
-**What to look for:**
-- `block_header.timestamp` — Unix timestamp of block
-- `block_header.reward` — miner reward in atomic units (divide by 100000 for DERO)
-- `txs` — list of transaction hashes in the block
-
----
-
-## Flow 6: Contract Deploy Prep (Read-Only)
-
-**User prompt:**
-> "Estimate gas for deploying this contract"
-
-**Agent steps:**
-
-1. Validate DVM-BASIC syntax (use `dvm-basic` Cursor skill if available)
-2. `dero_get_gas_estimate` with `sc: "<contract source>"`
-3. Report compute and storage costs
-
-**Important:** This MCP server is **read-only**. It cannot deploy contracts. After estimating gas, tell the user to deploy via:
-- DERO CLI wallet (`curl` to wallet RPC)
-- Engram wallet GUI
-- XSWD browser integration
-
-**Example:**
-> Gas estimate: 5,000 compute + 12,000 storage = 17,000 total. Deploy via your wallet — this MCP cannot submit transactions.
-
----
-
-## Flow 7: Mempool Check
-
-**User prompt:**
-> "Are there pending transactions?"
-
-**Agent steps:**
-
-1. `dero_get_tx_pool`
-2. Report count of pending transaction hashes
-
-**What to look for:**
-- `tx_hashes` array — pending transactions waiting for blocks
-- Empty array means mempool is clear
-- Large mempool may indicate network congestion
-
----
-
-## Flow 8: Encrypted Balance Lookup
-
-**User prompt:**
-> "Get the encrypted balance blob for address dero1qy..."
-
-**Agent steps:**
-
-1. `dero_get_encrypted_balance` with `address`, `topoheight: -1`
-2. Return the encrypted balance data
-
-**Important:** This returns **encrypted** balance data, not cleartext. Only the address owner can decrypt it with their private keys. This is useful for:
-- Building transactions (ring signatures need balance commitments)
-- Verifying an address exists on-chain
-
----
-
-## Flow 9: Mining Template (Advanced)
-
-**User prompt:**
-> "Get a block template for mining"
-
-**Agent steps:**
-
-1. `dero_get_block_template` with `wallet_address: "dero1qy..."`
-2. Return the template blob for mining software
-
-**Note:** This is for miners integrating with pools or solo mining. Most users won't need this.
-
----
-
-## Combining Flows
-
-Real conversations often combine multiple flows:
-
-**User:** "Check if my node is synced, then show me the latest block and any pending transactions."
-
-**Agent:**
-1. `dero_daemon_ping` → confirm reachable
-2. `dero_get_info` → get topoheight
-3. `dero_get_last_block_header` → latest block details
-4. `dero_get_tx_pool` → pending transactions
-
----
-
-## Tips for Agents
-
-1. **Always ping first** if unsure about daemon connectivity
-2. **Use `topoheight: -1`** for latest state in queries that accept it
-3. **SCIDs are 64-character hex** — validate format before calling
-4. **Atomic units**: DERO amounts are in 1/100000 units (5 decimals)
-5. **Read-only boundary**: This MCP cannot send transactions, deploy contracts, or modify state. Guide users to wallet tools for writes.
-6. **Use structured errors**: failed tools return `_meta.error` with `code`, `hint`, and `retryable` for recovery logic.
-
----
-
-## Related Skills
-
-If using Cursor, these skills complement the MCP tools:
-
-| Skill | Use for |
-|---|---|
-| `dero-rpc` | Direct curl commands, wallet RPC (transfers, scinvoke) |
-| `dvm-basic` | Writing and debugging smart contract code |
-| `smart-contracts` | Deployment workflows, ownership transfer |
-| `tela-publisher` | Deploying TELA web apps on-chain |
-| `gnomon-indexer` | Discovering contracts by stored variables |
-
-The MCP provides **live chain reads**. Skills provide **workflow guidance** and access to wallet operations the MCP intentionally excludes.
-
-## Built-in MCP Prompts
-
-These prompts are available from `prompts/list`:
-
-- `network_health_check`
-- `inspect_smart_contract`
-- `trace_transaction`
-
-Use `prompts/get` with arguments, then execute the suggested tool sequence.

package/docs/mcp-agent-ready-evidence.md

@@ -1,108 +0,0 @@
-# DERO MCP Agent-Ready Evidence
-
-**Last updated:** 2026-05-19  
-**Repo:** `DHEBP/dero-mcp-server` @ `6630dee`  
-**Mode:** Local stdio MCP (read-only daemon access)
-
----
-
-## One-line verdict
-
-DERO MCP is **agent-ready for local stdio usage**: surface contract is stable, diagnostics pass, flow tests pass, and CI now includes MCP smoke probes.
-
----
-
-## Verified surface
-
-| Primitive | Count | Notes |
-|---|---:|---|
-| Tools | 17 | Read-only daemon methods only |
-| Resources | 3 | Server info, safety boundary, example flows |
-| Prompts | 3 | Network health, SC inspection, tx tracing |
-
----
-
-## Proof commands and outcomes
-
-### 1) MCP smoke probes
-
-```bash
-npm run smoke:mcp
-```
-
-Result (latest run):
-
-- `tools/list` parity: **17**
-- `resources/list` parity: **3**
-- `prompts/list` parity: **3**
-- `prompts/get` check: **pass**
-- Structured error probe (`_meta.error`): **pass**
-
-### 2) Flow tests
-
-```bash
-npm run test:flows
-```
-
-Result (latest run):
-
-- **10 passed**
-- **0 failed**
-- **0 skipped**
-
-### 3) Daemon connectivity doctor
-
-```bash
-npm run doctor
-```
-
-Result (latest run):
-
-- TCP reachability: **pass**
-- `DERO.Ping`: **pass**
-- `DERO.GetInfo`: **pass**
-
-### 4) Build and type safety
-
-```bash
-npm run build
-npm run typecheck
-```
-
-Result (latest run):
-
-- Build: **pass**
-- Typecheck: **pass**
-
----
-
-## Security boundary (explicit)
-
-This MCP server remains **read-only** by design.
-
-Excluded methods include:
-
-- Wallet mutation calls (e.g., `transfer`, `scinvoke`)
-- `DERO.SendRawTransaction`
-- `DERO.SubmitBlock`
-
-Write operations must remain outside this server unless an explicit wallet-write gate policy is introduced.
-
----
-
-## CI gate
-
-Current CI runs:
-
-1. `npm run build`
-2. `npm run smoke:mcp`
-3. `npm run test:flows`
-4. `tsc --noEmit`
-
----
-
-## Deferred items
-
-- Wallet-write support (intentionally deferred)
-- Streamable HTTP/SSE transport (not required for current stdio-first strategy)
-- Domain DNS discovery artifacts (`.well-known`, `_mcp`, `_agentroot`, `_llms`) until remote transport exists

package/glama.json

@@ -1,6 +0,0 @@
-{
-  "$schema": "https://glama.ai/mcp/schemas/server.json",
-  "maintainers": [
-    "DHEBP"
-  ]
-}

package/scripts/doctor.sh

@@ -1,85 +0,0 @@
-#!/usr/bin/env bash
-# DERO MCP Server — connectivity doctor
-# Checks daemon reachability before using the MCP server.
-#
-# Usage:
-#   ./scripts/doctor.sh                          # uses DERO_DAEMON_URL or default
-#   ./scripts/doctor.sh http://127.0.0.1:10102   # explicit URL
-#   DERO_DAEMON_URL=http://... ./scripts/doctor.sh
-
-set -euo pipefail
-
-# Default: public RPC (same as server default)
-DEFAULT_URL="http://82.65.143.182:10102"
-
-# Accept CLI arg or env var
-DAEMON_URL="${1:-${DERO_DAEMON_URL:-$DEFAULT_URL}}"
-DAEMON_URL="${DAEMON_URL%/}"  # strip trailing slash
-
-echo "DERO MCP Doctor"
-echo "==============="
-echo "Daemon URL: ${DAEMON_URL}"
-echo ""
-
-fail=0
-
-# Check 1: Basic TCP reachability (extract host:port)
-host_port=$(echo "$DAEMON_URL" | sed -E 's|https?://||' | sed 's|/.*||')
-host=$(echo "$host_port" | cut -d: -f1)
-port=$(echo "$host_port" | cut -d: -f2)
-if [[ -z "$port" || "$port" == "$host" ]]; then
-  port=10102
-fi
-
-echo "1. TCP connectivity to ${host}:${port}"
-if nc -z -w 5 "$host" "$port" 2>/dev/null; then
-  echo "   OK — port reachable"
-else
-  echo "   FAIL — cannot reach ${host}:${port}"
-  echo "   Hint: Is the daemon running? Is the port open?"
-  fail=$((fail + 1))
-fi
-
-echo ""
-
-# Check 2: DERO.Ping RPC call
-echo "2. DERO.Ping RPC"
-ping_response=$(curl -sS -m 10 -X POST "${DAEMON_URL}/json_rpc" \
-  -H "Content-Type: application/json" \
-  -d '{"jsonrpc":"2.0","method":"DERO.Ping","id":1}' 2>/dev/null || echo '{"error":"curl_failed"}')
-
-if echo "$ping_response" | grep -Eq '"status":"OK"|"result":"Pong ?"' ; then
-  echo "   OK — daemon responded to ping"
-else
-  echo "   FAIL — DERO.Ping did not return a known success shape"
-  echo "   Response: $ping_response"
-  fail=$((fail + 1))
-fi
-
-echo ""
-
-# Check 3: DERO.GetInfo (confirms chain sync)
-echo "3. DERO.GetInfo RPC"
-info_response=$(curl -sS -m 10 -X POST "${DAEMON_URL}/json_rpc" \
-  -H "Content-Type: application/json" \
-  -d '{"jsonrpc":"2.0","method":"DERO.GetInfo","id":1}' 2>/dev/null || echo '{"error":"curl_failed"}')
-
-if echo "$info_response" | grep -q '"topoheight"'; then
-  topoheight=$(echo "$info_response" | grep -oE '"topoheight":[0-9]+' | grep -oE '[0-9]+')
-  echo "   OK — chain topoheight: ${topoheight:-unknown}"
-else
-  echo "   FAIL — DERO.GetInfo did not return chain data"
-  echo "   Response: $info_response"
-  fail=$((fail + 1))
-fi
-
-echo ""
-
-# Summary
-if [[ "$fail" -eq 0 ]]; then
-  echo "All checks passed. MCP server should work against this daemon."
-  exit 0
-else
-  echo "${fail} check(s) failed. Fix connectivity before using MCP."
-  exit 1
-fi

package/scripts/flow-test.ts

@@ -1,257 +0,0 @@
-#!/usr/bin/env npx tsx
-/**
- * DERO MCP Server — Flow Test
- * 
- * Tests the daemon RPC calls that the MCP tools wrap.
- * Run this against a live daemon (local or remote) to verify connectivity
- * and that the RPC methods return expected data shapes.
- * 
- * Usage:
- *   npx tsx scripts/flow-test.ts
- *   npx tsx scripts/flow-test.ts http://127.0.0.1:10102
- *   DERO_DAEMON_URL=http://... npx tsx scripts/flow-test.ts
- */
-
-const DEFAULT_URL = "http://82.65.143.182:10102";
-
-type FlowStatus = "pass" | "fail" | "skip";
-type FlowResult = {
-  id: string;
-  name: string;
-  status: FlowStatus;
-  message?: string;
-  durationMs: number;
-};
-
-async function deroRpc<T = unknown>(
-  endpoint: string,
-  method: string,
-  params?: unknown
-): Promise<T> {
-  const res = await fetch(`${endpoint}/json_rpc`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({
-      jsonrpc: "2.0",
-      id: "1",
-      method,
-      params,
-    }),
-  });
-
-  if (!res.ok) {
-    throw new Error(`HTTP ${res.status} from daemon`);
-  }
-
-  const data = await res.json();
-  if (data.error) {
-    throw new Error(`RPC error: ${JSON.stringify(data.error)}`);
-  }
-  return data.result;
-}
-
-function assert(condition: unknown, message: string): void {
-  if (!condition) throw new Error(message);
-}
-
-async function runFlow(
-  id: string,
-  name: string,
-  fn: () => Promise<void>
-): Promise<FlowResult> {
-  const start = performance.now();
-  try {
-    await fn();
-    return { id, name, status: "pass", durationMs: Math.round(performance.now() - start) };
-  } catch (error) {
-    return {
-      id,
-      name,
-      status: "fail",
-      message: error instanceof Error ? error.message : String(error),
-      durationMs: Math.round(performance.now() - start),
-    };
-  }
-}
-
-async function runAllFlows(daemonUrl: string): Promise<FlowResult[]> {
-  const results: FlowResult[] = [];
-
-  // Flow 1: Ping
-  results.push(
-    await runFlow("ping", "DERO.Ping — daemon reachable", async () => {
-      const result = await deroRpc<string>(daemonUrl, "DERO.Ping");
-      assert(result === "Pong " || result === "Pong", `Expected 'Pong', got '${result}'`);
-    })
-  );
-
-  // Flow 2: Echo
-  results.push(
-    await runFlow("echo", "DERO.Echo — roundtrip strings", async () => {
-      const words = ["hello", "dero", "mcp"];
-      const result = await deroRpc<string>(daemonUrl, "DERO.Echo", words);
-      assert(typeof result === "string", "Expected string response");
-      assert(result.includes("DERO") || words.some(w => result.includes(w)), "Echo should contain input or DERO");
-    })
-  );
-
-  // Flow 3: GetInfo
-  let topoheight: number | undefined;
-  results.push(
-    await runFlow("get-info", "DERO.GetInfo — chain metadata", async () => {
-      const result = await deroRpc<{
-        topoheight?: number;
-        height?: number;
-        network?: string;
-        version?: string;
-      }>(daemonUrl, "DERO.GetInfo");
-      assert(typeof result.topoheight === "number", "Missing topoheight");
-      assert(typeof result.height === "number", "Missing height");
-      topoheight = result.topoheight;
-    })
-  );
-
-  // Flow 4: GetHeight
-  results.push(
-    await runFlow("get-height", "DERO.GetHeight — block heights", async () => {
-      const result = await deroRpc<{
-        height?: number;
-        stableheight?: number;
-        topoheight?: number;
-      }>(daemonUrl, "DERO.GetHeight");
-      assert(typeof result.height === "number", "Missing height");
-      assert(typeof result.topoheight === "number", "Missing topoheight");
-    })
-  );
-
-  // Flow 5: GetBlockCount
-  results.push(
-    await runFlow("get-block-count", "DERO.GetBlockCount — total blocks", async () => {
-      const result = await deroRpc<{ count?: number }>(daemonUrl, "DERO.GetBlockCount");
-      assert(typeof result.count === "number", "Missing count");
-      assert(result.count > 0, "Block count should be > 0");
-    })
-  );
-
-  // Flow 6: GetLastBlockHeader
-  results.push(
-    await runFlow("get-last-block-header", "DERO.GetLastBlockHeader — tip block", async () => {
-      const result = await deroRpc<{ block_header?: { height?: number; hash?: string } }>(
-        daemonUrl,
-        "DERO.GetLastBlockHeader"
-      );
-      assert(result.block_header, "Missing block_header");
-      assert(typeof result.block_header.height === "number", "Missing height in header");
-    })
-  );
-
-  // Flow 7: GetBlock by height (use topoheight - 10 for safety)
-  results.push(
-    await runFlow("get-block-by-height", "DERO.GetBlock — fetch by height", async () => {
-      const testHeight = Math.max(1, (topoheight ?? 100) - 10);
-      const result = await deroRpc<{ block_header?: unknown }>(daemonUrl, "DERO.GetBlock", {
-        height: testHeight,
-      });
-      assert(result.block_header, "Missing block_header in response");
-    })
-  );
-
-  // Flow 8: GetTxPool (may be empty, just check shape)
-  results.push(
-    await runFlow("get-tx-pool", "DERO.GetTxPool — mempool check", async () => {
-      const result = await deroRpc<{ tx_hashes?: string[] }>(daemonUrl, "DERO.GetTxPool");
-      // tx_hashes may be null/undefined if empty, which is fine
-      assert(
-        result.tx_hashes === undefined || result.tx_hashes === null || Array.isArray(result.tx_hashes),
-        "tx_hashes should be array or null"
-      );
-    })
-  );
-
-  // Flow 9: NameToAddress (test known name "dero" — may not exist on all networks)
-  results.push(
-    await runFlow("name-to-address", "DERO.NameToAddress — resolve 'dero'", async () => {
-      try {
-        const result = await deroRpc<{ address?: string; name?: string }>(
-          daemonUrl,
-          "DERO.NameToAddress",
-          { name: "dero", topoheight: -1 }
-        );
-        // Name may not be registered, that's okay
-        if (result.address) {
-          assert(result.address.startsWith("dero") || result.address.startsWith("deto"), "Invalid address format");
-        }
-      } catch (e) {
-        // Name not found is acceptable
-        if (String(e).includes("NOT FOUND") || String(e).includes("not found")) {
-          return;
-        }
-        throw e;
-      }
-    })
-  );
-
-  // Flow 10: GetSC — test with the name registry SCID
-  const NAME_REGISTRY_SCID = "0000000000000000000000000000000000000000000000000000000000000001";
-  results.push(
-    await runFlow("get-sc", "DERO.GetSC — name registry contract", async () => {
-      const result = await deroRpc<{ code?: string; balances?: unknown }>(
-        daemonUrl,
-        "DERO.GetSC",
-        { scid: NAME_REGISTRY_SCID, code: true, variables: false }
-      );
-      assert(result.code, "Missing contract code");
-      assert(result.code.includes("Function"), "Code should contain Function keyword");
-    })
-  );
-
-  return results;
-}
-
-function formatReport(results: FlowResult[]): string {
-  const lines: string[] = [
-    "",
-    "DERO MCP Flow Test Results",
-    "==========================",
-    "",
-  ];
-
-  const passed = results.filter((r) => r.status === "pass").length;
-  const failed = results.filter((r) => r.status === "fail").length;
-  const skipped = results.filter((r) => r.status === "skip").length;
-
-  for (const r of results) {
-    const icon = r.status === "pass" ? "✓" : r.status === "fail" ? "✗" : "○";
-    const status = r.status.toUpperCase().padEnd(4);
-    lines.push(`${icon} ${status} ${r.name} (${r.durationMs}ms)`);
-    if (r.message) {
-      lines.push(`       ${r.message}`);
-    }
-  }
-
-  lines.push("");
-  lines.push(`Summary: ${passed} passed, ${failed} failed, ${skipped} skipped`);
-  lines.push("");
-
-  return lines.join("\n");
-}
-
-async function main() {
-  const daemonUrl = (process.argv[2] || process.env.DERO_DAEMON_URL || DEFAULT_URL).replace(/\/$/, "");
-
-  console.log(`Testing daemon at: ${daemonUrl}`);
-  console.log("");
-
-  try {
-    const results = await runAllFlows(daemonUrl);
-    console.log(formatReport(results));
-
-    const failed = results.filter((r) => r.status === "fail").length;
-    process.exit(failed > 0 ? 1 : 0);
-  } catch (error) {
-    console.error("Fatal error:", error instanceof Error ? error.message : error);
-    process.exit(1);
-  }
-}
-
-main();