v0.4.8

Added

• TELA app discovery — resolve a dURL to its SCID with no external indexer.
  Two new tools answer "what's the SCID for vault.tela?" and "what TELA apps
  exist?" entirely in-process:

  • dero_durl_to_scid — resolves a TELA dURL (e.g. vault.tela) to its
    on-chain SCID(s). dURLs are non-unique, so the newest contract is returned
    as the canonical primary and any other claimants are disclosed under
    other_candidates with collision: true.
  • dero_tela_list_apps — lists/searches the discovered TELA apps (dURL, name,
    SCID, doc count), with an index_meta block disclosing scan coverage.

  How it works (a tiny src/gnomon.ts, no Go sidecar, no separate Gnomon
  service, no bundled binary): one DERO.GetSC on the GnomonSC registry yields
  every SCID with its install height (~5s); since TELA is a recent platform,
  all indexed apps live in the newest ~1,500 SCIDs (measured live: scanning
  ranks 1,500–5,000 found zero more), so only the newest ~2,000 contracts are
  scanned and classified. Result: a ~14s one-time cold start (cached ~10 min,
  with incremental refresh), versus the full Gnomon indexer's ~hour over all
  50k+ contracts. Tunable via DERO_GNOMON_SCAN_DEPTH / DERO_GNOMON_CONCURRENCY.

  Routing note: a bare registered name like quickbrownfox (no dot) is NOT a
  dURL — dero_durl_to_scid returns found: false with a hint to use the
  existing dero_name_to_address for names.

  Total tools: 30 → 32 (11 composites).

Tests

• check:gnomon — 13 offline fixture assertions over a mock daemon (registry
  parse, newest-first scan, decode, dURL→SCID map, non-unique collision, cache).
  A flow-durl-discovery flow test resolves the real vault.tela over the live
  chain and asserts the name-routing guard. Both wired into CI.

v0.4.7

Fixed

