From c29f406f49a380b0c3fff933d79447b32010311e Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Thu, 28 May 2026 17:48:10 +0530 Subject: [PATCH 1/2] docs: enable builder toolkit playground links --- docs/nitrolite/builder-toolkit.mdx | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/docs/nitrolite/builder-toolkit.mdx b/docs/nitrolite/builder-toolkit.mdx index a7b36ae..92c3a2a 100644 --- a/docs/nitrolite/builder-toolkit.mdx +++ b/docs/nitrolite/builder-toolkit.mdx @@ -28,12 +28,15 @@ Start here when you want to build with Nitrolite before reading every page. Use -
+
-
Coming soon
+
Browser tooling

Nitrolite Playground

-

Manage channels and inspect active app sessions from one UI. App-session management will be available after the playground deployment is ready for builders.

- Deployment pending +

Manage channels and inspect active app sessions from one UI. Use production for live Nitronode flows or sandbox when you want a disposable test environment.

+
+
+ Production + Sandbox
@@ -46,12 +49,14 @@ Start here when you want to build with Nitrolite before reading every page. Use
-
+
-
Coming soon
+
Sandbox funding

Faucet App

-

Get testnet assets for the v1 builder flow without leaving the Nitrolite docs path. This will be linked here once the faucet deployment is ready.

- Deployment pending +

Use the integrated faucet inside the sandbox playground to drip sandbox YUSD while the standalone Faucet App UI is being designed.

