dero-mcp-server 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DHEBP
+
+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.

package/README.md

@@ -1,12 +1,53 @@
 # DERO MCP server
 
-[Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that exposes **read-only and analysis** calls against a DERO Stargate **daemon** JSON-RPC endpoint. Use it from **Claude Desktop**, **Cursor**, or any MCP client that launches a local process over stdio.
+> **Model Context Protocol server for DERO chain inspection** — query daemon state, inspect smart contracts, trace transactions, and run read-only diagnostics from Cursor, OpenCode, Claude Desktop, or any MCP host.
+
+[![MCP Registry](https://img.shields.io/badge/MCP-io.github.DHEBP%2Fdero--mcp--server-blue)](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.DHEBP/dero-mcp-server)
+[![CI](https://github.com/DHEBP/dero-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/DHEBP/dero-mcp-server/actions/workflows/ci.yml)
+[![dero-mcp-server MCP server](https://glama.ai/mcp/servers/DHEBP/dero-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/DHEBP/dero-mcp-server)
+
+**Registry listing:** `io.github.DHEBP/dero-mcp-server` · **Version:** `0.1.2` · **Transport:** `stdio` (npm package)
+
+---
+
+[Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that exposes **read-only and analysis** calls against a DERO Stargate **daemon** JSON-RPC endpoint. Use it from **Claude Desktop**, **Cursor**, **OpenCode**, or any MCP client that launches a local process over stdio.
+
+## Quick start
+
+### 1. Add this to your MCP host config
+
+```json
+{
+  "mcpServers": {
+    "dero-daemon": {
+      "command": "npx",
+      "args": ["-y", "dero-mcp-server"],
+      "env": {
+        "DERO_DAEMON_URL": "http://127.0.0.1:10102"
+      }
+    }
+  }
+}
+```
+
+Use your own daemon URL when possible. If `DERO_DAEMON_URL` is omitted, the server uses the default public RPC.
+
+### 2. Restart your MCP host
+
+### 3. Try a prompt
+
+> "Check if my DERO node is synced and summarize chain health."
+
+---
 
 ## What it does
 
 - Connects to `{DERO_DAEMON_URL}/json_rpc` (default `http://82.65.143.182:10102`).
 - Registers one MCP tool per common daemon method (`DERO.GetInfo`, `DERO.GetHeight`, `DERO.GetSC`, etc.).
+- Adds bundled docs retrieval tools for `derod`, `tela`, `hologram`, and `deropay` (ships inside the npm package — no local clone required).
+- Exposes MCP resources and prompts for consistent investigation workflows.
 - Returns JSON results as MCP text content.
+- Returns structured tool errors with `_meta.error` (`code`, `hint`, `retryable`) to help agents self-correct.
 
 **Not included (by design in v0.1):** wallet RPC (`transfer`, `scinvoke`), `DERO.SendRawTransaction`, `DERO.SubmitBlock`. Those can move funds or consensus data; add them only with explicit user consent and a locked-down setup.
 
@@ -39,7 +80,7 @@ The baked-in default is a **third-party** public RPC (`82.65.143.182:10102`) —
 
 Strip a trailing `/json_rpc` if you paste a full JSON-RPC URL — this server appends `/json_rpc`.
 
-## Claude Desktop
+## Claude Desktop (same pattern for OpenCode and Cursor)
 
 Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):
 
@@ -56,17 +97,109 @@ Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claud
 
 Optional: add `"env": { "DERO_DAEMON_URL": "http://127.0.0.1:10102" }` if you use a **local** daemon instead of the default public RPC.
 
-Restart Claude Desktop.
+Restart Claude Desktop (or your OpenCode/Cursor host).
 
-## Cursor
+## Cursor (or OpenCode)
 
-In **Cursor Settings → MCP**, add a server that runs the same `command` / `args` / `env` as above.
+In **Cursor Settings → MCP** (or OpenCode MCP settings), add a server that runs the same `command` / `args` / `env` as above.
+
+## OpenCode
+
+In **OpenCode MCP settings**, add a server with the same `command` / `args` / `env` as above.
 
 ## Environment
 
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `DERO_DAEMON_URL` | `http://82.65.143.182:10102` | Daemon **base** URL (no `/json_rpc` required). Set to `http://127.0.0.1:10102` for a local daemon. |
+| `DERO_DOCS_ROOT` | bundled index | Optional dev override: path to a local `dero-docs` clone to index live MDX instead of the shipped bundle. |
+
+## Maintainer: refresh bundled docs
+
+Before publishing a new npm version when `dero-docs` changed:
+
+```bash
+DERO_DOCS_ROOT=/path/to/dero-docs npm run build:docs
+npm run build
+npm publish
+mcp-publisher publish
+```
+
+`prepack` runs `build:docs` automatically when `dero-docs` is available at `../dero-docs` or via `DERO_DOCS_ROOT`.
+
+## Testing
+
+```bash
+# Check daemon connectivity
+npm run doctor
+
+# MCP surface contract checks (tools/resources/prompts + error probe)
+npm run smoke:mcp
+
+# Docs retrieval checks (bundled index — no clone required)
+npm run smoke:docs
+
+# Run flow tests (10 RPC checks)
+npm run test:flows
+
+# Typecheck
+npm run typecheck
+```
+
+Flow tests run against the default public RPC. Set `DERO_DAEMON_URL` to test against your own daemon.
+
+CI runs on every push and PR — see `.github/workflows/ci.yml`.
+
+## Official MCP Registry
+
+Publish flow (maintainers):
+
+```bash
+mcp-publisher validate
+mcp-publisher login github
+mcp-publisher publish
+```
+
+Verify listing:
+
+```bash
+curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.DHEBP/dero-mcp-server"
+```
+
+## MCP Surface
+
+- **Tools (20):** daemon read/analysis methods + docs retrieval (`dero_docs_search`, `dero_docs_get_page`, `dero_docs_list`)
+- **Resources (3):** `dero://mcp/server-info`, `dero://mcp/safety-boundary`, `dero://mcp/example-flows`
+- **Prompts (3):** `network_health_check`, `inspect_smart_contract`, `trace_transaction`
+
+## Error Contract
+
+When a tool call fails, the server returns a structured error payload in tool content:
+
+```json
+{
+  "ok": false,
+  "tool": "dero_get_sc",
+  "_meta": {
+    "error": {
+      "code": "RPC_UNREACHABLE",
+      "hint": "Confirm daemon is running and reachable, then rerun `npm run doctor`.",
+      "retryable": true,
+      "raw": "fetch failed"
+    }
+  }
+}
+```
+
+Common `code` values:
+
+- `INVALID_INPUT`
+- `RPC_INVALID_PARAMS`
+- `RPC_METHOD_NOT_FOUND`
+- `RPC_HTTP_ERROR`
+- `RPC_UNREACHABLE`
+- `RPC_INVALID_RESPONSE`
+- `TOOL_EXECUTION_ERROR`
 
 ## Roadmap