Merge pull request #4 from yepcode/feature/YEP-2942

YEP-2942 Add mcp tools for yepcode storage

Author: marcos-muino-garcia

package-lock.json

@@ -46,11 +46,11 @@
     "dev": "node --loader ts-node/esm src/index.ts",
     "build": "tsc && node -e \"require('fs').chmodSync('dist/index.js', '755')\"",
     "type-check": "tsc --noEmit",
-    "inspector": "npx @modelcontextprotocol/inspector node --env-file=.env dist/index.js"
+    "inspector": "npx @modelcontextprotocol/inspector@0.13.0 node --env-file=.env dist/index.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.1",
-    "@yepcode/run": "^1.7.0",
+    "@modelcontextprotocol/sdk": "^1.17.0",
+    "@yepcode/run": "^1.8.0",
     "dotenv": "^16.4.7",
     "zod": "^3.24.2"
   },

package.json

@@ -31,6 +31,14 @@ import {
 import { z } from "zod";
 import { getVersion, isEmpty } from "./utils.js";
 import Logger from "./logger.js";
+import {
+  DeleteObjectSchema,
+  DownloadObjectSchema,
+  ListObjectsSchema,
+  storageToolDefinitions,
+  storageToolNames,
+  UploadObjectSchema,
+} from "./tools/storage-tool-definitions.js";
 
 const RUN_PROCESS_TOOL_NAME_PREFIX = "run_ycp_";
 const RUN_PROCESS_TOOL_TAG = "mcp-tool";
@@ -197,47 +205,81 @@ class YepCodeMcpServer extends Server {
     };
   }
 
