Cadence-lang redesign + AI tools (MCP, Skills, LLM endpoints, AI Chat) by lmcmz · Pull Request #285 · onflow/cadence-lang.org

lmcmz · 2026-02-21T14:53:38Z

Summary

Complete redesign of cadence-lang.org with AI-native developer tooling.

Preview: https://cadence-lang.vercel.app/

Site Redesign

New homepage with ASCII 3D animation (Cadence logo, Flow token, CryptoKitty cycle)
Dark mode support with proper background colors
Responsive layout with mobile optimizations
Updated header nav with AI Tools link

MCP Server (`mcp-server/`)

Cadence MCP server wrapping the Flow CLI Language Server over JSON-RPC
6 tools: search_docs, get_doc, cadence_check, cadence_hover, cadence_definition, cadence_symbols
HTTP transport via Hono + WebStandardStreamableHTTPServerTransport (stateless)
Deployed on Railway at https://cadence-mcp.up.railway.app
Dockerfile with Flow CLI for containerized deployment
Stdio transport for local CLI usage
54 unit + integration tests covering LSP message parsing, formatters, and Cadence syntax/type error detection

AI Skills

SKILL.md — one-command install via npx skills add outblock/cadence-lang.org
Injects Cadence language reference, patterns, and best practices into AI coding agents

LLM Endpoints

/llms.txt — concise site overview for LLM context
/llms-full.txt — full documentation dump optimized for LLM context windows

AI Chat Panel

Embedded Cadence AI chat panel in docs pages
Drag-to-resize from left edge
Responsive (full width on mobile)

Fumadocs

Migrated documentation framework to Fumadocs
Structured navigation via meta.json files

AI Tools Documentation (`content/docs/ai-tools/`)

Skills — installation and usage guide
MCP Server — tools reference, Claude Desktop/Code config, HTTP usage, local setup
LLM Endpoints — llms.txt and llms-full.txt documentation
Integration guides for: Antigravity, Claude (Code/Desktop/API), Cursor, OpenAI Codex, Gemini, OpenCode

Test plan

MCP server: 54 tests passing (bun test in mcp-server/)
Homepage renders with 3D animation cycle
Dark mode background color applies correctly
AI Tools docs render in Fumadocs
MCP endpoint responds at https://cadence-mcp.up.railway.app/mcp

Complete rewrite of cadence-lang.org: - Fumadocs UI with TanStack Start router and Vite bundler - Tailwind CSS 4 with Geist font family (including Pixel display variants) - Custom Cadence syntax highlighting via Shiki + TextMate grammar - AI-native homepage: skills command, LogoLoop ticker, social proof section - AI toolkit section: Agent Skills, MCP Server, llms.txt, per-page AI actions - Theme toggle with View Transitions API sweep animation - StickerPeel draggable stickers (gsap + Draggable, SSR-safe) - SEO: JSON-LD structured data, sitemap, robots.txt - Env var VITE_SKILLS_ORG for org-agnostic skills command - All 82 docs migrated to content/docs/ with GFM admonitions Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Migrate from Docusaurus to Fumadocs + TanStack Start + Vite

- VITE_SKILLS_ORG env var controls homepage skills command org - Try/catch around Shiki codeToHtml with plain-text fallback - Add .vercel/output to .gitignore Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Migrate to Fumadocs + TanStack Start + Vite

- Set Nitro runtime to nodejs20.x (was defaulting to nodejs24.x) - Add buildCommand, installCommand, framework:null to vercel.json - Prevents Vercel from auto-detecting wrong framework Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Fix Vercel: nodejs20.x runtime + build config

- Remove cleanUrls/trailingSlash from vercel.json (may conflict with Nitro routing) - Simplify vite.config.ts to bare nitro({ preset: 'vercel' }) - Remove .vercel/output from git tracking (already in .gitignore) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

fix: simplify Vercel deployment config