• tela_get_doc_content now transparently decompresses gzipped files.
  TELA-CLI stores files as base64-encoded gzip (a .gz filename, the default),
  so the tool previously returned a compressed H4sIAAAA… blob and a "can't
  decompress" note — forcing an agent to shell out to gunzip it by hand. It now
  base64-decodes + gunzips (Node's built-in zlib, no new dependency) and
  returns the plaintext file, stripping .gz from filename while keeping the
  on-chain name in stored_filename and flagging decompressed: true. Verified
  live: feed.tela / cipherchess.tela index.html.gz → real <!DOCTYPE>.
• tela_inspect version history was always empty. Contracts store the
  numbered commit-TXID keys in uint64keys, but the parser only scanned
  stringkeys — so a contract at commit 4 reported "0 versions on chain", a
  contradiction that sent agents back to raw DERO.GetSC. It now scans both
  maps and decodes the TXIDs; verified live (FEED → 5 versions, Crypto hammer →
  4, Cipher Chess → 2).

Added

• tela_inspect surfaces a per-wallet ratings summary ({ voters, values[] }). Real INDEX contracts store each voter's address → <rating>_ <block>; the tool now summarizes this instead of leaving an agent to
  reverse-engineer the rating keys.

Tests

• check:tela-parse gains fixture F9 (version history in uint64keys +
  ratings). A new flow-tela-doc-content-gzip flow test decompresses
  feed.tela's real index.html.gz over the live chain, converting the gzip
  path into a real-data regression.

v0.4.6

Fixed

• tela_inspect now decodes hex-encoded stored values. DERO.GetSC
  returns smart-contract string-key values hex-encoded, which the TELA spec's
  plain-text examples obscured. Inspecting a real mainnet TELA app therefore
  returned the app name as 43727970746f2068616d6d6572 instead of
  "Crypto hammer", the dURL and description as hex, and — because DOC SCID
  values are the 128-char hex encoding of a 64-char SCID — flagged every DOC as
  "malformed". A defensive decodeScValue now hex-decodes any value that
  decodes to printable UTF-8 (leaving counters, binary, and already-plain
  values untouched), DOC SCIDs are decoded before validation (no more false
  malformed flags), the app name falls back to var_nameHdr, and
  telaVersion / likes / dislikes are surfaced. Verified live against the
  c-hammer2-site.tela and cipherchess.tela apps.

Tests

• check:tela-parse gains a hex-encoded fixture (F8) modeled on the live
  "Crypto hammer" app, and the flow-tela-inspect-real-scid flow test now runs
  by default against a real mainnet TELA INDEX (overridable via DERO_TELA_SCID)
  and asserts the decode — converting the offline-only parser proof into a
  live-chain regression. check:server-json now also guards the server.json
  description against the MCP registry's 100-char limit.

v0.4.5

Added

• TELA on-chain tooling — two new tools take TELA from docs-only to a
  read-only builder surface. tela_inspect fetches a SCID and parses it as a
  TELA-INDEX-1 app manifest or a TELA-DOC-1 file contract (auto-detected),
  enumerating the full ordered DOC1..DOCn list, mods, commit/version history,
  and an honest immutability note; non-TELA SCIDs return kind: not_tela
  (a success, not an error). tela_get_doc_content extracts a DOC's actual
  file content from the contract's DVM comment block, with offset pagination
  and .gz-compression flagging. Both read the raw DERO.GetSC stringkeys
  directly via a new shared parser (src/tela-parse.ts) so a large manifest's
  DOC list is not truncated by the 50-key surface cap. Total tools: 28 → 30.

Changed

• explain_smart_contract is now TELA-aware. TELA contracts are detected
  before the token/registry heuristics, fixing a misclassification where a
  TELA contract's EXISTS("nameHdr") made it register as a name registry. The
  kind union gains tela_index and tela_doc, and TELA contracts now cite
  the TELA spec pages.
• Docs search rewritten from substring matching to a BM25F scorer. The old
  binary .includes() scorer (no tokenization, stopwords, term frequency, or
  length normalization) ranked the wrong pages for real questions — e.g.
  "dero vs monero" matched the word "vs" across 144 of 147 pages. The new
  scorer adds word-boundary tokenization (incl. hyphenated standard names like
  TELA-INDEX-1), a curated stoplist, per-field length normalization (which
  ends the Captain-archive keyword-sponge problem), and IDF weighting so rare
  discriminating terms steer ranking. The previously-unused description field
  is now scored, and excerpts are query-centered. recommend_docs_path gains a
  narrow beginner-intent nudge that surfaces the "Understanding DERO"
  orientation page. Computed in-process at load time — no index-format change.

Fixed

• explain_smart_contract / dero_get_sc no longer overflow host token
  limits on large registries. The name service's 22,619 stored keys produced
  a ~413 KB response (rejected by MCP hosts) on the very SCID the tool docs
  recommend as the known-good example. State-variable maps are now capped at a
  sampled 50 keys with *_total / *_truncated markers.
• Tool failures now set isError: true at the protocol level, so MCP hosts
  that branch on the flag recognize a failed call (the structured
  ok:false/_meta.error body is unchanged).
• Two MCP prompt arguments could never validate. reference_topoheight
  (z.number()) and include_breakdown (z.boolean()) were declared with
  non-string zod types, but prompt arguments arrive as strings; they now coerce
  correctly.
• Metadata drift across the front door. README version, tool/resource/prompt
  counts, Node floor, and the registry description were stale; all corrected and
  the surface counts are now guarded by check:server-json.

Distribution

• The live mcp.derod.org streamable-HTTP endpoint is now published in the
  registry via a remotes entry in server.json.

Tests

• New offline guards wired into CI: check:tela-parse (21 TELA-parser fixture
  assertions, incl. a >50-DOC INDEX proving cap-bypass and a registry-is-not-TELA
  case) and check:docs-ranking (the 6 confirmed search cases as a before/after
  regression harness). A live tela_inspect false-positive guard asserts the
  22,619-key name registry classifies as not_tela.

v0.4.4

Fixed

• The bundled docs index silently stripped every code example from every
  page. mdxToPlainText deleted whole fenced code blocks
  (src/docs-parse.ts), so the flagship derod/rpc-api/daemon-rpc-api
  reference shipped with no curl, DERO.GetInfo, or jsonrpc — the source
  has 75 such occurrences, the index had 0. An agent asking "how do I call
  GetInfo" got prose with the command removed. The fence regex now preserves
  the code contents (drops only the ``` and language tag); the flagship page's
  indexed text went from ~6 KB to ~60 KB. A new mustContain content-fidelity
  probe in `smoke:docs` asserts `curl`/`DERO.GetInfo`/`jsonrpc` survive on that
  page so the regression can't silently return. Also folds in the docs refresh
  from dero-docs @ f21a5c9 (146 → 147 pages).

Changed

• docker compose fails loudly when DERO_MCP_VERSION is unset instead of
  silently defaulting to a months-old pin (was 0.2.4). Set it in
  deploy/.env.
• /health now reports docs_generated_at and docs_page_count so an
  operator can see at a glance whether the live server is serving a current
  docs bundle.

Docs

• Added docs/DOCS-BUNDLE-SYNC.md — the previously-missing runbook for the
  dero-docs → mcp-server → npm → VPS pipeline: what's automated vs. manual, the
  secrets involved, and manual-recovery steps.

v0.4.3

Fixed

• diagnose_chain_health mislabeled the network. Mainnet derod returns
  network: "" and signals the chain via the testnet boolean, so the
  narrative rendered "Chain appears healthy on (version…)" with a double space
  and chain.network: null, and the network signal was dropped entirely. A
  new resolveNetwork() helper derives mainnet/testnet from the testnet
  boolean when the string is blank — never fabricating "mainnet" from an empty
  string alone (a testnet node with a blank network would otherwise be
  mislabeled).
• audit_chain_artifact_claim reward formatting dropped atomic precision.
  (reward / 100_000).toFixed(3) truncated DERO's 5-decimal amounts and
  rounded: a per-miniblock reward of 30750 atoms rendered as 0.308 (a value
  never on-chain) instead of 0.30750. This narrative feeds the inflation-claim
  audit, where 5-digit fidelity is the deliverable. Now formatted via integer
  math (floor + % 100_000 padded to 5).
• Version self-report drift. The MCP handshake version, the HTTP
  PACKAGE_VERSION, and the deploy/.env.example default lagged behind
  package.json / server.json, so the running server advertised a stale
  version to clients. All six references are now pinned together and gated by
  check:server-json.
• rpc.ts lost specific daemon errors on non-2xx responses. The HTTP status
  was checked before the JSON-RPC body was parsed, so a daemon (or proxy)
  returning a non-2xx status with a JSON-RPC error body (e.g. -32098 DVM
  compile) surfaced as a generic HTTP {status} error. The body is now parsed
  first; the raw HTTP error is a fallback only when the body is not a usable
  JSON-RPC error.
• cborDecode silently accepted trailing bytes. The existing done() check
  was never called, so a deroproof… string with valid CBOR followed by junk
  decoded as if clean. It now throws cbor: trailing bytes after root value.

Changed

• Input hardening on user-supplied surfaces. forge_demo_proof's tx_hex
  gained a .max(100_000) bound (real DERO txs are well under 10 KB of hex) to
  prevent unbounded allocation; tx-parse now rejects an asset_count above the
  protocol maximum (PAYLOAD_LIMIT = 145) with a clear error instead of a
  cryptic EOF; and docs-parse validates numeric HTML-entity codepoints before
  String.fromCodePoint, passing out-of-range entities through as literal text
  rather than throwing a RangeError that would abort the whole doc index.

v0.4.1

Bugfix release for the v0.4.0 Streamable HTTP transport.

Fixes

• fix(http): fresh McpServer + transport per request. Previously a single StreamableHTTPServerTransport instance was reused across requests, which caused issues under concurrent or sequential calls. Each request now gets a fresh server + transport pair, matching the stateless design of the deployment.
• fix(deploy): bump base image to node:22-alpine. Resolves a silent HTTP 500 on POST /mcp initialize when running on node:20-alpine — the MCP SDK's streamable HTTP transport returns a 500 without throwing on Node 20, so the server's error handler never fired. Node 22 resolves it. engines.node also bumped to >=22 to prevent regression.

If you were running v0.4.0 in Docker via the bundled compose stack on node:20-alpine and hitting empty-body 500s, this is the fix.

Full Changelog: v0.4.0...v0.4.1

v0.4.0

First published release with Streamable HTTP transport and a hosted server at mcp.derod.org/mcp. Adds local-first daemon resolution, the dero_forge_demo_proof composite, and agent-ready docs surfaces.

Highlights

• Streamable HTTP transport — run as a hosted server alongside the existing stdio mode. Drop-in for ChatGPT Custom Connectors, Cursor hosted mode, or any MCP client that needs a URL instead of a subprocess. Docker Compose + Caddy reference deploy included.
• Local-first daemon resolution — automatically prefers a local derod on 127.0.0.1:10102 if reachable, falls back to a public node otherwise. No manual DERO_DAEMON_URL needed for self-hosters.
• dero_forge_demo_proof composite (#7) — produces a working forged payload-proof string, decoded and validated end to end. Backs the "Tier 1 — ask your agent" callout on the 2022 inflation-claim integrity page.
• Adversarial-context defense layer — flagged artifacts + proof decode + audit composite that surfaces forged-proof patterns in user-supplied data.
• Citations: per-page .md mirrors universal — every tool's citations now point at clean Markdown twins of the source docs, across the whole DERO docs ecosystem.
• Agent-ready docs — new SKILL.md (skill-aware agents) and POSITIONING.md; README rewrite for the public surface.

Full Changelog: v0.2.2...v0.4.0

v0.2.2 — Composites release (clean republish of 0.2.1)

First agent-ready release of dero-mcp-server. Adds five composite tools that fuse live DERO daemon reads with the bundled 145-page docs index, makes every tool safe for MCP host auto-approve via read-only annotations, and gives agents structured error codes they can react to programmatically.

All 20 v0.1.x primitives keep their identifiers, schemas, and behavior — this is an additive release. Clients pinned to 0.1.x will continue to work.

Note: 0.2.1 was briefly on npm and withdrawn; install 0.2.2. Same surface and schemas — only the bundled docs index and version strings differ from the withdrawn build.

What's new

Five composite tools (the wedge)

Each composite replaces a multi-step primitive chain with a single call, returns a plain-language narrative, and stitches curated docs citations.

• diagnose_chain_health — replaces Ping + GetInfo + GetHeight + GetTxPool. One call returns a health narrative + signals (healthy / stale-tip / lagging / unreachable) + citations to derod docs.
• explain_smart_contract — replaces GetSC + manual DVM-BASIC parsing + docs lookup. Parses the function surface, classifies the contract pattern (token / registry / minimal / generic), and selects the most relevant DVM docs page heuristically.
• recommend_docs_path — fans out a natural-language intent across all 4 DERO products (derod, tela, hologram, deropay) in parallel and ranks. Optional product_hint is a 1.5× score bias, not a filter.
• estimate_deploy_cost — DVM deploy pre-flight. Wraps GetGasEstimate with a plain-text breakdown of compute vs storage gas plus the parsed contract surface. Surfaces daemon -32098 DVM compile errors as structured INVALID_INPUT with the raw daemon message preserved.
• trace_transaction_with_context — wraps GetTransaction with confirmation classification, kind detection (sc_install / transfer_or_invocation / coinbase / unknown), and inline SC install surface extraction (no second GetSC call needed because install source is embedded in the tx record).

Agent-ready foundations

• Read-only annotations on every tool — readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false. MCP hosts can safely auto-approve any call from this server.
• Agent-instruction style descriptions on all 25 tools (call-timing, input requirements, output shape, fallback guidance) enforced by check:mcp-descriptions in CI.
• 16 curated related_docs citations across 7 tools, validated against the bundled docs index in CI by check:citations.
• Five structured _meta.error codes so agents can react programmatically: RPC_UNREACHABLE, RPC_INVALID_PARAMS, NO_DOCS_MATCH, INVALID_INPUT, TX_NOT_FOUND. Each includes a hint string and a retryable flag.

Resources and prompts

• +1 resource: dero://mcp/composites — JSON catalog of all 5 composites with replaces, when_to_call, inputs, output_highlights, and error_codes for connect-time agent orientation. (Total: 4 resources.)
• +2 prompts: find_dero_docs_for_intent (drives recommend_docs_path) and estimate_deploy_for_contract (drives estimate_deploy_cost). The three original prompts refreshed to call composites first with documented primitive fallbacks. (Total: 5 prompts.)

Documentation

User guide: derod.org/tools/mcp-server

Agent orientation at connect time: MCP resources dero://mcp/composites, dero://mcp/example-flows, and dero://mcp/safety-boundary (built into the server — no separate docs folder in the repo).

Install

npm install -g dero-mcp-server@0.2.2

Or in your MCP client config:

{
  "mcpServers": {
    "dero": {
      "command": "npx",
      "args": ["-y", "dero-mcp-server@0.2.2"]
    }
  }
}

Registry: io.github.DHEBP/dero-mcp-server

Verification (reproducible)

npm run check:mcp-descriptions   # 25/25 descriptions pass 4-check guard
npm run check:citations          # 16/16 citations resolve against bundled index
npm run smoke:mcp                # tools/resources/prompts parity + read-only annotations
npm run test:flows               # 10 primitive flows end-to-end vs public daemon
npm run test:composites          # 11 composite assertions including all failure modes

Backward compatibility

All 20 primitives unchanged. The only package.json field changes since 0.1.x are version and description. No removed exports, no renamed tools, no schema breaking changes.

v0.1.2

What's new

• Bundled DERO docs index (dero_docs_* tools) — zero-config documentation lookup
• Docs bundle sync automation
• Official MCP registry metadata (server.json, mcpName)
• CI, doctor script, and smoke/flow tests
• README and Glama onboarding polish

Install

npm install -g dero-mcp-server@0.1.2