@aigne/example-afs-mcp-server 1.0.0

package/.env.local.example

@@ -0,0 +1,44 @@
+# Change the name of this file to .env.local and fill in the following values
+
+# Uncomment the lines below to enable debug logging
+# DEBUG="aigne:*"
+
+# Use different Models
+
+# OpenAI
+# MODEL="openai/gpt-4.1"
+# OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
+
+# Anthropic claude
+# MODEL="anthropic/claude-3-7-sonnet-latest"
+# ANTHROPIC_API_KEY=""
+
+# Gemini
+MODEL="google/gemini-2.5-pro"
+# GEMINI_API_KEY=""
+
+# Bedrock nova
+# MODEL=bedrock:us.amazon.nova-premier-v1:0
+# AWS_ACCESS_KEY_ID=""
+# AWS_SECRET_ACCESS_KEY=""
+# AWS_REGION=us-west-2
+
+# DeepSeek
+# MODEL="deepseek/deepseek-chat"
+# DEEPSEEK_API_KEY=""
+
+# OpenRouter
+# MODEL="openrouter/openai/gpt-4o"
+# OPEN_ROUTER_API_KEY=""
+
+# xAI
+# MODEL="xai/grok-2-latest"
+# XAI_API_KEY=""
+
+# Ollama
+# MODEL="ollama/llama3.2"
+# OLLAMA_DEFAULT_BASE_URL="http://localhost:11434/v1";
+
+
+# Setup proxy if needed
+# HTTPS_PROXY=http://localhost:7890

package/LICENSE.md