The native binding (@takumi-rs/core-linux-x64-gnu) is not available in Vercel's serverless environment. Move to dynamic import so the module is only loaded when the OG image route is hit, with SVG fallback when the native binding is unavailable. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

fix: dynamic import for OG image native binding

…ibility and fumadocs theme

…ith 15 sections

vercel · 2026-02-21T14:53:46Z

@zenabot27 is attempting to deploy a commit to the Flow Team on Vercel.

A member of the Team first needs to authorize it.

… sidebar context crash

…idebar llms links

…thub icons, remove llms from header

…rt ./ MDX links to absolute paths

…scroll

…is visible on mobile

…-patterns and anti-patterns

…ange

TanStack Router's Link resolves `to` relative to the route pattern, not the actual page URL, breaking `./` and `../` relative links in MDX content. Add a custom link component that pre-resolves relative hrefs to absolute paths using standard URL resolution before passing to Fumadocs Link. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

fix: resolve relative MDX links before passing to TanStack Router

- Dockerfile: multi-stage build, compiles LSP v2 from Outblock/cadence-tools rewrite/lsp-v2 branch - client.ts: add lspBinary option to spawn v2 binary directly instead of flow CLI - http.ts/index.ts: pass LSP_BINARY env var to LSPManager Set LSP_BINARY=/usr/local/bin/lsp-v2 to use v2, unset to fall back to v1. Flow CLI is still used for `flow dependencies install` (DepsWorkspace). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add LSP_BINARY env var to run integration tests against a standalone LSP binary instead of Flow CLI. All 30 tests pass with v2. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

chore: sync SKILL.md from docs changes

The debug endpoint leaked file paths, flow.json contents, and directory listings without authentication. The /health endpoint is sufficient for monitoring LSP status. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

feat: integrate Cadence LSP v2 binary into MCP server

Add POST /api/security-scan that runs static analysis + LSP type check directly, bypassing the MCP tool call. This eliminates the need for Claude to re-output the entire contract code as tool arguments, which was extremely slow for large contracts (100KB+). Extract createApp() from http.ts for testability. Co-authored-by: ZenaBot <qq_agent_hao@proton.me> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

