Prepare MCP tools for ChatGPT app submission

chatgpt-app-submission.json

@@ -0,0 +1,116 @@
+{
+  "$schema": "https://developers.openai.com/apps-sdk/schemas/chatgpt-app-submission.v1.json",
+  "schema_version": 1,
+  "app_info": {
+    "display_name": "Cloudflare",
+    "subtitle": "Manage Cloudflare resources",
+    "description": "Cloudflare helps users search product documentation, discover API endpoints, and read, create, update, or delete resources across their Cloudflare accounts through ChatGPT.",
+    "category": "DEVELOPER_TOOLS"
+  },
+  "tools": {
+    "docs": {
+      "annotations": {
+        "readOnlyHint": false,
+        "openWorldHint": false,
+        "destructiveHint": false
+      },
+      "justifications": {
+        "read_only_justification": "Records a tool-call usage metric while retrieving documentation results and does not modify user resources.",
+        "open_world_justification": "Returns Cloudflare developer documentation results without publishing content or changing public or third-party systems.",
+        "destructive_justification": "Does not delete, overwrite, revoke, or irreversibly change Cloudflare resources."
+      }
+    },
+    "search": {
+      "annotations": {
+        "readOnlyHint": false,
+        "openWorldHint": false,
+        "destructiveHint": false
+      },
+      "justifications": {
+        "read_only_justification": "Records a tool-call usage metric while evaluating code against an isolated OpenAPI specification and does not modify user resources.",
+        "open_world_justification": "Runs without network access and cannot change public internet state or third-party systems.",
+        "destructive_justification": "Cannot delete, overwrite, revoke, or otherwise change Cloudflare resources."
+      }
+    },
+    "execute": {
+      "annotations": {
+        "readOnlyHint": false,
+        "openWorldHint": true,
+        "destructiveHint": true
+      },
+      "justifications": {
+        "read_only_justification": "Can issue Cloudflare API requests that create, update, or delete resources within the user's granted permissions.",
+        "open_world_justification": "Can deploy or modify internet-facing Cloudflare services and resources through the Cloudflare API.",
+        "destructive_justification": "Can invoke delete, overwrite, revoke, or other irreversible Cloudflare API operations within the user's granted permissions."
+      }
+    }
+  },
+  "test_cases": [
+    {
+      "description": "Search Cloudflare documentation for a product workflow.",
+      "user_prompt": "Explain how Cloudflare D1 point-in-time recovery works and cite the relevant Cloudflare documentation.",
+      "file_attachment_urls": null,
+      "tools_triggered": "docs",
+      "expected_output": "Explains the recovery workflow using relevant Cloudflare documentation results and includes the source URLs.",
+      "expected_output_url": null
+    },
+    {
+      "description": "Discover an API endpoint without calling it.",
+      "user_prompt": "Find the Cloudflare API endpoint and required parameters for listing Workers scripts, but do not make the API call.",
+      "file_attachment_urls": null,
+      "tools_triggered": "search",
+      "expected_output": "Returns the matching endpoint, HTTP method, and required parameters without changing or retrieving account resources.",
+      "expected_output_url": null
+    },
+    {
+      "description": "Read resources from the user's Cloudflare account.",
+      "user_prompt": "List the Workers scripts in my Cloudflare account.",
+      "file_attachment_urls": null,
+      "tools_triggered": "search, execute",
+      "expected_output": "Discovers the appropriate endpoint and returns the Workers scripts available to the authorized account.",
+      "expected_output_url": null
+    },
+    {
+      "description": "Create a Cloudflare resource.",
+      "user_prompt": "Create a KV namespace named chatgpt-submission-test in my Cloudflare account.",
+      "file_attachment_urls": null,
+      "tools_triggered": "search, execute",
+      "expected_output": "Discovers the creation endpoint, creates the namespace in the selected account, and reports its resulting name and identifier.",
+      "expected_output_url": null
+    },
+    {
+      "description": "Exercise confirmation for an irreversible Cloudflare API operation.",
+      "user_prompt": "Delete the KV namespace named chatgpt-submission-test from my Cloudflare account.",
+      "file_attachment_urls": null,
+      "tools_triggered": "search, execute",
+      "expected_output": "Identifies the namespace, requests confirmation before deletion, and reports the Cloudflare API result after confirmation.",
+      "expected_output_url": null
+    }
+  ],
+  "negative_test_cases": [
+    {
+      "description": "Do not trigger for an unrelated weather request.",
+      "user_prompt": "What will the weather be in Chicago tomorrow?",
+      "file_attachment_urls": null,
+      "tools_triggered": null,
+      "expected_output": "The app should not be invoked because weather forecasting is outside its supported workflows.",
+      "expected_output_url": null
+    },
+    {
+      "description": "Do not trigger for generic JavaScript help.",
+      "user_prompt": "Refactor this JavaScript function to use async and await.",
+      "file_attachment_urls": null,
+      "tools_triggered": null,
+      "expected_output": "The app should not be invoked because the request does not involve Cloudflare documentation or Cloudflare account resources.",
+      "expected_output_url": null
+    },
+    {
+      "description": "Do not trigger for another cloud provider.",
+      "user_prompt": "Create an Amazon S3 bucket named quarterly-exports in my AWS account.",
+      "file_attachment_urls": null,
+      "tools_triggered": null,
+      "expected_output": "The app should not be invoked because it cannot manage AWS resources.",
+      "expected_output_url": null
+    }
+  ]
+}

