JP's MCP Collection
JP's personal collection of Model Context Protocol (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:
# 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:
- Main Entry Point:
src/index.ts initializes the MCP server and registers all available tools. - 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
- 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
- Response Formatting: Each function formats its responses consistently as an object with
content property containing text output. - 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 clientgoogle-auth-library: Authentication for Google servicesgray-matter: Markdown frontmatter parsing for dynamic promptsopenai: OpenAI API client for chat completion and text processingexeca: Process execution for running system commandstrash: Safe file deletion by moving to system trashzod: 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 checkingGOOGLE_CLIENT_ID: Google OAuth client ID for Tasks APIGOOGLE_CLIENT_SECRET: Google OAuth client secret for Tasks APIGOOGLE_REDIRECT_URI: Google OAuth redirect URI for Tasks APIGOOGLE_REFRESH_TOKEN: Google OAuth refresh token for Tasks APIPROMPTS_DIRECTORY: Directory path containing markdown prompt files (defaults to "./prompts")
Dynamic Prompts Setup
Create markdown files in your prompts directory with frontmatter:
---
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