…ution (#13) Co-authored-by: ZenaBot <qq_agent_hao@proton.me> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

The rewrite/lsp-v2 branch has been merged to master with WASM slimming (47→22MB) and all Phase 1-3 LSP improvements. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

j1010001 · 2026-03-12T18:47:39Z

@lmcmz The Language reference (https://cadence-lang.org/docs/language) menu structure and order should be preserved, the new site is all over the place.

j1010001 · 2026-03-12T18:54:26Z

@lmcmz There is whole bunch of broken links in the language reference, see:
link-check-report.md

Keep LLM endpoints accessible via settings only. Co-authored-by: ZenaBot <qq_agent_hao@proton.me> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

joshuahannan

I started reviewing SKILL.md, but didn't get very far because there is a lot of bad advice. I assume you used AI to generate it.

I already spent a lot of time reviewing and added a bunch of advice to https://github.com/onflow/cadence-rules. Can you please import those rules into the AI that you're using to generate SKILL.md and have it re-generate it? Also make sure it knows about the few comments I already left here because I'm sure those apply to many of the skills in the rest of the file.

I also agree with Bastian about breaking this into smaller PRs. This is way too difficult to review as one big PR

joshuahannan · 2026-03-16T16:13:24Z

skills/cadence/SKILL.md

+| Testing framework | https://cadence-lang.org/docs/testing-framework |
+| Flow NFT Standard | https://github.com/onflow/flow-nft |
+| Flow FT Standard | https://github.com/onflow/flow-ft |
+


Probably should include other repos in here like core contracts, bridge, hybrid custody, NFT storefront, etc

joshuahannan · 2026-03-16T16:15:49Z

skills/cadence/SKILL.md

+| `access(all)` | Everyone (public read, callable by anyone) |
+| `access(self)` | Only within the type itself |
+| `access(contract)` | Same contract |
+| `access(account)` | Same account |


joshuahannan · 2026-03-16T16:16:35Z

skills/cadence/SKILL.md

+| `access(self)` | Only within the type itself |
+| `access(contract)` | Same contract |
+| `access(account)` | Same account |
+| `access(E)` | Callers holding entitlement `E` |


joshuahannan · 2026-03-16T16:18:22Z

skills/cadence/SKILL.md

+// 4. Borrow from another account
+let receiver = getAccount(address).capabilities
+    .borrow<&{FungibleToken.Receiver}>(/public/receiver)
+    ?? panic("Account has no receiver capability")


Can you update all the error messages in here to have more descriptive messages that include values? For example, this one should be, "Account \(address) has no FungibleToken.Receiver capability at path /public/receiver"

joshuahannan · 2026-03-16T16:21:08Z

skills/cadence/SKILL.md

+transaction(amount: UFix64, recipient: Address) {
+
+    // Declare fields shared across phases
+    let vaultRef: auth(FungibleToken.Withdraw) &FungibleToken.Vault


This is an invalid type. It should be &{FungibleToken.Vault}. You'll need to update this type wherever else it is in these skills

joshuahannan · 2026-03-16T16:21:18Z

skills/cadence/SKILL.md

+    // Access accounts — the ONLY phase with account access
+    prepare(signer: auth(BorrowValue) &Account) {
+        self.vaultRef = signer.storage
+            .borrow<auth(FungibleToken.Withdraw) &FungibleToken.Vault>(


still invalid

joshuahannan · 2026-03-16T16:21:30Z

skills/cadence/SKILL.md

+        self.vaultRef = signer.storage
+            .borrow<auth(FungibleToken.Withdraw) &FungibleToken.Vault>(
+                from: /storage/vault
+            ) ?? panic("No vault found")


need descriptive error message here and everywhere else in this file with error messages

…, SKILL.md, bun migration - Fix 68 broken internal links across language reference, tutorials, ai-tools, and migration guide - Restore Language Reference sidebar menu order to match production site - SKILL.md: add repo links (core-contracts, bridge, hybrid-custody, nft-storefront), fix access(account)/access(E) descriptions, fix invalid &FungibleToken.Vault types, improve all panic messages with descriptive values - Convert relative ./links in index.mdx files to absolute paths (Fumadocs resolves ./ from index pages incorrectly) - Fix anchor slugs (#semicolons → #-semicolon, #accessing-objects → #borrowing-objects, etc.) - Migrate from npm to bun (remove package-lock.json, add bun.lockb) - Add scripts/check-links.mjs for link validation Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

lmcmz · 2026-03-31T10:24:49Z

@j1010001 Both issues have been addressed in the latest push:

1. Language Reference menu order — Restored to match the production site order

2. Broken links — All 68 broken links from the link-check report have been fixed. The root cause was ./ relative links in index.mdx files

@joshuahannan All SKILL.md review comments resolved:

Added repo links (core-contracts, bridge, hybrid-custody, nft-storefront)
Fixed access(account) → "Contracts within the same account"
Fixed access(E) description
Fixed invalid &FungibleToken.Vault → &{FungibleToken.Vault} (Cadence 1.0 interface syntax)
Updated all panic messages with descriptive values (addresses, paths, capability IDs)

lmcmz · 2026-03-31T10:40:21Z

Hey @joshuahannan @j1010001 — quick update on the review feedback:

What's been fixed (latest push):

All broken links resolved (68 total, verified with a link checker across 107 pages — 0 remaining)
Language Reference sidebar order restored to match production
SKILL.md updates per Josh's review: added repo links, fixed access modifier descriptions, fixed &{FungibleToken.Vault} types, improved panic messages

On splitting the PR:
This is a static docs site framework migration — TanStack Start + Fumadocs replacing the old engine. The core MDX documentation content is unchanged; the diff is routing/config/components and link syntax adaptation. Splitting it isn't practical since the framework, routes, and components are interdependent — each piece wouldn't build or run on its own.

Review guide — where to focus:

skills/cadence/SKILL.md — Josh has already reviewed this line by line, updates applied
mcp-server/ — standalone package with 54 tests, can be reviewed independently
content/docs/ — the MDX content migrated from the old site. Spot-check a few pages against production to confirm nothing was lost
Everything else (components, routes, config) — framework scaffolding, not content

Happy to hand off further iterations:
The SKILL.md content and landing page copy are areas where Cadence experts/creator can improve directly. Feel free to push commits to this branch for any wording, code examples, or content changes — I'll keep the framework and tooling side working.

Preview is live at https://cadence-lang.vercel.app/ for testing.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

New MCP tool that validates JSON-CDC encoded arguments for Cadence scripts and transactions. Supports two modes: - Standalone: validates format, type names, and value correctness (integer ranges, Fix64 precision, Address format, nested types) - With source code: additionally verifies args match the entry function signature via LSP or regex fallback Stricter than FCL's @onflow/types — catches range overflows, invalid addresses, and type mismatches that FCL passes through silently. 220 tests with FCL-generated ground truth fixtures. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

This reverts commit 78a4c90.

…dk to 1.26.0 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

zenabot27 and others added 14 commits February 15, 2026 21:29

Merge pull request #1 from Outblock/feat/fumadocs-migration

a9e2385

Migrate from Docusaurus to Fumadocs + TanStack Start + Vite

Fix: add fallback for Shiki code highlighting, env var for org name

e5c7a4a

- VITE_SKILLS_ORG env var controls homepage skills command org - Try/catch around Shiki codeToHtml with plain-text fallback - Add .vercel/output to .gitignore Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Merge pull request #2 from Outblock/feat/fumadocs-migration

782eecc

Migrate to Fumadocs + TanStack Start + Vite

Merge pull request #3 from Outblock/feat/fumadocs-migration

0bb4d4d

Fix Vercel: nodejs20.x runtime + build config

Merge pull request #4 from Outblock/feat/fumadocs-migration

7100e22

fix: simplify Vercel deployment config

Merge pull request #5 from Outblock/feat/fumadocs-migration

7ecf1fb

fix: dynamic import for OG image native binding

style: optimize high-end aesthetics for light mode, improve ascii vis…

2d042ef

…ibility and fumadocs theme

Merge branch 'main' of https://github.com/Outblock/cadence-lang.org

0f887fa

feat: consolidate cadence skills into single comprehensive SKILL.md w…

26115bd

…ith 15 sections

Merge branch 'feat/fumadocs-migration'

7bb0fbf

zenabot27 added 15 commits February 22, 2026 02:13

fix: remove .mdx/.md from reference links, add llms links to nav, fix…

594c7db

… sidebar context crash

Merge branch 'feat/fumadocs-migration'

a333e13

fix: bulk fix relative ../ links across all doc subdirectories, add s…

d5b8a05

…idebar llms links

Merge branch 'feat/fumadocs-migration'

68e5198

feat: 404 page with GitHub issue report button, sidebar llms above gi…

4975a72

…thub icons, remove llms from header

Merge branch 'feat/fumadocs-migration'

eef8c7a

fix: disable 3D drag on mobile to prevent scroll conflict; bulk conve…

b087393

…rt ./ MDX links to absolute paths

Merge branch 'feat/fumadocs-migration'

19a8997

fix: make MorphingAscii responsive on mobile, fix pillars text overflow

94d5dc0

fix: disable pointer events on mobile canvas to allow page scroll

e1ac4ad

fix: disable R3F event system on mobile so canvas doesn't block page …

d7ae13d

…scroll

fix: move scroll overlay outside ascii-wrapper so AsciiRenderer text …

4040488

…is visible on mobile

style: remove grayscale filter from homepage video

de65c9b

fix: convert remaining relative MDX links to absolute paths in design…

3a71dff

…-patterns and anti-patterns

feat: GitHub Action to auto-update llms.txt and SKILL.md when docs ch…

435f3a1

…ange

zenabot27 and others added 16 commits March 4, 2026 02:03

chore: sync SKILL.md from docs changes

ee5921b

Merge pull request #10 from Outblock/worktree-foamy-gliding-thunder

40452b8

fix: resolve relative MDX links before passing to TanStack Router

chore: bust Docker cache for fresh v2 binary build

a6ea0e4

debug: add MCP-side logging for checkCode flow

b48cf63

debug: add /debug endpoint to inspect DepsWorkspace state

968fad4

fix: use ADD to bust Docker cache for LSP v2 binary builds

f57c00d

test: support LSP v2 binary in integration tests

3363229

Add LSP_BINARY env var to run integration tests against a standalone LSP binary instead of Flow CLI. All 30 tests pass with v2. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Merge pull request #9 from Outblock/auto/sync-skill-md

4100867

chore: sync SKILL.md from docs changes

fix: remove /debug endpoint that exposes internal server state

e5dfad8

The debug endpoint leaked file paths, flow.json contents, and directory listings without authentication. The /health endpoint is sufficient for monitoring LSP status. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Merge pull request #11 from Outblock/test/lsp-v2-mcp

3213894

feat: integrate Cadence LSP v2 binary into MCP server

✨ feat(mcp): add cadence_execute_script tool for on-chain script exec…

cf5e170

…ution (#13) Co-authored-by: ZenaBot <qq_agent_hao@proton.me> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

chore: update LSP v2 source to master branch

d71f073

The rewrite/lsp-v2 branch has been merged to master with WASM slimming (47→22MB) and all Phase 1-3 LSP improvements. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

chore(mcp): pin lsp-v2 build to cadence-tools 2.1.2

a670f27

chore: hide llms.txt commands from homepage hero (#14)

1a88fec

Keep LLM endpoints accessible via settings only. Co-authored-by: ZenaBot <qq_agent_hao@proton.me> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

joshuahannan reviewed Mar 16, 2026

View reviewed changes

peterargue mentioned this pull request Mar 26, 2026

Add flow mcp command for Cadence MCP server onflow/flow-cli#2306

Merged

5 tasks

lmcmz and others added 6 commits March 31, 2026 23:14

Improve link checking and fix docs links

1d82040

docs: add cadence_validate_args MCP tool design spec

78a4c90

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Revert "docs: add cadence_validate_args MCP tool design spec"

e53f0b4

This reverts commit 78a4c90.

chore(mcp): bump version to 1.2.0 and upgrade @modelcontextprotocol/s…

0c70bc9

…dk to 1.26.0 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chore(mcp): bump version to 1.2.1

75a054c

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

	\| `access(account)` \| Same account \|
	\| `access(account)` \| Contracts within the same account \|

	\| `access(E)` \| Callers holding entitlement `E` \|
	\| `access(E)` \| Either callers holding the actual object or callers holding a reference to the object authorized with entitlement `E` \|

Conversation

lmcmz commented Feb 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Site Redesign

MCP Server (mcp-server/)

AI Skills

LLM Endpoints

AI Chat Panel

Fumadocs

AI Tools Documentation (content/docs/ai-tools/)

Test plan

Uh oh!

vercel bot commented Feb 21, 2026

Uh oh!

j1010001 commented Mar 12, 2026

Uh oh!

j1010001 commented Mar 12, 2026

Uh oh!

joshuahannan left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joshuahannan Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

joshuahannan Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

joshuahannan Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

joshuahannan Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

joshuahannan Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

joshuahannan Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

joshuahannan Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

lmcmz commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lmcmz commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

lmcmz commented Feb 21, 2026 •

edited

Loading

MCP Server (`mcp-server/`)

AI Tools Documentation (`content/docs/ai-tools/`)

joshuahannan left a comment •

edited

Loading

lmcmz commented Mar 31, 2026 •

edited

Loading

lmcmz commented Mar 31, 2026 •

edited

Loading