+  private getCodingRules = async (): Promise<string> => {
+    try {
+      let rulesMdFile = await fetch(
+        "https://yepcode.io/docs/yepcode-coding-rules.md"
+      ).then((res) => res.text());
+      rulesMdFile = rulesMdFile.substring(
+        rulesMdFile.indexOf("## General Rules")
+      );
+      rulesMdFile = rulesMdFile.replace(
+        /(\[Section titled “.*”\]\(#.*\)\n)/g,
+        ""
+      );
+
+      return `Here you can find the general rules for YepCode coding:
+
+    ${rulesMdFile}`;
+    } catch (error) {
+      return "";
+    }
+  };
+
   private setupToolHandlers(): void {
     this.setRequestHandler(ListToolsRequestSchema, async () => {
       this.logger.info(`Handling ListTools request`);
-      const envVars = await this.yepCodeEnv.getEnvVars();
-      const tools = this.disableRunCodeTool
-        ? []
-        : [
-            {
-              name: "run_code",
-              description: `Execute LLM-generated code safely in YepCode’s secure, production-grade sandboxes.
-This tool is ideal when your AI agent needs to handle tasks that don’t have a predefined tool available — but could be solved by writing and running a custom script.
-
-It supports external dependencies (NPM or PyPI), so it’s perfect for:
-	•	Complex data transformations
-	•	API calls to services not yet integrated
-	•	Custom logic implementations
-	•	One-off utility scripts
-
-Tip: First try to find a tool that matches your task, but if not available, try generating the code and running it here!`,
-              inputSchema: zodToJsonSchema(
-                buildRunCodeSchema(envVars.map((envVar) => envVar.key))
-              ),
-            },
-            {
-              name: "set_env_var",
-              description:
-                "Set a YepCode environment variable to be available for future code executions",
-              inputSchema: zodToJsonSchema(SetEnvVarSchema),
-            },
-            {
-              name: "remove_env_var",
-              description: "Remove a YepCode environment variable",
-              inputSchema: zodToJsonSchema(RemoveEnvVarSchema),
-            },
-            {
-              name: "get_execution",
-              description:
-                "Get the status, result, logs, timeline, etc. of a YepCode execution",
-              inputSchema: zodToJsonSchema(GetExecutionSchema),
-            },
-          ];
+      const tools = [
+        {
+          name: "set_env_var",
+          title: "Set environment variable",
+          description:
+            "Set a YepCode environment variable to be available for future code executions",
+          inputSchema: zodToJsonSchema(SetEnvVarSchema),
+        },
+        {
+          name: "remove_env_var",
+          title: "Remove environment variable",
+          description: "Remove a YepCode environment variable",
+          inputSchema: zodToJsonSchema(RemoveEnvVarSchema),
+        },
+        {
+          name: "get_execution",
+          title: "Get process execution",
+          description:
+            "Get the status, result, logs, timeline, etc. of a YepCode execution",
+          inputSchema: zodToJsonSchema(GetExecutionSchema),
+        },
+        ...storageToolDefinitions,
+      ];
+
+      if (!this.disableRunCodeTool) {
+        const envVars = await this.yepCodeEnv.getEnvVars();
+        const codingRules = await this.getCodingRules();
+        tools.push({
+          name: "run_code",
+          title:
+            "Execute LLM-generated code in YepCode’s remote and secure sandboxes",
+          description: `This tool is ideal when your AI agent needs to handle tasks that don’t have a predefined tool available — but could be solved by writing and running a custom script.
+
+It supports JavaScript and Python, both with external dependencies (NPM or PyPI), so it’s perfect for:
+* Complex data transformations
+* API calls to services not yet integrated
+* Custom logic implementations
+* One-off utility scripts
+* To use files as input, first upload them to YepCode Storage using the upload storage MCP tools. Then, access them in your code using the \`yepcode.storage\` helper methods to download the files.
+*	To generate and output files, create them in the local execution storage, then upload them to YepCode Storage using the \`yepcode.storage\` helpers. Once uploaded, you can download them using the download storage MCP tool.
+
+Tip: First try to find a tool that matches your task, but if not available, try generating the code and running it here.`,
+          inputSchema: zodToJsonSchema(
+            buildRunCodeSchema(
+              envVars.map((envVar) => envVar.key),
+              codingRules
+            )
+          ),
+        });
+      }
+
       let page = 0;
       let limit = 100;
       while (true) {
@@ -262,6 +304,7 @@ Tip: First try to find a tool that matches your task, but if not available, try
               }
               return {
                 name: toolName,
+                title: process.name,
                 description: `${process.name}${
                   process.description ? ` - ${process.description}` : ""
                 }`,
@@ -405,6 +448,74 @@ Tip: First try to find a tool that matches your task, but if not available, try
               return await this.executionResult(data.executionId);
             }
           );
+
+        case storageToolNames.list:
+          return this.handleToolRequest(
+            ListObjectsSchema,
+            request,
+            async (data) => {
+              const objects = await this.yepCodeApi.getObjects({
+                prefix: data?.prefix || undefined,
+              });
+              return objects;
+            }
+          );
+        case storageToolNames.upload:
+          return this.handleToolRequest(
+            UploadObjectSchema,
+            request,
+            async (data) => {
+              const { filename, content } = data;
+
+              let fileContent: string | Buffer;
+
+              if (typeof content === "string") {
+                fileContent = content;
+              } else if (content.encoding === "base64") {
+                fileContent = Buffer.from(content.data, "base64");
+              } else {
+                throw new Error("Invalid content format");
+              }
+
+              await this.yepCodeApi.createObject({
+                name: filename,
+                file: new Blob([fileContent]),
+              });
+              return { result: `Object ${filename} uploaded successfully` };
+            }
+          );
+        case storageToolNames.download:
+          return this.handleToolRequest(
+            DownloadObjectSchema,
+            request,
+            async (data) => {
+              const { filename } = data;
+              const stream = await this.yepCodeApi.getObject(filename);
+
+              const chunks: Buffer[] = [];
+              for await (const chunk of stream) {
+                chunks.push(Buffer.from(chunk));
+              }
+              const buffer = Buffer.concat(chunks);
+
+              return {
+                content: buffer.toString("base64"),
+                encoding: "base64",
+                filename,
+                size: buffer.length,
+              };
+            }
+          );
+        case storageToolNames.delete:
+          return this.handleToolRequest(
+            DeleteObjectSchema,
+            request,
+            async (data) => {
+              const { filename } = data;
+              await this.yepCodeApi.deleteObject(filename);
+              return { result: `Object ${filename} deleted successfully` };
+            }
+          );
         default:
           this.logger.error(`Unknown tool requested: ${request.params.name}`);
           throw new McpError(

src/server.ts

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+
+export const storageToolNames = {
+  list: "list_files",
+  upload: "upload_file",
+  download: "download_file",
+  delete: "delete_file",
+};
+
+export const ListObjectsSchema = z.object({
+  prefix: z
+    .string()
+    .optional()
+    .describe(
+      "Prefix to filter files by. Filter results to include only files whose names begin with this prefix"
+    ),
+});
+
+export const UploadObjectSchema = z.object({
+  filename: z
+    .string()
+    .describe(
+      "Filename or path where to upload the file (e.g., 'file.txt' or 'folder/file.txt')"
+    ),
+  content: z
+    .union([
+      z.string().describe("File content as plain text (for text files)"),
+      z
+        .object({
+          data: z.string().describe("File content encoded in base64"),
+          encoding: z.literal("base64").describe("Encoding type"),
+        })
+        .describe("Base64 encoded file content (for binary files)"),
+    ])
+    .describe(
+      "File content. Use plain text for text files, or base64 object for binary files"
+    ),
+});
+
+export const DownloadObjectSchema = z.object({
+  filename: z
+    .string()
+    .describe(
+      "Filename or path where to download the file (e.g., 'file.txt' or 'folder/file.txt')"
+    ),
+});
+
+export const DeleteObjectSchema = z.object({
+  filename: z
+    .string()
+    .describe(
+      "Filename or path where to delete the file (e.g., 'file.txt' or 'folder/file.txt')"
+    ),
+});
+
+export const storageToolDefinitions = [
+  {
+    name: storageToolNames.list,
+    description: "List all files in storage",
+    inputSchema: zodToJsonSchema(ListObjectsSchema),
+  },
+  {
+    name: storageToolNames.upload,
+    description: "Upload a file to storage",
+    inputSchema: zodToJsonSchema(UploadObjectSchema),
+  },
+  {
+    name: storageToolNames.download,
+    description: "Download a file from storage",
+    inputSchema: zodToJsonSchema(DownloadObjectSchema),
+  },
+  {
+    name: storageToolNames.delete,
+    description: "Delete a file from storage",
+    inputSchema: zodToJsonSchema(DeleteObjectSchema),
+  },
+];