@autonomys/auto-mcp-servers 1.4.20 → 1.4.22

package/README.md

@@ -16,6 +16,17 @@ The Auto Drive server provides the following tools:
 - `download-object`: Download a text-based object (`text/*` or `application/json`) from the Autonomys network using its CID.
 - `search-objects`: Search for objects on the Autonomys network by name or CID fragment. Returns a JSON object containing an array of results, each including the object's name, CID, type, size, and mimeType (for files).
 
+### Auto Experiences Server
+
+The Auto Experiences server exposes functionality from the `@autonomys/auto-agents` package as MCP tools, specifically for managing agent experiences.
+
+#### Tools
+
+The Auto Experiences server provides the following tools:
+
+- `save-experience`: Saves agent experience data to the Autonomys network, uploads the data to AutoDrive, and updates the last experience CID. Returns the new CID, previous CID (if any), and EVM transaction hash (if available).
+- `retrieve-experience`: Retrieves an agent experience from the Autonomys network using its CID. Returns the full experience object including headers and data.
+
 More servers and tools will be coming soon!
 
 ## Usage
@@ -36,6 +47,21 @@ More servers and tools will be coming soon!
         "ENCRYPTION_PASSWORD": "my-password (optional)",
         "NETWORK": "mainnet or taurus (optional, defaults to mainnet)"
       }
+    },
+    "auto-experiences": {
+      "command": "npx",
+      "args": ["-y", "@autonomys/auto-mcp-servers", "auto-experiences"],
+      "env": {
+        "AUTO_DRIVE_API_KEY": "your-api-key",
+        "AGENT_PATH": "your-agent-path",
+        "AGENT_NAME": "your-agent-name",
+        "PRIVATE_KEY": "your-wallet-private-key",
+        "NETWORK": "mainnet or taurus (optional, defaults to mainnet)",
+        "UPLOAD_ENCRYPTION_PASSWORD": "my-password (optional)",
+        "AGENT_VERSION": "your-agent-version (optional)",
+        "RPC_URL": "your-evm-rpc-url (optional)",
+        "CONTRACT_ADDRESS": "your-contract-address (optional)"
+      }
     }
   }
 }
@@ -47,7 +73,7 @@ More servers and tools will be coming soon!
 
 You can use these MCP servers as tools with agent frameworks such as LangChain.
 
-1. Install the Auto Drive server into your project:
+1. Install the Auto MCP servers into your project:
 
 ```bash
 npm install @autonomys/auto-mcp-servers
@@ -96,6 +122,34 @@ const result = await model
 console.log(result)
 ```
 
+3. Use the Auto Experiences server in a similar way:
+
+```typescript
+// Create Auto Experiences tools
+const createAutoExperiencesTools = async (config: {
+  apiKey: string
+  agentPath: string
+  agentName: string
+  privateKey: string
+}): Promise<StructuredToolInterface[]> => {
+  const transport = new StdioClientTransport({
+    command: process.execPath,
+    args: ['node_modules/.bin/auto-experiences-server'],
+    env: {
+      AUTO_DRIVE_API_KEY: config.apiKey,
+      AGENT_PATH: config.agentPath,
+      AGENT_NAME: config.agentName,
+      PRIVATE_KEY: config.privateKey,
+    },
+  })
+
+  const client = new Client({ name: 'auto-experiences', version: '0.0.1' })
+  client.connect(transport)
+
+  return await loadMcpTools('auto-experiences', client)
+}
+```
+
 ## License
 
 MIT

package/dist/auto-drive/handlers.d.ts