+
+
+ Open sandbox faucet
From 7bbecdddc2ec590a7b502f9da32fd32c84313d11 Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Fri, 29 May 2026 16:18:43 +0530 Subject: [PATCH 2/2] docs: publish Yellow SDK MCP setup --- docs/nitrolite/api-reference/index.md | 2 +- docs/nitrolite/build/sdk/index.md | 2 +- docs/nitrolite/build/sdk/mcp.mdx | 155 ++++++++++++------ .../typescript-compat/migration-overview.mdx | 18 +- .../build/sdk/typescript-compat/overview.mdx | 4 +- docs/nitrolite/builder-toolkit.mdx | 17 +- docs/nitrolite/learn/index.mdx | 2 +- src/css/custom.css | 12 -- 8 files changed, 133 insertions(+), 79 deletions(-) diff --git a/docs/nitrolite/api-reference/index.md b/docs/nitrolite/api-reference/index.md index a108e2e..c7c0f1e 100644 --- a/docs/nitrolite/api-reference/index.md +++ b/docs/nitrolite/api-reference/index.md @@ -27,7 +27,7 @@ The official SDKs are the recommended way to call every method documented here: - **TypeScript:** [`@yellow-org/sdk`](../build/sdk/typescript/getting-started) for new apps, or [`@yellow-org/sdk-compat`](../build/sdk/typescript-compat/overview) for migrations from `@erc7824/nitrolite@0.5.3`. You get IDE autocomplete, parameter checking, discriminated-union response types, and correct amount-unit handling out of the box. - **Go:** [`github.com/layer-3/nitrolite/sdk/go`](../build/sdk/go/getting-started) for backends and CLI tooling, with typed structs for every request and response. -- **MCP server (`@yellow-org/sdk-mcp`, coming soon):** ask `lookup_rpc_method` for a method by name, for example `channels.v1.submit_state`, and `lookup_method` to find the matching SDK call. The MCP indexes the same `docs/api.yaml` surface and is intended for agentic browsing inside coding tools. +- **Yellow SDK MCP:** connect [`@yellow-org/sdk-mcp`](../build/sdk/mcp) to your AI coding tool when you want guided help instead of reading raw RPC tables manually. Ask it to find the matching SDK call, explain a flow, or look up a v1 wire method such as `channels.v1.submit_state`. The SDKs handle the `[type, requestId, method, payload, timestamp]` envelope, signing, response correlation, event streams, auth/session-key plumbing, and amount-unit conversions. Reach for the catalogue below when you genuinely need to inspect or generate against the wire surface. diff --git a/docs/nitrolite/build/sdk/index.md b/docs/nitrolite/build/sdk/index.md index 536bd01..52c9f1d 100644 --- a/docs/nitrolite/build/sdk/index.md +++ b/docs/nitrolite/build/sdk/index.md @@ -15,7 +15,7 @@ Yellow Network provides official SDKs for building applications on top of Nitrol | New TypeScript app | [`@yellow-org/sdk@1.2.1`](./typescript/getting-started) | `import { Client, createSigners } from '@yellow-org/sdk'` | Native v1 SDK; uses `Decimal` amounts. | | Migrating from 0.5.3 (TS) | [`@yellow-org/sdk-compat@1.2.1`](./typescript-compat/overview) | `import { NitroliteClient } from '@yellow-org/sdk-compat'` | Minimal-diff bridge for `@erc7824/nitrolite@0.5.3`; see the compat codemod workflow. | | Go integration | [`github.com/layer-3/nitrolite/sdk/go`](./go/getting-started) | `import "github.com/layer-3/nitrolite/sdk/go"` | Standard Go package; run `go get github.com/layer-3/nitrolite/sdk/go`. | -| Agentic IDE / AI agents | `@yellow-org/sdk-mcp@1.2.1` | `npx -y @yellow-org/sdk-mcp` | MCP server with binary `yellow-sdk-mcp`; coming soon on npm. | +| AI coding tools | [`@yellow-org/sdk-mcp@^1`](./mcp) | `npx -y @yellow-org/sdk-mcp@^1` | Connect Claude Code, Codex, Cursor, Windsurf, VS Code Copilot, and other MCP-compatible tools to Yellow SDK guidance. | | 0.5.3 codemod | `@yellow-org/nitrolite-codemod@1.0.0` | `npx -y @yellow-org/nitrolite-codemod` | One-time migration tool; use the source workflow until the npm package publishes. | ## Architecture diff --git a/docs/nitrolite/build/sdk/mcp.mdx b/docs/nitrolite/build/sdk/mcp.mdx index d2cd17e..d8b7e7d 100644 --- a/docs/nitrolite/build/sdk/mcp.mdx +++ b/docs/nitrolite/build/sdk/mcp.mdx @@ -1,94 +1,151 @@ --- -title: MCP Server -description: Use the Nitrolite SDK MCP server with AI coding tools. +title: Yellow SDK MCP +description: Build with Yellow SDK inside your AI coding tool. sidebar_position: 5 --- -# MCP Server +# Yellow SDK MCP -The Nitrolite SDK MCP server gives AI coding tools structured access to the TypeScript SDK, Go SDK, protocol docs, v1 RPC catalogue, examples, and migration guidance. +Build with Yellow SDK inside your AI coding tool. -:::caution Coming soon on npm -`@yellow-org/sdk-mcp` is not published on npm yet. `npm view @yellow-org/sdk-mcp version` currently returns `404`. Until the package is published, run the server from the Nitrolite source checkout. -::: +Yellow SDK MCP connects tools like Claude Code, Codex, Cursor, Windsurf, and VS Code Copilot to Yellow SDK knowledge. Ask your AI tool to find the right SDK call, explain a flow, create a starter app, or review a migration while you stay in your project. + +You do not need to clone the Nitrolite repository. Run it from npm: + +```bash +npx -y @yellow-org/sdk-mcp@^1 +``` ## What It Provides -| Capability | Tools and resources | +| Builder need | How MCP helps | | --- | --- | -| SDK lookup | `lookup_method`, `lookup_type`, `search_api`, and import validation for TypeScript and Go. | -| RPC lookup | `lookup_rpc_method` reads the same `docs/api.yaml` surface as the API Reference. | -| Protocol help | Protocol resources for channel lifecycle, state model, enforcement, cross-chain notes, and interactions. | -| Scaffolding | Starter project prompts for TypeScript and Go flows. | -| Migration help | Guidance for moving from `@erc7824/nitrolite@0.5.3` to the v1 package family. | +| Start a new app | Create TypeScript or Go starter code for transfer, app-session, and AI-agent flows. | +| Find the right call | Search Yellow SDK methods, types, and examples without reading every page first. | +| Understand a flow | Ask for plain-language help with channels, app sessions, signing, settlement, and protocol terms. | +| Check a migration | Review codemod leftovers, old 0.5.3 helper chains, imports, and native v1 replacements. | +| Need wire-level details | Look up v1 RPC methods when you are building a thin proxy, debugger, or non-SDK integration. | -## Source Setup +Most builders only need the setup command and natural-language prompts in their AI tool. The exact tool names are listed later for teams that want to be more explicit. -From a local Nitrolite source checkout: +## Setup + +### Claude Code ```bash -cd sdk/mcp -npm install -npm run build -npm run start +claude mcp add --transport stdio nitrolite -- npx -y @yellow-org/sdk-mcp@^1 ``` -For stdio clients, configure the server command from the repository root: +Then run `/mcp` inside Claude Code and confirm `nitrolite` is connected. + +### Codex + +```bash +codex mcp add nitrolite -- npx -y @yellow-org/sdk-mcp@^1 +``` + +### Claude Desktop + +Add this to Claude Desktop's MCP config, then restart Claude Desktop: ```json { "mcpServers": { "nitrolite": { - "command": "npm", - "args": ["--prefix", "/path/to/nitrolite/sdk/mcp", "run", "start"] + "type": "stdio", + "command": "npx", + "args": ["-y", "@yellow-org/sdk-mcp@^1"] } } } ``` -## Tool Setup Shapes - -The exact config file location depends on the AI tool. Use the same stdio command shape in each tool until the npm package is published. - -### Claude Code - -Add the `nitrolite` server to the project's MCP configuration and point it at the source checkout command above. Restart Claude Code so it reloads MCP servers. - -### Claude Desktop - -Add the `nitrolite` entry under `mcpServers` in Claude Desktop's MCP config. Use an absolute path to the Nitrolite repo if Claude Desktop is not launched from the repo root. - ### Cursor -Add a project MCP server named `nitrolite` with the stdio command above. Keep the working directory at the Nitrolite repo root or use absolute paths in `args`. - -### VS Code and Copilot-Compatible MCP Clients +Create `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` for all projects: -Use a workspace MCP configuration that starts `npm --prefix /path/to/nitrolite/sdk/mcp run start`. Restart the MCP client after changing the config. +```json +{ + "mcpServers": { + "nitrolite": { + "command": "npx", + "args": ["-y", "@yellow-org/sdk-mcp@^1"] + } + } +} +``` -### Generic Stdio Clients +### Windsurf -Use: +Add this to `~/.codeium/windsurf/mcp_config.json`, then refresh MCP servers in Windsurf: -```bash -npm --prefix /path/to/nitrolite/sdk/mcp run start +```json +{ + "mcpServers": { + "nitrolite": { + "command": "npx", + "args": ["-y", "@yellow-org/sdk-mcp@^1"] + } + } +} ``` -The server communicates over stdio, so the client must keep the process open for the duration of the session. - -## After NPM Publish +### VS Code and GitHub Copilot -Once `@yellow-org/sdk-mcp` is published, this page should switch from source setup to a package command, for example: +Create `.vscode/mcp.json` in your workspace, or add it from the command palette with **MCP: Add Server**: ```json { - "mcpServers": { + "servers": { "nitrolite": { + "type": "stdio", "command": "npx", - "args": ["-y", "@yellow-org/sdk-mcp"] + "args": ["-y", "@yellow-org/sdk-mcp@^1"] } } } ``` -Leave the source setup available as the local-development fallback. +You can also add it from the terminal: + +```bash +code --add-mcp '{"name":"nitrolite","type":"stdio","command":"npx","args":["-y","@yellow-org/sdk-mcp@^1"]}' +``` + +## Try It + +After setup, ask your AI coding tool questions like: + +```text +Use Yellow SDK MCP to build a minimal TypeScript transfer app. +``` + +```text +Find the right Yellow SDK calls to create, fund, and close an app session. +``` + +```text +Review my 0.5.3 migration TODOs and check whether each import belongs in @yellow-org/sdk or @yellow-org/sdk-compat. +``` + +## Tool Reference + +| Need | MCP surface | +| --- | --- | +| Find SDK calls and types | `search_api`, `lookup_method`, `lookup_type` | +| Check imports | `validate_import` | +| Explain protocol concepts | `explain_concept`, protocol resources | +| Inspect v1 wire methods | `lookup_rpc_method`, `get_rpc_method` | +| Create starter code | `scaffold_project` | +| Start guided workflows | `create-channel-app`, `migrate-from-v053`, `build-ai-agent-app` prompts | + +## For Contributors + +The npm package ships with a release-time content snapshot, so normal users can run it without a repo clone. If you are changing the MCP server itself, use the local source workflow in the Nitrolite monorepo: + +```bash +cd sdk/mcp +npm install +npm run build +npm run start +``` diff --git a/docs/nitrolite/build/sdk/typescript-compat/migration-overview.mdx b/docs/nitrolite/build/sdk/typescript-compat/migration-overview.mdx index 1568395..0bcb4f7 100644 --- a/docs/nitrolite/build/sdk/typescript-compat/migration-overview.mdx +++ b/docs/nitrolite/build/sdk/typescript-compat/migration-overview.mdx @@ -32,19 +32,19 @@ See the [overview](./overview) for the command sequence and `node dist/cli.js li ## MCP-Assisted Migration -:::info Coming soon -The Yellow SDK MCP server is proposed for npm publication as `@yellow-org/sdk-mcp`. Until that package is published, treat this as a preview of the assisted workflow, not a command that should work today. +:::tip Available now +Yellow SDK MCP is available from npm as `@yellow-org/sdk-mcp`. Connect it to your AI coding tool when you want a second pass on migration leftovers. ::: -After publication, connect the MCP server to your MCP-compatible client and use it as a second review pass after the codemod: +After the codemod, use the MCP server as a second review pass: -1. Run `server_info` to confirm the MCP content version matches the SDK version you are migrating to. -2. Use the `migrate-from-v053` prompt to walk through changed files and unresolved `TODO [codemod]` markers. -3. Use `validate_import` when you are unsure whether a symbol belongs to `@yellow-org/sdk-compat` or native `@yellow-org/sdk`. -4. Use `get_rpc_method` to map old `create*Message` + `sendRequest` + `parse*Response` flows onto the v1 wire method. -5. Use `lookup_method`, `lookup_type`, or `search_api` to verify direct v1 SDK replacements before reaching for `client.innerClient`. +1. [Set up Yellow SDK MCP](../mcp) in Claude Code, Codex, Cursor, Windsurf, VS Code Copilot, or another MCP-compatible tool. +2. Ask it to walk through changed files and unresolved `TODO [codemod]` markers. +3. Ask it to check whether uncertain imports belong to `@yellow-org/sdk-compat` or native `@yellow-org/sdk`. +4. Ask it to map old `create*Message` + `sendRequest` + `parse*Response` flows onto v1 SDK calls where possible. +5. Ask it to verify direct v1 SDK replacements before reaching for `client.innerClient`. -MCP assistance does not replace the manual checklist below. Tool-specific setup belongs with the package publish so the documented commands are runnable on the day they appear here. +MCP assistance does not replace the manual checklist below. Treat it as a practical review partner that can keep the SDK, RPC catalogue, examples, and migration guidance in the same conversation. ## Install Compat diff --git a/docs/nitrolite/build/sdk/typescript-compat/overview.mdx b/docs/nitrolite/build/sdk/typescript-compat/overview.mdx index 46ae303..dfe87b7 100644 --- a/docs/nitrolite/build/sdk/typescript-compat/overview.mdx +++ b/docs/nitrolite/build/sdk/typescript-compat/overview.mdx @@ -33,8 +33,8 @@ node dist/cli.js run --path /path/to/your-app --update-deps After running, search for `TODO [codemod]` in your codebase and resolve them manually. The codemod surfaces every place a chained `create*Message` + `sendRequest` + `parse*Response` pattern needs context. See `node dist/cli.js list` for the full transform list. -:::info MCP-assisted migration - coming soon -The Yellow SDK MCP server is planned for npm as `@yellow-org/sdk-mcp`, but it is not published yet. After it lands, use it as a second review pass for unresolved codemod markers, uncertain imports, old RPC helper chains, and direct v1 SDK replacements. See the [migration overview](./migration-overview#mcp-assisted-migration) for the planned workflow. +:::tip MCP-assisted migration +Yellow SDK MCP is available as `@yellow-org/sdk-mcp`. Connect it to your AI coding tool when you want help reviewing unresolved codemod markers, uncertain imports, old RPC helper chains, and direct v1 SDK replacements. See the [migration overview](./migration-overview#mcp-assisted-migration) for the workflow. ::: diff --git a/docs/nitrolite/builder-toolkit.mdx b/docs/nitrolite/builder-toolkit.mdx index 92c3a2a..5a76428 100644 --- a/docs/nitrolite/builder-toolkit.mdx +++ b/docs/nitrolite/builder-toolkit.mdx @@ -40,12 +40,21 @@ Start here when you want to build with Nitrolite before reading every page. Use
-
+
-
Coming soon
+
AI building companion

