@aigne/example-mcp-blocklet 1.5.0

package/.env.local.example

@@ -0,0 +1,4 @@
+# Change the name of this file to .env.local and fill in the following values
+
+OPENAI_API_KEY="" # Your OpenAI API key
+BLOCKLET_APP_URL="" # Your Blocklet app URL

package/README.md

@@ -0,0 +1,52 @@
+# MCP Blocklet Demo
+
+This is a demonstration of using [AIGNE Framework](https://github.com/AIGNE-io/aigne-framework) and MCP to interact with apps hosted on the [Blocklet platform](https://github.com/blocklet).
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org) and npm installed on your machine
+- [OpenAI API key](https://platform.openai.com/api-keys) used to interact with OpenAI API
+- [Pnpm](https://pnpm.io) [Optional] if you want to run the example from source code
+
+## Try without Installation
+
+```bash
+export OPENAI_API_KEY=YOUR_OPENAI_API_KEY # setup your OpenAI API key
+
+npx -y @aigne/example-mcp-blocklet # run the example
+```
+
+## Installation
+
+### Clone the Repository
+
+```bash
+git clone https://github.com/AIGNE-io/aigne-framework
+```
+
+### Install Dependencies
+
+```bash
+cd aigne-framework/examples/mcp-blocklet
+
+pnpm install
+```
+
+### Setup Environment Variables
+
+Setup your OpenAI API key in the `.env.local` file:
+
+```bash
+OPENAI_API_KEY="" # setup your OpenAI API key here
+BLOCKLET_APP_URL="" # setup your Blocklet app URL here
+```
+
+### Run the Example
+
+```bash
+pnpm start
+```
+
+## License
+
+This project is licensed under the MIT License.

package/index.ts

@@ -0,0 +1,125 @@
+#!/usr/bin/env npx -y bun
+
+import assert from "node:assert";
+import { runChatLoopInTerminal } from "@aigne/cli/utils/run-chat-loop.js";
+import { AIAgent, ExecutionEngine, MCPAgent, PromptBuilder } from "@aigne/core";
+import { OpenAIChatModel } from "@aigne/core/models/openai-chat-model.js";
+import { logger } from "@aigne/core/utils/logger.js";
+import { UnauthorizedError, refreshAuthorization } from "@modelcontextprotocol/sdk/client/auth.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+// @ts-ignore
+import JWT from "jsonwebtoken";
+
+import { TerminalOAuthProvider } from "./oauth.js";
+
+logger.enable(`aigne:mcp,${process.env.DEBUG}`);
+
+const { OPENAI_API_KEY, BLOCKLET_APP_URL } = process.env;
+assert(OPENAI_API_KEY, "Please set the OPENAI_API_KEY environment variable");
+assert(BLOCKLET_APP_URL, "Please set the BLOCKLET_APP_URL environment variable");
+console.info("Connecting to blocklet app", BLOCKLET_APP_URL);
+
+const appUrl = new URL(BLOCKLET_APP_URL);
+appUrl.pathname = "/.well-known/service/mcp/sse";
+
+const provider = new TerminalOAuthProvider(appUrl.host);
+const authCodePromise = new Promise((resolve, reject) => {
+  provider.once("authorized", resolve);
+  provider.once("error", reject);
+});
+
+const transport = new SSEClientTransport(appUrl, {
+  authProvider: provider,
+});
+
+try {
+  let tokens = await provider.tokens();
+  if (tokens) {
+    let decoded = JWT.decode(tokens.access_token);
+    console.info("Decoded access token:", decoded);
+    if (decoded) {
+      const now = Date.now();
+      const expiresAt = decoded.exp * 1000;
+      if (now < expiresAt) {
+        console.info("Tokens already exist and not expired, skipping authorization");
+      } else if (tokens.refresh_token) {
+        decoded = JWT.decode(tokens.refresh_token);
+        console.info("Decoded refresh token:", decoded);
+        if (decoded) {
+          const now = Date.now();
+          const expiresAt = decoded.exp * 1000;
+          if (now < expiresAt) {
+            console.info("Refresh token already exists and not expired, refreshing authorization");
+            try {
+              tokens = await refreshAuthorization(appUrl.href, {
+                // biome-ignore lint/style/noNonNullAssertion: <explanation>
+                clientInformation: (await provider.clientInformation())!,
+                refreshToken: tokens.refresh_token,
+              });
+              await provider.saveTokens(tokens);
+            } catch (error) {
+              console.error(
+                "Error refreshing authorization, resetting tokens and starting authorization",
+                error,
+              );
+              await provider.saveTokens(undefined);
+              await transport.start();
+            }
+          } else {
+            console.info("Refresh token already expired, starting authorization");
+            await transport.start();
+          }
+        }
+      }
+    }
+  } else {
+    console.info("No tokens found, starting authorization");
+    await transport.start();
+  }
+} catch (error) {
+  if (error instanceof UnauthorizedError) {
+    const code = await authCodePromise;
+    console.info("Authorization code received, finishing authorization...", Date.now());
+    await transport.finishAuth(code as string);
+    await transport.close();
+  } else {
+    console.error("Error authorizing:", error);
+    process.exit(1);
+  }
+}
+
+console.info("Starting connecting to blocklet mcp...");
+
+const model = new OpenAIChatModel({
+  apiKey: OPENAI_API_KEY,
+});
+
+const blocklet = await MCPAgent.from({
+  url: appUrl.href,
+  timeout: 8000,
+  opts: {
+    authProvider: provider,
+  },
+});
+
+const engine = new ExecutionEngine({
+  model,
+  tools: [blocklet],
+});
+
+const agent = AIAgent.from({
+  instructions: PromptBuilder.from(
+    "You are a helpful assistant that can help users query and analyze data from the blocklet. You can perform various database queries on the blocklet database, before performing any queries, please try to understand the user's request and generate a query base on the database schema.",
+  ),
+  memory: true,
+});
+
+const userAgent = engine.call(agent);
+
+await runChatLoopInTerminal(userAgent, {
+  welcome:
+    "Hello! I'm a chatbot that can help you interact with the blocklet. Try asking me a question about the blocklet!",
+  defaultQuestion: "How many users are there in the database?",
+});
+
+process.exit(0);

package/oauth.ts

@@ -0,0 +1,217 @@
+import { EventEmitter } from "node:events";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { join } from "node:path";
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import type {
+  OAuthClientInformation,
+  OAuthClientInformationFull,
+  OAuthTokens,
+} from "@modelcontextprotocol/sdk/shared/auth.js";
+import open from "open";
+
+export class TerminalOAuthProvider extends EventEmitter implements OAuthClientProvider {
+  private _tokens: OAuthTokens | undefined;
+  private _clientInformation: OAuthClientInformationFull | undefined;
+
+  private codeVerifierValue = "";
+  private localServerPort = 4444; // Choose an available port
+  private tokenFilePath: string;
+  private clientInfoPath: string;
+
+  constructor(host: string) {
+    super();
+
+    this.tokenFilePath = join(process.cwd(), ".oauth", host, "token.json");
+    this.clientInfoPath = join(process.cwd(), ".oauth", host, "client.json");
+
+    mkdirSync(join(process.cwd(), ".oauth", host), { recursive: true });
+
+    this.loadTokens();
+    this.loadClientInfo();
+  }
+
+  get redirectUrl() {
+    return `http://localhost:${this.localServerPort}/callback`;
+  }
+
+  get clientMetadata() {
+    return {
+      redirect_uris: [this.redirectUrl],
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      client_name: "AIGNE Examples",
+      client_uri: "https://www.aigne.io/framework",
+      logo_uri: "https://www.aigne.io/.well-known/service/blocklet/logo",
+      scope: "profile:read blocklet:read blocklet:write",
+      tos_uri: "https://www.arcblock.io/en/termsofuse",
+      policy_uri: "https://www.arcblock.io/en/privacy",
+      contacts: ["support@aigne.io"],
+      software_id: "AIGNE Framework",
+      software_version: "1.0.0",
+    };
+  }
+
+  async clientInformation(): Promise<OAuthClientInformation | undefined> {
+    return this._clientInformation;
+  }
+
+  async saveClientInformation(clientInformation: OAuthClientInformationFull): Promise<void> {
+    console.log("Saving client information:", clientInformation);
+    this._clientInformation = clientInformation;
+    this.persistClientInfo();
+  }
+
+  async tokens(): Promise<OAuthTokens | undefined> {
+    return this._tokens;
+  }
+
+  async saveTokens(tokens: OAuthTokens | undefined): Promise<void> {
+    if (tokens) {
+      console.log("Saving tokens:", tokens);
+      this._tokens = tokens;
+      this.persistTokens();
+    } else {
+      console.error("Reset tokens");
+      this._tokens = undefined;
+      this.persistTokens();
+    }
+  }
+
+  async redirectToAuthorization(authorizationUrl: URL): Promise<void> {
+    // Create a local server to handle the callback
+    return new Promise((resolve, reject) => {
+      const server = createServer(async (req, res) => {
+        if (req.url?.startsWith("/callback")) {
+          const url = new URL(req.url, this.redirectUrl);
+          const code = url.searchParams.get("code");
+          const error = url.searchParams.get("error");
+          const errorDescription = url.searchParams.get("error_description");
+
+          // Send a response to close the browser window
+          res.writeHead(200, { "Content-Type": "text/html" });
+          res.end(`
+            <html>
+              <head>
+                <title>Authorization</title>
+                <meta charset="UTF-8">
+                <meta name="viewport" content="width=device-width, initial-scale=1.0">
+                <style>
+                  body {
+                    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
+                    display: flex;
+                    justify-content: center;
+                    align-items: center;
+                    min-height: 100vh;
+                    margin: 0;
+                    background-color: #f5f5f5;
+                    color: #333;
+                  }
+                  .container {
+                    background: white;
+                    padding: 2rem;
+                    border-radius: 8px;
+                    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+                    text-align: center;
+                    max-width: 400px;
+                    width: 90%;
+                  }
+                  h1 {
+                    color: ${error ? "#dc3545" : "#28a745"};
+                    margin-bottom: 1rem;
+                  }
+                  p {
+                    margin: 0.5rem 0;
+                    line-height: 1.5;
+                  }
+                  .status-icon {
+                    font-size: 3rem;
+                    margin-bottom: 1rem;
+                  }
+                </style>
+              </head>
+              <body>
+                <div class="container">
+                  <div class="status-icon">${error ? "❌" : "✅"}</div>
+                  <h1>Authorization ${error ? "Failed" : "Successful"}!</h1>
+                  ${errorDescription ? `<p>${errorDescription}</p>` : ""}
+                  <p>You can close this window and return to the application.</p>
+                </div>
+                <script>window.close()</script>
+              </body>
+            </html>
+          `);
+
+          // Close the server
+          server.close();
+
+          if (code) {
+            this.emit("authorized", code);
+            console.info("Authorization successful!", Date.now());
+            resolve();
+          } else {
+            this.emit("error", new Error("No authorization code received"));
+            reject(new Error("No authorization code received"));
+          }
+        }
+      });
+
+      // Start the local server
+      server.listen(this.localServerPort, async () => {
+        console.log("Please authorize the application in your browser...");
+        // Open the authorization URL in the default browser
+        await open(authorizationUrl.toString());
+      });
+    });
+  }
+
+  async saveCodeVerifier(codeVerifier: string): Promise<void> {
+    this.codeVerifierValue = codeVerifier;
+  }
+
+  async codeVerifier(): Promise<string> {
+    return this.codeVerifierValue;
+  }
+
+  private loadTokens(): void {
+    try {
+      if (existsSync(this.tokenFilePath)) {
+        const data = readFileSync(this.tokenFilePath, "utf8");
+        this._tokens = JSON.parse(data);
+      }
+    } catch (error) {
+      console.error("Error loading tokens:", error);
+    }
+  }
+
+  private persistTokens(): void {
+    try {
+      if (this._tokens) {
+        writeFileSync(this.tokenFilePath, JSON.stringify(this._tokens, null, 2));
+      }
+    } catch (error) {
+      console.error("Error persisting tokens:", error);
+    }
+  }
+
+  private loadClientInfo(): void {
+    try {
+      if (existsSync(this.clientInfoPath)) {
+        const data = readFileSync(this.clientInfoPath, "utf8");
+        this._clientInformation = JSON.parse(data);
+      }
+    } catch (error) {
+      console.error("Error loading client information:", error);
+    }
+  }
+
+  private persistClientInfo(): void {
+    try {
+      if (this._clientInformation) {
+        writeFileSync(this.clientInfoPath, JSON.stringify(this._clientInformation, null, 2));
+      }
+    } catch (error) {
+      console.error("Error persisting client information:", error);
+    }
+  }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@aigne/example-mcp-blocklet",
+  "version": "1.5.0",
+  "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",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AIGNE-io/aigne-framework"
+  },
+  "bin": "index.ts",
+  "files": [
+    ".env.local.example",
+    "*.ts",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.9.0",
+    "jsonwebtoken": "^9.0.2",
+    "open": "^10.1.0",
+    "zod": "^3.24.2",
+    "@aigne/cli": "^1.2.0",
+    "@aigne/core": "^1.7.0"
+  },
+  "scripts": {
+    "start": "npx -y bun run index.ts",
+    "lint": "tsc --noEmit"
+  }
+}