Peekaboo MCP

--- description: globs: alwaysApply: false --- # Agent Instructions This file provides guidance to AI assistants when working with code in this repository. ## Project Overview This is the `peekaboo` project, which provides a Model Context Protocol (MCP) server that enables executing AppleScript and JavaScript for Automation (JXA) scripts on macOS. The server features a knowledge base of pre-defined scripts accessible by ID and supports inline scripts, script files, and argument passing. ## Architecture - **Server Configuration**: The server reads configuration from environment variables like `LOG_LEVEL` and `KB_PARSING`. - **MCP Tools**: Two main tools are provided: 1. `execute_script`: Executes AppleScript/JXA from inline content, file path, or knowledge base ID 2. `get_scripting_tips`: Retrieves information from the knowledge base - **Knowledge Base**: A collection of pre-defined scripts stored as Markdown files in `knowledge_base/` directory with YAML frontmatter - **ScriptExecutor**: Core component that executes scripts via `osascript` command ## Knowledge Base System The knowledge base (`knowledge_base/` directory) contains numerous Markdown files organized by category: - Each file has YAML frontmatter with metadata: `id`, `title`, `description`, `language`, etc. - The actual script code is contained in the Markdown body in a fenced code block - Scripts can use placeholders like `--MCP_INPUT:keyName` and `--MCP_ARG_N` for parameter substitution ## Common Development Commands ```bash # Install dependencies npm install # Run the server in development mode with hot reloading npm run dev # Build the TypeScript project npm run build # Start the compiled server npm run start # Lint the codebase npm run lint # Format the codebase npm run format # Validate the knowledge base npm run validate ``` ## Environment Variables - `LOG_LEVEL`: Set logging level (`DEBUG`, `INFO`, `WARN`, `ERROR`) - default is `INFO` - `KB_PARSING`: Controls when knowledge base is parsed: - `lazy` (default): Parsed on first request - `eager`: Parsed when server starts ## Working with the Knowledge Base When adding new scripts to the knowledge base: 1. Create a new `.md` file in the appropriate category folder 2. Include required YAML frontmatter (`title`, `description`, etc.) 3. Add the script code in a fenced code block 4. Run `npm run validate` to ensure the new content is correctly formatted ## Code Execution Flow 1. The `server.ts` file defines the MCP server and its tools 2. `knowledgeBaseService.ts` loads and indexes scripts from the knowledge base 3. `ScriptExecutor.ts` handles the actual execution of scripts 4. Input validation is handled via Zod schemas in `schemas.ts` 5. Logging is managed by the `Logger` class in `logger.ts` ## Security and Permissions Remember that scripts run on macOS require specific permissions: - Automation permissions for controlling applications - Accessibility permissions for UI scripting via System Events - Full Disk Access for certain file operations ## Agent Operational Learnings and Debugging Strategies This section captures key operational strategies and debugging techniques for the agent (me) based on collaborative sessions. ### Prioritizing Log Visibility for Debugging When an external tool or script (like AppleScript via `osascript`) returns cryptic errors, or when agent-generated code/substitutions might be faulty: 1. **Suspect Dynamic Content**: Issues often stem from the dynamic content being passed to the external tool (e.g., incorrect placeholder substitutions leading to syntax errors in the target language). 2. **Enable/Add Detailed Logging**: Prioritize enabling any built-in detailed logging features of the tool in question (e.g., `includeSubstitutionLogs: true` for this project's `execute_script` tool). 3. **Ensure Log Visibility**: If standard debug logging doesn't appear in the primary output channel the user is observing, attempt to modify the code to force critical diagnostic information (like step-by-step transformations, variable states, or the exact content being passed externally) into that main output. This might involve temporarily altering the structure of the success or error messages to include these logs. * **Confirm Restarts and Code Version**: For changes requiring server restarts (common in this project), leverage any features that confirm the new code is active. For example, the server startup timestamp and execution mode info appended to `get_scripting_tips` output helps verify that a restart was successful and the intended code version (e.g., TypeScript source via `tsx` vs. compiled `dist/server.js`) is running. ### Iterative Simplification for Complex Patterns (e.g., Regex) If a complex pattern (like a regular expression) in code being generated or modified by the agent is not working as expected, and the cause isn't immediately obvious: 1. **Isolate the Pattern**: Identify the specific complex pattern (e.g., a regex for string replacement). 2. **Drastically Simplify**: Reduce the pattern to its most basic form that should still achieve a part of the goal or match a core component of the target string. (e.g., simplifying `/(?:["'])--MCP_INPUT:(\w+)(?:["'])/g` to `/--MCP_INPUT:/g` to test basic matching of the placeholder prefix). 3. **Test the Simple Form**: Verify if this simplified pattern works. If it does, the core string manipulation mechanism is likely sound. 4. **Incrementally Rebuild & Test**: Gradually add back elements of the original complexity (e.g., capture groups, character sets, quantifiers, lookarounds, backreferences like `\1`). Test at each incremental step to pinpoint which specific construct or combination introduces the failure. This process helped identify that `(?:["'])` was problematic in our placeholder regex, leading to a solution using a capturing group and a backreference like `/(["'])--MCP_INPUT:(\w+)\1/g`. 5. **Verify Replacement Logic**: Ensure that if the pattern involves capturing groups for use in a replacement, the replacement logic correctly utilizes these captures and produces the intended output format (e.g., `valueToAppleScriptLiteral` for AppleScript). This methodical approach is more effective than repeatedly trying minor variations of an already complex and failing pattern.