@aigne/example-mcp-blocklet 1.17.5-beta → 1.17.5-beta.1

package/.env.local.example

@@ -44,4 +44,4 @@ OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
 # HTTPS_PROXY=http://localhost:7890
 
 # Setup Blocklet app URL
-BLOCKLET_APP_URL="" # Your Blocklet app URL
+BLOCKLET_APP_URL="https://xxx.xxxx.xxx" # Your Blocklet app URL

package/README.md

@@ -20,8 +20,9 @@ This demo demonstrates how to use [AIGNE Framework](https://github.com/AIGNE-io/
 
 ## Quick Start (No Installation Required)
 
+### Run the Example
+
 ```bash
-export OPENAI_API_KEY=YOUR_OPENAI_API_KEY # Set your OpenAI API key
 export BLOCKLET_APP_URL="https://xxx.xxxx.xxx" # Your Blocklet app URL
 
 # Run in one-shot mode (default)
@@ -34,45 +35,62 @@ npx -y @aigne/example-mcp-blocklet --chat
 echo "What are the features of this blocklet app?" | npx -y @aigne/example-mcp-blocklet
 ```
 
-## Installation
+### Connect to an AI Model
 
-### Clone the Repository
+As an example, running `npx -y @aigne/example-mcp-blocklet --chat` requires an AI model. If this is your first run, you need to connect one.
+
+![run example](./run-example.png)
+
+- Connect via the official AIGNE Hub
+
+Choose the first option and your browser will open the official AIGNE Hub page. Follow the prompts to complete the connection. If you're a new user, the system automatically grants 400,000 tokens for you to use.
+
+![connect to official aigne hub](../images/connect-to-aigne-hub.png)
+
+- Connect via a self-hosted AIGNE Hub
+
+Choose the second option, enter the URL of your self-hosted AIGNE Hub, and follow the prompts to complete the connection. If you need to set up a self-hosted AIGNE Hub, visit the Blocklet Store to install and deploy it: [Blocklet Store](https://store.blocklet.dev/blocklets/z8ia3xzq2tMq8CRHfaXj1BTYJyYnEcHbqP8cJ?utm_source=www.arcblock.io&utm_medium=blog_link&utm_campaign=default&utm_content=store.blocklet.dev#:~:text=%F0%9F%9A%80%20Get%20Started%20in%20Minutes).
+
+![connect to self hosted aigne hub](../images/connect-to-self-hosted-aigne-hub.png)
+
+- Connect via a third-party model provider
+
+Using OpenAI as an example, you can configure the provider's API key via environment variables. After configuration, run the example again:
 
 ```bash
-git clone https://github.com/AIGNE-io/aigne-framework
+export OPENAI_API_KEY="" # Set your OpenAI API key here
 ```
+For more details on third-party model configuration (e.g., OpenAI, DeepSeek, Google Gemini), see [.env.local.example](./.env.local.example).
 
-### Install Dependencies
+After configuration, run the example again.
 
-```bash
-cd aigne-framework/examples/mcp-blocklet
+### Debugging
 
-pnpm install
-```
+The `aigne observe` command starts a local web server to monitor and analyze agent execution data. It provides a user-friendly interface to inspect traces, view detailed call information, and understand your agent’s behavior during runtime. This tool is essential for debugging, performance tuning, and gaining insight into how your agent processes information and interacts with tools and models.
+
+Start the observation server.
 
-### Setup Environment Variables
+![aigne-observe-execute](../images/aigne-observe-execute.png)
+
+View a list of recent executions.
+
+![aigne-observe-list](../images/aigne-observe-list.png)
+
+## Installation
 
-Setup your OpenAI API key in the `.env.local` file:
+### Clone the Repository
 
 ```bash
-OPENAI_API_KEY="" # Set your OpenAI API key here
-BLOCKLET_APP_URL="" # Set your Blocklet app URL here
+git clone https://github.com/AIGNE-io/aigne-framework
 ```
 
-#### Using Different Models
-
-You can use different AI models by setting the `MODEL` environment variable along with the corresponding API key. The framework supports multiple providers:
+### Install Dependencies
 
-* **OpenAI**: `MODEL="openai:gpt-4.1"` with `OPENAI_API_KEY`
-* **Anthropic**: `MODEL="anthropic:claude-3-7-sonnet-latest"` with `ANTHROPIC_API_KEY`
-* **Google Gemini**: `MODEL="gemini:gemini-2.0-flash"` with `GEMINI_API_KEY`
-* **AWS Bedrock**: `MODEL="bedrock:us.amazon.nova-premier-v1:0"` with AWS credentials
-* **DeepSeek**: `MODEL="deepseek:deepseek-chat"` with `DEEPSEEK_API_KEY`
-* **OpenRouter**: `MODEL="openrouter:openai/gpt-4o"` with `OPEN_ROUTER_API_KEY`
-* **xAI**: `MODEL="xai:grok-2-latest"` with `XAI_API_KEY`
-* **Ollama**: `MODEL="ollama:llama3.2"` with `OLLAMA_DEFAULT_BASE_URL`
+```bash
+cd aigne-framework/examples/mcp-blocklet
 
-For detailed configuration examples, please refer to the `.env.local.example` file in this directory.
+pnpm install
+```
 
 ### Run the Example
 

package/index.ts

@@ -7,9 +7,12 @@ import { DefaultMemory } from "@aigne/default-memory";
 import { refreshAuthorization, UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import JWT from "jsonwebtoken";
+import { joinURL } from "ufo";
 import { TerminalOAuthProvider } from "./oauth.js";
 
-const rawUrl = process.argv[2] || process.env.BLOCKLET_APP_URL;
+const rawUrl =
+  process.argv.find((arg) => arg.startsWith("https://") || arg.startsWith("http://")) ||
+  process.env.BLOCKLET_APP_URL;
 assert(
   rawUrl,
   "Please provide a blocklet url as an argument or set the BLOCKLET_APP_URL environment variable",
@@ -17,8 +20,7 @@ assert(
 
 const appUrl = new URL(rawUrl);
 try {
-  appUrl.pathname = "/__blocklet__.js";
-  const result = await fetch(appUrl.href);
+  const result = await fetch(joinURL(appUrl.href, "__blocklet__.js"));
   if (result.status !== 200) {
     console.error("Seems like the provided url is not a valid blocklet url: ", rawUrl);
     process.exit(1);
@@ -28,7 +30,6 @@ try {
   process.exit(1);
 }
 
-appUrl.pathname = "/.well-known/service/mcp";
 console.info("Connecting to blocklet", appUrl.href);
 
 let transport: StreamableHTTPClientTransport;
@@ -111,8 +112,9 @@ try {
 
 await runWithAIGNE(
   async () => {
+    const url = joinURL(appUrl.origin, "/.well-known/service/mcp");
     const blocklet = await MCPAgent.from({
-      url: appUrl.href,
+      url,
       transport: "streamableHttp",
       opts: {
         authProvider: provider,

package/oauth.ts

@@ -49,6 +49,9 @@ export class TerminalOAuthProvider extends EventEmitter implements OAuthClientPr
       contacts: ["support@aigne.io"],
       software_id: "AIGNE Framework",
       software_version: "1.0.0",
+
+      token_endpoint_auth_method: "client_secret_post",
+      jwks_uri: `${this.redirectUrl}/.well-known/jwks.json`,
     };
   }
 
@@ -79,6 +82,10 @@ export class TerminalOAuthProvider extends EventEmitter implements OAuthClientPr
   }
 
   async redirectToAuthorization(authorizationUrl: URL): Promise<void> {
+    console.log(
+      "🚀 redirectToAuthorization called, authorizationUrl:",
+      authorizationUrl.toString(),
+    );
     // Create a local server to handle the callback
     return new Promise((resolve, reject) => {
       const server = createServer(async (req, res) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/example-mcp-blocklet",
-  "version": "1.17.5-beta",
+  "version": "1.17.5-beta.1",
   "description": "A demonstration of using AIGNE Framework and MCP Server hosted by the Blocklet platform",
   "author": "Arcblock <blocklet@arcblock.io> https://github.com/blocklet",
   "homepage": "https://github.com/AIGNE-io/aigne-framework/tree/main/examples/mcp-blocklet",
@@ -16,18 +16,19 @@
     "README.md"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.18.0",
+    "@modelcontextprotocol/sdk": "^1.21.1",
     "jsonwebtoken": "^9.0.2",
     "open": "^10.2.0",
+    "ufo": "^1.6.1",
     "zod": "^3.25.67",
-    "@aigne/agent-library": "^1.23.0-beta",
-    "@aigne/cli": "^1.58.0-beta",
-    "@aigne/core": "^1.71.0-beta",
-    "@aigne/default-memory": "^1.3.5-beta"
+    "@aigne/agent-library": "^1.23.0-beta.1",
+    "@aigne/cli": "^1.58.0-beta.1",
+    "@aigne/core": "^1.71.0-beta.1",
+    "@aigne/default-memory": "^1.3.5-beta.1"
   },
   "devDependencies": {
     "@types/jsonwebtoken": "^9.0.10",
-    "@aigne/test-utils": "^0.5.68-beta"
+    "@aigne/test-utils": "^0.5.68-beta.1"
   },
   "scripts": {
     "start": "bun run index.ts",