JP's MCP Collection

# JP's MCP Collection JP's personal collection of [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) modules that provides a set of utility functions for Claude and other AI assistants. Built using the MCP SDK, this server exposes tools for system operations, Google services integration, and AI-powered text processing. ## Overview MCPs are built using the MCP SDK and exposes a set of tools that can be used by AI assistants to interact with: - System command execution - File system operations - Google Sheets integration - Google Tasks management - OpenAI chat completion and grammar checking - Dynamic prompt loading from markdown files ## Features ### System Operations - Command Execution: Run shell commands on the system with proper error handling and safety checks ### File System Operations - Move Files to Trash: Safely delete files by moving them to the system trash - Read Images: Read image files and return base64-encoded content with metadata ### Google Sheets Integration - List Sheets: Get available sheets in the configured spreadsheet - Read Sheet Content: Read data from specific ranges with pagination support - Update Sheets: Modify cell values in spreadsheets - Delete Rows: Remove specific rows from sheets - Get Sheet Properties: Retrieve metadata about sheet structure - Conditional Formatting: Add row-based conditional formatting rules ### Google Tasks Management - Task Lists: Create, update, delete, and list task lists - Tasks: Full CRUD operations for tasks including creation, updates, completion, and deletion - Subtasks: Create hierarchical task structures - Task Properties: Manage due dates, notes, and task status ### AI-Powered Text Processing - Chat Completion: Send prompts to OpenAI's GPT models with customizable parameters - Grammar Checking: Improve text grammar and clarity using AI ### Dynamic Prompt Management - Automatic Prompt Loading: Loads prompts from markdown files at server startup - Flexible Configuration: Configure prompt directory via environment variables - Smart Naming: Auto-generate prompt names from filenames when not specified in frontmatter - Frontmatter Support: Parse markdown frontmatter for prompt metadata ## Usage The server runs using Deno and can be started in development mode: ```bash # Run in development mode npm run dev # Run with the MCP inspector for debugging npm run monitor # Format code npm run format ``` ## Project Organization ### Directory Structure ``` jp-mcps/ ├── package.json # Project configuration and dependencies ├── README.md # Documentation ├── .env.example # Environment variables template ├── prompts/ # Default directory for dynamic prompts └── src/ # Source code ├── modules/ # Modular MCP tool implementations │ ├── command/ # System command execution │ │ ├── functions/ │ │ │ ├── run-command.ts │ │ │ └── index.ts │ │ ├── registerCommand.ts │ │ └── index.ts │ ├── dynamic-prompts/ # Dynamic prompt loading │ │ ├── functions/ │ │ │ ├── load-prompts.ts │ │ │ └── index.ts │ │ ├── utils/ │ │ │ ├── to-snake-case.ts │ │ │ └── index.ts │ │ ├── registerDynamicPrompts.ts │ │ └── index.ts │ ├── filesystem/ # File system operations │ │ ├── functions/ │ │ │ ├── move-file-to-trash.ts │ │ │ ├── read-image.ts │ │ │ └── index.ts │ │ ├── registerFilesystem.ts │ │ └── index.ts │ ├── hello/ # Reference implementation module │ ├── openai/ # OpenAI API integration │ │ ├── functions/ │ │ │ ├── chat-completion.ts │ │ │ ├── check-grammar.ts │ │ │ └── index.ts │ │ ├── registerOpenAI.ts │ │ └── index.ts │ ├── sheets/ # Google Sheets API integration │ │ ├── functions/ │ │ │ ├── list-sheets.ts │ │ │ ├── list-sheet-content.ts │ │ │ ├── update-sheet.ts │ │ │ ├── delete-row.ts │ │ │ ├── get-sheet-properties.ts │ │ │ ├── add-row-conditional-formatting.ts │ │ │ └── index.ts │ │ ├── registerGoogleSheets.ts │ │ ├── utils.ts │ │ └── index.ts │ └── tasks/ # Google Tasks API integration │ ├── functions/ │ │ ├── list-task-lists.ts │ │ ├── create-task-list.ts │ │ ├── update-task-list.ts │ │ ├── delete-task-list.ts │ │ ├── list-tasks.ts │ │ ├── create-task.ts │ │ ├── update-task.ts │ │ ├── complete-task.ts │ │ ├── delete-task.ts │ │ ├── create-subtask.ts │ │ └── index.ts │ ├── registerGoogleTasks.ts │ ├── client.ts │ └── index.ts └── index.ts # Main entry point ``` ### Code Organization The JP MCPs project follows a modular architecture designed for maintainability and extensibility: 1. Main Entry Point: `src/index.ts` initializes the MCP server and registers all available tools. 2. Modular Functions: Each capability is encapsulated in its own module within the `modules` directory with standardized patterns: - Each module has a `functions/` directory containing individual function implementations - Functions are named in kebab-case for consistency - Each function file includes its Zod input schema alongside the implementation - Modules export their functions and corresponding schema definitions for type safety - Each function follows a consistent error handling pattern 3. MCP Tool Registration: Tools are registered in module-specific register files using the `server.tool()` method which takes: - A tool name (used by Claude to invoke the function) - A schema definition (using Zod for runtime type validation) - An async handler function implementing the tool's logic 4. Response Formatting: Each function formats its responses consistently as an object with `content` property containing text output. 5. Error Handling: Comprehensive error handling with a TypeScript-safe approach using a utility function `getErrorMessage()` that properly handles both Error objects and unknown error types. ### Design Patterns JP MCPs employs several key design patterns: - Facade Pattern: Each module presents a simplified interface to complex subsystems (APIs, filesystem, etc.) - Function-based Organization: Clean separation of concerns with focused functions for each operation - Schema Validation: All inputs are validated using Zod schemas before processing - Consistent Error Handling: Try/catch blocks with standardized error responses - Type Safety: Heavy use of TypeScript and `zod.infer` for type definitions ## Dependencies - `@modelcontextprotocol/sdk`: Core MCP SDK for building MCP servers - `@googleapis/sheets`: Google Sheets API client - `@googleapis/tasks`: Google Tasks API client - `google-auth-library`: Authentication for Google services - `gray-matter`: Markdown frontmatter parsing for dynamic prompts - `openai`: OpenAI API client for chat completion and text processing - `execa`: Process execution for running system commands - `trash`: Safe file deletion by moving to system trash - `zod`: Schema validation and type safety ## Environment Variables The following environment variables need to be configured: - `OPENAI_API_KEY`: Your OpenAI API key for chat completion and grammar checking - `GOOGLE_CLIENT_ID`: Google OAuth client ID for Tasks API - `GOOGLE_CLIENT_SECRET`: Google OAuth client secret for Tasks API - `GOOGLE_REDIRECT_URI`: Google OAuth redirect URI for Tasks API - `GOOGLE_REFRESH_TOKEN`: Google OAuth refresh token for Tasks API - `PROMPTS_DIRECTORY`: Directory path containing markdown prompt files (defaults to "./prompts") ### Dynamic Prompts Setup Create markdown files in your prompts directory with frontmatter: ```markdown --- name: my_prompt description: Description of what this prompt does --- Your prompt content here... ``` Naming Rules: - If `name` is provided in frontmatter, it will be used as-is - If `name` is missing, the filename (without .md) will be converted to snake_case - If `description` is missing, it defaults to an empty string Example: - File: `Code Review.md` → Prompt name: `code_review` - File: `generate-tests.md` → Prompt name: `generate_tests` ## Integration JP MCPs is designed to be used as a tool provider for AI assistants like Claude through the Model Context Protocol, which allows the assistant to invoke functions defined in this server. ## Security Notes - Command execution includes safety checks for potentially dangerous operations - File operations are limited to safe actions (move to trash, read images) - All API calls are properly authenticated and use official client libraries - Input validation is performed using Zod schemas before any operations - Dynamic prompts are loaded from configurable directories to avoid hardcoded paths