diff --git a/docs/ai/introduction.md b/docs/ai/introduction.md index 8afb2874915..7fa6522a302 100644 --- a/docs/ai/introduction.md +++ b/docs/ai/introduction.md @@ -12,7 +12,7 @@ our **Shade Agent Framework** allows to create verifiable and trustless AI agent :::tip Using AI to build on NEAR? -Searching for how to use AI to help you build NEAR dApps, check our [Building NEAR Apps with AI](./llms.md) documentation +Searching for how to use AI to help you build NEAR dApps, check [Tools for AI Agents](./tools-for-ai.md) ::: @@ -23,7 +23,7 @@ Searching for how to use AI to help you build NEAR dApps, check our [Building NE AI Agents can easily control account and assets on all blockchains thanks to NEARs unique features. You simply need to give them access to a NEAR account and they can start interacting with smart contracts, sending transactions, and managing assets everywhere. -Check our [NEAR MCP](./near-mcp.md) documentation to get started. +Check [Tools for AI Agents](./tools-for-ai.md) to get started. --- @@ -43,8 +43,7 @@ Shade Agents power [Agentic Protocols](./shade-agents/concepts/what-can-you-buil | Docs | Best if you... | |--------------------------------------------------------------------------------|------------------------------------------------------------------------------------------| -| [AI + NEAR](./near-mcp.md) | Already have an AI Agent, and want to connect it to NEAR (and other chains) | -| [Building NEAR Apps with AI](./llms.md) | Are building a NEAR App, and want your Code Agents to help you better | +| [Tools for AI Agents](./tools-for-ai.md) | Want one practical guide for docs context, agent skills, and NEAR on-chain tooling | | [Trustless Multi-chain Agents](./shade-agents/getting-started/introduction.md) | Are building an agent from zero and need to securely handle funds across multiple chains | --- diff --git a/docs/ai/llms.md b/docs/ai/llms.md deleted file mode 100644 index a358be0fa66..00000000000 --- a/docs/ai/llms.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -id: using-llms -title: Using NEAR documentation with your AI Coding Agents -sidebar_label: Docs with AI Coding Agents -description: "Using llms.txt to improve your workflow when using AI coding agents." ---- - -NEAR Docs hosts a [`llms.txt`](https://docs.near.org/llms.txt) file to provide information to help LLMs use the complete NEAR documentation at inference time. - -While websites serve both human readers and LLMs, LLMs benefit from concise information gathered in a single, accessible location. This is critical for use cases like development environments, where LLMs need quick access to programming documentation and APIs. - -:::info - -If you want to learn more about the `llms.txt` standard, check [this website](https://llmstxt.org/). - -::: - -## Using `llms.txt` - -The `llms.txt` core purpose is to provide context that the AI agent can reference before generating or modifying code. - -Using an `llms.txt` file as a reference for AI coding agents is an advanced technique to guide the AI's behavior, improve code quality, and enforce project-specific patterns. It's essentially a way to provide contextual, in-the-flow documentation. - -Next, you can find examples of how to integrate `llms.txt` with [Visual Studio Code](#visual-studio-code) and [Cursor](#cursor). - -## Visual Studio Code - -To use [NEAR Docs llms.txt](https://docs.near.org/llms.txt) as reference when working with Copilot Chat, follow these steps. - -1. Open the Copilot Chat sidebar on VS Code. -2. Ask your question, and use the `#fetch` keyword to add `https://docs.near.org/llms.txt` as reference. - For example: - ``` - How can I upgrade a contract state? - #fetch https://docs.near.org/llms.txt - ``` - - ![VS Code](/assets/docs/tools/llm-vscode1.png) - -3. Get your AI-generated answer, along with direct reference links from the NEAR documentation site. - - ![VS Code](/assets/docs/tools/llm-vscode2.png) - -## Cursor - -When using Cursor, you can add [NEAR Docs llms.txt](https://docs.near.org/llms.txt) as documentation reference following these steps, so it will be available when asking questions to the AI agent. - -1. Open Cursor Chat window. -2. Click on `@`, select `Docs`, and `+ Add new doc`. On the text box, enter: - ``` - https://docs.near.org/llms.txt - ``` - - ![VS Code](/assets/docs/tools/llm-cursor1.png) - -2. You can now select `NEAR Protocol` as documentation reference when asking your questions. - - ![VS Code](/assets/docs/tools/llm-cursor2.png) - -3. Get your AI-generated answer based on NEAR documentation. - - ![VS Code](/assets/docs/tools/llm-cursor3.png) diff --git a/docs/ai/near-mcp.md b/docs/ai/near-mcp.md deleted file mode 100644 index 188eff997f6..00000000000 --- a/docs/ai/near-mcp.md +++ /dev/null @@ -1,174 +0,0 @@ ---- -id: near-mcp -title: NEAR MCP Server -sidebar_label: NEAR MCP Server -description: "Equip AI agents with tools for using the NEAR blockchain via Model Context Protocol (MCP)." ---- - -import {Github} from "@site/src/components/UI/Codetabs" -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -The NEAR MCP Server is an open-source toolkit offers a standardized way for AI applications to integrate with NEAR. It provides [23 tools](https://github.com/nearai/near-mcp/blob/main/TOOLS.md) which enable agents to sign on-chain transactions, manage access keys, exchange tokens, interact with contracts, and more! - -:::info Heads up... - -MCP stands for [Model Context Protocol](https://modelcontextprotocol.io), an open-source standard for connecting AI agents with external services - -Not to be confused with the MPC (Multi-Party Computation) service used by [chain signatures](../chain-abstraction/chain-signatures.md) - -::: - ---- - -## Usage Guide - -Since the NEAR MCP Server needs to handle private keys, it is designed to run locally on your machine or on a trusted remote server. Currently there is **no hosted version** of the NEAR MCP server. - -
- -### Quickstart -You can either install the MCP server globally and start it, or run it directly using `npx`. - - - - - ```bash - # Install and Run - npm install -g @nearai/near-mcp@latest - near-mcp run - - # Without Installing - npx @nearai/near-mcp@latest run - ``` - - - - - -:::tip - -By default the MCP server will run a local input/output server, to start a web server instead add the `--port 4000 --remote` flags - -```bash -npx @nearai/near-mcp@latest run --port 4000 --remote -``` - -::: - -
- -### Local MCP Server - -Once the NEAR MPC starts locally it starts what is called a [`stdio server`](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio). To connect your AI agent to the server you will need to use an MCP client library: - - - -In order to use the NEAR MCP server, you will need to manually parse its tool: - - - -You can then use the tools as part of your prompt: - - - -:::tip Accounts - -By default the MCP server will have no accounts loaded, your agent can either import and account using the `system_import_account` tool, or you can specify which keystore to load by setting the `NEAR_KEYSTORE` environment variable - -```bash -NEAR_KEYSTORE=/path/to/keystore npx @nearai/near-mcp@latest run -``` - -::: - -
- - -### Example Prompts - -The Agent using the MCP server will readily have tool to answer prompts like: - -- What is the balance of `agency.testnet`? -- Add the account `example.testnet` using the private key `ed25519:...` -- Transfer 0.1 NEAR from `agency.testnet` to `example.testnet` -- Call the `ft_transfer` method on the `usdc.fakes.testnet` contract -- What are the public methods of `social.near`? - ---- - -## Integrate With AI Clients - -You can use the NEAR MCP server with any standard MCP client. Here are instructions for some popular clients: - - - - - - Go to **Settings** > **MCP Servers**, and add a new server with the following details: - - - **Name**: near-mcp - - **Command**: npx - - **Arguments**: ["-y", "@nearai/near-mcp@latest", "run"] - - **Environment Variables**: (optional) Add any necessary environment variables, e.g., `NEAR_KEYSTORE`. - - You can now use the NEAR MCP tools in your prompts. - - - - - - ##### 1. Install Claude Code - - ```bash - npm install -g @anthropic-ai/claude-code - ``` - - ##### 2. Add MCP Server to Claude Code - - ```bash - claude mcp add near-mcp npx @nearai/near-mcp@latest run - ``` - - ##### 3. Start Claude Code and Run Tests - - ``` - claude - ``` - - - - - - Add to your JSON config: - - ```json - { - "mcpServers": { - "near-mcp": { - "command": "npx", - "args": ["-y", "@nearai/near-mcp@latest", "run"], - "env": {} - } - } - } - ``` - - - - - ---- - -## Remote MCP Server - -Read these [instructions](https://github.com/nearai/near-mcp/blob/main/tee.md) to deploy the MCP server remotely on Phala Cloud. - ---- - -## Contributing - -Visit NEAR AI's [GitHub repository](https://github.com/nearai/near-mcp) to create issues or submit pull requests. diff --git a/docs/ai/tools-for-ai.md b/docs/ai/tools-for-ai.md new file mode 100644 index 00000000000..1c67221e2bd --- /dev/null +++ b/docs/ai/tools-for-ai.md @@ -0,0 +1,124 @@ +--- +id: tools-for-ai +title: Tools for AI Agents +description: "Guide your agent on building NEAR applications" +--- + +import Card from '@site/src/components/UI/Card'; + +NEAR offers multiple tools and resources to help your AI agents build and use NEAR applications. This page provides an overview of the key tools available and how to use them effectively. + +
+
+ +

When you need to provide your agent with a quick reference to all NEAR docs.

+ Open section → + +
+
+ +

When you want agents to search docs in real-time for up-to-date details.

+ Open section → + +
+
+
+
+ +

When you need your agent to become an expert in a specific task (e.g. using our API).

+ Open section → + +
+
+ +

When your agent needs to perform on-chain actions (e.g., transfers and function calls).

+ Open section → + +
+
+ +--- + +## llms.txt + +**What it is:** Curated NEAR docs context for coding assistants. + +**Use it when:** You need to provide your agent with a quick reference to all NEAR docs. + +**Link:** [https://docs.near.org/llms.txt](https://docs.near.org/llms.txt) + +
+VS Code Setup + +Use `#fetch` in your prompt: + +```text +How can I upgrade a contract state? +#fetch https://docs.near.org/llms.txt +``` + +
+ +
+Cursor Setup + +Add docs source once in Cursor Chat: + +1. `@` → `Docs` → `+ Add new doc` +2. Add: `https://docs.near.org/llms.txt` +3. Select the source while prompting + +
+ +--- + +## Docs MCP endpoint + +**What it is:** An endpoint to search NEAR documentation via MCP. + +**Use it when:** You want agents to search docs in real-time for up-to-date details and narrower API lookups. + +**Link:** [https://docs.near.org/mcp](https://docs.near.org/mcp) + +Use two complementary layers: + +1. **Static context (`llms.txt`)** for fast, high-signal docs grounding. +2. **Retrieval (Docs MCP)** when the agent needs live lookup across docs. + +--- + +## NEAR Agent Skills + +NEAR Agent Skills are reusable capabilities that package repeatable workflows. + +**Use it when:** You need your agent to become an expert in specific tasks (for example, using NEAR APIs). + +**Link:** [https://github.com/near/agent-skills](https://github.com/near/agent-skills) + +| Skill | Focus | +|----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------| +| [near-ai-cloud](https://github.com/near/agent-skills/tree/main/skills/near-ai-cloud) | Verifiable private AI inference and attestation | +| [near-api-js](https://github.com/near/agent-skills/tree/main/skills/near-api-js) | JS/TS blockchain interaction, transactions, tokens, and wallet integration | +| [near-dapp](https://github.com/near/agent-skills/tree/main/skills/near-dapp) | dApp project setup, wallet integration, React/Next.js patterns | +| [near-intents](https://github.com/near/agent-skills/tree/main/skills/near-intents) | Cross-chain swaps via the 1Click API | +| [near-kit](https://github.com/near/agent-skills/tree/main/skills/near-kit) | TypeScript SDK with type-safe contracts and sandbox testing | +| [near-smart-contracts](https://github.com/near/agent-skills/tree/main/skills/near-smart-contracts) | Rust smart contract development, security, and state management | + +--- + +## NEAR MCP Server + +The NEAR MCP Server is a tool server (currently [23 tools](https://github.com/nearai/near-mcp/blob/main/TOOLS.md)) that enables agents to perform blockchain operations. + +**Use it when:** Your agent needs to hold funds, transfer funds, interact with smart contracts, or perform any action on-chain in NEAR Protocol + +**Repo**: [https://github.com/nearai/near-mcp](https://github.com/nearai/near-mcp) + +**Remote deployment guide**: [https://github.com/nearai/near-mcp/blob/main/tee.md](https://github.com/nearai/near-mcp/blob/main/tee.md) + +:::warning + +The NEAR MCP is designed to run **locally** or on your **trusted infrastructure** because it handles private keys. There is no hosted public version. + +::: + diff --git a/website/sidebars.js b/website/sidebars.js index 733be958c2f..adda9d43814 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -191,8 +191,7 @@ const sidebar = { }, items: [ 'ai/introduction', - 'ai/near-mcp', - 'ai/using-llms', + 'ai/tools-for-ai', { "Shade Agents": [ {