From 1bc309fc5a9649851b9a1395c471682e25bb6d9e Mon Sep 17 00:00:00 2001
From: Dominik Jain <dominik.jain@outlook.com>
Date: Thu, 2 Oct 2025 17:12:53 +0200
Subject: [PATCH] Provide list of all API types in initial instructions

---
 mcp-server/data/prompts.yml               |  2 ++
 mcp-server/src/ApiDocs.ts                 |  2 +-
 mcp-server/src/PenpotMcpServer.ts         | 12 ++++++++----
 mcp-server/src/tools/PenpotApiInfoTool.ts |  9 ++++++---
 4 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/mcp-server/data/prompts.yml b/mcp-server/data/prompts.yml
index 6a33c3b..6085909 100644
--- a/mcp-server/data/prompts.yml
+++ b/mcp-server/data/prompts.yml
@@ -22,6 +22,8 @@ initial_instructions: |
   directly in the connected project.
   To execute code correctly, you need to understand the Penpot Plugin API. You can retrieve API documentation via 
   the `penpot_api_info` tool.
+  
+  This is the full list of types/interfaces in the Penpot API: $api_types
 
   When writing code, a key object is the `penpot` object (which is of type `Penpot`):
     * `penpot.selection` provides the list of shapes the user has selected in the Penpot UI.
diff --git a/mcp-server/src/ApiDocs.ts b/mcp-server/src/ApiDocs.ts
index ab8f551..c6374ea 100644
--- a/mcp-server/src/ApiDocs.ts
+++ b/mcp-server/src/ApiDocs.ts
@@ -116,7 +116,7 @@ export class ApiDocs {
      * Returns all available type names.
      */
     getTypeNames(): string[] {
-        return Array.from(this.apiTypes.keys());
+        return Array.from(this.apiTypes.values()).map((type) => type.getName());
     }
 
     /**
diff --git a/mcp-server/src/PenpotMcpServer.ts b/mcp-server/src/PenpotMcpServer.ts
index 7425a87..f941e77 100644
--- a/mcp-server/src/PenpotMcpServer.ts
+++ b/mcp-server/src/PenpotMcpServer.ts
@@ -13,6 +13,7 @@ import { HighLevelOverviewTool } from "./tools/HighLevelOverviewTool";
 import { PenpotApiInfoTool } from "./tools/PenpotApiInfoTool";
 import { ExportShapeTool } from "./tools/ExportShapeTool";
 import { ReplServer } from "./ReplServer";
+import { ApiDocs } from "./ApiDocs";
 
 export class PenpotMcpServer {
     private readonly logger = createLogger("PenpotMcpServer");
@@ -22,6 +23,7 @@ export class PenpotMcpServer {
     private app: any;
     public readonly pluginBridge: PluginBridge;
     private readonly replServer: ReplServer;
+    private apiDocs: ApiDocs;
 
     private readonly transports = {
         streamable: {} as Record<string, StreamableHTTPServerTransport>,
@@ -34,15 +36,15 @@ export class PenpotMcpServer {
         replPort: number = 4403
     ) {
         this.configLoader = new ConfigurationLoader();
+        this.apiDocs = new ApiDocs();
 
-        const instructions = this.configLoader.getInitialInstructions();
         this.server = new McpServer(
             {
                 name: "penpot-mcp-server",
                 version: "1.0.0",
             },
             {
-                instructions: instructions,
+                instructions: this.getInitialInstructions(),
             }
         );
 
@@ -54,7 +56,9 @@ export class PenpotMcpServer {
     }
 
     public getInitialInstructions(): string {
-        return this.configLoader.getInitialInstructions();
+        let instructions = this.configLoader.getInitialInstructions();
+        instructions = instructions.replace("$api_types", this.apiDocs.getTypeNames().join(", "));
+        return instructions;
     }
 
     private registerTools(): void {
@@ -63,7 +67,7 @@ export class PenpotMcpServer {
             new PrintTextTool(this),
             new ExecuteCodeTool(this),
             new HighLevelOverviewTool(this),
-            new PenpotApiInfoTool(this),
+            new PenpotApiInfoTool(this, this.apiDocs),
             new ExportShapeTool(this),
         ];
 
diff --git a/mcp-server/src/tools/PenpotApiInfoTool.ts b/mcp-server/src/tools/PenpotApiInfoTool.ts
index 38d99b0..a8f1dba 100644
--- a/mcp-server/src/tools/PenpotApiInfoTool.ts
+++ b/mcp-server/src/tools/PenpotApiInfoTool.ts
@@ -41,9 +41,9 @@ export class PenpotApiInfoTool extends Tool<PenpotApiInfoArgs> {
      *
      * @param mcpServer - The MCP server instance
      */
-    constructor(mcpServer: PenpotMcpServer) {
+    constructor(mcpServer: PenpotMcpServer, apiDocs: ApiDocs) {
         super(mcpServer, PenpotApiInfoArgs.schema);
-        this.apiDocs = new ApiDocs();
+        this.apiDocs = apiDocs;
     }
 
     public getToolName(): string {
@@ -51,7 +51,10 @@ export class PenpotApiInfoTool extends Tool<PenpotApiInfoArgs> {
     }
 
     public getToolDescription(): string {
-        return "Retrieves Penpot API documentation for types and their members";
+        return (
+            "Retrieves Penpot API documentation for types and their members." +
+            "Be sure to read the 'Penpot High-Level Overview' first."
+        );
     }
 
     protected async executeCore(args: PenpotApiInfoArgs): Promise<ToolResponse> {