@@ -0,0 +1,93 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,269 @@
+# AFS MCP Server Example
+
+<p align="center">
+  <picture>
+    <source srcset="https://raw.githubusercontent.com/AIGNE-io/aigne-framework/main/logo-dark.svg" media="(prefers-color-scheme: dark)">
+    <source srcset="https://raw.githubusercontent.com/AIGNE-io/aigne-framework/main/logo.svg" media="(prefers-color-scheme: light)">
+    <img src="https://raw.githubusercontent.com/AIGNE-io/aigne-framework/main/logo.svg" alt="AIGNE Logo" width="400" />
+  </picture>
+</p>
+
+This example shows how to mount any [MCP (Model Context Protocol)](https://www.anthropic.com/news/model-context-protocol) server as an AFS module, making it accessible to AI agents through a unified file system interface. We use the GitHub MCP Server as a real-world demonstration.
+
+## What You'll See
+
+**User asks:** "Search for a repo named aigne"
+
+**Behind the scenes:**
+1. LLM calls `afs_exec` → `/modules/github-mcp-server/search_repositories`
+2. MCP server searches GitHub and returns JSON results
+3. LLM presents results naturally: "Found 89 repositories. Notable matches: aigne-framework..."
+
+**The power:** AI agents can access GitHub (or any MCP server) through a simple, unified AFS interface - just like accessing files!
+
+## Prerequisites
+
+* [Node.js](https://nodejs.org) (>=20.0) and npm installed on your machine
+* [Docker](https://www.docker.com/) installed and running
+* A [GitHub Personal Access Token](https://github.com/settings/tokens) for GitHub API access
+* An [OpenAI API key](https://platform.openai.com/api-keys) for interacting with OpenAI's services
+* Optional dependencies (if running the example from source code):
+  * [Pnpm](https://pnpm.io) for package management
+  * [Bun](https://bun.sh) for running unit tests & examples
+
+## Quick Start (No Installation Required)
+
+```bash
+# Set your GitHub Personal Access Token
+export GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token_here
+
+# Set your OpenAI API key
+export OPENAI_API_KEY=your_openai_api_key_here
+
+# Run in interactive chat mode
+npx -y @aigne/example-afs-mcp-server --chat
+
+# Ask a specific question
+npx -y @aigne/example-afs-mcp-server --input "Search for a repo named aigne"
+```
+
+## See It In Action
+
+Here's what happens when you ask to search for a repository:
+
+```
+👤 You: "Search for a repo named aigne"
+
+🤖 Agent thinks: I need to search GitHub repositories...
+   → Calls: afs_exec("/modules/github-mcp-server/search_repositories")
+
+📡 GitHub MCP Server:
+   ✓ Found 89 repositories matching "aigne"
+
+🤖 AI: "I searched GitHub for 'aigne'. Results: 89 repositories found.
+
+       Notable matches:
+       • aigne-framework (AIGNE-io/aigne-framework) - ⭐ 150 stars
+       • aigne-examples (user/aigne-examples) - ⭐ 12 stars
+       ...
+
+       Would you like me to open any of these repos or see more details?"
+```
+
+**Key insight:** The agent treats the GitHub MCP Server like any other AFS module - no special integration code needed!
+
+## Installation
+
+### Clone the Repository
+
+```bash
+git clone https://github.com/AIGNE-io/aigne-framework
+```
+
+### Install Dependencies
+
+```bash
+cd aigne-framework/examples/afs-mcp-server
+
+pnpm install
+```
+
+### Setup Environment Variables
+
+Setup your API keys in the `.env.local` file:
+
+```bash
+GITHUB_PERSONAL_ACCESS_TOKEN="" # Set your GitHub Personal Access Token here
+OPENAI_API_KEY="" # Set your OpenAI API key here
+```
+
+#### 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:
+
+* **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`
+
+For detailed configuration examples, please refer to the `.env.local.example` file in this directory.
+
+### Run the Example
+
+```bash
+# Run in interactive chat mode
+pnpm start --chat
+
+# Run with a single message
+pnpm start --input "What are the recent issues in the AIGNE repository?"
+```
+
+## How It Works: 3 Simple Steps
+
+### 1. Launch the MCP Server
+
+```typescript
+import { MCPAgent } from "@aigne/core";
+
+const mcpAgent = await MCPAgent.from({
+  command: "docker",
+  args: [
+    "run", "-i", "--rm",
+    "-e", `GITHUB_PERSONAL_ACCESS_TOKEN=${process.env.GITHUB_PERSONAL_ACCESS_TOKEN}`,
+    "ghcr.io/github/github-mcp-server",
+  ],
+});
+```
+
+### 2. Mount It as an AFS Module
+
+```typescript
+import { AFS } from "@aigne/afs";
+import { AFSHistory } from "@aigne/afs-history";
+
+const afs = new AFS()
+  .mount(new AFSHistory({ storage: { url: ":memory:" } }))
+  .mount(mcpAgent);  // Mounted at /modules/github-mcp-server
+```
+
+### 3. Create an AI Agent
+
+```typescript
+import { AIAgent } from "@aigne/core";
+
+const agent = AIAgent.from({
+  instructions: "Help users interact with GitHub via the github-mcp-server module.",
+  inputKey: "message",
+  afs,  // Agent automatically gets access to all mounted modules
+});
+```
+
+**That's it!** The agent can now call `/modules/github-mcp-server/search_repositories`, `/modules/github-mcp-server/list_issues`, and all other GitHub MCP tools through the AFS interface.
+
+## Try These Examples
+
+```bash
+# Search for repositories
+npx -y @aigne/example-afs-mcp-server --input "Search for a repo named aigne"
+
+# Get repository information
+npx -y @aigne/example-afs-mcp-server --input "Tell me about the AIGNE-io/aigne-framework repository"
+
+# Check recent issues
+npx -y @aigne/example-afs-mcp-server --input "What are the recent open issues in AIGNE-io/aigne-framework?"
+
+# Interactive mode - ask follow-up questions naturally
+npx -y @aigne/example-afs-mcp-server --chat
+```
+
+**In chat mode, try:**
+- "Show me the most popular AIGNE repositories"
+- "Search for repos about AI agents"
+- "What pull requests are open in aigne-framework?"
+- "Find code examples of MCPAgent usage"
+
+## Why Mount MCP as AFS?
+
+**The Problem:** Each MCP server has its own protocol and tools. AI agents need custom code to work with each one.
+
+**The Solution:** Mount all MCP servers as AFS modules:
+
+```typescript
+const afs = new AFS()
+  .mount("/github", await MCPAgent.from({ /* GitHub MCP */ }))
+  .mount("/slack", await MCPAgent.from({ /* Slack MCP */ }))
+  .mount("/notion", await MCPAgent.from({ /* Notion MCP */ }));
+
+// Now the agent uses ONE interface (afs_exec) to access ALL services!
+```
+
+**Benefits:**
+- **Unified Interface**: All MCP servers accessible through `afs_list`, `afs_read`, `afs_exec`
+- **Composability**: Mix MCP servers with file systems, databases, custom modules
+- **Path-Based**: Multiple MCP servers coexist at different paths
+- **No Rewiring**: AI agents work with any mounted MCP server automatically
+
+## Use Any MCP Server
+
+Replace GitHub with **any** MCP server:
+
+```typescript
+// Slack MCP Server
+.mount(await MCPAgent.from({
+  command: "npx",
+  args: ["-y", "@modelcontextprotocol/server-slack"],
+  env: { SLACK_BOT_TOKEN: process.env.SLACK_BOT_TOKEN },
+}))
+
+// File System MCP Server
+.mount(await MCPAgent.from({
+  command: "npx",
+  args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"],
+}))
+
+// Postgres MCP Server
+.mount(await MCPAgent.from({
+  command: "npx",
+  args: ["-y", "@modelcontextprotocol/server-postgres"],
+  env: { POSTGRES_CONNECTION_STRING: process.env.DATABASE_URL },
+}))
+```
+
+## Mix MCP with Other AFS Modules
+
+```typescript
+import { LocalFS } from "@aigne/afs-local-fs";
+import { UserProfileMemory } from "@aigne/afs-user-profile-memory";
+
+const afs = new AFS()
+  .mount(new AFSHistory({ storage: { url: ":memory:" } }))
+  .mount(new LocalFS({ localPath: "./docs" }))
+  .mount(new UserProfileMemory({ context }))
+  .mount(await MCPAgent.from({ /* GitHub MCP */ }))
+  .mount(await MCPAgent.from({ /* Slack MCP */ }));
+
+// Agent now has: history, local files, user profiles, GitHub, Slack!
+```
+
+## Related Examples
+
+- [AFS Memory Example](../afs-memory/README.md) - Conversational memory with user profiles
+- [AFS LocalFS Example](../afs-local-fs/README.md) - File system access with AI agents
+
+## MCP Resources
+
+- [Model Context Protocol Official Site](https://www.anthropic.com/news/model-context-protocol)
+- [GitHub MCP Server](https://github.com/github/mcp-server)
+- [MCP Servers List](https://github.com/modelcontextprotocol/servers)
+
+## TypeScript Support
+
+This package includes full TypeScript type definitions.
+
+## License
+
+[MIT](../../LICENSE.md)

package/index.test.ts

@@ -0,0 +1,11 @@
+import { expect, test } from "bun:test";
+import { runExampleTest } from "@aigne/test-utils/run-example-test.js";
+
+test(
+  "should successfully run the chatbot",
+  async () => {
+    const { status } = await runExampleTest();
+    expect(status).toBe(0);
+  },
+  { timeout: 600000 },
+);

package/index.ts

@@ -0,0 +1,37 @@
+#!/usr/bin/env npx -y bun
+
+import { AFS } from "@aigne/afs";
+import { AFSHistory } from "@aigne/afs-history";
+import { runWithAIGNE } from "@aigne/cli/utils/run-with-aigne.js";
+import { AIAgent, MCPAgent } from "@aigne/core";
+
+const afs = new AFS()
+  .mount(new AFSHistory({ storage: { url: ":memory:" } })) // In-memory history for this example
+  .mount(
+    // Integrate github-mcp-server MCP server as an AFS module, so that AI agents can access github repo via AFS API
+    await MCPAgent.from({
+      command: "docker",
+      args: [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        `GITHUB_PERSONAL_ACCESS_TOKEN=${process.env.GITHUB_PERSONAL_ACCESS_TOKEN}`,
+        "ghcr.io/github/github-mcp-server",
+      ],
+    }),
+  );
+
+const agent = AIAgent.from({
+  instructions:
+    "You are a friendly chatbot that can help users interact with a github repository via github-mcp-server mounted on AFS. Use the provided 'github-mcp-server' module to answer user questions about the repository. If you don't know the answer, just say you don't know. Do not try to make up an answer.",
+  inputKey: "message",
+  afs,
+});
+
+await runWithAIGNE(agent, {
+  chatLoopOptions: {
+    welcome:
+      "Hello! I'm a chatbot that can help you interact with github by github-mcp-server. Ask me anything about the github repository!",
+  },
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@aigne/example-afs-mcp-server",
+  "version": "1.0.0",
+  "description": "A demonstration of using AIGNE Framework with AFS mount a MCP server",
+  "author": "Arcblock <blocklet@arcblock.io> https://github.com/blocklet",
+  "homepage": "https://github.com/AIGNE-io/aigne-framework/tree/main/examples/afs-mcp-server",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AIGNE-io/aigne-framework"
+  },
+  "bin": "index.ts",
+  "files": [
+    ".env.local.example",
+    "*.ts",
+    "README.md"
+  ],
+  "dependencies": {
+    "yargs": "^18.0.0",
+    "@aigne/afs": "^1.2.0-beta",
+    "@aigne/afs-history": "^1.0.0",
+    "@aigne/afs-local-fs": "^1.1.0-beta",
+    "@aigne/cli": "^1.55.0-beta",
+    "@aigne/core": "^1.68.0-beta"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.22",
+    "@aigne/test-utils": "^0.5.60-beta"
+  },
+  "scripts": {
+    "start": "bun run index.ts",
+    "lint": "tsc --noEmit",
+    "test:llm": "bun test index.test.ts"
+  }
+}