Yellow SDK MCP

-

Structured SDK, protocol, RPC, examples, and migration context for AI coding tools. This should help teams build with Yellow SDK with fewer hallucinated method shapes.

- NPM package pending +

Connect Yellow SDK knowledge to Claude Code, Codex, Cursor, Windsurf, VS Code Copilot, and other MCP-compatible tools. Ask your AI coding tool to find the right SDK call, explain a flow, create a starter app, or review a migration while you build.

+
+ npx -y @yellow-org/sdk-mcp@^1 + TypeScript SDK + Go SDK + Migration help +
+
+
+ Set up MCP + View npm package
diff --git a/docs/nitrolite/learn/index.mdx b/docs/nitrolite/learn/index.mdx index 983dac0..f4fee66 100644 --- a/docs/nitrolite/learn/index.mdx +++ b/docs/nitrolite/learn/index.mdx @@ -56,7 +56,7 @@ After completing the Learn section, continue to: - **[Build](/nitrolite/build/getting-started/quickstart)**: Implement complete Yellow applications. - **[Protocol](/nitrolite/protocol/introduction)**: Read the authoritative protocol specification. -- **MCP tools**: Agent-assisted protocol and SDK lookup documentation is coming soon. +- **[Yellow SDK MCP](/nitrolite/build/sdk/mcp)**: Connect Yellow SDK to your AI coding tool so you can ask guided questions while you learn and build. --- diff --git a/src/css/custom.css b/src/css/custom.css index 2f6e0ae..5ff349a 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -414,18 +414,6 @@ a.table-of-contents__link.table-of-contents__link--active code { gap: 10px; } -.nitrolite-toolkit-card--disabled { - opacity: 0.68; - background: var(--ifm-color-emphasis-100); - border-style: dashed; -} - -.nitrolite-toolkit-card--disabled .button.disabled { - pointer-events: none; - cursor: not-allowed; - opacity: 0.72; -} - .nitrolite-toolkit-links { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr));