Repository navigation
docs: AI-readability pass — llms.txt, AI Support section, MCP schema parity - #22
Merged
Merged
Conversation
The fenced code block was labeled `shell` but contains a JavaScript `getTronWeb()` example. Correct the language identifier so it gets proper JS syntax highlighting and is accurately identified by machine/LLM readers. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Improve machine/LLM readability across DApp, mobile and plugin-wallet docs: - Code fence languages: relabel mislabeled ```shell blocks — deeplink HTML links -> ```html and JSON payloads -> valid ```json (comments moved to prose); message-signing hex/error output -> ```text; stake2 -> ```javascript; dapp-support -> ```java. Remove inline <style> blocks from markdown bodies. - Heading hierarchy: promote active-requests/passive-messages from H1->H3 (no H2) up one level so sections sit at H2; promote dapp bold pseudo-headings (**Overview** etc.) to real ## headings and drop the empty **Specification** sections. - passive-messages: JS arrays / TS type literals were tagged ```json (invalid JSON) -> ```javascript / ```typescript. - deeplink: fix contactAddress->contractAddress, replace placeholder test IPs with example.com, align request/callback actionIds, repair the malformed result-code table, standardize protocol value. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Follow-up to the P0 readability pass, addressing review feedback: - Restore the Technical Specification / 技术规范 sections that were dropped, now as proper parent headings (##) with Code Example / Parameters / Returns nested as ### subsections, in transfer, multi-sign-transfer and message-signing (en + zh). Preserves the original section grouping instead of flattening it. - Restore the inline <style> img max-width override in deeplink and stake2 (en + zh) so flow screenshots keep displaying full-width (overriding the global 300px cap in extra.css). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add machine-readable AI entry points and consolidate scattered
reference material (inspired by docs.justlend.org):
- llms.txt: curated, llmstxt.org-compliant index of the docs, served
at the site root for AI/LLM discovery.
- llms-full.txt: single-fetch full-text bundle of all English pages,
generated by scripts/gen_llms_full.py (re-runnable; wire into CI).
- AI Support overview page (ai-support/ai-llms): landing page for the
AI/agent tooling that links the machine artifacts and indexes the
six tool pages.
- Reference section (reference/networks, glossary, faq):
- Networks & Addresses: chainIds (hex + EVM decimal), RPC endpoints,
explorers, faucets, address formats, units, USDT contract —
consolidating values previously scattered across docs.
- Glossary: defines previously-undefined terms (TIP/EIP standards,
ProviderRpcError, ABI, chainId, Energy/Bandwidth, wallet objects).
- FAQ: common integration issues with links to the relevant pages.
All new pages added to both en and zh navs.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Address the AI Agent doc-standard P0/P1 findings, grounded in each
package's real package.json (no fabricated codes/schemas):
P0 (CLI + MCP server):
- tronlink-cli: add Exit Codes, Errors (with retryable) sourced from
documented conditions (OUT_OF_ENERGY/REVERT/FAILED, rejection,
timeout), a real ```json output schema, and a Safety & Side Effects
section (read vs write classification, HITL, retry policy).
- mcp-server-tronlink: add Tool Contract & Side Effects — link the
input/output schema and {code,retryable} error contract to
tronlink-mcp-core (SSOT), plus side-effect classification, HITL,
and retry guidance.
P1 (all six AI-Support docs):
- Reconcile tool/command counts with each doc's own enumeration
(mcp-server 55+→52, mcp-core 56+→52, skills 34→33).
- Add Version & License sections with real versions and
SPDX-License-Identifier: MIT (verified from each package.json).
llms base path:
- The site is served under /docs/ (repo name). Fix all absolute URLs
in llms.txt, llms-full.txt, the AI Support overview, and the
generator's SITE constant to https://docs.tronlink.org/docs/.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Hardcoded https://docs.tronlink.org/docs/ URLs break staging/test environments. Switch all same-site links to relative paths so they resolve against the fetched document's own URL under any domain or base path: - llms.txt: page links -> relative (introduction/, ai-support/...) - ai-support/ai-llms.{en,zh}.md: -> ../../llms.txt, ../../llms-full.txt - llms-full.txt: url markers -> relative; regenerated - gen_llms_full.py: drop hardcoded SITE; emit relative paths External links (tronweb.network, tron.network, llmstxt.org) stay absolute. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Per the deployed directory structure, docs live under /docs/ (e.g.
/docs/llms.txt, /docs/introduction/). Use root-relative paths that
include the /docs base and omit the domain, so links resolve on any
host (prod, staging, test) without hardcoding docs.tronlink.org:
- llms.txt: page links -> /docs/<page>/
- ai-support/ai-llms.{en,zh}.md: -> /docs/llms.txt, /docs/llms-full.txt
- llms-full.txt: url markers -> /docs/<page>/ ; regenerated
- gen_llms_full.py: page_url emits /docs/<slug>/
External links (tronweb.network, tron.network, llmstxt.org) stay absolute.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ndaries, wallet secret storage, CLI exit code split Address the standards-driven P0 findings surfaced in the AI-readability review. All edits are documentation-only and apply to both EN and ZH. P0-1 — Structured error contract (mcp-core SSOT): - tronlink-mcp-core: replace the flat "25+ error codes" string with a 21-row SSOT table (`code` / `retryable` / `hint` / typical trigger); add `retryable`, `hint`, `meta.schemaVersion` to the error envelope example; spell out custom-code extension rules. - mcp-server-tronlink: deep-link the Tool Contract section to the SSOT table; clarify "branch on `error.code`, not on `message`". P0-2 — mcp-tronlink-signer side effects + Errors: - Split the 7-tool table to add `side_effect` and `auto_retry_safe` columns; treat `sign_transaction(broadcast=true)` separately from `broadcast=false`. - New Errors section documents USER_REJECTED, TIMEOUT, BROWSER_DISCONNECTED, NETWORK_ERROR, BROADCAST_FAILED, ON_CHAIN_FAILED, INVALID_INPUT, CANCELLED with retryable + retry guidance. P0-3 — Security Boundaries on both MCP servers: - mcp-server-tronlink: 7 boundaries — prompt injection (untrusted on-chain strings), SSRF host allowlist, API key passthrough, the high-risk `tl_evaluate` primitive, HITL bypass on Direct-API, confused deputy, transport. - mcp-tronlink-signer: 7 boundaries — prompt injection, 127.0.0.1-only binding, SSRF, API key, structural HITL guarantee, tab hijack protection, confused deputy. P0-4 — Wallet Secret Storage (mcp-server-tronlink): - Explicit Path A (production, env-injected password) vs Path B (auto-create, password written plaintext to `~/.agent-wallet/runtime_secrets.json`). - Document file permissions (0600 expected, no umask hardening), git isolation, Knowledge Store redaction boundary, backup pitfalls, and production guidance favoring mcp-tronlink-signer for fund-moving tools. P0-5 — CLI exit code split (tronlink-cli): - Replace 0/non-zero with stable 0=success / 1=invalid input / 2=user rejected / 3=signing timeout / 4=on-chain failure / 5=network so scripts and agents can branch without parsing prose. - Rewrite the Errors table as condition -> exit code map. Bonus: reconcile "25+ error codes" highlight in mcp-core summary with the actual documented table; regenerate docs/llms-full.txt. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Close the remaining standards gaps for the docs P0 wave 1 missed: P0: - tronlink-signer: add Safety & Side Effects — method side-effect classification (Read / Sign-only / Remote Write / Connection), HITL on signing, and a retry policy keyed to BroadcastResult status (don't blindly resend on `pending`; reconcile via waitForTransaction). - tronlink-skills: it is read-only, so add explicit Network Read / safe-to-retry side-effect rows + a query error model (rate limit retryable, bad input not) and point writes to the signer SDK / MCP server. (No write-safety section — there are no writes.) P1: - mcp-server-tronlink: document that per-tool input schemas are Zod-validated and discoverable at runtime via MCP list_tools (inputSchema), with list_tools as the authoritative source. - OpenAPI/API contract is intentionally N/A (wallet/provider, not an API-first product). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…s, AGENTS.md Close the standards gaps that wave 2 left open. Doc-side enforcement patterns are spelled out where code-side flags don't yet exist. P0: - mcp-server-tronlink: pin @bankofai/agent-wallet to ^2.3.0 (was "latest" — supply-chain risk for a fund-moving project) and @tronlink/tronlink-mcp-core to ^0.1.0 (was "local"). Versions verified against the upstream mcp-server-tronlink@0.1.1 package.json. - mcp-server-tronlink: add "Disabling tl_evaluate" block with concrete config snippets for Claude Code (permissions.deny), Claude Desktop (disabledTools), and generic MCP clients (list_tools filter). The same pattern applies to tl_seed_contract / tl_seed_contracts. - mcp-server-tronlink: add "How to enforce Path A" to Wallet Secret Storage — provision wallet out-of-band, inject AGENT_WALLET_PASSWORD via host secret manager, block tl_wallet_create on the agent side. Flagged the long-term --no-auto-create flag as a code-side follow-up. - tronlink-cli: clarify --local-broadcast is mutually exclusive with signer broadcast (not redundant); document what happens if a stale signer broadcast races with the local one (node-side dedup by tx id, benign after first inclusion). P1: - scripts/gen_llms_full.py: header now records the git short SHA, UTC ISO timestamp, page count, and a coarse token estimate (chars / 4 — zero-dep on purpose). Agents can decide whether to ingest before pulling the body. - tronlink-skills: cost-examples table and the "1 frozen TRX ~ 4.5 Energy/day" line now carry "Effective as of 2026-05" with sources; estimates are flagged as dynamic, with a pointer to the live estimate-energy command. - mcp-server-tronlink: SunSwap V2/V3 router and WTRX env-var rows now document that the example values are effective as of 2026-05, with no built-in default — operators are expected to pin via env when the router upgrades. - tronlink-cli: pin tronweb 6.2.2 and tronlink-signer 0.1.4 in Requirements, with a note that the ABI v2 trigger path depends on TronWeb 6.x. - tronlink-skills: each of the 6 skills now has a "When NOT to use" line so route-selection LLMs can rule out wrong skills (writes go to signer SDK / MCP Server, etc.). P2: - New top-level AGENTS.md: 50-line orientation file for AI coding agents — clarifies this repo is docs (not source), lists curated entry points (llms.txt / llms-full.txt), maps topics to files, records SSOT boundaries (error codes in mcp-core; tool schemas via list_tools), and points at the 5 upstream code repos. Regenerated llms-full.txt — 23 pages, ~43k tokens. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…mage alt-text
Close the last batch of in-repo gaps from the AI-readability review.
P1-C bilingual llms bundles:
- scripts/gen_llms_full.py: render per-language bundles. Emits
docs/llms-full.en.txt and docs/llms-full.zh.txt, each with a header
recording the language plus the existing commit SHA / timestamp /
page count / token estimate. URL markers use /docs/<slug>/ for EN
and /docs/zh/<slug>/ for ZH so a downstream LLM can resolve a
single page back. docs/llms-full.txt is now a verbatim copy of the
EN bundle so the existing /docs/llms-full.txt URL keeps working.
- docs/llms.txt: new Localized section pointing at both bundles and
explaining the EN/ZH translation-pair contract and the bundle
header semantics.
P1-D TronGrid quota visibility:
- mcp-server-tronlink.{en,zh}.md: TL_TRONGRID_API_KEY row now spells
out free-tier ballpark (~100k req/day, ~5 QPS), the existence of
paid tiers, the pricing page link, X-Ratelimit-* headers to inspect
at runtime, and the 50/80/95% billing-alert recommendation. The
mapping HTTP 429 -> TL_CHAIN_QUERY_FAILED (retryable) is called out
so agents branch correctly.
P2-5 multi-agent host snippets:
- tronlink-skills.{en,zh}.md: added concrete config snippets after the
"Other AI Platforms" table — Cursor (shares schema with Windsurf),
Codex CLI symlink + verification, OpenCode plugins block, and a
LangChain/CrewAI Python Tool wrapper. Each is ~5-10 lines and
copy-pasteable.
P2-2 screenshot alt-text:
- plugin-wallet/active-requests.{en,zh}.md, passive-messages.{en,zh}.md
- dapp/transfer.{en,zh}.md, message-signing.{en,zh}.md, stake2.{en,zh}.md
- Replaced every "" with a descriptive alt-text describing
the on-screen content (e.g. "TronLink connection authorization popup
showing the requesting site origin with Confirm and Reject buttons").
Non-multimodal LLMs now ingest a text equivalent of each screenshot.
Width attributes preserved where present.
Regenerated llms-full.{txt,en.txt,zh.txt} with the new content
(EN ~44k tokens, ZH ~30k tokens, both stamped with commit 3c5a22f).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- ai-support/ai-llms: retitle to "AI / LLMs" and restructure to match the JustLend/USDD convention — Available endpoints / Which file should I use? / Add to your AI tool / Coverage / Notes for agents. Nav label updated to "AI / LLMs". - Tag bare ``` fences wrapping ASCII architecture diagrams, directory trees and hex/sketch output as ```text across ai-support and plugin-wallet. Convert ledger's invalid-JSON sketches (`.....other property`) from ```json to ```text. - mkdocs.yml site_url -> https://docs.tronlink.org/docs/ to match the /docs base path (correct canonical tags + sitemap). - Regenerate llms-full bundles (en/zh/alias). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ll↔MCP map
- Architecture diagrams in mcp-server-tronlink + tronlink-mcp-core (en+zh)
convert from ASCII trees to ```mermaid; enable pymdownx.superfences with
mermaid custom_fence in mkdocs.yml so they render
- mcp-server-tronlink.zh gains parallel "兑换安全" (slippage/MEV/minOut/router
pinning) and "多签凭证管理" (per-env isolation, rotation, revocation,
least privilege) sections matching the existing EN copy
- ai-llms.{en,zh} endpoint tables and "which file?" sections now surface
/docs/llms.zh.txt and /docs/llms-full.{en,zh}.txt alongside the EN bundles
- docs/llms.zh.txt: new curated Chinese index (llmstxt.org format)
- tronlink-skills.{en,zh}: add Skill ↔ MCP Tool map — 33-command table
mapping each CLI command to its real MCP tool name from upstream
scripts/mcp_server.mjs (25 MCP tools, 8 CLI-only marked), plus a
21-row intent → skill → tool routing table for agent disambiguation
- mcp-tronlink-signer.{en,zh}: keep end-to-end User → Agent → Tool →
Approve → Result example
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…angelog + compat policy
- README.md: new "For AI Agents" section pointing at AGENTS.md, llms.txt /
llms.zh.txt / llms-full.{en,zh}.txt, and docs/ai-support/; AI Support
added to documentation TOC. Closes the GitHub-landing P2.
- tronlink-skills.{en,zh}: "❌ When NOT to route here" with 6 negative
examples (send / freeze / vote / approve / execute swap / claim) showing
the read-only command that looks plausible vs. the correct signer or
mcp-server route, plus a verb-heuristic.
- mcp-tronlink-signer.{en,zh}: real inline changelog from GitHub releases
v0.1.1 and v0.1.2 (2026-04-15); v0.1.3 / v0.1.4 noted as npm-only.
- Compatibility & migration policy subsection added to all 6 ai-support
packages (mcp-server-tronlink, tronlink-mcp-core, tronlink-skills,
tronlink-cli, tronlink-signer, mcp-tronlink-signer × en+zh). Each lists
stable contracts (tool names, error.code, exit codes, schemaVersion,
BroadcastResult shape, capability interfaces), volatile contracts
(prose messages, log lines, internals), deprecation window, and
post-upgrade verification steps. Pre-1.0 packages get a "no GitHub
tag yet" honesty note; v1.0.x packages get standard-semver framing.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…vider methods
- mcp-server-tronlink.{en,zh}: new "Selected tool schemas (inline mirror)"
subsection under Tool Contract & Side Effects, with JSON Schema Draft 7
for 7 high-impact tools (tl_chain_send, tl_chain_swap_v3, tl_chain_stake,
tl_multisig_submit_tx, tl_gasfree_send, tl_chain_get_account, tl_evaluate).
Each block lists required, properties, types, enums, and per-field
descriptions extracted from tronlink-mcp-core/src/mcp-server/schemas.ts.
Honest about scope: list_tools remains the authoritative source for all 52.
- tronlink-mcp-core.{en,zh}: new SSOT pointer at the top of "52 Tool
Definitions" linking to schemas.ts upstream and the downstream mirror.
- docs/mobile/deeplink.{en,zh}: new "JSON Schema Reference" section after
Result Code, covering all 6 DeepLink actions — common envelope plus
per-action request/callback schemas for open wallet, open DApp, login,
transfer (with tokenId/contract mutual-exclusion), sign transaction,
sign message.
- docs/plugin-wallet/active-requests.{en,zh}: new "JSON Schema Reference"
section before Legacy Usage, covering eth_requestAccounts (TIP-1102),
wallet_watchAsset, wallet_switchEthereumChain (TIP-3326),
tronweb.trx.sign/multiSign/signMessageV2, TIP-6963 event pattern, and
legacy tron_requestAccounts. Each method documents request shape,
response shape, and error code enum where applicable.
Closes the last two P2 items from the audit (per-tool inline JSON schema,
DeepLink/provider JSON Schema).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
URL fix — i18n plugin strips .en/.zh suffixes at build time:
- /docs/llms-full.en.txt → /docs/llms-full.txt
- /docs/llms.zh.txt → /docs/zh/llms.txt
- /docs/llms-full.zh.txt → /docs/zh/llms-full.txt
Verified live: the source-name URLs return 404 on
xueyuanying.github.io/docs/; the suffix-stripped URLs return 200.
Updates:
- README.md: rewrite the For-AI-Agents links with deployed URLs and
a note about source-vs-deployed naming.
- ai-llms.{en,zh}.md: rewrite the endpoint and use-case tables to
use deployed URLs, with an admonition explaining the rule.
- llms.txt / llms.zh.txt: rewrite the Localized cross-references
the same way.
- llms-full.{en,zh}.txt + llms-full.txt: regenerated via
scripts/gen_llms_full.py to roll in all P2 wave 2 content and
the URL corrections.
Audit corrections:
- mcp-server-tronlink.{en,zh}.md: "52 tools" → "55 tools" (52 core
from tronlink-mcp-core + 3 wallet management from this server's
src/wallet-tools.ts, verified against upstream definitions.ts).
Mode 2 heading expanded to "Direct API + Wallet Management";
table gains a Source column distinguishing core vs server origin
and a mode-agnostic row. Annotated 27 Playwright math as
52 − 22 chain/multisig/gasfree − 3 mode-agnostic = 27.
- tronlink-mcp-core.zh.md: copy the 9 capability TypeScript
interface blocks from en.md (TS is language-neutral).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- scripts/check_doc_schema_parity.py: fetch upstream tronlink-mcp-core
src/mcp-server/schemas.ts (default ref: main, override via SCHEMAS_PIN
env), brace-match each `z.object({...})` body, extract top-level fields
by indent (4 spaces) with depth-0 `.optional()` detection so nested
optionality does not bleed up. Parse the inline JSON Schema blocks
for the 7 mirrored tools (tl_chain_send, tl_chain_swap_v3,
tl_chain_stake, tl_multisig_submit_tx, tl_gasfree_send,
tl_chain_get_account, tl_evaluate) in both EN and ZH docs; diff field
sets and required flags; fail on drift.
- .github/workflows/check-doc-schema-parity.yml: trigger on push and
PR for the relevant paths, run daily at 06:00 UTC to catch upstream
drift even when our docs are unchanged, and on workflow_dispatch
with an optional SHA override.
- mcp-server-tronlink.{en,zh}.md: admonition under "Selected tool
schemas (inline mirror)" announcing the CI enforcement so readers
know the schemas below are guaranteed in sync with upstream.
Verified locally: 7 tools × 2 docs = 14 checks pass against upstream
main. Closes the only remaining P2 (CI parity script) from the
2026-05-21 audit. Two parser bugs were caught and fixed during local
runs — exactly the kind of drift this CI is meant to surface.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
llms.txt/llms-full.txtbundles (EN + ZH) and a new AI Support section (MCP server, CLI, signer, skills, core).window.tronprovider, fixed anchors.