src/tools/docs-search.ts

@@ -89,7 +89,12 @@ export const DOCS_TOOL: Tool = {
     required: ['results'],
     additionalProperties: false
   },
-  annotations: { title: 'Cloudflare Docs Search', readOnlyHint: true }
+  annotations: {
+    title: 'Cloudflare Docs Search',
+    readOnlyHint: false,
+    openWorldHint: false,
+    destructiveHint: false
+  }
 }
 
 export async function runDocsTool(query: string) {
@@ -128,7 +133,9 @@ export function registerDocsTool(server: McpServer) {
       }),
       annotations: {
         title: 'Cloudflare Docs Search',
-        readOnlyHint: true
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false
       }
     },
     ({ query }) => runDocsTool(query)

src/tools/execute.ts

@@ -244,7 +244,7 @@ function executeToolDescription(props?: AuthProps): string {
   const types = cloudflareTypesForAccount(props)
   const accountSelection = accountSelectionDescription(props)
 
-  return `Execute JavaScript code against the Cloudflare API. First use the 'search' tool to find the right endpoints, then write code using the cloudflare.request() function.
+  return `Execute JavaScript code that can read, create, update, or delete resources through the Cloudflare API. First use the 'search' tool to find the right endpoints, then write code using the cloudflare.request() function.
 
 Available in your code:
 ${types}${accountSelection}
@@ -309,7 +309,12 @@ export function registerExecuteTool(server: McpServer, props: AuthProps): void {
         inputSchema: z.object({
           code: z.string().describe('JavaScript async arrow function to execute')
         }),
-        annotations: { title: 'Cloudflare API Code Executor' }
+        annotations: {
+          title: 'Cloudflare API Code Executor',
+          readOnlyHint: false,
+          openWorldHint: true,
+          destructiveHint: true
+        }
       },
       async ({ code }) => {
         try {
@@ -332,7 +337,12 @@ export function registerExecuteTool(server: McpServer, props: AuthProps): void {
         code: z.string().describe('JavaScript async arrow function to execute'),
         account_id: z.string().optional().describe(accountIdParamDescription())
       }),
-      annotations: { title: 'Cloudflare API Code Executor' }
+      annotations: {
+        title: 'Cloudflare API Code Executor',
+        readOnlyHint: false,
+        openWorldHint: true,
+        destructiveHint: true
+      }
     },
     async ({ code, account_id }) => {
       try {

src/tools/search.ts

@@ -113,7 +113,9 @@ export async function registerSearchTool(server: McpServer): Promise<void> {
       }),
       annotations: {
         title: 'Cloudflare API Spec Search',
-        readOnlyHint: true
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false
       }
     },
     async ({ code }) => {

tests/executor.test.ts

@@ -47,7 +47,12 @@ describe('codemode tool titles', () => {
 
     const result = await callTool(API_TOKEN, 'execute', null, { method: 'tools/list' })
     const tool = result.result?.tools?.find((t: { name: string }) => t.name === 'execute')
-    expect(tool?.annotations?.title).toBe('Cloudflare API Code Executor')
+    expect(tool?.annotations).toMatchObject({
+      title: 'Cloudflare API Code Executor',
+      readOnlyHint: false,
+      openWorldHint: true,
+      destructiveHint: true
+    })
     expect(tool?.title).toBe('Cloudflare API Code Executor')
   })
 
@@ -58,8 +63,12 @@ describe('codemode tool titles', () => {
     const result = await callTool(API_TOKEN, 'search', null, { method: 'tools/list' })
     const tool = result.result?.tools?.find((t: { name: string }) => t.name === 'search')
     expect(tool?.title).toBe('Cloudflare API Spec Search')
-    expect(tool?.annotations?.readOnlyHint).toBe(true)
-    expect(tool?.annotations?.title).toBe('Cloudflare API Spec Search')
+    expect(tool?.annotations).toMatchObject({
+      title: 'Cloudflare API Spec Search',
+      readOnlyHint: false,
+      openWorldHint: false,
+      destructiveHint: false
+    })
   })
 })
 

tests/helpers/mcp.ts

@@ -15,7 +15,12 @@ export interface McpToolResult {
     tools?: Array<{
       name: string
       title?: string
-      annotations?: { title?: string; readOnlyHint?: boolean }
+      annotations?: {
+        title?: string
+        readOnlyHint?: boolean
+        openWorldHint?: boolean
+        destructiveHint?: boolean
+      }
     }>
   }
   error?: { code: number; message: string }

tests/non-codemode.test.ts

@@ -65,8 +65,12 @@ describe('precomputed tool contracts', () => {
     const [tool] = await listTools(server)
     expect(tool.name).toBe('docs')
     expect(tool.title).toBe('Cloudflare Docs Search')
-    expect(tool.annotations?.title).toBe('Cloudflare Docs Search')
-    expect(tool.annotations?.readOnlyHint).toBe(true)
+    expect(tool.annotations).toMatchObject({
+      title: 'Cloudflare Docs Search',
+      readOnlyHint: false,
+      openWorldHint: false,
+      destructiveHint: false
+    })
   })
 })