address review comments

Co-authored-by: Saikrishna321 <[email protected]>

Author: SrinivasanTarget

docs/CONTRIBUTING.md

@@ -6,8 +6,8 @@ Welcome! This guide will help you extend MCP Appium by adding new tools and reso
 
 - [Adding New Tools](#adding-new-tools)
 - [Adding New Resources](#adding-new-resources)
-- [Tool Metadata with YAML](#tool-metadata-with-yaml)
 - [Code Style Guidelines](#code-style-guidelines)
+- [Formatting Best Practices](#formatting-best-practices)
 
 ---
 
@@ -250,107 +250,13 @@ export default function registerResources(server: any) {
 
 ---
 
-## Tool Metadata with YAML
-
-For better maintainability, tool metadata can be defined in YAML files.
-
-### YAML File Structure
-
-Create a YAML file for your tool metadata:
-
-```yaml
-# src/tools/metadata/my-tool.yaml
-name: appium_my_tool
-description: |
-  This is a detailed description of what the tool does.
-  It can span multiple lines.
-
-parameters:
-  param1:
-    type: string
-    description: Description of the first parameter
-    required: true
-  param2:
-    type: number
-    description: Description of the second parameter
-    required: false
-
-annotations:
-  readOnly: false
-  openWorld: false
-
-# Instructions for prompt-based tools (optional)
-instructions: |
-  ## Instructions for AI
-  - Point 1
-  - Point 2
-```
-
-### Using YAML Metadata
-
-```typescript
-// src/tools/my-tool.ts
-import { loadToolMetadata } from './metadata-loader.js';
-import yaml from 'js-yaml';
-import fs from 'fs';
-import { z } from 'zod';
-
-export default function myTool(server: FastMCP): void {
-  // Load YAML metadata
-  const yamlPath = './src/tools/metadata/my-tool.yaml';
-  const metadata = yaml.load(fs.readFileSync(yamlPath, 'utf8'));
-
-  // Convert YAML schema to Zod schema
-  const parameters = buildZodSchema(metadata.parameters);
-
-  server.addTool({
-    name: metadata.name,
-    description: metadata.description,
-    parameters,
-    annotations: {
-      readOnlyHint: metadata.annotations.readOnly,
-      openWorldHint: metadata.annotations.openWorld,
-    },
-    execute: async (args: any, context: any): Promise<any> => {
-      // Tool implementation
-      // You can access metadata.instructions if needed
-    },
-  });
-}
-```
-
-### Benefits of YAML
-
-1. **Maintainability**: Metadata separated from implementation
-2. **Clarity**: Easier to read and understand tool definitions
-3. **Version Control**: Track metadata changes independently
-4. **Internationalization**: Easier to translate descriptions
-5. **Documentation**: Auto-generate docs from YAML
-
-### When to Use YAML
-
-**Use YAML when:**
-
-- Tool has complex instructions or descriptions
-- Multiple tools share similar metadata
-- You want to version metadata separately
-- You need to generate documentation automatically
-
-**Use inline metadata when:**
-
-- Tool is simple and straightforward
-- Metadata is tightly coupled with implementation
-- You prefer keeping everything in one place
-
----
 
 ## Code Style Guidelines
 
 ### 1. File Naming
 
 - Tools: `kebab-case.ts` (e.g., `boot-simulator.ts`)
 - Resources: `kebab-case.ts` (e.g., `java-template.ts`)
-- YAML files: `tool-name.yaml`
 
 ### 2. Function Exports
 
@@ -438,6 +344,45 @@ After adding a new tool:
 
 ---
 
+---
+
+## Formatting Best Practices
+
+### Long Descriptions
+
+For better readability when descriptions are long, use template literals with proper indentation:
+
+**Bad (hard to read):**
+```typescript
+description: 'REQUIRED: First ASK THE USER which mobile platform they want to use (Android or iOS) before creating a session. DO NOT assume or default to any platform. You MUST explicitly prompt the user to choose between Android or iOS. This is mandatory before proceeding to use the create_session tool.',
+```
+
+**Good (readable):**
+```typescript
+description: `REQUIRED: First ASK THE USER which mobile platform they want to use (Android or iOS) before creating a session.
+  DO NOT assume or default to any platform.
+  You MUST explicitly prompt the user to choose between Android or iOS.
+  This is mandatory before proceeding to use the create_session tool.
+  `,
+```
+
+### Parameter Descriptions
+
+For long parameter descriptions, also use template literals:
+
+```typescript
+parameters: z.object({
+  platform: z
+    .enum(['ios', 'android'])
+    .describe(
+      `REQUIRED: Must match the platform the user explicitly selected via the select_platform tool.
+      DO NOT default to Android or iOS without asking the user first.`
+    ),
+})
+```
+
+---
+
 ## Need Help?
 
 - Check existing tools in `src/tools/`

package.json

@@ -8,7 +8,7 @@
   },
   "scripts": {
     "build": "rimraf dist && tsc && chmod +x dist/index.js && npm run copy-docs",
-    "copy-docs": "mkdir -p dist/tools/documentation/uploads && cp -f src/tools/documentation/uploads/documents.json dist/tools/documentation/uploads/documents.json 2>/dev/null || echo 'No documents.json found, run npm run index-docs first'",
+    "copy-docs": "mkdir -p dist/tools/documentation/uploads && cp -f src/tools/documentation/uploads/documents.json dist/tools/documentation/uploads/documents.json 2>/dev/null || true",
     "start": "node src/index.js",
     "start:stdio": "node src/index.js",
     "start:sse": "node src/index.js --sse",
@@ -43,7 +43,6 @@
     "appium-xcuitest-driver": "^10.2.1",
     "fast-xml-parser": "^5.2.3",
     "fastmcp": "^1.23.2",
-    "js-yaml": "^4.1.0",
     "langchain": "^0.3.27",
     "lodash": "^4.17.21",
     "node-simctl": "^8.0.4",
@@ -61,7 +60,6 @@
     "conventional-changelog-conventionalcommits": "^8.0.0",
     "@jest/globals": "^29.7.0",
     "@types/jest": "^29.5.12",
-    "@types/js-yaml": "^4.0.9",
     "@types/lodash": "^4.17.17",
     "@types/node": "^22.15.18",
     "@typescript-eslint/eslint-plugin": "^8.34.0",

src/scripts/simple-index-documentation.ts

@@ -47,9 +47,7 @@ if (args.length > 0 && args[0]) {
   }
 } else {
   // Use default path to resources directory
-  const __filename = fileURLToPath(import.meta.url);
-  const __dirname = path.dirname(__filename);
-  markdownPath = path.resolve(__dirname, '../resources');
+  markdownPath = path.resolve(process.cwd(), 'src/resources');
   console.log(`Using default resources directory: ${markdownPath}`);
 }
 

src/tools/README.md

@@ -107,15 +107,6 @@ export default function registerTools(server: FastMCP): void {
 }
 ```
 
-## Using YAML Metadata (Optional)
-
-For better maintainability, you can store tool metadata in YAML files:
-
-1. Create `src/tools/metadata/my-tool.yaml`
-2. Use `loadToolMetadata()` to load metadata
-3. See `metadata/README.md` for YAML schema
-4. Example: `scroll-with-yaml.example.ts`
-
 ## Best Practices
 
 1. **Always check for active session**: Use `getDriver()` and check for null

src/tools/answerAppium.ts

@@ -10,7 +10,9 @@ import {
 export default function answerAppium(server: any): void {
   server.addTool({
     name: 'appium_documentation_query',
-    description: `Query Appium documentation using RAG (Retrieval-Augmented Generation). This tool searches through indexed Appium documentation to answer questions about Appium features, setup, configuration, drivers, and usage.`,
+    description: `Query Appium documentation using RAG (Retrieval-Augmented Generation).
+      This tool searches through indexed Appium documentation to answer questions about Appium features, setup, configuration, drivers, and usage.
+      `,
     parameters: z.object({
       query: z
         .string()

src/tools/boot-simulator.ts

@@ -8,14 +8,13 @@ import { IOSManager } from '../devicemanager/ios-manager.js';
 export default function bootSimulator(server: any): void {
   server.addTool({
     name: 'boot_simulator',
-    description:
-      'Boot an iOS simulator and wait for it to be ready. This speeds up subsequent session creation by ensuring the simulator is already running.',
+    description: `Boot an iOS simulator and wait for it to be ready.
+      This speeds up subsequent session creation by ensuring the simulator is already running.`,
     parameters: z.object({
-      udid: z
-        .string()
-        .describe(
-          'The UDID of the iOS simulator to boot. Use select_platform and select_device tools first to get the UDID.'
-        ),
+      udid: z.string().describe(
+        `The UDID of the iOS simulator to boot.
+          Use select_platform and select_device tools first to get the UDID.`
+      ),
     }),
     annotations: {
       readOnlyHint: false,

src/tools/create-session.ts

@@ -36,13 +36,16 @@ interface CapabilitiesConfig {
 export default function createSession(server: any): void {
   server.addTool({
     name: 'create_session',
-    description:
-      'Create a new mobile session with Android or iOS device (MUST use select_platform tool first to ask the user which platform they want - DO NOT assume or default to any platform)',
+    description: `Create a new mobile session with Android or iOS device.
+      MUST use select_platform tool first to ask the user which platform they want.
+      DO NOT assume or default to any platform.
+      `,
     parameters: z.object({
       platform: z
         .enum(['ios', 'android'])
         .describe(
-          'REQUIRED: Must match the platform the user explicitly selected via the select_platform tool. DO NOT default to Android or iOS without asking the user first.'
+          `REQUIRED: Must match the platform the user explicitly selected via the select_platform tool.
+          DO NOT default to Android or iOS without asking the user first.`
         ),
       capabilities: z
         .object({})

src/tools/install-wda.ts

@@ -158,8 +158,9 @@ async function isWDARunning(simulatorUdid: string): Promise<boolean> {
 export default function installWDA(server: any): void {
   server.addTool({
     name: 'install_wda',
-    description:
-      'Install and launch the WebDriverAgent (WDA) app on a booted iOS simulator using the app path from setup_wda. This tool requires WDA to be already set up using setup_wda and at least one simulator to be booted.',
+    description: `Install and launch the WebDriverAgent (WDA) app on a booted iOS simulator using the app path from setup_wda.
+      This tool requires WDA to be already set up using setup_wda and at least one simulator to be booted.
+      `,
     parameters: z.object({
       simulatorUdid: z
         .string()
@@ -171,7 +172,8 @@ export default function installWDA(server: any): void {
         .string()
         .optional()
         .describe(
-          'The path to the WDA app bundle (.app file) that be generated by setup_wda tool. If not provided, will try to find the latest cached WDA app.'
+          `The path to the WDA app bundle (.app file) that be generated by setup_wda tool.
+          If not provided, will try to find the latest cached WDA app.`
         ),
     }),
     annotations: {

src/tools/interactions/screenshot.ts

@@ -1,11 +1,14 @@
 import { FastMCP } from 'fastmcp/dist/FastMCP.js';
 import { z } from 'zod';
 import { getDriver } from '../sessionStore.js';
+import { writeFile } from 'fs/promises';
+import { join } from 'path';
 
 export default function screenshot(server: FastMCP): void {
   server.addTool({
     name: 'appium_screenshot',
-    description: 'Take a screenshot of the current screen in base64 format',
+    description:
+      'Take a screenshot of the current screen and return as PNG image',
     annotations: {
       readOnlyHint: false,
       openWorldHint: false,
@@ -17,12 +20,24 @@ export default function screenshot(server: FastMCP): void {
       }
 
       try {
-        const screenshot = await driver.getScreenshot();
+        const screenshotBase64 = await driver.getScreenshot();
+
+        // Convert base64 to buffer
+        const screenshotBuffer = Buffer.from(screenshotBase64, 'base64');
+
+        // Generate filename with timestamp
+        const timestamp = Date.now();
+        const filename = `screenshot_${timestamp}.png`;
+        const filepath = join(process.cwd(), filename);
+
+        // Save screenshot to disk
+        await writeFile(filepath, screenshotBuffer);
+
         return {
           content: [
             {
               type: 'text',
-              text: screenshot,
+              text: `Screenshot saved successfully to: ${filename}`,
             },
           ],
         };