@@ -2,7 +2,7 @@ import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 export declare const createAutoDriveHandlers: (apiKey: string, network: "taurus" | "mainnet", encryptionPassword?: string) => {
     uploadObjectHandler: ({ filename, data, }: {
         filename: string;
-        data: Record<string, any>;
+        data: Record<string, unknown>;
     }) => Promise<CallToolResult>;
     downloadObjectHandler: ({ cid }: {
         cid: string;

package/dist/auto-drive/handlers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/auto-drive/handlers.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAA;AAEnE,eAAO,MAAM,uBAAuB,GAClC,QAAQ,MAAM,EACd,SAAS,QAAQ,GAAG,SAAS,EAC7B,qBAAqB,MAAM;+CAWtB;QACD,QAAQ,EAAE,MAAM,CAAA;QAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAC1B,KAAG,OAAO,CAAC,cAAc,CAAC;qCAIY;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,KAAG,OAAO,CAAC,cAAc,CAAC;sCAsExC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,KAAG,OAAO,CAAC,cAAc,CAAC;CActF,CAAA"}
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/auto-drive/handlers.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAA;AAEnE,eAAO,MAAM,uBAAuB,GAClC,QAAQ,MAAM,EACd,SAAS,QAAQ,GAAG,SAAS,EAC7B,qBAAqB,MAAM;+CAWtB;QACD,QAAQ,EAAE,MAAM,CAAA;QAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAC9B,KAAG,OAAO,CAAC,cAAc,CAAC;qCAIY;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,KAAG,OAAO,CAAC,cAAc,CAAC;sCAuExC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,KAAG,OAAO,CAAC,cAAc,CAAC;CActF,CAAA"}

package/dist/auto-drive/handlers.js

@@ -92,10 +92,11 @@ export const createAutoDriveHandlers = (apiKey, network, encryptionPassword) =>
                     content: [
                         {
                             type: 'text',
-                            text: `Error: File type \'${mimeType}\' is not supported for direct download in this client. Only text/* and application/json are supported.`,
+                            text: `Error: File type '${mimeType}' is not supported for direct download in this client. Only text/* and application/json are supported.`,
                         },
                     ],
                 };
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
             }
             catch (error) {
                 console.error(`Failed to download object with CID ${cid}:`, error);

package/dist/auto-drive/index.js

@@ -25,16 +25,16 @@ autoDriveServer.tool('upload-object', 'Upload an object permanently to the Auton
       The keys are strings that describe the type of data being stored.
       The values are the actual data being stored.
       `),
-}, (_a, _extra_1) => __awaiter(void 0, [_a, _extra_1], void 0, function* ({ filename, data }, _extra) {
+}, (_a) => __awaiter(void 0, [_a], void 0, function* ({ filename, data }) {
     return yield uploadObjectHandler({ filename, data });
 }));
 autoDriveServer.tool('download-object', 'Download a text-based object (text/*, application/json) from the Autonomys Network using Auto Drive using its Content Identifier (CID).', {
     cid: z.string().describe('The Content Identifier (CID) of the object to download.'),
-}, (_a, _extra_1) => __awaiter(void 0, [_a, _extra_1], void 0, function* ({ cid }, _extra) {
+}, (_a) => __awaiter(void 0, [_a], void 0, function* ({ cid }) {
     return yield downloadObjectHandler({ cid });
 }));
 autoDriveServer.tool('search-objects', 'Search for objects on the Autonomys Network using Auto Drive by name or CID.', {
     query: z.string().describe('The name or CID fragment to search for.'),
-}, (_a, _extra_1) => __awaiter(void 0, [_a, _extra_1], void 0, function* ({ query }, _extra) {
+}, (_a) => __awaiter(void 0, [_a], void 0, function* ({ query }) {
     return yield searchObjectsHandler({ query });
 }));

package/dist/auto-experiences/handlers.d.ts

@@ -0,0 +1,20 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { ExperienceManagerOptions } from '@autonomys/auto-agents/dist/experiences/types.js';
+export declare const createExperienceHandlers: (options: ExperienceManagerOptions) => {
+    /**
+     * Saves the provided agent experience data.
+     * Uploads data to AutoDrive and updates the last experience CID.
+     * @param data - The experience data (JSON object).
+     */
+    saveExperienceHandler: ({ data, }: {
+        data: Record<string, unknown> | unknown[] | string;
+    }) => Promise<CallToolResult>;
+    /**
+     * Retrieves an agent experience from AutoDrive using its CID.
+     * @param cid - The CID of the experience to retrieve.
+     */
+    retrieveExperienceHandler: ({ cid }: {
+        cid: string;
+    }) => Promise<CallToolResult>;
+};
+//# sourceMappingURL=handlers.d.ts.map

package/dist/auto-experiences/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/auto-experiences/handlers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAA;AAGnE,OAAO,EAGL,wBAAwB,EAEzB,MAAM,kDAAkD,CAAA;AA6CzD,eAAO,MAAM,wBAAwB,GAAI,SAAS,wBAAwB;IAEtE;;;;OAIG;uCAGA;QACD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,EAAE,GAAG,MAAM,CAAA;KACnD,KAAG,OAAO,CAAC,cAAc,CAAC;IAmB3B;;;OAGG;yCACwC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,KAAG,OAAO,CAAC,cAAc,CAAC;CAsBvF,CAAA"}

package/dist/auto-experiences/handlers.js

@@ -0,0 +1,96 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+// Use ExperienceManager for saving/retrieving full experiences
+import { createExperienceManager } from '@autonomys/auto-agents';
+// Store a singleton instance to ensure we only create one ExperienceManager
+let experienceManagerInstance;
+let experienceManagerPromise;
+/**
+ * Ensures that the ExperienceManager is only created once and properly initialized.
+ * @param options Configuration options for the ExperienceManager
+ * @returns A promise that resolves to the ExperienceManager instance
+ */
+const getExperienceManager = (options) => __awaiter(void 0, void 0, void 0, function* () {
+    // Return existing instance if already created
+    if (experienceManagerInstance) {
+        return experienceManagerInstance;
+    }
+    // Return in-flight promise if initialization is already in progress
+    if (experienceManagerPromise) {
+        return experienceManagerPromise;
+    }
+    // Create a new initialization promise
+    console.error('Creating ExperienceManager instance...');
+    experienceManagerPromise = createExperienceManager(options)
+        .then((manager) => {
+        console.error('ExperienceManager created successfully');
+        experienceManagerInstance = manager;
+        return manager;
+    })
+        .catch((error) => {
+        console.error('Failed to create ExperienceManager:', error);
+        // Clear promise so next call will try again
+        experienceManagerPromise = undefined;
+        throw error;
+    });
+    return experienceManagerPromise;
+});
+export const createExperienceHandlers = (options) => {
+    return {
+        /**
+         * Saves the provided agent experience data.
+         * Uploads data to AutoDrive and updates the last experience CID.
+         * @param data - The experience data (JSON object).
+         */
+        saveExperienceHandler: (_a) => __awaiter(void 0, [_a], void 0, function* ({ data, }) {
+            try {
+                const experienceManager = yield getExperienceManager(options);
+                // saveExperience handles header creation, upload, and saving the latest CID
+                const result = yield experienceManager.saveExperience(data);
+                const responseText = `Experience saved successfully. CID: ${result.cid}${result.previousCid ? `, Previous CID: ${result.previousCid}` : ''}${result.evmHash ? `, EVM Tx: ${result.evmHash}` : ', EVM save skipped/failed.'}`;
+                return { content: [{ type: 'text', text: responseText }] };
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            }
+            catch (error) {
+                console.error('Failed to save experience:', error);
+                return {
+                    isError: true,
+                    content: [{ type: 'text', text: `Error saving experience: ${error.message}` }],
+                };
+            }
+        }),
+        /**
+         * Retrieves an agent experience from AutoDrive using its CID.
+         * @param cid - The CID of the experience to retrieve.
+         */
+        retrieveExperienceHandler: (_a) => __awaiter(void 0, [_a], void 0, function* ({ cid }) {
+            var _b;
+            try {
+                const experienceManager = yield getExperienceManager(options);
+                // retrieveExperience handles download and potential retries
+                const experience = yield experienceManager.retrieveExperience(cid);
+                // Return the full experience object (header + data or V0 structure) as JSON string
+                return { content: [{ type: 'text', text: JSON.stringify(experience, null, 2) }] };
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            }
+            catch (error) {
+                console.error(`Failed to retrieve experience for CID ${cid}:`, error);
+                // Provide more specific error if possible (e.g., Not Found)
+                const errorMessage = ((_b = error.message) === null || _b === void 0 ? void 0 : _b.includes('Not Found'))
+                    ? `Experience not found for CID: ${cid}`
+                    : `Error retrieving experience: ${error.message}`;
+                return {
+                    isError: true,
+                    content: [{ type: 'text', text: errorMessage }],
+                };
+            }
+        }),
+    };
+};

package/dist/auto-experiences/index.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare const autoExperiencesServer: McpServer;
+//# sourceMappingURL=index.d.ts.map

package/dist/auto-experiences/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auto-experiences/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAyEnE,eAAO,MAAM,qBAAqB,WAAgE,CAAA"}

package/dist/auto-experiences/index.js

@@ -0,0 +1,99 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var _a, _b, _c;
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { createExperienceHandlers } from './handlers.js';
+// AutoDrive Config
+const AUTO_DRIVE_API_KEY = (_a = process.env.AUTO_DRIVE_API_KEY) !== null && _a !== void 0 ? _a : (() => {
+    throw new Error('AUTO_DRIVE_API_KEY env var missing');
+})();
+const NETWORK = process.env.NETWORK === 'taurus' ? 'taurus' : 'mainnet';
+const UPLOAD_ENCRYPTION_PASSWORD = process.env.UPLOAD_ENCRYPTION_PASSWORD;
+// Agent Config
+const AGENT_PATH = (_b = process.env.AGENT_PATH) !== null && _b !== void 0 ? _b : (() => {
+    throw new Error('AGENT_PATH env var missing');
+})();
+const AGENT_NAME = (_c = process.env.AGENT_NAME) !== null && _c !== void 0 ? _c : (() => {
+    throw new Error('AGENT_NAME env var missing');
+})();
+const AGENT_VERSION = process.env.AGENT_VERSION; // Optional
+// Wallet / EVM Config
+const RPC_URL = process.env.RPC_URL;
+const PRIVATE_KEY = process.env.PRIVATE_KEY;
+const CONTRACT_ADDRESS = process.env.CONTRACT_ADDRESS;
+// Construct ExperienceManagerOptions
+const experienceManagerOptions = {
+    autoDriveApiOptions: {
+        apiKey: AUTO_DRIVE_API_KEY,
+        network: NETWORK,
+    },
+    agentOptions: Object.assign({ agentPath: AGENT_PATH, agentName: AGENT_NAME }, (AGENT_VERSION && { agentVersion: AGENT_VERSION })),
+    // Wallet options are required by ExperienceManager for signing uploads, even if EVM isn't used for CID storage
+    walletOptions: Object.assign(Object.assign({}, (RPC_URL && CONTRACT_ADDRESS
+        ? {
+            contractInfo: {
+                rpcUrl: RPC_URL,
+                contractAddress: CONTRACT_ADDRESS,
+            },
+        }
+        : {})), { privateKey: PRIVATE_KEY !== null && PRIVATE_KEY !== void 0 ? PRIVATE_KEY : (() => {
+            throw new Error('PRIVATE_KEY env var missing');
+        })() }),
+    // Ensure uploadOptions is always present and includes required fields
+    uploadOptions: Object.assign(Object.assign({}, (UPLOAD_ENCRYPTION_PASSWORD && { password: UPLOAD_ENCRYPTION_PASSWORD })), { compression: true }),
+};
+// Check if EVM details are partially missing for CID storage, Wallet is still needed for signing
+if (!RPC_URL || !CONTRACT_ADDRESS) {
+    console.error('EVM environment variables (RPC_URL, CONTRACT_ADDRESS) not fully set. Experience manager will operate in offline mode with local-only CID storage. Wallet private key IS still required for signing uploads.');
+}
+// Create MCP Server
+export const autoExperiencesServer = new McpServer({ name: 'Auto Experiences', version: '0.1.0' });
+// Initialize handlers - now fully synchronous with internal async management
+console.error('Initializing Auto Experiences Handlers...');
+const { saveExperienceHandler, retrieveExperienceHandler } = createExperienceHandlers(experienceManagerOptions);
+// Register save-experience tool with a simpler, more permissive schema
+autoExperiencesServer.tool('save-experience', 'Saves the provided agent experience data. Uploads to AutoDrive and updates the last experience CID.', {
+    // Using a simpler schema that's more compatible across clients
+    data: z
+        .object({})
+        .passthrough()
+        .optional()
+        .describe('The experience data to save. Can be any JSON object with fields like title, description, etc.'),
+}, (args) => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        console.error('save-experience received args:', JSON.stringify(args));
+        // If data is missing entirely, use empty object
+        const inputData = (args === null || args === void 0 ? void 0 : args.data) || {};
+        console.error('Processed data for save:', JSON.stringify(inputData));
+        return yield saveExperienceHandler({ data: inputData });
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        console.error('Error in save-experience tool:', errorMessage);
+        return {
+            isError: true,
+            content: [{ type: 'text', text: `Error processing save request: ${errorMessage}` }],
+        };
+    }
+}));
+// Register retrieve-experience tool
+autoExperiencesServer.tool('retrieve-experience', 'Retrieves an agent experience from AutoDrive using its CID.', {
+    cid: z.string().describe('The Content Identifier (CID) string of the experience to retrieve.'),
+}, (args) => __awaiter(void 0, void 0, void 0, function* () {
+    if (!args.cid) {
+        return {
+            isError: true,
+            content: [{ type: 'text', text: 'Error: Missing required cid parameter' }],
+        };
+    }
+    return yield retrieveExperienceHandler({ cid: args.cid });
+}));
+console.error('Auto Experiences MCP tools registered.');

package/dist/bin/auto-drive.js

@@ -9,7 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { autoDriveServer } from '../index.js';
+import { autoDriveServer } from '../auto-drive/index.js';
 const main = () => __awaiter(void 0, void 0, void 0, function* () {
     const transport = new StdioServerTransport();
     yield autoDriveServer.connect(transport);

package/dist/bin/auto-experiences.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=auto-experiences.d.ts.map

package/dist/bin/auto-experiences.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-experiences.d.ts","sourceRoot":"","sources":["../../src/bin/auto-experiences.ts"],"names":[],"mappings":""}

package/dist/bin/auto-experiences.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+// Import directly from the root index file
+import { autoExperiencesServer } from '../auto-experiences/index.js';
+// Main function with improved error handling and process management
+const main = () => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        console.error('Starting Auto Experiences MCP server...');
+        // Create transport
+        const transport = new StdioServerTransport();
+        // Connect to transport (this initiates message handling)
+        yield autoExperiencesServer.connect(transport);
+        console.error('Auto Experiences server running and ready to accept requests');
+    }
+    catch (error) {
+        console.error('Failed to start Auto Experiences server:', error);
+        process.exit(1);
+    }
+});
+// Execute main function with global error handling
+main().catch((error) => {
+    console.error('Unhandled error in main():', error);
+    process.exit(1);
+});

package/dist/bin/main.js

@@ -10,40 +10,64 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { autoDriveServer } from '../auto-drive/index.js';
+import { autoExperiencesServer } from '../auto-experiences/index.js';
 const showHelp = () => {
-    console.log(`
+    console.error(`
 Usage: auto-mcp-servers [server-name]
 
 Available servers:
-  auto-drive    Start the Auto Drive MCP server
+  auto-drive       Start the Auto Drive MCP server
+  auto-experiences Start the Auto Experiences MCP server
 
 Environment variables:
   For Auto Drive server:
     AUTO_DRIVE_API_KEY     API key for Auto Drive (required)
     NETWORK                'mainnet' (default) or 'taurus'
     ENCRYPTION_PASSWORD    Password for encryption (optional)
+
+  For Auto Experiences server:
+    AUTO_DRIVE_API_KEY     API key for Auto Drive (required)
+    NETWORK                'mainnet' (default) or 'taurus'
+    UPLOAD_ENCRYPTION_PASSWORD  Password for encryption (optional)
+    AGENT_PATH             Path to agent (required)
+    AGENT_NAME             Name of agent (required)
+    AGENT_VERSION          Version of agent (optional)
+    PRIVATE_KEY            Wallet private key (required)
+    RPC_URL                EVM RPC URL (optional)
+    CONTRACT_ADDRESS       Contract address (optional)
   `);
     process.exit(1);
 };
 const main = () => __awaiter(void 0, void 0, void 0, function* () {
     const serverName = process.argv[2] || 'auto-drive';
     const transport = new StdioServerTransport();
-    switch (serverName) {
-        case 'auto-drive':
-            yield autoDriveServer.connect(transport);
-            break;
-        case 'help':
-        case '--help':
-        case '-h':
-            showHelp();
-            break;
-        default:
-            console.error(`Unknown server: ${serverName}`);
-            showHelp();
-            break;
+    try {
+        switch (serverName) {
+            case 'auto-drive':
+                console.error('Starting Auto Drive MCP server...');
+                yield autoDriveServer.connect(transport);
+                break;
+            case 'auto-experiences':
+                console.error('Starting Auto Experiences MCP server...');
+                yield autoExperiencesServer.connect(transport);
+                break;
+            case 'help':
+            case '--help':
+            case '-h':
+                showHelp();
+                break;
+            default:
+                console.error(`Unknown server: ${serverName}`);
+                showHelp();
+                break;
+        }
+    }
+    catch (error) {
+        console.error(`Failed to start ${serverName} server:`, error);
+        process.exit(1);
     }
 });
 main().catch((error) => {
-    console.error(`Failed to start MCP server:`, error);
+    console.error('Failed to start MCP server:', error);
     process.exit(1);
 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@autonomys/auto-mcp-servers",
   "packageManager": "yarn@4.7.0",
-  "version": "1.4.20",
+  "version": "1.4.22",
   "description": "Autonomys Network MCP servers",
   "repository": {
     "type": "git",
@@ -19,6 +19,7 @@
   "main": "dist/index.js",
   "bin": {
     "auto-drive-server": "./dist/bin/auto-drive.js",
+    "auto-experiences-server": "./dist/bin/auto-experiences.js",
     "auto-mcp-servers": "./dist/bin/main.js"
   },
   "scripts": {
@@ -30,7 +31,8 @@
     "server"
   ],
   "dependencies": {
-    "@autonomys/auto-drive": "^1.4.20",
+    "@autonomys/auto-agents": "^1.4.22",
+    "@autonomys/auto-drive": "^1.4.22",
     "@modelcontextprotocol/sdk": "^1.9.0",
     "zod": "^3.24.2"
   },
@@ -39,5 +41,5 @@
     "ts-node": "^10.9.1",
     "typescript": "^5.8.3"
   },
-  "gitHead": "838c478688bcdf9a757cc9e4a4b2e5ff36b15e64"
+  "gitHead": "ef4c21d683cad697f7015e52becd399a8ca2ed84"
 }

package/src/auto-drive/handlers.ts

@@ -18,7 +18,7 @@ export const createAutoDriveHandlers = (
       data,
     }: {
       filename: string
-      data: Record<string, any>
+      data: Record<string, unknown>
     }): Promise<CallToolResult> => {
       const cid = await autoDriveApi.uploadObjectAsJSON({ data }, filename, uploadOptions)
       return { content: [{ type: 'text', text: `Object uploaded successfully with ${cid}` }] }
@@ -80,10 +80,11 @@ export const createAutoDriveHandlers = (
           content: [
             {
               type: 'text',
-              text: `Error: File type \'${mimeType}\' is not supported for direct download in this client. Only text/* and application/json are supported.`,
+              text: `Error: File type '${mimeType}' is not supported for direct download in this client. Only text/* and application/json are supported.`,
             },
           ],
         }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
       } catch (error: any) {
         console.error(`Failed to download object with CID ${cid}:`, error)
         const errorMessage = error.message || 'Unknown error occurred during download.'

package/src/auto-drive/index.ts

@@ -28,8 +28,8 @@ autoDriveServer.tool(
       The values are the actual data being stored.
       `,
     ),
-  } as any,
-  async ({ filename, data }, _extra): Promise<CallToolResult> => {
+  },
+  async ({ filename, data }): Promise<CallToolResult> => {
     return await uploadObjectHandler({ filename, data })
   },
 )
@@ -39,8 +39,8 @@ autoDriveServer.tool(
   'Download a text-based object (text/*, application/json) from the Autonomys Network using Auto Drive using its Content Identifier (CID).',
   {
     cid: z.string().describe('The Content Identifier (CID) of the object to download.'),
-  } as any,
-  async ({ cid }, _extra): Promise<CallToolResult> => {
+  },
+  async ({ cid }): Promise<CallToolResult> => {
     return await downloadObjectHandler({ cid })
   },
 )
@@ -50,8 +50,8 @@ autoDriveServer.tool(
   'Search for objects on the Autonomys Network using Auto Drive by name or CID.',
   {
     query: z.string().describe('The name or CID fragment to search for.'),
-  } as any,
-  async ({ query }, _extra): Promise<CallToolResult> => {
+  },
+  async ({ query }): Promise<CallToolResult> => {
     return await searchObjectsHandler({ query })
   },
 )

package/src/auto-experiences/handlers.ts

@@ -0,0 +1,110 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
+// Use ExperienceManager for saving/retrieving full experiences
+import { createExperienceManager } from '@autonomys/auto-agents'
+import {
+  AgentExperience,
+  AgentExperienceV0,
+  ExperienceManagerOptions,
+  ExperienceSaveResult,
+} from '@autonomys/auto-agents/dist/experiences/types.js'
+
+// Define a type for the ExperienceManager to help with typing
+type ExperienceManager = Awaited<ReturnType<typeof createExperienceManager>>
+
+// Store a singleton instance to ensure we only create one ExperienceManager
+let experienceManagerInstance: ExperienceManager | undefined
+let experienceManagerPromise: Promise<ExperienceManager> | undefined
+
+/**
+ * Ensures that the ExperienceManager is only created once and properly initialized.
+ * @param options Configuration options for the ExperienceManager
+ * @returns A promise that resolves to the ExperienceManager instance
+ */
+const getExperienceManager = async (
+  options: ExperienceManagerOptions,
+): Promise<ExperienceManager> => {
+  // Return existing instance if already created
+  if (experienceManagerInstance) {
+    return experienceManagerInstance
+  }
+
+  // Return in-flight promise if initialization is already in progress
+  if (experienceManagerPromise) {
+    return experienceManagerPromise
+  }
+
+  // Create a new initialization promise
+  console.error('Creating ExperienceManager instance...')
+  experienceManagerPromise = createExperienceManager(options)
+    .then((manager) => {
+      console.error('ExperienceManager created successfully')
+      experienceManagerInstance = manager
+      return manager
+    })
+    .catch((error) => {
+      console.error('Failed to create ExperienceManager:', error)
+      // Clear promise so next call will try again
+      experienceManagerPromise = undefined
+      throw error
+    })
+
+  return experienceManagerPromise
+}
+
+export const createExperienceHandlers = (options: ExperienceManagerOptions) => {
+  return {
+    /**
+     * Saves the provided agent experience data.
+     * Uploads data to AutoDrive and updates the last experience CID.
+     * @param data - The experience data (JSON object).
+     */
+    saveExperienceHandler: async ({
+      data,
+    }: {
+      data: Record<string, unknown> | unknown[] | string // Allow object or array data
+    }): Promise<CallToolResult> => {
+      try {
+        const experienceManager = await getExperienceManager(options)
+        // saveExperience handles header creation, upload, and saving the latest CID
+        const result: ExperienceSaveResult = await experienceManager.saveExperience(data)
+        const responseText = `Experience saved successfully. CID: ${result.cid}${
+          result.previousCid ? `, Previous CID: ${result.previousCid}` : ''
+        }${result.evmHash ? `, EVM Tx: ${result.evmHash}` : ', EVM save skipped/failed.'}`
+        return { content: [{ type: 'text', text: responseText }] }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } catch (error: any) {
+        console.error('Failed to save experience:', error)
+        return {
+          isError: true,
+          content: [{ type: 'text', text: `Error saving experience: ${error.message}` }],
+        }
+      }
+    },
+
+    /**
+     * Retrieves an agent experience from AutoDrive using its CID.
+     * @param cid - The CID of the experience to retrieve.
+     */
+    retrieveExperienceHandler: async ({ cid }: { cid: string }): Promise<CallToolResult> => {
+      try {
+        const experienceManager = await getExperienceManager(options)
+        // retrieveExperience handles download and potential retries
+        const experience: AgentExperience | AgentExperienceV0 =
+          await experienceManager.retrieveExperience(cid)
+        // Return the full experience object (header + data or V0 structure) as JSON string
+        return { content: [{ type: 'text', text: JSON.stringify(experience, null, 2) }] }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } catch (error: any) {
+        console.error(`Failed to retrieve experience for CID ${cid}:`, error)
+        // Provide more specific error if possible (e.g., Not Found)
+        const errorMessage = error.message?.includes('Not Found')
+          ? `Experience not found for CID: ${cid}`
+          : `Error retrieving experience: ${error.message}`
+        return {
+          isError: true,
+          content: [{ type: 'text', text: errorMessage }],
+        }
+      }
+    },
+  }
+}

package/src/auto-experiences/index.ts

@@ -0,0 +1,136 @@
+import { ExperienceManagerOptions } from '@autonomys/auto-agents'
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { z } from 'zod'
+import { createExperienceHandlers } from './handlers.js'
+
+// AutoDrive Config
+const AUTO_DRIVE_API_KEY =
+  process.env.AUTO_DRIVE_API_KEY ??
+  (() => {
+    throw new Error('AUTO_DRIVE_API_KEY env var missing')
+  })()
+const NETWORK = process.env.NETWORK === 'taurus' ? 'taurus' : 'mainnet'
+const UPLOAD_ENCRYPTION_PASSWORD = process.env.UPLOAD_ENCRYPTION_PASSWORD
+
+// Agent Config
+const AGENT_PATH =
+  process.env.AGENT_PATH ??
+  (() => {
+    throw new Error('AGENT_PATH env var missing')
+  })()
+const AGENT_NAME =
+  process.env.AGENT_NAME ??
+  (() => {
+    throw new Error('AGENT_NAME env var missing')
+  })()
+const AGENT_VERSION = process.env.AGENT_VERSION // Optional
+
+// Wallet / EVM Config
+const RPC_URL = process.env.RPC_URL
+const PRIVATE_KEY = process.env.PRIVATE_KEY
+const CONTRACT_ADDRESS = process.env.CONTRACT_ADDRESS
+
+// Construct ExperienceManagerOptions
+const experienceManagerOptions: ExperienceManagerOptions = {
+  autoDriveApiOptions: {
+    apiKey: AUTO_DRIVE_API_KEY,
+    network: NETWORK,
+  },
+  agentOptions: {
+    agentPath: AGENT_PATH,
+    agentName: AGENT_NAME,
+    ...(AGENT_VERSION && { agentVersion: AGENT_VERSION }),
+  },
+  // Wallet options are required by ExperienceManager for signing uploads, even if EVM isn't used for CID storage
+  walletOptions: {
+    ...(RPC_URL && CONTRACT_ADDRESS
+      ? {
+          contractInfo: {
+            rpcUrl: RPC_URL,
+            contractAddress: CONTRACT_ADDRESS,
+          },
+        }
+      : {}),
+    privateKey:
+      PRIVATE_KEY ??
+      (() => {
+        throw new Error('PRIVATE_KEY env var missing')
+      })(),
+  },
+  // Ensure uploadOptions is always present and includes required fields
+  uploadOptions: {
+    ...(UPLOAD_ENCRYPTION_PASSWORD && { password: UPLOAD_ENCRYPTION_PASSWORD }),
+    compression: true,
+  },
+}
+
+// Check if EVM details are partially missing for CID storage, Wallet is still needed for signing
+if (!RPC_URL || !CONTRACT_ADDRESS) {
+  console.error(
+    'EVM environment variables (RPC_URL, CONTRACT_ADDRESS) not fully set. Experience manager will operate in offline mode with local-only CID storage. Wallet private key IS still required for signing uploads.',
+  )
+}
+
+// Create MCP Server
+export const autoExperiencesServer = new McpServer({ name: 'Auto Experiences', version: '0.1.0' })
+
+// Initialize handlers - now fully synchronous with internal async management
+console.error('Initializing Auto Experiences Handlers...')
+const { saveExperienceHandler, retrieveExperienceHandler } =
+  createExperienceHandlers(experienceManagerOptions)
+
+// Register save-experience tool with a simpler, more permissive schema
+autoExperiencesServer.tool(
+  'save-experience',
+  'Saves the provided agent experience data. Uploads to AutoDrive and updates the last experience CID.',
+  {
+    // Using a simpler schema that's more compatible across clients
+    data: z
+      .object({})
+      .passthrough()
+      .optional()
+      .describe(
+        'The experience data to save. Can be any JSON object with fields like title, description, etc.',
+      ),
+  },
+  async (args) => {
+    try {
+      console.error('save-experience received args:', JSON.stringify(args))
+
+      // If data is missing entirely, use empty object
+      const inputData = args?.data || {}
+
+      console.error('Processed data for save:', JSON.stringify(inputData))
+
+      return await saveExperienceHandler({ data: inputData })
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error)
+      console.error('Error in save-experience tool:', errorMessage)
+      return {
+        isError: true,
+        content: [{ type: 'text', text: `Error processing save request: ${errorMessage}` }],
+      }
+    }
+  },
+)
+
+// Register retrieve-experience tool
+autoExperiencesServer.tool(
+  'retrieve-experience',
+  'Retrieves an agent experience from AutoDrive using its CID.',
+  {
+    cid: z.string().describe('The Content Identifier (CID) string of the experience to retrieve.'),
+  },
+  async (args: { cid?: string }) => {
+    if (!args.cid) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: 'Error: Missing required cid parameter' }],
+      }
+    }
+
+    return await retrieveExperienceHandler({ cid: args.cid })
+  },
+)
+
+console.error('Auto Experiences MCP tools registered.')

package/src/bin/auto-drive.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
-import { autoDriveServer } from '../index.js'
+import { autoDriveServer } from '../auto-drive/index.js'
 
 const main = async () => {
   const transport = new StdioServerTransport()

package/src/bin/auto-experiences.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+// Import directly from the root index file
+import { autoExperiencesServer } from '../auto-experiences/index.js'
+
+// Main function with improved error handling and process management
+const main = async () => {
+  try {
+    console.error('Starting Auto Experiences MCP server...')
+
+    // Create transport
+    const transport = new StdioServerTransport()
+
+    // Connect to transport (this initiates message handling)
+    await autoExperiencesServer.connect(transport)
+    console.error('Auto Experiences server running and ready to accept requests')
+  } catch (error) {
+    console.error('Failed to start Auto Experiences server:', error)
+    process.exit(1)
+  }
+}
+
+// Execute main function with global error handling
+main().catch((error) => {
+  console.error('Unhandled error in main():', error)
+  process.exit(1)
+})

package/src/bin/main.ts

@@ -2,19 +2,32 @@
 
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { autoDriveServer } from '../auto-drive/index.js'
+import { autoExperiencesServer } from '../auto-experiences/index.js'
 
 const showHelp = () => {
-  console.log(`
+  console.error(`
 Usage: auto-mcp-servers [server-name]
 
 Available servers:
-  auto-drive    Start the Auto Drive MCP server
+  auto-drive       Start the Auto Drive MCP server
+  auto-experiences Start the Auto Experiences MCP server
 
 Environment variables:
   For Auto Drive server:
     AUTO_DRIVE_API_KEY     API key for Auto Drive (required)
     NETWORK                'mainnet' (default) or 'taurus'
     ENCRYPTION_PASSWORD    Password for encryption (optional)
+
+  For Auto Experiences server:
+    AUTO_DRIVE_API_KEY     API key for Auto Drive (required)
+    NETWORK                'mainnet' (default) or 'taurus'
+    UPLOAD_ENCRYPTION_PASSWORD  Password for encryption (optional)
+    AGENT_PATH             Path to agent (required)
+    AGENT_NAME             Name of agent (required)
+    AGENT_VERSION          Version of agent (optional)
+    PRIVATE_KEY            Wallet private key (required)
+    RPC_URL                EVM RPC URL (optional)
+    CONTRACT_ADDRESS       Contract address (optional)
   `)
   process.exit(1)
 }
@@ -23,23 +36,33 @@ const main = async () => {
   const serverName = process.argv[2] || 'auto-drive'
   const transport = new StdioServerTransport()
 
-  switch (serverName) {
-    case 'auto-drive':
-      await autoDriveServer.connect(transport)
-      break
-    case 'help':
-    case '--help':
-    case '-h':
-      showHelp()
-      break
-    default:
-      console.error(`Unknown server: ${serverName}`)
-      showHelp()
-      break
+  try {
+    switch (serverName) {
+      case 'auto-drive':
+        console.error('Starting Auto Drive MCP server...')
+        await autoDriveServer.connect(transport)
+        break
+      case 'auto-experiences':
+        console.error('Starting Auto Experiences MCP server...')
+        await autoExperiencesServer.connect(transport)
+        break
+      case 'help':
+      case '--help':
+      case '-h':
+        showHelp()
+        break
+      default:
+        console.error(`Unknown server: ${serverName}`)
+        showHelp()
+        break
+    }
+  } catch (error) {
+    console.error(`Failed to start ${serverName} server:`, error)
+    process.exit(1)
   }
 }
 
 main().catch((error) => {
-  console.error(`Failed to start MCP server:`, error)
+  console.error('Failed to start MCP server:', error)
   process.exit(1)
 })

package/src/index.ts

@@ -1,2 +0,0 @@
-// Export servers
-export { autoDriveServer } from './auto-drive/index.js'