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:

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:

---
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